symusic 0.6.0

A high performance MIDI file parser with comprehensible interface.

symusic

ISMIR 2024 LBD Demo Video: YouTube Bilibili

Symusic ("Symbolic Music") is a cross-platform symbolic music toolkit for note-level MIDI and ABC workflows. The core is written in C++20 and exposed to Python through nanobind, which keeps common parsing and transformation workloads hundreds of times faster than the pure-Python stacks many MIR pipelines still rely on.

The project builds on top of minimidi for parsing, zpp_bits for fast pickling, and prestosynth for SoundFont rendering.

The canonical documentation is hosted on Read the Docs at symusic.readthedocs.io. The legacy GitHub Pages mdBook remains available at yikai-liao.github.io/symusic for historical links only.

Documentation

• Read the Docs is the primary public documentation target: https://symusic.readthedocs.io/en/stable/.
• The documentation source for RTD lives under docs/ and is built with Sphinx + MyST.
• CHANGELOG.md tracks the current v0.6.0 work and backfills published historical releases.
• The legacy mdBook stays online for historical reference but is no longer updated.
• Build the docs locally via python -m venv .venv, source .venv/bin/activate, pip install -r docs/requirements.txt, and pip install . -C cmake.define.SYMUSIC_FAST_BUILD=ON before running sphinx-build -b html docs docs/_build/html.

Features

• Load MIDI and ABC files with Score("path.mid") or Score("path.abc", fmt="abc").
• Convert scores between tick, quarter, and second time units.
• Export back to MIDI or ABC with dump_midi, dump_abc, and dumps_abc.
• Compute beats, downbeats, and piano rolls for analysis and model pipelines.
• Apply vectorized transformations on Score and Track objects such as shift_pitch, shift_velocity, shift_time, sort, and filter.
• Serialize containers efficiently with pickle and structured NumPy exports.
• Render audio through SoundFonts with Synthesizer, BuiltInSF2, BuiltInSF3, and dump_wav.

Installation

Use pre-built wheels

pip install symusic

Build from source

Make sure your system has CMake and a C++20-capable compiler, then clone the repository with submodules and install it through pip:

git clone --recursive https://github.com/Yikai-Liao/symusic
cd symusic
pip install .

Or install the source distribution from PyPI:

pip install symusic --no-binary symusic

On Windows, pip install . will prefer Ninja + MSVC when it runs inside a Visual Studio Developer shell. In a regular shell it keeps using the default Visual Studio generator.

For debugging, you can pass -Ccmake.define.MEM_LEAK_WARNING=True to pip install to enable the nanobind leak-warning instrumentation:

pip install -Ccmake.define.MEM_LEAK_WARNING=True .

Python compatibility and CI coverage

The wheel publication workflow builds CPython wheels for Python 3.9 through 3.14 across the Linux, macOS, and Windows targets listed in .github/workflows/wheel.yml, including win_arm64. PyPy wheels are currently published for pp311 on manylinux_x86_64, macosx_x86_64, and macosx_arm64.

+freethreaded variants are not tested yet. CPython 3.12 can still emit nanobind leak warnings even when the build is otherwise healthy.

Benchmark

• midifile is written in C++ and can parse MIDI files to both event level and note level. It is still slowed down by iostream.
• mido is written in pure Python and only parses MIDI files to event level.
• pretty_midi and miditoolkit build on top of mido and expose note-level abstractions.
• For libraries written in Python or with Python bindings, we use timeit to measure parse time. nanobench is used for C++ libraries and BenchmarkTools for Julia libraries.
• The benchmark scripts live in symusic-benchmark.
• The published chart was measured on GitHub Actions M1 runners.

Citation

@inproceedings{symusic2024,
    title={symusic: A swift and unified toolkit for symbolic music processing},
    author={Yikai Liao, Zhongqi Luo, et al.},
    booktitle={Extended Abstracts for the Late-Breaking Demo Session of the 25th International Society for Music Information Retrieval Conference},
    year={2024},
    url={https://ismir2024program.ismir.net/lbd_426.html#lbd},
}

Acknowledgement

• minimidi : A fast and lightweight MIDI parsing library written in C++, which is the foundation of this project.
• prestosynth : A fast SoundFont synthesizer written in C++, which powers Symusic's synthesis layer.
• nanobind : An efficient and lightweight library for binding C++ to Python.
• zpp_bits : A fast single-header serialization library used for pickle support.
• geek_time_cpp : Example code from the book "Modern C++ Programming Practice". We use metamacro.h from it to shorten repetitive code.
• utfcpp : A portable library for handling UTF-8 strings in C++.