musiccleaner

A small Python toolkit for cleaning up AI-generated music audio so it transcribes to MIDI cleanly. Bundles a humanizer pass for waveform timing, a piano-transcription wrapper, and a FastAPI server if you want to call it over HTTP.

Status: v0.0.2. Built for personal use, packaged so others can try it.

What it does

Generative music tools (Suno, Udio, etc.) produce audio that sounds good but resists clean MIDI extraction. The notes are slightly too rigid, the timing too quantised, and any naive transcription run produces choppy MIDI that doesn't replay well. This tool:

1. Humanizes the waveform with small, controlled timing and amplitude jitter so a transcriber treats it as a real performance.
2. Runs piano transcription via piano_transcription_inference.
3. Post-processes the MIDI (legato fix, velocity clamp, duration smoothing) before writing it out.

Optional FastAPI server lets you POST a WAV and get a MIDI back.

Install

pip install musiccleaner
# or with the optional transcribe + server extras:
pip install 'musiccleaner[transcribe,server]'

Use

The CLI uses subcommands — there's no single "clean + transcribe" command, so the typical flow is two steps:

# 1. Humanize a WAV (produces a humanized WAV):
musiccleaner humanize input.wav -o humanized.wav

# 2. Transcribe the humanized WAV to MIDI:
musiccleaner transcribe humanized.wav --output output.mid

# Other subcommands: spectrogram | compare | velocity-rescale
musiccleaner --help

# Or run the HTTP server (handles both steps in one job — see below):
musiccleaner-server  # binds 127.0.0.1:8000

The server runs jobs in the background. POST the audio, then poll for the result:

# Submit a job (returns {"job_id": "..."}):
curl -F 'file=@input.wav' http://127.0.0.1:8000/process

# Poll status:
curl http://127.0.0.1:8000/jobs/<job_id>

# When status is "done", fetch artifacts:
curl http://127.0.0.1:8000/jobs/<job_id>/wav  -o output.wav
curl http://127.0.0.1:8000/jobs/<job_id>/midi -o output.mid

Dependencies

Base: numpy, scipy, soundfile, matplotlib, mido. Transcription extra: piano_transcription_inference (pulls torch). Server extra: FastAPI + uvicorn.

Layout

src/musiccleaner/
  cli.py            CLI entry
  pipeline.py       end-to-end pipeline orchestration
  transcribe.py     piano_transcription wrapper
  midi_post.py      post-processing on the produced MIDI
  server.py         FastAPI server
  stages/           individual humanizer stages
  eval/             evaluation scripts
tests/              pytest tests

Status and scope

Personal project. Tested on solo piano. Not validated for orchestral or vocal audio. PRs welcome if you find it useful.

License

MIT.