Skip to main content
R

dsh-pianochart (dsh-bundle)

regrevia/dsh-pianochart/dsh-bundle

Adds piano_score, which takes one audio link and writes a piano score: staff PNGs, numbered notation, MusicXML, MIDI. It transcribes the background music and drops the vocal; drums and non-melodic parts are folded into the left hand. Three tiers share one arrangement and differ only in key signature, so easy has the fewest black keys and playback restores the original pitch. Long audio can be previewed with seconds.

Install

dsh plugin --profile web add github:regrevia/dsh-pianochart

This plugin lives in the dsh-bundle subdirectory of the repository.

README

pianochart

One audio link in, one playable piano score out: five-line staff images, numbered (jianpu) notation, MusicXML and MIDI, in three tiers that share one arrangement.

audio -> source separation (Demucs) -> melody and bass (pYIN, chroma)
      -> arrangement (three tiers) -> staff + numbered notation

First page of a score

What it does and does not do

  • Transcribes the background music only. Vocals are separated out and dropped.
  • A drum kit does not become playable piano. Percussion can only show up as rhythmic weight, not as notes.
  • Non-melodic instruments that carry harmony are folded into the left hand.
  • Three tiers share one arrangement: same rhythm, same density, same register. Only the key signature differs, so easy has the fewest black keys and is the tier to play. Playback restores the original pitch.

Both hands are written to be playable: at most three keys under one hand at a time, never wider than an octave.

Install

The pipeline is Python; the DSH plugin is a thin bundle around it. You need both.

git clone https://github.com/regrevia/dsh-pianochart.git
cd dsh-pianochart

# 1. Python environment
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
brew install cairo            # macOS, for cairosvg

# 2. Separation weights, into models/demucs_repo/ (84 MB, not in the repo)
#    Demucs normally downloads these; offline you fetch them once:
mkdir -p models/demucs_repo
curl -L -o models/demucs_repo/955717e8-8726e21a.th \
  https://huggingface.co/akhaliq/Demucs/resolve/main/955717e8-8726e21a.th
printf "models: ['955717e8']\n" > models/demucs_repo/htdemucs.yaml

models/demucs_repo/ holds exactly two files: the .th state dict and the htdemucs.yaml index. Point the pipeline elsewhere with --demucs-repo.

Run the pipeline directly

PYTHONPATH=src .venv/bin/python -m pianochart.cli \
  --input track.m4a --preset all --out out/track

Options: --seconds N analyse only the first N seconds; --no-separate skip separation for a fast try; --preset easy|medium|hard|all; --transpose N; --fingering key|all|none; --out DIR; --cache-dir DIR; --demucs-repo DIR; --device cpu|mps.

Fingering is key by default: numbers on the few notes where the hand has to be told how to get there (first note, after a rest, a leap, a crossing, a grip change), and nothing else. all numbers every note, for reading a piece one note at a time; none leaves the staff unmarked. The numbers come from a cost model adapted from performer (MIT); they are a suggestion, not a teacher's marking.

Output per tier in out/<name>/: .musicxml, .mid, .jianpu.txt, -p01.png staff pages, -roll.png piano roll, and report.json. The MusicXML and the staff pages carry the finger numbers; report.json records how many were marked.

Use it from DeepSeek Harness

Install the bundle, then call the host tool piano_score:

{ "source": "https://example.com/track.mp3", "tier": "easy" }
  • source is an audio file URL, a local path, or a page URL (the plugin tries to find the audio on it and hands over to Envoy when the page needs a browser).
  • seconds for a preview of long audio; jianpuChars caps the numbered notation returned in chat; transpose shifts the written key; fingering is key (default), all or none.
  • Outputs land in a new directory under out/; the absolute paths come back.

There is also a small local service: PYTHONPATH=src .venv/bin/python -m pianochart.serve --port 8797 answers POST /api/score with {"source", "tier", "fingering", "seconds"}, returns a job id, and reports the artifacts when the job is done. It exists so a web page can hand a link to a runner on this machine.

The same pipeline is also served over MCP as piano_score on stdio, so any MCP client can use it. The bundle starts it from lib/pianochart_mcp.py; point it at your checkout with PIANOCHART_REPO if it is not next to the plugin.

Reading the numbers

report.json carries the arrangement statistics and two similarity figures against the source: chroma_cos_mean (tonal agreement over the track) and chroma_cos_p10 (worst tenth). They measure pitch content, not playability. A short clip scores lower for lack of material.

What is not done

MuseScore or LilyPond PDF rendering, AMT refinement (Transkun, basic-pitch), drum and beat grid refinement, multi-voice left-hand textures.

License

MIT. The Demucs weights are MIT and remain under their own license; they are downloaded, not redistributed here.

Checking the finger numbers

A wrong digit on one note is invisible in a picture, so the check is mechanical: give it a run's pickle and it clears the numbers, re-fingers, and compares the arrangement against the staff file on disk.

PYTHONPATH=src python scripts/verify_fingering.py out/<run>/<stem>-<tier>.arr.pkl --mode key

It exits non-zero when they disagree, so it can gate a release.

Related plugins