transcribe_stem
Destructive
Transcribe a single-instrument stem into clean notes, removing harmonics and noise, with options for sustained and monophonic parts.
Instructions
Turn a recording of one instrument into notes, cleaned of what it is not.
Returns:
Dictionary with how many notes were heard and how many survived cleaning, the
pitch range, the span in beats, a sample of the notes, and the write result
where one was asked for.
Note:
**This transcribes pitch, and percussion has no pitch.** A drum kit returns cymbal
and shell resonances, reporting success: measured on a four minute drum stem, 39
notes for 488 beats, none of them a kick, and nothing across forty bars of steady
playing. Never write drums from here. Held material fails the other way: a wavering
sustained note reads as several, so a pad arrives at the right pitches with a rhythm
nobody played. Measured 2026-09-19 over four stems in their busiest 20 seconds,
written attacks ran 3.35 a second against 2.85 onsets on bass, 3.50 against 1.30 on
a strummed guitar, and 5.35 and 5.30 against 0.10 and 0.55 on pad and keys.
``transcription_suspect`` flags that disagreement, ``kind`` says which way, and
``transcription_checked`` says whether the comparison ran at all, since it needs a
macOS-only second decode: elsewhere no warning means nothing. Measured 2026-09-19
against exported MIDI for five pitched stems, pitch content agreed 93.7 to 96.2
percent: which notes, not when, the export's own timing having drifted. Harmonics
are removed where a lower, louder note at the same time explains them;
``monophonic`` then leaves nothing sounding at the same time as anything else.
``scripts/eval_transcription.py`` recomputes these.
Writing needs a clip: ``create_clip`` on the target slot first, long enough for the
whole part, then this with ``confirm=True``. ``span_beats`` runs from beat 0 to the
last note's end, so a clip of that length rounded up to a bar holds it. Writing
replaces every note in the clip, with no undo here and no rollback in the LOM: a
write that fails after the removal leaves nothing.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the audio to transcribe. A separated stem, one instrument at a time. A whole mix transcribes as one tangle. | |
| slot | No | Session clip slot on that track. | |
| tempo | Yes | Beats per minute, to turn seconds into clip beats. Read the set's own tempo unless the recording has a different one. A recording whose tempo drifts will separate from one number over the length of a song. | |
| track | No | Track to write the notes into. -1 returns them instead of writing, which is the default and is how to look before committing. | |
| confirm | No | True writes into the clip, replacing every note already in it. False reports what would be written and changes nothing. | |
| preview | No | How many notes to include in the answer. | |
| sustained | No | True for material that holds its notes rather than striking them: a pad, a string section, an organ. It joins same-pitch fragments separated by a gap too small to play, which is how one held chord stops arriving as eight notes. Off by default because on struck material it costs agreement on pitch content, between one and ten points measured over five stems, and it does not repair a pad: it took one from 5.35 written attacks a second to 2.25, where the recording started 0.10. See transcription_suspect. | |
| monophonic | No | True for a part played one note at a time, such as a bass or a sung line. It reduces the result to the lowest note sounding, which is how a bass loses the harmonics a transcriber hears above it, and which throws away the upper voices of anything that plays chords. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||