muscriptor.cpp

Native C++ inference for MuScriptor — transcribe audio to MIDI / note events via ggml (CPU, Apple Metal, or NVIDIA CUDA).

This repository’s code is MIT. Model weights are CC BY-NC 4.0 (non-commercial); accept the license on Hugging Face before downloading.

Install

git clone --recurse-submodules https://github.com/audiohacking/muscriptor.cpp.git
cd muscriptor.cpp
make          # Metal on macOS · CUDA if nvcc is available · else CPU

make cpu      # or: make metal / make cuda
# CUDA tip: export CUDACXX=$(command -v nvcc)

Models

Same sizes as upstream MuScriptor (--model small|medium|large):

Size	Params	Layers	Dim	HF repo
small	103M	14	768	muscriptor-small
medium (default)	307M	24	1024	muscriptor-medium
large	1.4B	48	1536	muscriptor-large

# 1) Download safetensors (needs `hf` CLI + HF login for gated weights)
pipx install 'huggingface_hub[cli]'
hf auth login
./scripts/download_gguf.sh medium    # or small / large

# medium also available from the audiohacking bucket:
# ./scripts/download_from_bucket.sh

# 2) Convert to GGUF (optional Python — convert/ only)
python3 -m venv .venv && ./.venv/bin/pip install -r convert/requirements.txt
./scripts/convert_gguf.sh models/hf-medium models/muscriptor-medium-F16.gguf f16

Transcribe

CLI mirrors the Python muscriptor options:

./build-cuda/muscriptor song.wav -o out.mid
./build-cuda/muscriptor song.wav -m large --instruments piano,drums -o out.mid
./build-cuda/muscriptor song.wav -f jsonl -o events.jsonl
./build-cuda/muscriptor list-instruments

Flag	Meaning
-m, --model	small / medium / large or path to a .gguf
-d, --device	auto / cpu / cuda / metal
-o, --output	Output path (- = stdout)
-f, --format	midi (default) / json / jsonl
--sampling / -t	Temperature sampling
--cfg-coef	Classifier-free guidance (keep 1 for released models)
-b, --batch-size	Chunks per step (>1 needs --no-prelude-forcing)
--beam-size	Beam width (1 = greedy/sampling)
--strict-eos	Fail if a chunk never emits EOS
--prelude-forcing / --no-prelude-forcing	Tie prologue across 5 s chunks
--instruments	Comma-separated groups (abbreviations ok)
--notes	Print events to stderr (use with -f json)