danceflow-stemlab 1.2.0__tar.gz → 1.3.0__tar.gz

{danceflow_stemlab-1.2.0 → danceflow_stemlab-1.3.0}/MANIFEST.in

@@ -13,3 +13,8 @@ include .github/workflows/release.yml
 include scripts/check_codex_timeline.py
 include scripts/loop_demo.py
 include scripts/capture_loop_workflow.py
+include docs/midi.md
+include scripts/smoke_midi.py
+include docs/cue-alignment.md
+include docs/evidence-models.md
+include scripts/benchmark_evidence_corpus.py

{danceflow_stemlab-1.2.0/src/danceflow_stemlab.egg-info → danceflow_stemlab-1.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: danceflow-stemlab
-Version: 1.2.0
-Summary: StemLab audio timing analysis and loopable sections for creating Shorts videos; DanceFlow and WordPress DanceMoves
+Version: 1.3.0
+Summary: Local, evidence-led music analysis for stems, timing, structure, harmony, lyrics, and loopable sections for Shorts
 Author: Kieran Simkin
 Maintainer: Kieran Simkin
 License-Expression: MIT
@@ -49,6 +49,8 @@ Provides-Extra: speech
 Requires-Dist: faster-whisper; extra == "speech"
 Provides-Extra: beats
 Requires-Dist: beat-this>=1.1.0; extra == "beats"
+Requires-Dist: madmom-prebuilt==0.17.post1; python_version >= "3.11" and extra == "beats"
+Requires-Dist: mido>=1.2.6; extra == "beats"
 Provides-Extra: deep
 Requires-Dist: sentence-transformers<7,>=6.1; extra == "deep"
 Requires-Dist: all-in-one-infer>=3.1; extra == "deep"
@@ -56,6 +58,40 @@ Provides-Extra: semantic-nc
 Requires-Dist: muq; extra == "semantic-nc"
 Provides-Extra: amt
 Requires-Dist: basic-pitch<0.5,>=0.4; python_version < "3.12" and extra == "amt"
+Provides-Extra: midi
+Requires-Dist: pretty-midi<0.3,>=0.2.10; extra == "midi"
+Requires-Dist: mido<2,>=1.3; extra == "midi"
+Requires-Dist: psutil>=5.9; extra == "midi"
+Provides-Extra: midi-piano
+Requires-Dist: pretty-midi<0.3,>=0.2.10; extra == "midi-piano"
+Requires-Dist: mido<2,>=1.3; extra == "midi-piano"
+Requires-Dist: psutil>=5.9; extra == "midi-piano"
+Requires-Dist: piano-transcription-inference==0.0.6; extra == "midi-piano"
+Provides-Extra: midi-transkun
+Requires-Dist: pretty-midi<0.3,>=0.2.10; extra == "midi-transkun"
+Requires-Dist: mido<2,>=1.3; extra == "midi-transkun"
+Requires-Dist: psutil>=5.9; extra == "midi-transkun"
+Requires-Dist: transkun==2.0.1; extra == "midi-transkun"
+Requires-Dist: setuptools<81; extra == "midi-transkun"
+Provides-Extra: midi-mt3
+Requires-Dist: pretty-midi<0.3,>=0.2.10; extra == "midi-mt3"
+Requires-Dist: mido<2,>=1.3; extra == "midi-mt3"
+Requires-Dist: psutil>=5.9; extra == "midi-mt3"
+Requires-Dist: mt3-infer[torch]==0.2.0; extra == "midi-mt3"
+Provides-Extra: evidence
+Requires-Dist: psutil>=5.9; extra == "evidence"
+Provides-Extra: evidence-vocals
+Requires-Dist: psutil>=5.9; extra == "evidence-vocals"
+Requires-Dist: fireredvad<0.1,>=0.0.2; extra == "evidence-vocals"
+Provides-Extra: evidence-pitch
+Requires-Dist: psutil>=5.9; extra == "evidence-pitch"
+Requires-Dist: swift-f0[audio]<0.4,>=0.3; extra == "evidence-pitch"
+Provides-Extra: evidence-align
+Requires-Dist: psutil>=5.9; extra == "evidence-align"
+Requires-Dist: qwen-asr; extra == "evidence-align"
+Provides-Extra: evidence-chords
+Requires-Dist: psutil>=5.9; extra == "evidence-chords"
+Requires-Dist: lv-chordia; extra == "evidence-chords"
 Provides-Extra: server
 Requires-Dist: fastapi<1,>=0.115; extra == "server"
 Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "server"
@@ -77,6 +113,8 @@ Requires-Dist: openunmix>=1.3.0; extra == "all"
 Requires-Dist: bs-roformer-infer>=0.1.5; extra == "all"
 Requires-Dist: faster-whisper; extra == "all"
 Requires-Dist: beat-this>=1.1.0; extra == "all"
+Requires-Dist: madmom-prebuilt==0.17.post1; python_version >= "3.11" and extra == "all"
+Requires-Dist: mido>=1.2.6; extra == "all"
 Requires-Dist: sentence-transformers<7,>=6.1; extra == "all"
 Requires-Dist: all-in-one-infer>=3.1; extra == "all"
 Requires-Dist: fastapi<1,>=0.115; extra == "all"
@@ -92,7 +130,11 @@ Dynamic: license-file
 
 > **Packaging identity:** the canonical project name is **StemLab**. StemLab is part of the **Dance Flow** project. The PyPI distribution is named `danceflow-stemlab` solely because Python package-registry names are globally unique. The Python import, CLI, GitHub repository and container image remain `stemlab`.
 
-StemLab provides **audio timing analysis and finds loopable sections for creating Shorts and other short-form videos**. It is the audio-analysis engine in Kieran Simkin's **DanceFlow** BPM and motion-response workflow. It separates and interprets a master track into synchronised stem, BPM/beat, structure, harmony, timbre, speech/lyric and semantic data. Those outputs can drive downstream motion-aware experiences, including the WordPress **DanceMoves** plugin, while StemLab remains usable as a standalone CLI, Python library, web service and container.
+## Synopsis
+
+**StemLab is a local, evidence-led music analysis toolkit that turns a master recording into inspectable stems, timing, structure, harmony, lyric and sonic evidence, then finds complete-bar loopable sections for Shorts and other short-form videos.**
+
+It combines independent separation and music-information-retrieval routes rather than treating any single model as the answer. Results remain traceable through source hashes, manifests, JSON/TSV/NPZ artefacts, portable Sonic Visualiser sessions and a shared React timeline for playback and comparison. StemLab can run as a CLI, Python library, web service, container or local Codex MCP plugin. It is the music-understanding layer of Kieran Simkin's **DanceFlow** workflow and can supply downstream motion systems such as the WordPress **DanceMoves** plugin, while remaining useful on its own.
 
 > **Model weights are not redistributed by this project.** They are fetched from their upstream registries/releases on first use. This avoids silently republishing checkpoints whose licensing may differ from the source code license, and lets upstream integrity metadata be used where available.
 
@@ -134,13 +176,19 @@ Relevant upstreams:
 
 For every successful separator, **every WAV it emits** is retained. Stem names are discovered from files rather than truncated to a hard-coded four-stem schema, which is important for MVSep Mega 53. For the master and every stem, StemLab writes both a PNG spectrogram and compressed `.npz` spectrogram data (time axis, frequency axis, dB matrix, FFT metadata).
 
+Full-resolution spectrogram evidence stays in the `.npz`; the PNG renderer is bounded to 8,192 time frames so long tracks cannot expand into multi-gigabyte Matplotlib RGBA buffers. If an older run retained the NPZ but failed while drawing the PNG, repair it in place without rerunning models:
+
+```powershell
+stemlab repair-spectrograms "path\to\analysis-results"
+```
+
 The preferred vocal stem is passed through the Silero VAD implementation bundled with `faster-whisper`. Speech regions are used to create a timeline-preserving `spoken_word.wav` (non-speech is zeroed rather than concatenated), then Whisper is run with word timestamps. Outputs include `whisper.json`, `speech_regions.json`, `transcript.txt`, `transcript.srt`, and `words.tsv`.
 
 Whisper runs in repetition-safe mode by default (`condition_on_previous_text=False`) to prevent a repeated syllable in one window contaminating later windows. `whisper.json` records that setting and includes repeated-token diagnostics. Use `--whisper-condition-on-previous-text` only for an explicit comparison run; a flagged transcript remains evidence requiring section-wise recovery or listening QA, not a trustworthy lyric source.
 
 Beat analysis runs:
 
-- **BeatNet** in offline/DBN mode when a compatible legacy environment is separately provisioned; it is not included in the current installable extras because its pinned NumPy/Numba requirements conflict with StemLab's core.
+- **BeatNet** in offline/DBN mode through StemLab's checksum-verified runtime bootstrap. StemLab uses the maintained `madmom-prebuilt` wheel and bypasses only BeatNet 1.1.3's obsolete NumPy/Numba package metadata.
 - **Beat This!** using the `final0` checkpoint and its minimal postprocessor.
 - **Beat Transformer**, using the original released model code/checkpoints. The model was trained on five demixed mel streams, so StemLab maps BS-RoFormer-SW to vocals, drums, bass, piano, and `other + guitar`, makes 128-bin mel-power spectrograms at the original 44.1 kHz / 4096 FFT / 1024-hop settings, and averages all eight released fold checkpoints by default. It uses the original madmom DBN decoder if madmom is importable, otherwise a documented SciPy peak-picking fallback.
 
@@ -305,9 +353,128 @@ sample indexing, thresholds, limitations and reproducible screenshot examples.
 
 ![Loop selection and playback in the existing analysis frontend](docs/screenshots/loops-playing.png)
 
+## Audio-to-MIDI model comparison
+
+MIDI extraction is an **optional, independent model pass**. It adds Transkun V2
+and high-resolution note/pedal piano transcription, plus MR-MT3 and YourMT3
+multi-instrument transcription, alongside Spotify Basic Pitch. Automatic source
+selection uses piano/keyboard stems for the piano specialists, pitched stems for
+Basic Pitch and the mix for MT3-family models. Missing stems are reported, never
+silently substituted. The legacy `--basic-pitch` command remains supported.
+
+```bash
+# Install the chosen runtime; the standard profiles do not install MIDI models.
+python -m pip install -e ".[midi-transkun]"
+stemlab midi-models
+
+# Use an existing separated piano, without rerunning any earlier analysis.
+stemlab midi analysis-master --model transkun
+
+# Or transcribe a directly supplied piano recording to a new folder.
+stemlab midi piano.wav -o midi-piano --model transkun
+
+# Full mix comparison requires the separately installed midi-mt3 extra.
+# Both requested checkpoints need explicit first-use download consent.
+stemlab midi mix.wav -o midi-comparison --model mr_mt3 --model yourmt3 --allow-model-downloads
+```
+
+Each model/source gets its original `.mid`, tempo-aware `notes.json` and
+`notes.csv`, an optional real note `piano-roll.png`, source/checkpoint hashes,
+package versions and a worker log. Native MIDI controllers, pitch bends, tempo
+changes and drums are preserved. Note sample numbers are original-rate
+**estimates**, not a claim that the transcription is sample-accurate ground truth.
+The MIDI clock is not used to overwrite StemLab's measured beat grid.
+
+New analyses can opt in with repeated `--midi-model` switches and
+`--midi-allow-downloads`. Existing Codex installations gain a workspace-scoped
+`stemlab_start_midi_scan` job tool after updating the Python installation and
+restarting the session. Models remain optional and no Python dependencies are
+automatically installed. Incompatible research runtimes can use separate
+`--backend-python MODEL=PATH` interpreters.
+
+See [the MIDI guide](docs/midi.md) for all models, installation choices, checkpoint
+and licensing caveats, saved-stem targeting, Codex usage, exact output semantics,
+real-inference smoke commands and test limitations. The React timeline remains
+the analysis inspector; this patch adds no MIDI synthesizer or new interactive
+piano-roll lane. Static note plots are not frontend screenshots.
+
+## Align timed musical cues to detected beats
+
+Use saved analysis to snap an LRC cue file without rerunning models or editing audio:
+
+```bash
+stemlab snap-cues analysis-master "musical cues.lrc" -o cue-review
+stemlab snap-cues analysis-master "musical cues.lrc" -o cue-review-100ms --tolerance-ms 100
+stemlab generate-cues analysis-master -o generated-cues --title "Song title"
+```
+
+Only timestamps change: bracketed labels such as `[DROP: CHORUS 1]`, metadata,
+encoding and line layout are preserved. A cue with **no detected beat within
+±150 ms** is highlighted as **REVIEW**, with its nearest-beat gap, and kept unchanged
+by default. `--force-snap` moves distant cues too but retains their warnings.
+`--downbeats` restricts targets to reported bar starts; `--beat-model` selects a
+specific detector. No constant-tempo beats are invented to fill detection gaps.
+
+Each new output folder contains the rewritten `.beat-snapped.lrc`, `report.json`,
+a colour-coded `review.html`, and `review.txt`. Exact mode preserves the stored
+beat timestamp; explicit millisecond/centisecond compatibility modes report
+rounding. Source-rate sample-frame estimates are included when the rate is known.
+Use `--fail-on-review` to write results and exit 2 when review is needed.
+Generated section-cue files use a title-specific, WordPress-safe filename so
+multiple releases can be uploaded and mapped without ambiguous duplicate names.
+For the retained 3 October 2026 future-release batch,
+`scripts/run-upcoming-full-cues.ps1` resumes full analyses without overwriting an
+incomplete directory, and `scripts/summarize-upcoming-cues.ps1` reads each closed
+manifest/report to produce one reproducible hash, cue-action and error-count row
+per release. The summary script refuses missing or ambiguous generated LRCs.
+
+For a new analysis, add `--snap-cues "musical cues.lrc"` and optionally
+`--cue-tolerance-ms 100`. Cue alignment uses that run's detected events and appears
+in `analysis.json`. See [the cue alignment guide](docs/cue-alignment.md) for exact
+precision, offsets, all switches, safety rules and interpretation of warnings.
+
+## Complementary evidence models
+
+StemLab now has an optional **evidence-model layer** for models that add a different
+kind of musical evidence instead of duplicating the normal separation or MIDI
+backends. Nothing in this layer is enabled by a normal profile.
+
+```bash
+stemlab evidence-models
+
+# Singing/speech/music activity + continuous pitch on saved vocals.
+stemlab evidence analysis-master -o evidence-vocals \
+  --model firered_aed --model swift_f0 \
+  --model-path firered_aed=/models/FireRedVAD/AED
+
+# Align approved lyrics without replacing them.
+stemlab evidence analysis-master -o evidence-align \
+  --model qwen_forced_aligner --canonical-text lyrics.txt --allow-model-downloads
+
+# Independent harmony evidence.
+stemlab evidence analysis-master -o evidence-chords --model lv_chordia
+```
+
+The built-in registry covers **FireRed AED**, **HeartTranscriptor**, **Qwen3
+ForcedAligner**, **SwiftF0**, **SongFormer**, **lv-chordia** and **ADTOF PyTorch**.
+It also exposes explicit external-runtime bridges for **GAME**, **SheetSage2**,
+**MOSS-Music** and **AudioSep** so large or restricted research dependencies never
+get silently bundled into StemLab. Outputs stay independent: singing activity,
+forced alignment, pitch, structure, chords and drum hits are review evidence, not
+a hidden combined ground-truth score.
+
+Saved analyses automatically route vocal models to a preferred full vocal stem,
+drum transcription to a drum stem, continuous pitch to pitched stems, and
+structure/harmony models to the master. Missing specialist stems are reported.
+Use `--backend-python MODEL=/path/to/python` for conflicting research environments.
+
+See [the evidence-model guide](docs/evidence-models.md) for model terms, routing,
+external bridges and interpretation rules. `scripts/benchmark_evidence_corpus.py`
+probes an authorised evaluation collection without copying audio into the repo.
+
 ## Install
 
-Python 3.10 or 3.11 is recommended for the broad optional-model ecosystem. The `beats` and `all` extras install Beat This! but not BeatNet: BeatNet's current published NumPy/Numba pins conflict with StemLab's core Librosa requirement. The BeatNet adapter is retained for separately provisioned compatible legacy setups; a missing BeatNet result must not be mistaken for a successful detector run.
+Python 3.11 is recommended for the broad optional-model ecosystem. The `beats` and `all` extras install Beat This! plus the compatible `madmom-prebuilt` decoder. BeatNet 1.1.3 itself still publishes obsolete NumPy/Numba dependency pins, so StemLab downloads its official pure-Python wheel separately, verifies the published SHA-256, and exposes only the BeatNet code and bundled model weights from its cache. This route is supported on Python 3.11-3.13; a missing BeatNet result must not be mistaken for a successful detector run.
 
 From PyPI, install the released StemLab distribution with:
 
@@ -330,6 +497,18 @@ SCNet and Beat Transformer are research repositories rather than stable pip infe
 stemlab bootstrap all
 ```
 
+For BeatNet alone:
+
+```bash
+pip install "danceflow-stemlab[beats]"
+stemlab bootstrap beatnet
+stemlab doctor
+```
+
+`stemlab doctor` reports BeatNet as ready only when the normal package or the
+verified StemLab cache can actually be found. `analyze --no-bootstrap` never
+downloads BeatNet and records the unavailable backend instead.
+
 For only the Vamp analysis stack:
 
 ```bash
@@ -439,6 +618,7 @@ endpoints, events and the Arcadians reference workflow.
 - [Web service](docs/web.md)
 - [Containers](docs/containers.md)
 - [Publishing and releases](docs/publishing.md)
+- [BeatNet compatibility](docs/beatnet.md)
 - [Changelog](CHANGELOG.md)
 
 ## Codex plugin and MCP server

danceflow_stemlab-1.2.0/PKG-INFO → danceflow_stemlab-1.3.0/README.md

@@ -1,89 +1,3 @@
-Metadata-Version: 2.4
-Name: danceflow-stemlab
-Version: 1.2.0
-Summary: StemLab audio timing analysis and loopable sections for creating Shorts videos; DanceFlow and WordPress DanceMoves
-Author: Kieran Simkin
-Maintainer: Kieran Simkin
-License-Expression: MIT
-Project-URL: Homepage, https://kieransimkin.co.uk/
-Project-URL: My Songs portfolio, https://kieransimkin.co.uk/my-songs/
-Project-URL: Arcadians showcase, https://kieransimkin.co.uk/arcadians/
-Project-URL: Repository, https://github.com/kieransimkin/stemlab
-Project-URL: Issues, https://github.com/kieransimkin/stemlab/issues
-Project-URL: Documentation, https://github.com/kieransimkin/stemlab/tree/main/docs
-Project-URL: Changelog, https://github.com/kieransimkin/stemlab/blob/main/CHANGELOG.md
-Project-URL: About Kieran, https://kieransimkin.co.uk/about-me/
-Project-URL: Contact, https://kieransimkin.co.uk/contact/
-Keywords: music,audio,MIR,source separation,BPM,rhythm,harmony,DanceFlow,DanceMoves,motion response,WordPress
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy
-Requires-Dist: scipy
-Requires-Dist: torch>=2.4
-Requires-Dist: torchaudio>=2.4
-Requires-Dist: soundfile>=0.12
-Requires-Dist: matplotlib
-Requires-Dist: typer>=0.12
-Requires-Dist: rich>=13.7
-Requires-Dist: platformdirs>=4.2
-Requires-Dist: librosa>=0.11
-Requires-Dist: pyloudnorm>=0.2
-Requires-Dist: cmudict>=1.1.3
-Provides-Extra: codex
-Requires-Dist: mcp<3,>=2.2; extra == "codex"
-Requires-Dist: fastapi<1,>=0.115; extra == "codex"
-Requires-Dist: uvicorn<1,>=0.34; extra == "codex"
-Provides-Extra: separation
-Requires-Dist: demucs>=4.0.1; extra == "separation"
-Requires-Dist: openunmix>=1.3.0; extra == "separation"
-Requires-Dist: bs-roformer-infer>=0.1.5; extra == "separation"
-Provides-Extra: speech
-Requires-Dist: faster-whisper; extra == "speech"
-Provides-Extra: beats
-Requires-Dist: beat-this>=1.1.0; extra == "beats"
-Provides-Extra: deep
-Requires-Dist: sentence-transformers<7,>=6.1; extra == "deep"
-Requires-Dist: all-in-one-infer>=3.1; extra == "deep"
-Provides-Extra: semantic-nc
-Requires-Dist: muq; extra == "semantic-nc"
-Provides-Extra: amt
-Requires-Dist: basic-pitch<0.5,>=0.4; python_version < "3.12" and extra == "amt"
-Provides-Extra: server
-Requires-Dist: fastapi<1,>=0.115; extra == "server"
-Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "server"
-Requires-Dist: python-socketio<6,>=5.12; extra == "server"
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: ruff>=0.6; extra == "dev"
-Requires-Dist: build>=1.2; extra == "dev"
-Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
-Requires-Dist: httpx2; extra == "dev"
-Provides-Extra: binary
-Requires-Dist: nuitka>=2.7; extra == "binary"
-Requires-Dist: ordered-set>=4.1; extra == "binary"
-Requires-Dist: zstandard>=0.23; extra == "binary"
-Requires-Dist: lazy-loader==0.4; extra == "binary"
-Provides-Extra: all
-Requires-Dist: demucs>=4.0.1; extra == "all"
-Requires-Dist: openunmix>=1.3.0; extra == "all"
-Requires-Dist: bs-roformer-infer>=0.1.5; extra == "all"
-Requires-Dist: faster-whisper; extra == "all"
-Requires-Dist: beat-this>=1.1.0; extra == "all"
-Requires-Dist: sentence-transformers<7,>=6.1; extra == "all"
-Requires-Dist: all-in-one-infer>=3.1; extra == "all"
-Requires-Dist: fastapi<1,>=0.115; extra == "all"
-Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "all"
-Requires-Dist: python-socketio<6,>=5.12; extra == "all"
-Dynamic: license-file
-
 # StemLab
 
 <!-- mcp-name: io.github.kieransimkin/stemlab -->
@@ -92,7 +6,11 @@ Dynamic: license-file
 
 > **Packaging identity:** the canonical project name is **StemLab**. StemLab is part of the **Dance Flow** project. The PyPI distribution is named `danceflow-stemlab` solely because Python package-registry names are globally unique. The Python import, CLI, GitHub repository and container image remain `stemlab`.
 
-StemLab provides **audio timing analysis and finds loopable sections for creating Shorts and other short-form videos**. It is the audio-analysis engine in Kieran Simkin's **DanceFlow** BPM and motion-response workflow. It separates and interprets a master track into synchronised stem, BPM/beat, structure, harmony, timbre, speech/lyric and semantic data. Those outputs can drive downstream motion-aware experiences, including the WordPress **DanceMoves** plugin, while StemLab remains usable as a standalone CLI, Python library, web service and container.
+## Synopsis
+
+**StemLab is a local, evidence-led music analysis toolkit that turns a master recording into inspectable stems, timing, structure, harmony, lyric and sonic evidence, then finds complete-bar loopable sections for Shorts and other short-form videos.**
+
+It combines independent separation and music-information-retrieval routes rather than treating any single model as the answer. Results remain traceable through source hashes, manifests, JSON/TSV/NPZ artefacts, portable Sonic Visualiser sessions and a shared React timeline for playback and comparison. StemLab can run as a CLI, Python library, web service, container or local Codex MCP plugin. It is the music-understanding layer of Kieran Simkin's **DanceFlow** workflow and can supply downstream motion systems such as the WordPress **DanceMoves** plugin, while remaining useful on its own.
 
 > **Model weights are not redistributed by this project.** They are fetched from their upstream registries/releases on first use. This avoids silently republishing checkpoints whose licensing may differ from the source code license, and lets upstream integrity metadata be used where available.
 
@@ -134,13 +52,19 @@ Relevant upstreams:
 
 For every successful separator, **every WAV it emits** is retained. Stem names are discovered from files rather than truncated to a hard-coded four-stem schema, which is important for MVSep Mega 53. For the master and every stem, StemLab writes both a PNG spectrogram and compressed `.npz` spectrogram data (time axis, frequency axis, dB matrix, FFT metadata).
 
+Full-resolution spectrogram evidence stays in the `.npz`; the PNG renderer is bounded to 8,192 time frames so long tracks cannot expand into multi-gigabyte Matplotlib RGBA buffers. If an older run retained the NPZ but failed while drawing the PNG, repair it in place without rerunning models:
+
+```powershell
+stemlab repair-spectrograms "path\to\analysis-results"
+```
+
 The preferred vocal stem is passed through the Silero VAD implementation bundled with `faster-whisper`. Speech regions are used to create a timeline-preserving `spoken_word.wav` (non-speech is zeroed rather than concatenated), then Whisper is run with word timestamps. Outputs include `whisper.json`, `speech_regions.json`, `transcript.txt`, `transcript.srt`, and `words.tsv`.
 
 Whisper runs in repetition-safe mode by default (`condition_on_previous_text=False`) to prevent a repeated syllable in one window contaminating later windows. `whisper.json` records that setting and includes repeated-token diagnostics. Use `--whisper-condition-on-previous-text` only for an explicit comparison run; a flagged transcript remains evidence requiring section-wise recovery or listening QA, not a trustworthy lyric source.
 
 Beat analysis runs:
 
-- **BeatNet** in offline/DBN mode when a compatible legacy environment is separately provisioned; it is not included in the current installable extras because its pinned NumPy/Numba requirements conflict with StemLab's core.
+- **BeatNet** in offline/DBN mode through StemLab's checksum-verified runtime bootstrap. StemLab uses the maintained `madmom-prebuilt` wheel and bypasses only BeatNet 1.1.3's obsolete NumPy/Numba package metadata.
 - **Beat This!** using the `final0` checkpoint and its minimal postprocessor.
 - **Beat Transformer**, using the original released model code/checkpoints. The model was trained on five demixed mel streams, so StemLab maps BS-RoFormer-SW to vocals, drums, bass, piano, and `other + guitar`, makes 128-bin mel-power spectrograms at the original 44.1 kHz / 4096 FFT / 1024-hop settings, and averages all eight released fold checkpoints by default. It uses the original madmom DBN decoder if madmom is importable, otherwise a documented SciPy peak-picking fallback.
 
@@ -305,9 +229,128 @@ sample indexing, thresholds, limitations and reproducible screenshot examples.
 
 ![Loop selection and playback in the existing analysis frontend](docs/screenshots/loops-playing.png)
 
+## Audio-to-MIDI model comparison
+
+MIDI extraction is an **optional, independent model pass**. It adds Transkun V2
+and high-resolution note/pedal piano transcription, plus MR-MT3 and YourMT3
+multi-instrument transcription, alongside Spotify Basic Pitch. Automatic source
+selection uses piano/keyboard stems for the piano specialists, pitched stems for
+Basic Pitch and the mix for MT3-family models. Missing stems are reported, never
+silently substituted. The legacy `--basic-pitch` command remains supported.
+
+```bash
+# Install the chosen runtime; the standard profiles do not install MIDI models.
+python -m pip install -e ".[midi-transkun]"
+stemlab midi-models
+
+# Use an existing separated piano, without rerunning any earlier analysis.
+stemlab midi analysis-master --model transkun
+
+# Or transcribe a directly supplied piano recording to a new folder.
+stemlab midi piano.wav -o midi-piano --model transkun
+
+# Full mix comparison requires the separately installed midi-mt3 extra.
+# Both requested checkpoints need explicit first-use download consent.
+stemlab midi mix.wav -o midi-comparison --model mr_mt3 --model yourmt3 --allow-model-downloads
+```
+
+Each model/source gets its original `.mid`, tempo-aware `notes.json` and
+`notes.csv`, an optional real note `piano-roll.png`, source/checkpoint hashes,
+package versions and a worker log. Native MIDI controllers, pitch bends, tempo
+changes and drums are preserved. Note sample numbers are original-rate
+**estimates**, not a claim that the transcription is sample-accurate ground truth.
+The MIDI clock is not used to overwrite StemLab's measured beat grid.
+
+New analyses can opt in with repeated `--midi-model` switches and
+`--midi-allow-downloads`. Existing Codex installations gain a workspace-scoped
+`stemlab_start_midi_scan` job tool after updating the Python installation and
+restarting the session. Models remain optional and no Python dependencies are
+automatically installed. Incompatible research runtimes can use separate
+`--backend-python MODEL=PATH` interpreters.
+
+See [the MIDI guide](docs/midi.md) for all models, installation choices, checkpoint
+and licensing caveats, saved-stem targeting, Codex usage, exact output semantics,
+real-inference smoke commands and test limitations. The React timeline remains
+the analysis inspector; this patch adds no MIDI synthesizer or new interactive
+piano-roll lane. Static note plots are not frontend screenshots.
+
+## Align timed musical cues to detected beats
+
+Use saved analysis to snap an LRC cue file without rerunning models or editing audio:
+
+```bash
+stemlab snap-cues analysis-master "musical cues.lrc" -o cue-review
+stemlab snap-cues analysis-master "musical cues.lrc" -o cue-review-100ms --tolerance-ms 100
+stemlab generate-cues analysis-master -o generated-cues --title "Song title"
+```
+
+Only timestamps change: bracketed labels such as `[DROP: CHORUS 1]`, metadata,
+encoding and line layout are preserved. A cue with **no detected beat within
+±150 ms** is highlighted as **REVIEW**, with its nearest-beat gap, and kept unchanged
+by default. `--force-snap` moves distant cues too but retains their warnings.
+`--downbeats` restricts targets to reported bar starts; `--beat-model` selects a
+specific detector. No constant-tempo beats are invented to fill detection gaps.
+
+Each new output folder contains the rewritten `.beat-snapped.lrc`, `report.json`,
+a colour-coded `review.html`, and `review.txt`. Exact mode preserves the stored
+beat timestamp; explicit millisecond/centisecond compatibility modes report
+rounding. Source-rate sample-frame estimates are included when the rate is known.
+Use `--fail-on-review` to write results and exit 2 when review is needed.
+Generated section-cue files use a title-specific, WordPress-safe filename so
+multiple releases can be uploaded and mapped without ambiguous duplicate names.
+For the retained 3 October 2026 future-release batch,
+`scripts/run-upcoming-full-cues.ps1` resumes full analyses without overwriting an
+incomplete directory, and `scripts/summarize-upcoming-cues.ps1` reads each closed
+manifest/report to produce one reproducible hash, cue-action and error-count row
+per release. The summary script refuses missing or ambiguous generated LRCs.
+
+For a new analysis, add `--snap-cues "musical cues.lrc"` and optionally
+`--cue-tolerance-ms 100`. Cue alignment uses that run's detected events and appears
+in `analysis.json`. See [the cue alignment guide](docs/cue-alignment.md) for exact
+precision, offsets, all switches, safety rules and interpretation of warnings.
+
+## Complementary evidence models
+
+StemLab now has an optional **evidence-model layer** for models that add a different
+kind of musical evidence instead of duplicating the normal separation or MIDI
+backends. Nothing in this layer is enabled by a normal profile.
+
+```bash
+stemlab evidence-models
+
+# Singing/speech/music activity + continuous pitch on saved vocals.
+stemlab evidence analysis-master -o evidence-vocals \
+  --model firered_aed --model swift_f0 \
+  --model-path firered_aed=/models/FireRedVAD/AED
+
+# Align approved lyrics without replacing them.
+stemlab evidence analysis-master -o evidence-align \
+  --model qwen_forced_aligner --canonical-text lyrics.txt --allow-model-downloads
+
+# Independent harmony evidence.
+stemlab evidence analysis-master -o evidence-chords --model lv_chordia
+```
+
+The built-in registry covers **FireRed AED**, **HeartTranscriptor**, **Qwen3
+ForcedAligner**, **SwiftF0**, **SongFormer**, **lv-chordia** and **ADTOF PyTorch**.
+It also exposes explicit external-runtime bridges for **GAME**, **SheetSage2**,
+**MOSS-Music** and **AudioSep** so large or restricted research dependencies never
+get silently bundled into StemLab. Outputs stay independent: singing activity,
+forced alignment, pitch, structure, chords and drum hits are review evidence, not
+a hidden combined ground-truth score.
+
+Saved analyses automatically route vocal models to a preferred full vocal stem,
+drum transcription to a drum stem, continuous pitch to pitched stems, and
+structure/harmony models to the master. Missing specialist stems are reported.
+Use `--backend-python MODEL=/path/to/python` for conflicting research environments.
+
+See [the evidence-model guide](docs/evidence-models.md) for model terms, routing,
+external bridges and interpretation rules. `scripts/benchmark_evidence_corpus.py`
+probes an authorised evaluation collection without copying audio into the repo.
+
 ## Install
 
-Python 3.10 or 3.11 is recommended for the broad optional-model ecosystem. The `beats` and `all` extras install Beat This! but not BeatNet: BeatNet's current published NumPy/Numba pins conflict with StemLab's core Librosa requirement. The BeatNet adapter is retained for separately provisioned compatible legacy setups; a missing BeatNet result must not be mistaken for a successful detector run.
+Python 3.11 is recommended for the broad optional-model ecosystem. The `beats` and `all` extras install Beat This! plus the compatible `madmom-prebuilt` decoder. BeatNet 1.1.3 itself still publishes obsolete NumPy/Numba dependency pins, so StemLab downloads its official pure-Python wheel separately, verifies the published SHA-256, and exposes only the BeatNet code and bundled model weights from its cache. This route is supported on Python 3.11-3.13; a missing BeatNet result must not be mistaken for a successful detector run.
 
 From PyPI, install the released StemLab distribution with:
 
@@ -330,6 +373,18 @@ SCNet and Beat Transformer are research repositories rather than stable pip infe
 stemlab bootstrap all
 ```
 
+For BeatNet alone:
+
+```bash
+pip install "danceflow-stemlab[beats]"
+stemlab bootstrap beatnet
+stemlab doctor
+```
+
+`stemlab doctor` reports BeatNet as ready only when the normal package or the
+verified StemLab cache can actually be found. `analyze --no-bootstrap` never
+downloads BeatNet and records the unavailable backend instead.
+
 For only the Vamp analysis stack:
 
 ```bash
@@ -439,6 +494,7 @@ endpoints, events and the Arcadians reference workflow.
 - [Web service](docs/web.md)
 - [Containers](docs/containers.md)
 - [Publishing and releases](docs/publishing.md)
+- [BeatNet compatibility](docs/beatnet.md)
 - [Changelog](CHANGELOG.md)
 
 ## Codex plugin and MCP server