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.
Early-stage release. The app is actively developed; some workflows and UI details may still change. Keep backups of your data.
See CHANGELOG.md.
- 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.
Use a release build from GitHub Releases (recommended for normal use).
- Linux: download the AppImage, make it executable, run it.
- Windows: download Setup (
ABCarus-setup-x64.exe) or Portable (ABCarus-portable-x64.exe), then launch. - macOS: download the DMG for your CPU (arm64/x64), install, then launch.
Release builds already bundle everything needed for normal use, including the Python runtime used by MusicXML import/export.
For users:
- User Guide (how to use ABCarus): docs/USER_GUIDE.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
See WORKFLOW.md for:
- 3–5-command release flow (version → tag → push → verify)
- What we commit / keep local (e.g.
scripts/local/**) - Useful debug env vars (e.g.
ABCARUS_DEBUG_KEYS=1) - Fast local checks:
npm run test:quickandnpm run test:ui-smoke
- 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
- 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.