ABCarus is a desktop application for working with music encoded in ABC notation. It is designed for navigating, editing, rendering, and organizing large collections of .abc files. It treats each tune (from X: to the next X:) as an independent unit, which supports archival workflows and large libraries.
- Text-first ABC editing with tune-level navigation (
X:blocks) - Fast rendering and playback for iterative editing
- Focus/selection playback controls for targeted practice/debug
- Print/PDF export for single tunes or full files
- MusicXML import/export (bundled in release builds)
- Error scanning and grouped diagnostics for large files
ABCarus is in active development with regular updates. Behavior is kept stable, but selected UI/workflow details may be refined between releases.
- Release page: GitHub Releases
- Linux: AppImage · Portable (AppDir tar.gz) · SHA256
- Windows: Setup · Portable (.exe) · Portable (win-unpacked zip) · SHA256
- macOS (experimental): DMG (arm64) · DMG (x64) · SHA256 (arm64) · SHA256 (x64)
macOS note: builds are currently not notarized. On some macOS versions, Gatekeeper may report the app as “damaged” and refuse to open it.
After verifying the SHA256 sums, you can remove the quarantine attribute:
xattr -dr com.apple.quarantine /Applications/ABCarus.app.
| Platform | Artifact | Recommended for | Notes |
|---|---|---|---|
| Windows | ABCarus-setup-x64.exe |
Most users | Easiest install/update path |
| Windows | ABCarus-win-unpacked-x64.zip |
Portable use with faster startup | No installer, folder-based |
| Windows | ABCarus-portable-x64.exe |
Single-file portability | May start slowly on some systems |
| Linux | ABCarus-x86_64.AppImage |
Most users | Single file, standard desktop flow |
| Linux | ABCarus-x86_64-portable.tar.gz |
Portable/folder deployment | No AppImage runtime dependency |
| macOS (experimental) | ABCarus-macos-*.dmg |
Manual install/testing | Not notarized yet |
- Open GitHub Releases and download the build for your OS.
- Verify SHA256 checksums for your platform.
- Install/launch:
Linux:
chmod +x ABCarus-x86_64.AppImage && ./ABCarus-x86_64.AppImageWindows: run Setup or unpack portable zip and launchABCarus.exemacOS: mount DMG, move app to/Applications, launch
Release builds already bundle everything needed for normal use, including the Python runtime used by MusicXML import/export.
You can pass startup options when launching ABCarus:
--version/-version— print app version and exit.--input <path>/-input <path>— open the specified ABC file at startup.- positional file path (without
--input) is also accepted. --factorysettings/-factorysettings— reset saved app state/settings before startup.--log/-log— write a session log file in userData while the app runs.
Examples:
- Linux AppImage:
./ABCarus-x86_64.AppImage --input "/path/to/tune.abc"
- Windows:
"C:\\Program Files\\ABCarus\\ABCarus.exe" --input "C:\\abc\\collection.abc"
- macOS:
open -a ABCarus --args --input "/Users/name/collection.abc"
- Development (npm):
npm start -- --input "/path/to/tune.abc"
- Windows single-file portable (
ABCarus-portable-x64.exe) may start slowly on some systems (for example due to pre-launch extraction and OS security scanning). In this period, app UI may not appear immediately. - If this affects your workflow, use
ABCarus-win-unpacked-x64.zip(folder-based portable build), which typically starts faster and more predictably.
- App does not appear immediately on Windows portable
.exe: UseABCarus-win-unpacked-x64.zipand launch from the extracted folder. - macOS reports app as “damaged”:
Verify SHA256, then run
xattr -dr com.apple.quarantine /Applications/ABCarus.app. - Playback seems inconsistent after many quick edits: Restart app and retest with a fresh playback run; if reproducible, capture a debug dump and report.
- ChordPro preview unavailable: Check ChordPro CLI availability/settings (see User Guide).
For users:
- User Guide (how to use ABCarus): docs/USER_GUIDE.md
- Changelog (what changed): CHANGELOG.md
For contributors:
- Quick workflow (dev + release): WORKFLOW.md
- Developer documentation index: docs/README.md
- Detailed release checklist: docs/RELEASE_CHECKLIST.md
- Product + engineering invariants: docs/REQUIREMENTS.md
- Methodology (chat-driven, docs-backed): docs/METHODOLOGY.md
- Requirements: Node.js (LTS) and npm
- Install dependencies:
npm install - Run the app:
npm start
Python is not required for basic editing/rendering/playback in development. It is only needed for MusicXML import/export. For import/export in development, install PBS runtime for your current OS:
- Linux/macOS:
bash devtools/pbs/pbs-install-all.sh - Windows:
pwsh -ExecutionPolicy Bypass -File devtools/pbs/pbs-install-all.ps1
ABCarus ships only one bundled soundfont (TimGM6mb.sf2). Additional soundfonts are optional and installed locally. See docs/soundfonts.md.
ABCarus ships several bundled notation/text fonts (SIL OFL 1.1) for abc2svg rendering. See docs/notation-fonts.md and NOTICE.md.
Release builds bundle a local Python runtime (PBS) for MusicXML import/export. See docs/python-build-standalone.md and docs/python-runtime.md.
- Recursive scanning of folders containing
.abcfiles - File + tune navigation (tunes are separated by
X:headers) - Text-first editing of ABC
- Notation rendering
- Print/export PDF for single tunes or full files
- Playback for editing/reference (including Focus/selection controls and soundfont-based output)
- Error scanning and grouped diagnostics
ABCarus is a text-first editor and workflow tool for ABC notation. It is not intended to replace DAWs, full engraving suites, or performance-grade interpretation engines.
- Text-first workflow
- Predictable, reproducible behavior
- Minimal abstractions over the ABC format
- Suitability for large libraries
- Long-term maintainability
Playback and rendering are implemented to support reading and editing, not to replace musical interpretation.
%%sepcan trigger abc2svg errors in some scores. ABCarus first tries normal rendering; if that fails and%%sepis present, it retries with a length-safe%%sepfallback and shows a warning.- Printing/exporting all tunes includes error summaries and inline error cards for tunes that fail to render.
- SemVer is used, with
package.jsonas the source of truth. - Releases are tagged
vX.Y.Zand documented in CHANGELOG.md. - See docs/VERSIONING.md and docs/RELEASES.md.
- Electron
- JavaScript
- ABC notation
- abc2svg (rendering and basic playback)
Import/Export uses external Python converters stored under third_party/:
third_party/abc2xml/abc2xml.py(ABC → MusicXML)third_party/xml2abc/xml2abc.py(MusicXML → ABC)third_party/midi2xml/midi2xml.py(MIDI → MusicXML, experimental backend)third_party/midi2abc/midi2abc.mjs(MIDI → ABC, experimental)
By default, ABCarus prefers a bundled Python runtime (PBS). In development, install PBS with:
- Linux/macOS:
bash devtools/pbs/pbs-install-all.sh - Windows:
pwsh -ExecutionPolicy Bypass -File devtools/pbs/pbs-install-all.ps1
System Python fallback is opt-in only via ABCARUS_ALLOW_SYSTEM_PYTHON=1.
- Linux, Windows, macOS (release builds provided; Linux is the primary development platform)
Major third-party components used by ABCarus:
- abc2svg — https://chiselapp.com/user/moinejf/repository/abc2svg/doc/trunk/README.md
- abc2xml — https://wim.vree.org/svgParse/abc2xml.html
- xml2abc — https://wim.vree.org/svgParse/xml2abc.html
- music21 — https://github.com/cuthbertLab/music21
- midi2abc — https://github.com/marmooo/midi2abc
- CodeMirror — https://codemirror.net/
- Tabulator — https://tabulator.info/
- Electron — https://www.electronjs.org/
- Node.js — https://nodejs.org/
- Python — https://www.python.org/
- TimGM6mb.sf2 (soundfont) — https://timbrechbill.com/saxguru/
See NOTICE.md for licenses and attribution details.
| Name | Project(s) | Why it matters to ABCarus | Link |
|---|---|---|---|
| Chris Walshaw | ABC notation | Where ABC comes from and where the spec lives | https://abcnotation.com/ |
| Jean‑François Moine | abc2svg, txtmus, abcm2ps | The rendering engine we build on (abc2svg) and a lot of ABC craft around it | http://moinejf.free.fr/ |
| Seymour Shlien | EasyABC, runabc, midiexplorer | A long-running desktop editor that shaped many real-world workflows | https://ifdo.ca/~seymour/runabc/top.html |
| James Allwright | abcMIDI | The classic ABC→MIDI toolbox many people still rely on | https://abcmidi.sourceforge.io/ |
| Michael Eskin | ABC Transcription Tools | A huge set of practical online helpers for everyday ABC work | https://michaeleskin.com/abctools/abctools.html |
| cuthbertLab | music21 | MIDI parsing backend used by the optional MIDI -> MusicXML -> ABC pipeline | https://github.com/cuthbertLab/music21 |
| marmooo | midi2abc | Practical MIDI → ABC conversion baseline used for bundled import | https://github.com/marmooo/midi2abc |
| Paul Rosen | abcjs | One of the most common ABC renderers on the web | https://www.abcjs.net/ |
| Johan Vromans | ChordPro | A strong song/chords world that overlaps with ABC use cases | https://www.chordpro.org/ |
| Willem Vree | abc2xml, xml2abc | The MusicXML bridge (ABC ↔ MusicXML) | https://wim.vree.org/ |
| Sergio Di Mico | AbcToSheet | Another take on turning ABC into sheet music | https://abctosheet.my.to/ |
| Benoît Rouits | qabc, redrose | Small, sharp ABC projects worth studying | https://github.com/be1 |
| MTG | SymbTr | Research angle on symbolic music data | https://github.com/MTG/symbtr |
These are personal sources of inspiration and gratitude, separate from the technical projects above:
- Houshamadyan — a project to reconstruct Ottoman Armenian town and village life.
- Ara Dinkjian — composer, musician, and oud teacher.
- Corpus Musicae Ottomanicae — critical edition of Near Eastern music manuscripts.
- My Lord and Savior Yeshua
ABCarus source code is licensed under the MIT License.
This project uses third-party components, including abc2svg (LGPL) and CodeMirror (MIT). See NOTICE.md for details.