README.md

---
title: MuScriptor Studio
emoji: 🎼
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Audio → MIDI via muscriptor (Kyutai × Mirelo)
---

# MuScriptor Studio

Drop in an audio file → get a MIDI transcription back, using
[muscriptor](https://github.com/muscriptor/muscriptor) (a transformer-LM
audio-to-MIDI model from Kyutai × Mirelo). For busy mixes you can
isolate the vocals first with
[demucs](https://github.com/facebookresearch/demucs) — voice is decoded
much better on its own.

## What it does

1. **Upload** any `mp3` / `wav` / `m4a` / `flac` file.
2. Optionally tick **Isolate vocals** to run `demucs htdemucs --two-stems vocals`
   first (saves the voice stem, feeds that to muscriptor).
3. Pick **Model size**: `small` / `medium` / `large`. Larger = better, slower.
4. Optionally constrain the **instruments** (comma-separated, e.g.
   `voice,acoustic_piano,accordion,drums` for Balkan folk).
5. Hit **Transcribe → MIDI** — the `.mid` file appears for download.

The MIDI has detected tempo + time signature burned into the file when
`best-effort` detection succeeds.

## How it's built

- Python 3.11 slim base, ffmpeg + libsndfile + git
- `requirements.txt` installs `muscriptor` from its GitHub repo
- `app.py` is a Gradio Blocks UI that calls
  `TranscriptionModel.load_model(...).transcribe_and_postprocess(...)`
- Model weights cache at `/data/hf` (persistent HF cache volume)

## Caveats

- First request downloads the chosen model's weights — a few hundred MB
  per size. They cache to `/data` across restarts.
- CPU is fine for `small`; `medium`/`large` benefit from a GPU Space.
- Beat/tempo detection is `best-effort` — tracks without a steady pulse
  get a 120 BPM placeholder.

## License

- App: MIT
- [muscriptor](https://github.com/muscriptor/muscriptor): MIT
- [demucs](https://github.com/facebookresearch/demucs): MIT