StemLab — timing and loops for Shorts

StemLab

By [Kieran Simkin](https://kieransimkin.co.uk/) · DanceFlow ecosystem · Vector logo and usage guide.

Local music analysis for stems, timing, beats, harmony, lyrics, MIDI and loopable sections for Shorts. https://kieransimkin.co.uk/

Complete lyric-line gates and separate vocal parts

Canonical LRC export rejects missing anchors, implausibly long cross-gap phrases, compressed line clusters and rounded onset collisions before ranking candidates. The repetition-safe python -m stemlab.lyric_batch route preserves native ASR evidence and holds complete export when a section fails; it never interpolates missing lines. Optional python -m stemlab.lyric_acoustic reuses existing local Whisper weights for known-text alignment. Explicit separate-part line selections can retain simultaneous onsets without serializing backing vocals.

Read the commands, synthetic demonstration and limits. Recognition scores and forced text coverage do not prove sung-word accuracy or voice identity. All exports remain drafts until artist listening confirmation; existing files, canonical lyrics and selected EPK timings are preserved.

Canonical song example — Star Lights Glow (Mystery Liquid Kick)

examples/star-lights-glow-mystery-liquid-kick/ holds Bass Ben & Friends' Star Lights Glow (Mystery Liquid Kick) as a verified 192 kbps CBR MP3 listening/analysis reference with the original supplied front-cover JPEG and ID3 metadata. The original lossless WAV remains the canonical source master, identified by SHA-256 in evidence.json rather than redistributed as a second large binary. The mix is separate from *Star Lights Glow (Anthem)*; BPM, phase, release date and ISRC are unconfirmed. Verify with python scripts/verify_star_lights_reference.py and consult the example's README. The MIT code licence does not license the music or artwork.

Independent beat finding and counting (experimental)

Tempo precision update: Classical autocorrelation and comb-filter lag peaks now retain their original 100 Hz integer-bin BPM while also reporting a bounded sub-frame estimate. Local tempo windows use the same refinement, and tempo families expose source-wide observed-onset-path coverage as a review diagnostic, not as calibrated confidence or automatic BPM approval. Predicted beats, observed onset candidates and inferred ordinal gaps remain distinct. See beat-evidence documentation.

stemlab compare-beats now compares model-free audio, N-dimensional DanceRudiments recordings, rig captures and verified motion-package accents. Five complementary classical rhythm decoders produce reviewable BPM, beat count, phase, accent-cycle and local-tempo hypotheses. It can also import existing Beat This!/BeatNet/Beat Transformer/All-In-One model result JSON without re-running models; no model weights are downloaded. Cross-source phase scores require explicit clock offsets. No inferred downbeat or predicted grid is silently accepted as a real detection or canonical timeline. See usage and evidence schema and the model and implementation research roadmap.

The review now groups half/double tempo families rather than majority-voting correlated algorithms, scores DP coverage across the original source, and fits original saved model timestamps with robust residual/drift guards. Optional --annotation NAME=FILE evaluates beat timing only against a matching, human-reviewed, SHA-bound annotation; separately-held-out reliability calibration abstains without enough independent annotated songs. The non-destructive scripts/benchmark_example_beats.py handles Arcadians, The Truth is a Virus, and the separately pinned Star Lights Glow (Mystery Liquid Kick) derivative. No estimator approves beat 1, changes an audio master or replaces a canonical beat map. See beat evidence.

Rigged mesh rhythm and loop evidence

The optional stemlab analyze-rig-motion command analyses timestamped DanceRudiments rig captures or verified time-only motion packages from animated FBX/BVH/glTF/BLEND Actions. It estimates kinematic movement accents and BPM candidates, discovers repeated pose cycles, and suggests reviewable loop seams with velocity and root-drift checks. It can export an explicitly unverified source beat map for the existing DanceRudiments 64-pip compiler. This is not verified musical beat 1, audio synchronization, or automatic looping/mesh-seam repair. No model downloads or native sampler are involved. The optional DanceRudiments authoring loader validates all motion-package chunk hashes. Tempo ranking uses periodicity and spectral support to distinguish plausible half- and double-time pulses. See rig-motion analysis.

Python callers with an independently aligned beat grid can also use stemlab.analysis.motion_loop_seams.rank_aligned_motion_loops to rank hard-cut recording loops of a fixed beat count. It reuses the pose, velocity and root gates, can reject large PCM join steps, and accepts optional full-body and lower-body camera measurements. It keeps both endpoints within a bounded shared shift from the supplied beats. See beat-constrained seam ranking.

For original captures, --world-motion world-motion-evidence.json consumes the source-hash-bound world-space/foot-contact sidecar produced by DanceRudiments. It checks the exact capture, rig profile, timestamps and coverage, retains the original control analysis, and exposes contact/world tempo alternatives plus contact-state loop diagnostics. --tempo-strategy consensus prefers a contact pulse corroborated by control/world timing; contradictory families abstain. Explicit control, world and contact selections remain available and never approve music timing. Root/world/height traces share one kinematic lineage; correlated streams are not counted as independent model votes. Selecting an alternative consensus candidate checks corroboration for that exact candidate. Source coverage is recorded from the original timestamps even without a world sidecar; gaps and isolated frames cannot become interpolated alignment events or selected world-aware loop spans. Original control evidence remains available for review.

prepare-alignment-events, align-motion-audio and confirm-motion-alignment complete the source-clock handoff: import actual observed accents or saved audio detections, verify original source bytes, supply an explicit clock map, compare offset/half-speed/double-speed and bounded variable-tempo proposals, then write a separate review revision. Gaps remain unmapped, periodic phase ambiguity is reported, and beat one/meter require separate explicit confirmations. Generated affine endpoints receive bounded floating-point roundoff correction before review; reviewed mappings still require exact source bounds. Nothing retimes source media or silently changes a canonical beat map. The offline modules use NumPy; python -m stemlab.rig_motion_cli --help also exposes this workflow without importing the audio/model pipeline. See the alignment guide, JSON contracts and reproducible example.

The motion-evidence CI job builds the actual wheel, verifies isolated offline imports without audio/model dependencies, and tests source binding, world/contact sidecars, timing candidates and review revisions on Python 3.10/3.12. Production companion dependencies still require official published releases; this source gate does not claim listening, retargeted-character or deployment acceptance.

The real-song reference timeline preserves its explicitly hash-pinned public detector JSON byte for byte, including newlines, on Windows and Linux. Generic exports still remove private paths. Container model weights and model-specific caches live under the owning project's ignored /opt/stemlab/models/ directory; they are excluded from the build context and source/package artifacts.

StemLab by [Kieran Simkin](https://kieransimkin.co.uk/) · My Songs portfolio · Arcadians EPK · Source

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.

Before every new workflow

Check the latest stable official release and the actual installed/imported version before starting; do not infer currency from a directory name or a development checkout. Read the current release notes, tagged capability documentation and relevant Potential problems. Use the DanceFlow release preflight and complete capability references.

People and agents should consider the full ecosystem, use all capabilities that materially serve the task, compose supported files/APIs, and improve a demonstrated reusable gap in its canonical tool. Record why no worthwhile change is justified when that is the result. Keep independent tool identities, compatibility, source clocks, privacy, model/download costs and publication/deployment permissions intact. Store weights and model-specific caches in the owning project's ignored models/.

Find your route

Synopsis · Install · CLI · Output layout · Analysis performed · Curated default model set (September 2026) · Speech transcription · Comprehensive sonic, harmonic, rhythmic and semantic analysis · Find DanceRudiments matching candidates from each stem

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.

Install

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 Stem