<p align="center"> <img src="assets/icons/abcarus_96.png" width="96" height="96" alt="ABCarus logo" /> </p> <h1 align="center">ABCarus</h1>

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.

Highlights

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

Status

ABCarus is in active development with regular updates. Behavior is kept stable, but selected UI/workflow details may be refined between releases.

Downloads (latest)

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.

Choose your build

| 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 |

Quick install (end users)

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.AppImage Windows: run Setup or unpack portable zip and launch ABCarus.exe macOS: 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.

Command-line startup options

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"

Known limitations

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.

Troubleshooting

App does not appear immediately on Windows portable .exe: Use ABCarus-win-unpacked-x64.zip and 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).

Documentation

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

Quick start (development)

Development setup

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

Soundfonts

ABCarus ships only one bundled soundfont (TimGM6mb.sf2). Additional soundfonts are optional and installed locally. See docs/soundfonts.md.

Notation fonts (SMuFL)

ABCarus ships several bundled notation/text fonts (SIL OFL 1.1) for abc2svg rendering. See docs/notation-fonts.md and NOTICE.md.

Release builds

Release builds bundle a local Python runtime (PBS) for MusicXML import/export. See docs/python-build-standalone.md and docs/python-runtime.md.

Core features

Recursive scanning of folders containing .abc files
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

Scope / non-goals

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.

Design goals

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.

Rendering notes

%%sep can trigger abc2svg errors in some scores. ABCarus first tries normal rendering; if that fails and %%sep is present, it retries with a length-safe %%sep fallback and shows a warning.
Printing/exporting all tunes includes error summaries and inline error cards for tunes that fail to render.

Versioning & Releases

SemVer is used, with package.json as the source of truth.
Releases are tagged vX.Y.Z and documented in CHANGELOG.md.
See docs/VERSIONING.md and docs/RELEASES.md.

Technology

Electron
JavaScript
ABC notation
abc2svg (rendering and basic playback)

ABCarus rendering/playback behavior follows the bundled abc2svg engine by Jean-Francois Moine. For ABC/abcm2ps directive reference (including %%MIDI family), see:

http://moinejf.free.fr/abcm2ps-doc/index.html

Import/Export prerequisites

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.

Platforms

Linux, Windows, macOS (release builds provided; Linux is the primary development platform)

Credits

Major third-party components used b

Abcarus

Install / Use

README