{"id":39547476,"url":"https://github.com/topchyan/abcarus","last_synced_at":"2026-04-04T04:02:11.471Z","repository":{"id":332701182,"uuid":"1124235503","full_name":"topchyan/abcarus","owner":"topchyan","description":"ABCarus is a desktop application for working with music encoded in ABC notation.","archived":false,"fork":false,"pushed_at":"2026-02-08T02:28:34.000Z","size":21022,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-08T10:42:56.744Z","etag":null,"topics":["abcnotation","classical-music","folk-music","microtonality","microtonalmusic","music-","music-theory","scores-libraries","solfege","tools","tunes"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/topchyan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-28T16:11:58.000Z","updated_at":"2026-02-08T02:28:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/topchyan/abcarus","commit_stats":null,"previous_names":["topchyan/abcarus"],"tags_count":65,"template":false,"template_full_name":null,"purl":"pkg:github/topchyan/abcarus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topchyan%2Fabcarus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topchyan%2Fabcarus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topchyan%2Fabcarus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topchyan%2Fabcarus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/topchyan","download_url":"https://codeload.github.com/topchyan/abcarus/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topchyan%2Fabcarus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29352843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T01:03:07.613Z","status":"ssl_error","status_checked_at":"2026-02-12T01:00:51.346Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abcnotation","classical-music","folk-music","microtonality","microtonalmusic","music-","music-theory","scores-libraries","solfege","tools","tunes"],"created_at":"2026-01-18T06:48:32.537Z","updated_at":"2026-04-04T04:02:11.462Z","avatar_url":"https://github.com/topchyan.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/icons/abcarus_96.png\" width=\"96\" height=\"96\" alt=\"ABCarus logo\" /\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eABCarus\u003c/h1\u003e\n\nABCarus 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.\n\n## Highlights\n\n- Text-first ABC editing with tune-level navigation (`X:` blocks)\n- Fast rendering and playback for iterative editing\n- Focus/selection playback controls for targeted practice/debug\n- Print/PDF export for single tunes or full files\n- MusicXML import/export (bundled in release builds)\n- Error scanning and grouped diagnostics for large files\n\n## Status\n\nABCarus is in active development with regular updates. Behavior is kept stable, but selected UI/workflow details may be refined between releases.\n\n## Downloads (latest)\n\n- Release page: [GitHub Releases][releases-latest]\n- Linux: [AppImage][dl-linux-appimage] · [Portable (AppDir tar.gz)][dl-linux-portable] · [SHA256][sha-linux]\n- Windows: [Setup][dl-win-setup] · [Portable (.exe)][dl-win-portable] · [Portable (win-unpacked zip)][dl-win-unpacked] · [SHA256][sha-windows]\n- macOS (experimental): [DMG (arm64)][dl-mac-arm64] · [DMG (x64)][dl-mac-x64] · [SHA256 (arm64)][sha-mac-arm64] · [SHA256 (x64)][sha-mac-x64]\n\nmacOS note: builds are currently not notarized. On some macOS versions, Gatekeeper may report the app as “damaged” and refuse to open it.\nAfter verifying the SHA256 sums, you can remove the quarantine attribute:\n`xattr -dr com.apple.quarantine /Applications/ABCarus.app`.\n\n[releases-latest]: https://github.com/topchyan/abcarus/releases/latest\n\n[dl-linux-appimage]: https://github.com/topchyan/abcarus/releases/latest/download/ABCarus-x86_64.AppImage\n[dl-linux-portable]: https://github.com/topchyan/abcarus/releases/latest/download/ABCarus-x86_64-portable.tar.gz\n[sha-linux]: https://github.com/topchyan/abcarus/releases/latest/download/SHA256SUMS-linux.txt\n\n[dl-win-setup]: https://github.com/topchyan/abcarus/releases/latest/download/ABCarus-setup-x64.exe\n[dl-win-portable]: https://github.com/topchyan/abcarus/releases/latest/download/ABCarus-portable-x64.exe\n[dl-win-unpacked]: https://github.com/topchyan/abcarus/releases/latest/download/ABCarus-win-unpacked-x64.zip\n[sha-windows]: https://github.com/topchyan/abcarus/releases/latest/download/SHA256SUMS-windows.txt\n\n[dl-mac-arm64]: https://github.com/topchyan/abcarus/releases/latest/download/ABCarus-macos-arm64.dmg\n[dl-mac-x64]: https://github.com/topchyan/abcarus/releases/latest/download/ABCarus-macos-x64.dmg\n[sha-mac-arm64]: https://github.com/topchyan/abcarus/releases/latest/download/SHA256SUMS-macos-arm64.txt\n[sha-mac-x64]: https://github.com/topchyan/abcarus/releases/latest/download/SHA256SUMS-macos-x64.txt\n\n## Choose your build\n\n| Platform | Artifact | Recommended for | Notes |\n|---|---|---|---|\n| Windows | `ABCarus-setup-x64.exe` | Most users | Easiest install/update path |\n| Windows | `ABCarus-win-unpacked-x64.zip` | Portable use with faster startup | No installer, folder-based |\n| Windows | `ABCarus-portable-x64.exe` | Single-file portability | May start slowly on some systems |\n| Linux | `ABCarus-x86_64.AppImage` | Most users | Single file, standard desktop flow |\n| Linux | `ABCarus-x86_64-portable.tar.gz` | Portable/folder deployment | No AppImage runtime dependency |\n| macOS (experimental) | `ABCarus-macos-*.dmg` | Manual install/testing | Not notarized yet |\n\n## Quick install (end users)\n\n1. Open [GitHub Releases][releases-latest] and download the build for your OS.\n2. Verify SHA256 checksums for your platform.\n3. Install/launch:\nLinux: `chmod +x ABCarus-x86_64.AppImage \u0026\u0026 ./ABCarus-x86_64.AppImage`\nWindows: run Setup or unpack portable zip and launch `ABCarus.exe`\nmacOS: mount DMG, move app to `/Applications`, launch\n\nRelease builds already bundle everything needed for normal use, including the Python runtime used by MusicXML import/export.\n\n## Command-line startup options\n\nYou can pass startup options when launching ABCarus:\n\n- `--version` / `-version` — print app version and exit.\n- `--input \u003cpath\u003e` / `-input \u003cpath\u003e` — open the specified ABC file at startup.\n- positional file path (without `--input`) is also accepted.\n- `--factorysettings` / `-factorysettings` — reset saved app state/settings before startup.\n- `--log` / `-log` — write a session log file in userData while the app runs.\n\nExamples:\n\n- Linux AppImage:\n  - `./ABCarus-x86_64.AppImage --input \"/path/to/tune.abc\"`\n- Windows:\n  - `\"C:\\\\Program Files\\\\ABCarus\\\\ABCarus.exe\" --input \"C:\\\\abc\\\\collection.abc\"`\n- macOS:\n  - `open -a ABCarus --args --input \"/Users/name/collection.abc\"`\n- Development (npm):\n  - `npm start -- --input \"/path/to/tune.abc\"`\n\n## Known limitations\n\n- 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.\n- If this affects your workflow, use `ABCarus-win-unpacked-x64.zip` (folder-based portable build), which typically starts faster and more predictably.\n\n## Troubleshooting\n\n- App does not appear immediately on Windows portable `.exe`:\nUse `ABCarus-win-unpacked-x64.zip` and launch from the extracted folder.\n- macOS reports app as “damaged”:\nVerify SHA256, then run `xattr -dr com.apple.quarantine /Applications/ABCarus.app`.\n- Playback seems inconsistent after many quick edits:\nRestart app and retest with a fresh playback run; if reproducible, capture a debug dump and report.\n- ChordPro preview unavailable:\nCheck ChordPro CLI availability/settings (see User Guide).\n\n## Documentation\n\nFor users:\n- User Guide (how to use ABCarus): [docs/USER_GUIDE.md](docs/USER_GUIDE.md)\n- Changelog (what changed): [CHANGELOG.md](CHANGELOG.md)\n\nFor contributors:\n- Quick workflow (dev + release): [WORKFLOW.md](WORKFLOW.md)\n- Developer documentation index: [docs/README.md](docs/README.md)\n- Detailed release checklist: [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md)\n- Product + engineering invariants: [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md)\n- Methodology (chat-driven, docs-backed): [docs/METHODOLOGY.md](docs/METHODOLOGY.md)\n\n## Quick start (development)\n\n### Development setup\n- Requirements: Node.js (LTS) and npm\n- Install dependencies: `npm install`\n- Run the app: `npm start`\n\nPython is not required for basic editing/rendering/playback in development. It is only needed for MusicXML import/export.\nFor import/export in development, install PBS runtime for your current OS:\n- Linux/macOS: `bash devtools/pbs/pbs-install-all.sh`\n- Windows: `pwsh -ExecutionPolicy Bypass -File devtools/pbs/pbs-install-all.ps1`\n\n### Soundfonts\nABCarus ships only one bundled soundfont (`TimGM6mb.sf2`). Additional soundfonts are optional and installed locally. See [docs/soundfonts.md](docs/soundfonts.md).\n\n### Notation fonts (SMuFL)\nABCarus ships several bundled notation/text fonts (SIL OFL 1.1) for abc2svg rendering. See [docs/notation-fonts.md](docs/notation-fonts.md) and [NOTICE.md](NOTICE.md).\n\n### Release builds\nRelease builds bundle a local Python runtime (PBS) for MusicXML import/export. See [docs/python-build-standalone.md](docs/python-build-standalone.md) and [docs/python-runtime.md](docs/python-runtime.md).\n\n### Core features\n\n- Recursive scanning of folders containing `.abc` files\n- File + tune navigation (tunes are separated by `X:` headers)\n- Text-first editing of ABC\n- Notation rendering\n- Print/export PDF for single tunes or full files\n- Playback for editing/reference (including Focus/selection controls and soundfont-based output)\n- Error scanning and grouped diagnostics\n\n## Scope / non-goals\n\nABCarus is a text-first editor and workflow tool for ABC notation.\nIt is not intended to replace DAWs, full engraving suites, or performance-grade interpretation engines.\n\n## Design goals\n\n- Text-first workflow\n- Predictable, reproducible behavior\n- Minimal abstractions over the ABC format\n- Suitability for large libraries\n- Long-term maintainability\n\nPlayback and rendering are implemented to support reading and editing, not to replace musical interpretation.\n\n### Rendering notes\n\n- `%%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.\n- Printing/exporting all tunes includes error summaries and inline error cards for tunes that fail to render.\n\n### Versioning \u0026 Releases\n\n- SemVer is used, with `package.json` as the source of truth.\n- Releases are tagged `vX.Y.Z` and documented in [CHANGELOG.md](CHANGELOG.md).\n- See [docs/VERSIONING.md](docs/VERSIONING.md) and [docs/RELEASES.md](docs/RELEASES.md).\n\n### Technology\n\n- Electron\n- JavaScript\n- ABC notation\n- abc2svg (rendering and basic playback)\n\n### Import/Export prerequisites\n\nImport/Export uses external Python converters stored under `third_party/`:\n\n- `third_party/abc2xml/abc2xml.py` (ABC → MusicXML)\n- `third_party/xml2abc/xml2abc.py` (MusicXML → ABC)\n- `third_party/midi2xml/midi2xml.py` (MIDI → MusicXML, experimental backend)\n- `third_party/midi2abc/midi2abc.mjs` (MIDI → ABC, experimental)\n\nBy default, ABCarus prefers a bundled Python runtime (PBS). In development, install PBS with:\n\n- Linux/macOS: `bash devtools/pbs/pbs-install-all.sh`\n- Windows: `pwsh -ExecutionPolicy Bypass -File devtools/pbs/pbs-install-all.ps1`\n\nSystem Python fallback is opt-in only via `ABCARUS_ALLOW_SYSTEM_PYTHON=1`.\n\n### Platforms\n\n- Linux, Windows, macOS (release builds provided; Linux is the primary development platform)\n\n### Credits\n\nMajor third-party components used by ABCarus:\n\n- abc2svg — https://chiselapp.com/user/moinejf/repository/abc2svg/doc/trunk/README.md\n- abc2xml — https://wim.vree.org/svgParse/abc2xml.html\n- xml2abc — https://wim.vree.org/svgParse/xml2abc.html\n- music21 — https://github.com/cuthbertLab/music21\n- midi2abc — https://github.com/marmooo/midi2abc\n- CodeMirror — https://codemirror.net/\n- Tabulator — https://tabulator.info/\n- Electron — https://www.electronjs.org/\n- Node.js — https://nodejs.org/\n- Python — https://www.python.org/\n- TimGM6mb.sf2 (soundfont) — https://timbrechbill.com/saxguru/\n\nSee [NOTICE.md](NOTICE.md) for licenses and attribution details.\n\n### Inspiration\n\n| Name | Project(s) | Why it matters to ABCarus | Link |\n|---|---|---|---|\n| Chris Walshaw | ABC notation | Where ABC comes from and where the spec lives | https://abcnotation.com/ |\n| 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/ |\n| Seymour Shlien | EasyABC, runabc, midiexplorer | A long-running desktop editor that shaped many real-world workflows | https://ifdo.ca/~seymour/runabc/top.html |\n| James Allwright | abcMIDI | The classic ABC→MIDI toolbox many people still rely on | https://abcmidi.sourceforge.io/ |\n| Michael Eskin | ABC Transcription Tools | A huge set of practical online helpers for everyday ABC work | https://michaeleskin.com/abctools/abctools.html |\n| cuthbertLab | music21 | MIDI parsing backend used by the optional MIDI -\u003e MusicXML -\u003e ABC pipeline | https://github.com/cuthbertLab/music21 |\n| marmooo | midi2abc | Practical MIDI → ABC conversion baseline used for bundled import | https://github.com/marmooo/midi2abc |\n| Paul Rosen | abcjs | One of the most common ABC renderers on the web | https://www.abcjs.net/ |\n| Johan Vromans | ChordPro | A strong song/chords world that overlaps with ABC use cases | https://www.chordpro.org/ |\n| Willem Vree | abc2xml, xml2abc | The MusicXML bridge (ABC ↔ MusicXML) | https://wim.vree.org/ |\n| Sergio Di Mico | AbcToSheet | Another take on turning ABC into sheet music | https://abctosheet.my.to/ |\n| Benoît Rouits | qabc, redrose | Small, sharp ABC projects worth studying | https://github.com/be1 |\n| MTG | SymbTr | Research angle on symbolic music data | https://github.com/MTG/symbtr |\n\n### Personal acknowledgements\n\nThese are personal sources of inspiration and gratitude, separate from the technical projects above:\n\n- [Houshamadyan](https://www.houshamadyan.org/home.html) — a project to reconstruct Ottoman Armenian town and village life.\n- [Ara Dinkjian](https://www.aradinkjian.com/) — composer, musician, and oud teacher.\n- [Corpus Musicae Ottomanicae](https://corpus-musicae-ottomanicae.de/content/index.xml) — critical edition of Near Eastern music manuscripts.\n- My Lord and Savior Yeshua\n\n### Licensing\n\nABCarus source code is licensed under the MIT License.\n\nThis project uses third-party components, including abc2svg (LGPL) and CodeMirror (MIT).\nSee [NOTICE.md](NOTICE.md) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopchyan%2Fabcarus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftopchyan%2Fabcarus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopchyan%2Fabcarus/lists"}