reference-dissector

mcp
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Take a reference track apart (tempo grid, tuning, drum hits, sample identification, 808) and rebuild it in Ableton Live through ableton-live-mcp

README.md

reference-dissector

Take a reference track apart and rebuild it in Ableton Live. The pipeline:

  1. finds the tempo grid, the meter and the tuning;
  2. finds every drum hit, layered hits included, and the 808's notes to the cent;
  3. transcribes the melodic layers and the chords;
  4. identifies the exact samples in your library (or the nearest ones), at any pitch;
  5. fits a synthesized 808;
  6. builds the result in Live, with the original stems muted underneath for A/B, through ableton-live-mcp.

Replica mode (12) aims at a 1:1 rebuild of a trap or hip-hop reference, measured against the answer on 48 synthetic beats where every answer is known.

The work started from one question: can an AI that cannot hear tell whether the sound it placed is the sound in the song? It can, if listening is turned into measurements it can read (numbers and pictures) and those measurements are calibrated against cases with a known answer. This repository holds the code, the measurements and what was learned on the way, from a Turkish trap track (Mavi – PIRAMIT) and a set of synthetic beats built for the purpose.

PIRAMIT's hat, snare and 808 against their library matches and the synthesized 808

Results at a glance

PIRAMIT (126 s, Demucs stems), from refdissect analyze, melodic, match, fit-808 and plan with replica mode (the run of 2026-10-29: fit-808 again with the code of 1f5506d, and plan with that of e08d786, which merged the fixes of the first live check; 02 gives the m3 code's plan, the first replica-mode run, of 2026-10-22, and the run before replica mode beside it):

What Found
Tempo grid 137.00 BPM (136.999), 4/4, first bar line 23.4 ms in. beat_this's 144 beats lie on one line at 68.498 BPM, and 100–180 BPM takes the octave above. Every bar's onsets sit within a few ms of the grid (p90 4.7–11.3 ms). At the 136.36 BPM a beat tracker gave, they drift 8 ms a bar: 50 ms off by bar 7, 0.59 s by the end (computed).
Tuning The melodic stems at A440 (other −2, piano +1.5 cents). The 808 alone sits at +11.8 cents: its sample is detuned, not the track. That is its template's settled pitch (32.93 Hz); the +33 cents read before replica mode heard the 808's pitch drop. (An earlier version read +0.28 semitones for everything; that was librosa.estimate_tuning's error, see 01.)
Hi-hat A hat from the local library, at its own pitch. NCC 0.984; it wins 310 of 327 hits; null-test residual −14.9 dB (next best −10.9 dB). The verdict is "same family", not "same sample" as before replica mode: searched at any pitch, another kit's hat 3 semitones up reaches 0.958, and the margin fell from 0.078 to 0.025. The joint fit found 54 of its 389 hits under other sounds, 36 of them under the snares.
Snare (odd bars) A library snare pitched −1 semitone (Transpose −1, Detune 0). NCC 0.923; it wins 28 of 28 hits; residual −8.3 dB (next best −7.1 dB). The same file plays at its own pitch in bars 24–31 (NCC 0.986, 30 of 30 hits, residual −15.7 dB), on a pad of its own. Before replica mode this table had odd and even bars swapped.
Snare (even bars) Not in the library: the best match is NCC 0.47.
808 101 notes, 87 of them on C1. No note is held over silence now: on 2026-10-22 one note was held through sections D and E, over two rests (the 808 band 40 dB under its median note peak) and the notes the 808 plays alone in D. A note now ends where the 808 falls silent, and a 9 dB rise starts one: D has four C1 notes. The stem shows a fifth attack there, which rises only 6.5 dB over the note still ringing and is still kept in it (not checked by ear). A synth voice fitted to the template's 53 notes reaches NCC 0.938 and a 1.3 dB envelope error, against the best of 865 library 808s at 0.894 and 1.4 dB. The library 808 is closer in the upper harmonics: 8.7 dB off, against 12.9 dB for the synth. The fit starts at 120 Hz with a 0.3 ms attack, both on its search's bounds: the shape of a kick's sweep (not checked by ear). The one-shot the plan plays now follows the template's own pitch until its drop settles (269 ms): the C1 notes of 120–250 ms needed a 41-cent Detune correction with the m3 code's one-shot and need −0.1 cents now, and 91 of the 101 notes sound within 20 cents of the analysis as the plan plays them (82 before). Its waveform NCC against the fit's reference fell from 0.921 to 0.880 (not checked by ear).
Sections A 1–24 · B 25–28 · C 29–32 · A 33–47 · D 48–51 · E 52–56 · A 57–71 · D 72–73: D is the 808 alone, E the breakdown, as the stem shows them. On 2026-10-22 the held 808 note merged them into one section, D 49–56.
Live Built and recorded in Live 12.4.6 (2026-10-29, the second live check, as 5 build_tracks calls): its 11 Simplers held the plan's files, its 1,881 notes read back as sent, its 630 drum hits and 101 808 notes played within 0.04 and 0.11 ms of where render.py plays them, and its 8 locators sat where planned. Not checked by ear, and with no truth to score it against; a later plan of the song (565 drum notes, 95 808 notes, from ableton-live-mcp's dissect_reference job) was built in Live 12.4.16 on 2026-11-16 and heard as a whole (02). 630 drum notes on 10 Drum Rack pads, each at its match's Transpose and Detune and at a Volume of its own where the stems hold its sound, −12.1 to 0 dB under a −12.6 dB drum fader (the loudest, a perc, is read mostly on hits it shares with the hat); 98 of them start 1 ms early, where Live starts them 1 ms late. 101 808 notes at Transpose +36 and Detune +1, 62 of them 1 ms early for the same reason; three muted melodic tracks; 4/4; 8 locators. The first live check, on the plan of 1f5506d, stopped at a pad whose one-character file name Live's browser search did not return, and another pad played an FX hit of the same name: each pad's file now loads under a name of its content. The 2026-10-22 plan had 607 notes on 7 pads: a pad now needs 5 hits here, not 12, and a sound of the residual pass must recur bar to bar. That adds a perc, the hat's file found in the snare band and a snare-like sound (7–8 notes each, not checked by ear). Before replica mode, refdissect live-build built the earlier plan (6 pads, 549 drum notes, 126 808 notes, reference stems for A/B, 8 locators) into an empty Live set with one build_tracks call, in 4.9 s on Live 12.4.2 (9.7 s track by track before).

Replica mode, on the calibration-v2 suite (refdissect suite; 03, 12).

  • 48 synthetic beats in 22 scenarios: 72–160 BPM, 3/4 and 6/8, swing, rolls, layered hits, flams, pitched copies, 808 glides, melodic layers, lead-ins.
  • Each is mastered, passed through mp3 and separated by Demucs.
  • Scores are strict: no offset is removed, and a hit counts within 20 ms of where its sound starts.
  • Means over scenarios. The analysis is what the pipeline heard; the plan is what Live will play, rendered offline.
  • "Now" is replica mode with its fixes of 2026-10-29 (tags m5 and m5-ft). m4 is m3 with two of them added, a level per drum pad and an 808 one-shot that follows its template's own pitch; m5 is m4 with the fixes of the first live check: each pad on one voice and the 808's release as Live plays them, the plan's meter, and pads loaded by their content. 12 gives m4, m3 and the merged code before the fixes (m2g) beside it.
before replica mode now (htdemucs, the default) now on htdemucs_ft
drum hits and 808 onsets, F1@20, analysis / plan 0.368 / 0.282 0.888 / 0.876 0.900 / 0.902
drums, F1@20, analysis / plan 0.397 / 0.283 0.883 / 0.868 0.895 / 0.898
kick / snare / hat, F1@20, analysis 0.25 / 0.70 / 0.51 0.88 / 0.96 / 0.86 0.93 / 0.89 / 0.91
open hat, F1@20, analysis / plan 0.33 / 0 0.98 / 0.98 0.99 / 0.99
kick timing, median (p90), analysis +16.6 (20.9) ms +0.1 (5.3) ms −0.5 (3.3) ms
808 notes (50 ms, 50 cents), F1, analysis / plan 0.278 / 0.229 0.936 / 0.934 0.924 / 0.934
808 pitch, median abs error, analysis / plan 55 / 70 cents 6 / 4.4 cents 12 / 9.6 cents
808 written note right not scored 0.970 0.959
beats / downbeats, F, analysis 0.72 / 0.64 0.96 / 0.94 0.96 / 0.94
meter right, analysis / plan 0.91 / 0.91 0.95 / 0.95 0.95 / 0.95
melodic notes, F1; chords, majmin (4 beats) not read 0.63; 0.98 0.64; 0.98
plan levels: median distance from a perfect kit 7.18 dB 1.20 dB 1.15 dB
plan levels: median balance (each sound against the median sound) 4.15 dB 0.51 dB 0.48 dB
  • Drum pads on evidence. A sound gets a pad from 3 hits (one per 16 bars in a longer song), with a clean template and a close library match or a place in the beat's backbone; a sound of the residual pass must also recur bar to bar. The 12-hit gate this replaced left open hats at 0.043 in the plan. False hits fell from 23.0 to 9.6 a beat (10.2 to 3.7 on htdemucs_ft), against the merged code before these fixes (tags m2g-vel and m2g-ft-vel). Each drum note now starts early by its pad sample's own attack.
  • Each drum pad plays at a level of its own (m3 → m4). A pad is read where the stems hold its sound: over 50 ms from each hit's attack, in its role's band, the stems against the pad's own track at 0 dB, the median over its hits. A kick is read on the drum and bass stems together, less the plan's own 808, since Demucs hands part of a kick to the bass stem; every other sound is read on the drum stem. The loudest pad plays at 0 dB and the others under it: −19.7 to 0 dB on the suite.
    • The plan went 4.09 → 1.25 dB from a perfect kit and its balance 3.03 → 0.55 dB (htdemucs_ft 3.70 → 1.23 dB and 2.84 → 0.50 dB). Before the pad gate, at m2g-vel, they were 3.67 and 2.24 dB.
    • With every pad at 0 dB, hats played 6.2 dB and open hats 11.6 dB over a perfect kit; at m4 they sat 1.1 and 0.09 dB under it (at m5 hats 0.90 dB under, open hats 0.15 dB over).
    • Still open: the kick against the snare. At m4 the mean over scenarios of |kick − snare| per beat is 1.45 dB (4.67 at m3; htdemucs_ft 1.16, 2.86 at m3-ft), but it is farther from 0 than at m3 on 2 of 42 beats (6 of 43). On bass_low-2 the kick's hits play the hat's file: the analysis gave its kick sound the hat's file, and its hats (found 29 ms early) a kick file that is neither sound's. On tempo95-2 the kick plays where it did at m3 and the snare 2.2 dB louder. Its kick reads 1.7 dB lower under the new one-shot than under m3's: the kick's Volume fell by that, and the drum fader, matched by RMS, rose by about as much, which lifted the other pads.
  • The 808 one-shot follows the 808 it copies (m3 → m4). It keeps the fitted voice's envelope and drive, but crosses zero where its template does until the template's pitch drop has settled, and it attacks where the template attacks after its onset. The fitted voice alone fell faster than the 808s it copies, so one Detune left the plan's notes off by their length: bass_low-1 played a median 41.7 cents off.
    • The plan's 808 note F1 went 0.921 → 0.934 (htdemucs_ft 0.910 → 0.934), its median error 8.3 → 4.5 cents (13.6 → 9.6), and bass_low-1's note F1 0.72 → 1.00 (0.45 → 0.98).
    • full's fell, 0.890 → 0.851 (0.910 → 0.890). The analysis writes one of its notes a semitone high and hears 5 short notes 41 cents low, and m3's one-shot happened to offset both.
  • Live's measured playback is in the plan (m4 → m5). The first live check found pads that cut their own sounding hit and start the new one 1 ms late, an 808 that ends in a 50 ms release, and a 3/4 beat built in 4/4. render.py and the estimates now play each pad on one voice and the 808's release and restart, notes that Live starts late start 1 ms early, and the plan carries its meter.
    • The plan went 1.25 → 1.20 dB from a perfect kit and its balance 0.55 → 0.51 dB (htdemucs_ft 1.23 → 1.15 and 0.50 → 0.48); its meter is right on 0.955 of the scenarios (0.909), meter34 now in 3/4. Every F1 is the same.
    • Worse: dynamics, 1.27 → 2.16 dB from the kit. With its pads on one voice, dynamics-2's drum track plays 1.3 dB quieter at unity, and its RMS-matched fader rose by as much.
  • htdemucs stays the default. htdemucs_ft's drums are better, but its 808 notes at analysis level (bass_low 0.949 → 0.338) and its snares (0.961 → 0.891) are worse.
  • Velocities follow Live 12.4.6's measured law, with "Vol < Vel" set to 35 % on every Simpler. Built with linear velocities, m2g's plans would have played 9.3 dB from a perfect kit in Live, against 3.7 dB (computed from the law). The law held in Live from velocity 35 to 127.
  • In Live (Live 12.4.6, 2026-10-29, 07). Two checks built plans with the build's calls and recorded them. On four m5 plans Live played every drum hit within 0.04 ms and every 808 note within 0.11 ms of render.py, drum F1@20 per role read off the recordings equals render.py's, and the levels differ only by Simpler's top-end loss, which render.py does not model (hats up to 0.97 dB). Pad Volumes under 0 dB (within a display step of 0.05 dB), Detune, "Vol < Vel" and the one-shot on its template's pitch play as the plan assumes.
  • The 808's slides, on request (--slides; tags g1 and g1-ft, 2026-11-05). The table above is the default, which writes no legato notes and equals m5. With --slides the reader reads a slide from the 808 band's pitch: a hold, a straight move to a whole transposition, a hold, and no restart; a kick under the move, or a template fit without a rise of the band, no longer makes it an attack.
    • Legato notes found, of the truth's: on seed 1, where the thresholds were chosen, 8 of 10 on each model, none wrong, starting a median 3.4 ms from the truth's (htdemucs_ft 4.8); on seed 2, whose slide beats were seen while the rule was designed, 4 of 14 (3 of 14). On held-out glide beats with the suite's kits and new patterns, 7 of 18 on the half with seed 1's kit (8 of 18) and 5 of 22 on the half held out in kit and pattern (6 of 22); with new kits, 14 of 52 (19 of 52).
    • 808 note F1@50 over the 48 beats: 0.9360 → 0.9391 at analysis (htdemucs_ft 0.9245 → 0.9263), 0.9342 → 0.9377 in the plan (0.9345 → 0.9360); glides 0.791 → 0.851 (0.839 → 0.884). Half of each gain is on seed 1 (in-sample): glides-2 alone 0.7037 → 0.7652 (0.8000 → 0.8319). glides-1's and glides-2's plans turn Glide on.
    • It stays off: beats without a slide get false legato notes (bass_low-2, meter68-2, swing66-2 and tempo160-2 on htdemucs; bass_low-2 and swing66-2, three, on htdemucs_ft, whose swing66-2 plan then turns Glide on), and the 808's onset p90 (7.98 → 8.03 ms) and htdemucs_ft's levels (1.1516 → 1.1536 dB from a perfect kit) get slightly worse. PIRAMIT has no slide either way.
    • In Live (2026-11-05), an 8-bar excerpt of glides-1's plan with Glide played its slides within 1.21 cents (p90) of render.py, its 808 31.5 dB of residual under the render. The 808 reader finds 3 of those slides in Live's audio and 1 in render.py's (first reported as none, from a script that read the wrong key).
  • Not verified in Live: locators off Live's grid, which Live moves and the build deletes (live-build zooms in first, through ableton-live-mcp v2.4.1, and a 3/4 blueprint's locators all landed). An htdemucs_ft plan's excerpt, a plan with choke groups and a build that stops half way were checked on 2026-11-18 (07). refdissect live-build itself was checked end to end on 2026-11-14 (Live 12.4.16): an 8-bar excerpt (--bars 1-8) and PIRAMIT's whole plan built through ableton-live-mcp's build_from_blueprint with clean read-backs and recorded equal to the builds of live-build --direct, the build before it, sample for sample (07); --direct was removed on 2026-11-16.
  • The scores: results/calibration/suite-base-htdemucs.json, suite-m5.json and suite-m5-ft.json; the slides on request, suite-g1.json and suite-g1-ft.json; m4, before the fixes of the live check, suite-m4.json and suite-m4-ft.json; m3, before the pad levels and the new one-shot, suite-m3.json and suite-m3-ft.json; the merged code before the fixes of 2026-10-29, suite-m2g-vel.json and suite-m2g-ft-vel.json.

Calibration v1: 6 synthetic beats built from known library samples, mastered loud, passed through mp3 and Demucs.

Sound Identified at known hit times Blind transcription F1 (mean) Identified blind
Snare 6/6 1.00 6/6
Open hat 6/6 0.83 5/5
Hat 5/6 0.77 7/10 templates
Kick 4/6 0.70 5/10 templates
808 6/6 (865 candidates, ±12 semitones) — —

At known hit times, 27 of 30 sounds are found among 8,854 one-shots. Details are in docs/03-calibration.md.

How it works

song.mp3 ──Demucs──▶ stems ──▶ grid + tuning ──▶ drum templates ──▶ hits (joint fit)
                       │                               │
                       │                               └──▶ library match, any pitch ──▶ pads
                       ├──▶ 808 notes (transpositions of its own 808) ──▶ 808 fit (synth) ──┐
                       └──▶ melodic notes and chords                                        │
                                                                                            ▼
          plan.json (notes in beats, pads with Transpose, Detune and Volume, levels, locators) ──▶ Live (ableton-live-mcp)
  • Grid: beat_this's beats and downbeats decide the octave, the first bar line and the meter. A comb search over tempo and phase on the onset envelope, coarse then fine, gives the tempo, and its phase is moved onto the attacks. --bpm-range picks between half and double time.
  • Drums: in each band (low, snare, hat), onsets are moved back to where their sound starts. They are grouped by their place in the beat (straight or swung 16ths, triplets, 32nds), then by waveform: one template per sound. Averaging N hits lowers whatever plays along by about √N.
    • A second pass groups the onsets no template explains: rare sounds, crashes, fills.
    • Each template slides over the whole stem as a matched filter. Every moment is then fit with all the templates near it (non-negative least squares on the kick, snare and hat bands). So a hat under a snare, a flam's grace note, a 64th roll and a hat at another pitch are hits of their own.
  • Identification: normalized cross-correlation (NCC) against every library one-shot, in three bands, over ±30 ms of lag.
    • In the snare and hat bands it works at any pitch, to a quarter cent. A speckle index, the fine structure of a noisy sample's spectrum, proposes the file and its transposition. Kicks keep whole semitones.
    • Identities are handed out from the strongest match down, so a hat that always plays along with a kick is not taken for the kick.
    • A library file that peaks under −60 dBFS is never a match, and a band whose five best sounds tie within 0.002 NCC names none of them: a kick's click in the hat band matched 20 kick, 808 and synth-bass files alike.
    • The verdict uses NCC, the margin over the next different sound and per-hit votes; a null test is reported beside it. A pad plays its match with Simpler's Transpose and Detune.
  • 808: notes are read as transpositions of the song's own 808: a template learnt from its long notes, preferably those that start on kicks. A note's written pitch is its settled pitch less the 808's tuning.
    • A note ends where the 808 falls 40 dB under its peak, and a rise of 9 dB starts a new one. Where the template's own notes are too short to settle, its settled pitch is read on the notes that reach past it.
    • A sine + glide + envelope + tanh-drive voice is fitted to the template's notes by differential evolution. It is scored on waveform, harmonics and envelope, not on correlation alone.
    • The one-shot the plan plays is that voice on the template's own pitch: it crosses zero where the template does until the template's drop has settled, and attacks where the template attacks after its onset.
    • Simpler's Transpose and Detune put the one-shot on the written notes.
  • Melodic layers: Basic Pitch on each tonal stem, moved onto A440 by its tuning. Chords come from its note posteriorgrams, with the 808 as their bass. The plan carries them as muted MIDI tracks.
  • Live: ableton-live-mcp's build_tracks builds the whole set from one spec.
    • A sound gets a Drum Rack pad on evidence: enough hits, a clean template, and a close match or a place in the beat's backbone; a sound of the residual pass must also recur bar to bar. Each note starts early by its pad sample's attack, and a pad plays each strike once.
    • Each pad plays at a Volume of its own, read where the stems hold its sound (a kick on the drum and bass stems, less the plan's 808), the loudest at 0 dB. The drum fader matches the drum stem's RMS, and the 808's puts the 808 where the bass stem holds each note's attack, as the suite scores it. Velocities follow Live's measured law, and the stems are muted for A/B.
    • Each pad's file goes into the User Library under a name of its content, and the build reads back the file each Simpler holds. Snap and the 808's filter are off; the 808 keeps Live's 50 ms release, which render.py plays, as it plays each pad on one voice. The plan's meter becomes Live's time signature.
    • Two live checks recorded built plans: Live played them as render.py does, but for Simpler's top-end loss (07).
  • Measuring: refdissect suite builds synthetic beats with every answer kept, runs the pipeline on them and scores the analysis and the plan against the answer.

Each step is described in docs/01-pipeline.md, replica mode in docs/12-replica-mode.md.

Quick start

Needs Python 3.11+ and uv. Three models run in uv environments of their own, installed on first use: Demucs for separate (a few hundred MB), beat_this for analyze (an 81 MB checkpoint) and Basic Pitch for melodic. For live-build, Ableton Live (12.4 or later, which loads a sample by its path) must be running with ableton-live-mcp's Remote Script.

git clone https://github.com/CanArslanDev/reference-dissector && cd reference-dissector
uv sync                                   # add --extra live for live-build

W=~/refdissect                            # a work folder outside the clone (docs/09)
# your sample library, once; index-library also writes the speckle index (any-pitch matching)
uv run refdissect inventory "/Applications/Ableton Live 12 Suite.app/Contents/App-Resources/Core Library/Samples" \
    "<your User Library folder>" --out "$W/work/inventory.json"
uv run refdissect index-library "$W/work/inventory.json" --out "$W/work/library.npz"
uv run refdissect index-library "$W/work/inventory.json" --808 --out "$W/work/library_808.npz"
uv run refdissect index-speckle "$W/work/library.npz"    # only for a library indexed before the speckle index

# a song
uv run refdissect separate song.mp3 --out "$W/song/stems"
uv run refdissect analyze "$W/song/stems" --work "$W/song/refdissect"    # grid, drums, 808 notes
uv run refdissect melodic "$W/song/refdissect"                           # notes per tonal stem, chords
uv run refdissect match "$W/song/refdissect" --library "$W/work/library.npz"
uv run refdissect fit-808 "$W/song/refdissect" --library-808 "$W/work/library_808.npz"
uv run refdissect plan "$W/song/refdissect"            # plan.json + midi/drums.mid, midi/808.mid
uv run --extra live refdissect live-build "$W/song/refdissect"   # into an empty Live set, by build_from_blueprint
uv run refdissect blueprint "$W/song/refdissect"     # blueprint.json alone, no Live (docs/07)

# comparing and choosing (docs/11)
uv run refdissect separate rebuild.wav --out "$W/song/rebuild_stems"      # the same model as the reference
uv run refdissect compare "$W/song/stems" "$W/song/rebuild_stems" --out "$W/song/compare.json"
uv run refdissect check-rebuild "$W/song/refdissect" --reference song.mp3 --mp3 256   # the plan rendered, mastered
                                    # like the song, separated alike: descriptors before/after, null tests (local)
uv run refdissect listening-round ref.wav cand1.wav cand2.wav --question "Which chords?" --out "$W/song/round1"
uv run refdissect space "$W/song/stems/other.wav" --spans 40-56 100-116
uv run refdissect mix-gains "$W/song/recorded" --targets targets.json
uv run refdissect candidates "$W/song/refdissect" --out "$W/song/sketches" --n 6 --seed 1 --section A
#   new 8-bar beats drawn from the plan's statistics, rendered, compared and put into one listening round

# calibration v1: six synthetic beats from your own library, scored
uv run refdissect calibrate "$W/work/inventory.json" --library "$W/work/library.npz" \
    --library-808 "$W/work/library_808.npz" --beats 6 --out "$W/work/calibration"

# calibration v2 (replica mode): 48 beats with every answer kept, run and scored per tag (docs/03, docs/12)
S="$W/work/calibration-v2"
uv run refdissect suite build "$W/work/inventory.json" --out "$S" --v1-truth "$V1_TRUTH"
uv run refdissect suite run "$S" --library "$W/work/library.npz" --library-808 "$W/work/library_808.npz" \
    --tag mine --jobs 2 --render                           # --model htdemucs_ft, --scenarios a,b, --resume, --cache, --subset dev
uv run refdissect suite run "$S" --library "$W/work/library.npz" --library-808 "$W/work/library_808.npz" \
    --tag mine-b --steps analyze,match,plan,score --reuse mine --jobs 2 --render
uv run refdissect suite report "$S" --tags mine,mine-b --out "$W/work/mine-b.md"

Every step writes JSON next to its inputs, so you can read what it decided before the next step uses it.

  • analyze and fit-808 keep the 808 reader's result and the 808 fit in the work folder's cache/. A later run reads them back where nothing that decides them changed: the stems' or the template's samples, the settings, numpy's, scipy's and soxr's versions, and the .py files of the step as the process loaded them: the module that makes the result and every module of the package it imports (an edit elsewhere, to live.py say, keeps them). The log names each file read back; --no-cache runs them again. suite run keeps nothing unless --cache, so its seconds are the code's.
  • live-build writes the plan as ableton-live-mcp's blueprint v1 (blueprint.json beside it) and calls its build_from_blueprint tool in-process to build it: every file loaded by its path, then read back (files, Volumes, choke groups, locators, time signature, tempo). The [live] extra pins ableton-live-mcp v2.4.2 (the tool since v2.4.0; locators placed on Live's grid since v2.4.1). The build before it, live-build --direct, built sets that played the same audio sample for sample in Live (2026-11-14) and was removed on 2026-11-16; what changed is in 07.
  • blueprint writes the blueprint alone: what live-build has Live build, with the files to copy and their digests, each Simpler's playback mode and the pads' filter off. It needs no Live (07).
  • scripts/export_results.py turns a work folder into the shareable results/ and figures/: no audio, and no file names from a personal library.
  • scripts/export_results.py --suite DIR TAG publishes a suite tag's means per scenario, and nothing else.
  • --v1-truth takes the six v1 beats rebuilt with truth stems. No command here makes them: without them the suite has the 42 scenario beats. 12 has every suite option.

Development

uv sync installs pytest, pytest-xdist and ruff. No test needs your library, Demucs, Live or a model download.

uv run pytest -m "not slow" -n auto     # the fast loop: 306 tests in 22 s at -n 4
uv run pytest -n auto                   # the whole suite, before every commit and in CI: 94 s at -n 4 (307 s in one process)
uv run ruff check .
  • The 48 test functions marked slow (62 test items, with their parameters) took 2 s or more each in one process: 250 of the 308 s of test time. The fast loop leaves them out; the whole suite stays the gate.
  • With -n, an idle worker takes tests from a busy one (--dist worksteal, set in pyproject). At -n 4 that cut the whole suite from 132 s to 94–96 s.
  • On a machine you are working on, -n 4 leaves cores free.
  • Measured on a 10-core Apple M4 (2026-11-04/05): 366 passed, 3 skipped, 2 expected failures (the one-process time with 363, before the library store's 3 tests, which take under 1 s). CI runs -n auto: a job took 3m50s on ubuntu and 4m40s on macOS (PR #2), 4m44s and 7m55s (PR #3), 2m51s and 2m14s, then 6m10s and 7m23s on main after each merge; in one process 7.4 and 12.6 min (PR #1's last run). GitHub's runners vary from run to run.

For pipeline changes, iterate on the suite's dev subset, then measure on every beat:

uv run refdissect suite run "$S" --library "$W/work/library.npz" --library-808 "$W/work/library_808.npz" \
    --tag try --subset dev --cache --jobs 2 --render
uv run refdissect suite report "$S" --tags <the dev subset's base tag>,try
uv run refdissect suite clean "$S" --keep m5,m5-ft          # a dry run; --yes empties the other tags' run folders
uv run --extra live refdissect live-build "$W/song/refdissect" --bars 9-16   # a short live check
  • The dev subset is 11 beats, one of each scenario family (03). At 2 jobs it took 260–268 s once its beats' cache/ held the 808 reader's results and the fits, and 672–681 s to fill it (673 s with no cache). The whole suite takes about 45 minutes a model.
  • Compare a subset run with a run of the same subset. The final numbers stay on all 48 beats of both models.
  • suite clean keeps every tag's scores.json, so a cleaned tag can still be compared beat by beat.
  • live-build --bars A-B builds bars A to B of a plan from 0, with the stems cut alike (07): build_from_blueprint cuts them into excerpt-A-B/, named by their content. Checked in Live on 2026-11-14 (bars 1-8 of a suite plan, 07).
  • The library's arrays are memory-mapped, so the jobs of a run share one copy. At 2 jobs each job's peak physical footprint fell from 1.7–1.8 GB to 1.0 GB, at the same wall time (12).
  • None of this changes an output: on the dev subset's 11 beats, every output file of a fresh run at this code but log.txt equals m5's and m5-ft's, seconds and run records aside.

Documentation

01 – Pipeline Every step, its parameters and why they are what they are
02 – Case study: PIRAMIT Everything measured on the track, including what is still wrong
03 – Calibration Synthetic beats with a known answer: v1's six beats, and the 48-beat calibration-v2 suite with its strict scores
04 – Identifying samples What "the same sound" means, and how NCC, margin, votes and null tests decide it
05 – Synthesizing the 808 The voice model, the fit, and why one similarity number is not enough
06 – Listening for a model How a model that cannot hear compares sounds: numbers, pictures, calibrated verdicts
07 – Building in Live The plan, the ableton-live-mcp tools used, and Live behaviour measured on the way
08 – Pitfalls Every mistake made here and how it showed up
09 – Data and copyright What is published, what stays local, and why
10 – Roadmap What replica mode finished, the targets and their gaps, and what comes next
11 – A new beat in a song's style Two rejected beats: the groove, effect and same-pipeline checks they led to, what each step cost, and 8-bar sketches drawn from a plan (candidates)
12 – Replica mode Rebuilding a reference 1:1: running it, the stages and their files, what each measured, and what is not verified in Live
13 – A song like this one Where the melodic layer's sound and notes come from on each path, sounds ranked against a layer (CLAP, descriptors, a fitted voice, the stock sounds), what the ear said (single layers first, then their notes), and the proposed order of work

Türkçe özet: README.tr.md

Layout

src/refdissect/
  audio.py       read, bands, transposition (as Simpler does it), attack times, onset trimming
  xcorr.py       normalized cross-correlation and the matched filter (lag convention tested)
  hits.py        onsets, where sounds start, grouping hits by waveform, averaging into templates
  grid.py        tempo/phase fit, octave, bar line, meter, swing, tempo map, per-beat offsets, tuning
  beats.py       beat_this's beats and downbeats, in its own uv environment
  detect.py      template discovery on the attacks, one template per sound, each hit counted once
  layers.py      every drum moment fit with every template: layers, flams, rolls, pitched copies
  bass808.py     the 808's notes as transpositions of its own template, to the cent
  library.py     inventory, index, speckle index, matching (NCC at any pitch), votes, null test, verdicts
  describe.py    producer-facing descriptors: pitch/cents, glide, decay, harmonics, brightness
  synth808.py    the 808 voice, its fit, one-shots on the template's own periods
  melodic.py     notes per tonal stem, loop voting, chords
  basicpitch.py  Basic Pitch in its own uv environment; posteriorgram frames by time
  structure.py   per-bar activity and sections
  groove.py      ducking under the kick, drum-role balance, one-shots cut by their notes
  space.py       width per octave, reverb tails, the band-pass between two sections
  rhythm.py      a layer's rhythm from onsets (48 points per bar)
  loudness.py    BS.1770 integrated loudness
  listening.py   A/B files: reference, beep, candidate at equal loudness
  mixsim.py      gains decided on recorded stems instead of re-recording
  symmetric.py   a rebuild and its reference measured the same way, against the reference's own spread
  mastering.py   a rebuild mastered like its reference: loudness, spectral tilt, a limiter at its peak, mp3
  rebuildcheck.py  check-rebuild: a plan rendered, mastered, separated alike; null tests per stem and per sound
  rounds.py      listening rounds: numbered reference-beep-candidate files and a manifest
  live.py        plan (pads with Transpose, Detune and a Volume each; the 808 with Detune and Glide), MIDI files, the build
  render.py      a plan played offline, as the plan-level scores assume Live plays it
  separate.py    Demucs in its own uv environment, seeded
  scenarios.py   calibration v2: 21 scenarios rendered with their truth (events.json)
  voices.py      the scenarios' melodic parts, every note known
  suite.py       calibration v2 end to end: build, run per tag (--steps, --reuse), report
  evaluate.py    strict scores of an analysis or a plan against a truth (schema refdissect.events/1)
  calibrate.py   calibration v1: synthetic beats and their scoring
  figures.py     spectrograms side by side, the calibration plot
  pipeline.py    the steps, each writing JSON
  cache.py       the 808 reader's results and the 808 fits kept on disk, keyed on their inputs and their step's code
  served.py      beat_this's and Basic Pitch's workers kept running between a suite job's beats
  cli.py         refdissect
  workers/       the Demucs, beat_this and Basic Pitch workers
results/         measured numbers (calibration v1, the suite's means per scenario, PIRAMIT) - no audio
figures/         spectrograms and the calibration plot
scripts/         export_results.py
tests/           synthetic drums, 808 lines and short scenario beats: lag convention, grouping, layers, the
                 808 reader, matching, grid, scoring, plan, suite, caches

Status

This is a working pipeline with measured limits, not a finished product:

  • Measured on synthetic beats. On the calibration-v2 suite, drum hits and 808 onsets score F1@20 0.888 in the analysis and 0.876 in the plan. A song has no truth to score against.
  • The levels are read on the stems. Each pad's Volume comes from the separated stems. On the suite the plan sat 1.20 dB from a perfect kit at m5, and 1.10 dB with the 808's fader matched per note, as its level is scored (since 2026-11-18; 1.25 at m4; 4.09 dB at m3, with every pad at 0 dB), but at m4 the kick against the snare was further off than at m3 on 2 of 42 beats, and one voice per pad took dynamics 1.27 → 2.16 dB. A song has no truth to check its levels against.
  • One Detune for every 808 note. The one-shot now follows its template's pitch, and bass_low-1's plan notes are right (F1 0.72 → 1.00). A note the analysis hears off the line's tuning is still played at that tuning: full's plan 808 notes fell 0.890 → 0.851.
  • The build in Live is checked, not finished. Built and recorded on 2026-10-29 (Live 12.4.6): on four m5 plans and PIRAMIT's every Simpler held its plan's file, and Live played the drum hits within 0.04 ms and the 808 notes within 0.11 ms of render.py. The levels differ only by Simpler's top-end loss (hats up to 0.97 dB). render.py models it since 2026-11-16, behind plan --live-sr 48000, off by default: on the suite it makes the balance within each stem group worse on both models, a median over the 48 beats of 0.190 → 0.240 dB (htdemucs_ft 0.195 → 0.245; 07; the cause, the suite's master clipper: 12). refdissect live-build itself ran end to end on 2026-11-14 (Live 12.4.16), through build_from_blueprint, PIRAMIT's whole plan in one build_tracks call, and recorded equal to the build before it (live-build --direct, removed on 2026-11-16). On 2026-11-18 a whole plan with Glide was built and recorded (one voice takes over a release under Glide, as render.py now plays it), and so were an htdemucs_ft plan's excerpt, a plan with choke groups and a plan moved onto Live's bars (07). Not verified: locators off Live's Arrangement grid, which Live moves and the build deletes, on plans left at the song's seconds.
  • A rebuild can be checked like the song, offline (check-rebuild, 11). The plan is rendered, mastered like the song (loudness, tilt, peak) and separated by the same Demucs. On 11 suite beats its per-sound null tests rank sounds as the suite's F1@20 does (Spearman −0.90 on htdemucs, −0.86 on htdemucs_ft), on magnitudes; the waveform null does not, since a hat 0.2 ms off nulls at 0 dB. Separated against separated, which is all a song allows, the drums' null hardly ranks beats as their drum F1 does (−0.06, −0.30).
  • Melodies are transcribed but not played. They go to muted placeholder tracks, and the original melodic stems play under the rebuilt beat.
  • The 808's slides are off by default. The reader writes no legato notes unless asked (--slides). Asked, it finds 8 of seed 1's 10 slides (in-sample) but 4 of seed 2's 14 and 5 of 22 on held-out beats of a new kit and pattern (htdemucs), and beats without a slide get false legato notes (4 notes on each model). The rule before it, which called every unattacked pitch move a slide, was right 6 times in 79.

See the roadmap.

License

MIT for the code (see LICENSE). The songs, their stems and any samples are not part of this repository and keep their own rights: see docs/09-data-and-copyright.md.

Reviews (0)

No results found