# abcforge

CLI for converting music notation from Guitar Pro, MusicXML into .abc (supports interleaving).

Why? Existing tools like abctoolkit have subtle bugs (patched here) for abc interleaving. The abc2xml script by W.G. Vree has been made importable and easily usable in batch mode. Finally we add a wrapper around MuseScore that batches conversions. 

We hope this is useful for reproducability in MIR research for pipelines such as [CLAMP3](https://github.com/sanderwood/clamp3).

## Install

```bash
pip install abcforge
# or run without installing:
uvx abcforge --help
```

## Commands

```bash
abcforge gp2xml   <input_dir> <output_dir>   # .gp/.gpx/.gp5 → .musicxml  (requires MuseScore)
abcforge xml2abc  <input_dir> <output_dir>   # .musicxml → .abc
abcforge abc2abci <input_dir> <output_dir>   # .abc → interleaved .abc
abcforge view     <file>                     # open .abc or .musicxml in browser
```

All batch commands accept `--workers N` (default: cpu count), `--resume` (skip already-converted files), and `--log <path>` (errors to file instead of stderr).

## Viewer

`abcforge view` opens files at [abcviewer.sven.zone](https://abcviewer.sven.zone). Supports both ABC notation and MusicXML — the viewer auto-detects the format and renders MusicXML via OpenSheetMusicDisplay.

```bash
abcforge view song.abc
abcforge view song.musicxml
abcforge view song.abc --url     # print URL only, don't open browser
```

## Notes

- MusicXML → ABC conversion uses [xml2abc](https://wim.vree.org/js/xml2abc-js_index.html) by W.G. Vree (LGPL).
- The vendored `abctoolkit` is a patched fork of [abctoolkit 0.0.6](https://pypi.org/project/abctoolkit/) with fixes for voice attribute parsing and bar splitting. Do not replace it with the PyPI version.
- MuseScore must be installed for `gp2xml`.
