danceflow-stemlab 1.3.4__tar.gz → 1.4.1__tar.gz

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: danceflow-stemlab
-Version: 1.3.4
+Version: 1.4.1
 Summary: Local music analysis for stems, timing, beats, harmony, lyrics, MIDI and loopable sections for Shorts. https://kieransimkin.co.uk/
 Author: Kieran Simkin
 Maintainer: Kieran Simkin
@@ -38,6 +38,8 @@ Requires-Dist: platformdirs>=4.2
 Requires-Dist: librosa>=0.11
 Requires-Dist: pyloudnorm>=0.2
 Requires-Dist: cmudict>=1.1.3
+Provides-Extra: rudiments
+Requires-Dist: dancerudiments<1,>=0.2.4; extra == "rudiments"
 Provides-Extra: codex
 Requires-Dist: mcp<3,>=2.2; extra == "codex"
 Requires-Dist: fastapi<1,>=0.115; extra == "codex"
@@ -255,6 +257,55 @@ The derived artifacts live under `deep/` (`sonic/`, `rhythm/`, `harmony/`, `stru
 `lyrics/`, `semantic_text/`, optional `semantic_audio/` and `basic_pitch/`, plus
 `song_map/song_map.json` and `summary.json`).
 
+## Find DanceRudiments matching candidates from each stem
+
+Install the separately maintained **optional** native package with
+`python -m pip install -e ".[rudiments]"`. StemLab calls
+[`dancerudiments.catalogue()` and `dancerudiments.sample()`](https://github.com/kieransimkin/DanceRudiments)
+directly—no cloned movement functions or bundled catalogue. It extracts per-stem
+RMS attack peaks, maps them onto detected beats, and ranks 16-beat windows
+against position/speed/acceleration salience of actual native motion samples.
+Scores are **comparative similarities**, not probabilities or guarantees of a good motion.
+
+```sh
+# Match the mix plus every saved stem without running separation again.
+stemlab rudiments ./analysis-master --top 20
+# Limit an existing analysis to two stems, or choose one of six official collections.
+stemlab rudiments ./analysis-master --stem drums --stem bass --collection club
+# Include matching as an opt-in part of a new full analysis.
+stemlab analyze master.wav --output ./analysis-master --rudiments
+# The bundled Arcadians MP3 has a documented BPM but no pre-separated stems.
+stemlab rudiments 'examples/arcadians/Arcadians - 320kbps.mp3' \
+  --bpm 145 --collection initial --top 28 --output ./arcadians-rudiments
+```
+
+### Measured Arcadians benchmark
+
+The mix-only offline benchmark found **1,821** energy-rise peaks and **15 candidate
+patterns at ≥0.68** similarity among the authentic 28-pattern DanceRudiments
+initial collection, led by `groove_b_played` (0.739), `groove_b_grid` (0.737),
+and `lfo_morph` (0.724). The benchmark read DanceRudiments' officially compiled
+sample tables through an **offline adapter**; the native C++-extension test is
+separate and skips when that optional package is not installed. The BPM grid
+starts at zero with **unverified beat phase**. No stem separation was claimed.
+
+These are **actual Chromium screenshots** of the measured local HTML report,
+not schematic illustrations or captures of the main React timeline.
+
+![Actual Arcadians audio attack peaks overlaid with a matching DanceRudiments motion descriptor in local report](docs/screenshots/arcadians-rudiments-report.png)
+
+![Actual ranked Arcadians DanceRudiments candidate table captured in Chromium](docs/screenshots/arcadians-rudiments-ranked.png)
+
+The analysis writes `deep/rudiments/report.json`, `index.html`, and `overview.png`.
+See **[method, score caveats, provenance, examples and screenshot reproduction](docs/rudiments.md)**.
+
+**Native CI coverage:** the main GitHub Actions `CI` workflow now has a dedicated
+Python 3.10/3.11 job that installs the official DanceRudiments *binary wheel*,
+requires the actual C++ module, and runs the Arcadians test with skipping disabled.
+Fewer than **12 real-audio matches** fails CI; passing runs publish the JSON,
+HTML and measured overlay PNG as downloadable CI artifacts. See the
+[native CI validation instructions](docs/rudiments.md#native-github-actions-gate).
+
 ## Timeline analysis gallery
 
 The browser workspace is intended to make the analysis output inspectable, not just downloadable. The illustrations below explain the main analysis families using the same shared timeline vocabulary as the frontend: one clock, one playhead, zoomable lanes, and consistent section alignment across spectrogram, beat, lyric and deep-analysis layers.
@@ -368,6 +419,16 @@ exported WAVs and writes no files. **Zoom to loop** focuses the shared timeline.
 See [the complete loop workflow](docs/loops.md) for installation of both patches,
 sample indexing, thresholds, limitations and reproducible screenshot examples.
 
+For line-complete alternatives when a musically satisfying restart is the goal,
+use `stemlab phrase-loops analysis-master --feedback artist-ratings.json --export-audio`.
+This opt-in search compares the musical context around both cuts, preserves
+canonical lyric occurrences, uses explicit artist feedback and selects diverse
+passages. Suggestions remain separate from strict accepted loops. See
+[phrase-loop methodology, feedback format and synthetic example](docs/phrase-loops.md).
+For longer excerpts, add `--min-seconds 20 --max-seconds 30`; optional
+`--max-bar-phase-error 0.125` also screens out mismatched measured bar positions.
+These filters suggest auditions and do not establish seamless or listening approval.
+
 ![Loop selection and playback in the existing analysis frontend](docs/screenshots/loops-playing.png)
 
 ## Audio-to-MIDI model comparison
@@ -611,6 +672,10 @@ analysis-master/
     lyrics/
     semantic_text/
     song_map/
+    rudiments/             # optional native DanceRudiments candidate report
+      report.json
+      index.html
+      overview.png
     summary.json
   sonic_visualiser/
     session.sv

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/README.md

@@ -130,6 +130,55 @@ The derived artifacts live under `deep/` (`sonic/`, `rhythm/`, `harmony/`, `stru
 `lyrics/`, `semantic_text/`, optional `semantic_audio/` and `basic_pitch/`, plus
 `song_map/song_map.json` and `summary.json`).
 
+## Find DanceRudiments matching candidates from each stem
+
+Install the separately maintained **optional** native package with
+`python -m pip install -e ".[rudiments]"`. StemLab calls
+[`dancerudiments.catalogue()` and `dancerudiments.sample()`](https://github.com/kieransimkin/DanceRudiments)
+directly—no cloned movement functions or bundled catalogue. It extracts per-stem
+RMS attack peaks, maps them onto detected beats, and ranks 16-beat windows
+against position/speed/acceleration salience of actual native motion samples.
+Scores are **comparative similarities**, not probabilities or guarantees of a good motion.
+
+```sh
+# Match the mix plus every saved stem without running separation again.
+stemlab rudiments ./analysis-master --top 20
+# Limit an existing analysis to two stems, or choose one of six official collections.
+stemlab rudiments ./analysis-master --stem drums --stem bass --collection club
+# Include matching as an opt-in part of a new full analysis.
+stemlab analyze master.wav --output ./analysis-master --rudiments
+# The bundled Arcadians MP3 has a documented BPM but no pre-separated stems.
+stemlab rudiments 'examples/arcadians/Arcadians - 320kbps.mp3' \
+  --bpm 145 --collection initial --top 28 --output ./arcadians-rudiments
+```
+
+### Measured Arcadians benchmark
+
+The mix-only offline benchmark found **1,821** energy-rise peaks and **15 candidate
+patterns at ≥0.68** similarity among the authentic 28-pattern DanceRudiments
+initial collection, led by `groove_b_played` (0.739), `groove_b_grid` (0.737),
+and `lfo_morph` (0.724). The benchmark read DanceRudiments' officially compiled
+sample tables through an **offline adapter**; the native C++-extension test is
+separate and skips when that optional package is not installed. The BPM grid
+starts at zero with **unverified beat phase**. No stem separation was claimed.
+
+These are **actual Chromium screenshots** of the measured local HTML report,
+not schematic illustrations or captures of the main React timeline.
+
+![Actual Arcadians audio attack peaks overlaid with a matching DanceRudiments motion descriptor in local report](docs/screenshots/arcadians-rudiments-report.png)
+
+![Actual ranked Arcadians DanceRudiments candidate table captured in Chromium](docs/screenshots/arcadians-rudiments-ranked.png)
+
+The analysis writes `deep/rudiments/report.json`, `index.html`, and `overview.png`.
+See **[method, score caveats, provenance, examples and screenshot reproduction](docs/rudiments.md)**.
+
+**Native CI coverage:** the main GitHub Actions `CI` workflow now has a dedicated
+Python 3.10/3.11 job that installs the official DanceRudiments *binary wheel*,
+requires the actual C++ module, and runs the Arcadians test with skipping disabled.
+Fewer than **12 real-audio matches** fails CI; passing runs publish the JSON,
+HTML and measured overlay PNG as downloadable CI artifacts. See the
+[native CI validation instructions](docs/rudiments.md#native-github-actions-gate).
+
 ## Timeline analysis gallery
 
 The browser workspace is intended to make the analysis output inspectable, not just downloadable. The illustrations below explain the main analysis families using the same shared timeline vocabulary as the frontend: one clock, one playhead, zoomable lanes, and consistent section alignment across spectrogram, beat, lyric and deep-analysis layers.
@@ -243,6 +292,16 @@ exported WAVs and writes no files. **Zoom to loop** focuses the shared timeline.
 See [the complete loop workflow](docs/loops.md) for installation of both patches,
 sample indexing, thresholds, limitations and reproducible screenshot examples.
 
+For line-complete alternatives when a musically satisfying restart is the goal,
+use `stemlab phrase-loops analysis-master --feedback artist-ratings.json --export-audio`.
+This opt-in search compares the musical context around both cuts, preserves
+canonical lyric occurrences, uses explicit artist feedback and selects diverse
+passages. Suggestions remain separate from strict accepted loops. See
+[phrase-loop methodology, feedback format and synthetic example](docs/phrase-loops.md).
+For longer excerpts, add `--min-seconds 20 --max-seconds 30`; optional
+`--max-bar-phase-error 0.125` also screens out mismatched measured bar positions.
+These filters suggest auditions and do not establish seamless or listening approval.
+
 ![Loop selection and playback in the existing analysis frontend](docs/screenshots/loops-playing.png)
 
 ## Audio-to-MIDI model comparison
@@ -486,6 +545,10 @@ analysis-master/
     lyrics/
     semantic_text/
     song_map/
+    rudiments/             # optional native DanceRudiments candidate report
+      report.json
+      index.html
+      overview.png
     summary.json
   sonic_visualiser/
     session.sv

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/mcp-registry/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.kieransimkin/stemlab",
   "title": "StemLab \u2014 timing and loops for Shorts",
   "description": "Music and stem analysis, timing and loopable Shorts. https://kieransimkin.co.uk/",
-  "version": "1.3.4",
+  "version": "1.4.1",
   "websiteUrl": "https://kieransimkin.co.uk/my-songs/",
   "repository": {
     "url": "https://github.com/kieransimkin/stemlab",
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "danceflow-stemlab",
-      "version": "1.3.4",
+      "version": "1.4.1",
       "runtimeHint": "uvx",
       "runtimeArguments": [
         {

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/plugins/stemlab/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "stemlab",
-  "version": "1.3.4",
+  "version": "1.4.1",
   "description": "Local music analysis for stems, timing, beats, harmony, lyrics, MIDI and loopable sections for Shorts. https://kieransimkin.co.uk/",
   "skills": "./skills/",
   "mcpServers": "./.mcp.json",

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/plugins/stemlab/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "stemlab",
-  "version": "1.3.4",
+  "version": "1.4.1",
   "description": "Local music analysis for stems, timing, beats, harmony, lyrics, MIDI and loopable sections for Shorts. https://kieransimkin.co.uk/",
   "author": {
     "name": "Kieran Simkin",

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/plugins/stemlab/skills/stemlab/SKILL.md

@@ -39,6 +39,14 @@ Created by Kieran Simkin — https://kieransimkin.co.uk/my-songs/
 9. Quote `start_sample` inclusive and `end_sample` exclusive in native source sample
    frames, not interleaved channel values. Do not move cuts to force a preferred
    lyric. Vocal energy and timing gates are heuristics; listening QA is still needed.
+10. For complete lyric-line alternatives and musical restarts, the local CLI
+    `stemlab phrase-loops RESULTS --feedback RATINGS.json --export-audio` reuses
+    explicit canonical timings and saved evidence. See `docs/phrase-loops.md`.
+    Use caller-selected duration bounds and optional `--max-bar-phase-error` to
+    screen measured bar-position mismatches; preserve unknown context and listening holds.
+    Its separate report contains suggestions, never strict accepted loops or
+    listening approval. Artist ratings are source-hash-bound; keep private
+    ratings and song material out of public examples and packages.
 
 ## Evidence and privacy
 

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/pyproject.toml

@@ -50,6 +50,8 @@ Changelog = "https://github.com/kieransimkin/stemlab/blob/main/CHANGELOG.md"
 Contact = "https://kieransimkin.co.uk/contact/"
 
 [project.optional-dependencies]
+# Explicit opt-in: native motions/catalogue stay entirely in DanceRudiments.
+rudiments = ["dancerudiments>=0.2.4,<1"]
 # Local MCP transport and read-only viewer for the existing React timeline.
 # Model backends remain separately selected; no duplicate React bundle is shipped.
 codex = ["mcp>=2.2,<3", "fastapi>=0.115,<1", "uvicorn>=0.34,<1"]

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/src/danceflow_stemlab.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: danceflow-stemlab
-Version: 1.3.4
+Version: 1.4.1
 Summary: Local music analysis for stems, timing, beats, harmony, lyrics, MIDI and loopable sections for Shorts. https://kieransimkin.co.uk/
 Author: Kieran Simkin
 Maintainer: Kieran Simkin
@@ -38,6 +38,8 @@ Requires-Dist: platformdirs>=4.2
 Requires-Dist: librosa>=0.11
 Requires-Dist: pyloudnorm>=0.2
 Requires-Dist: cmudict>=1.1.3
+Provides-Extra: rudiments
+Requires-Dist: dancerudiments<1,>=0.2.4; extra == "rudiments"
 Provides-Extra: codex
 Requires-Dist: mcp<3,>=2.2; extra == "codex"
 Requires-Dist: fastapi<1,>=0.115; extra == "codex"
@@ -255,6 +257,55 @@ The derived artifacts live under `deep/` (`sonic/`, `rhythm/`, `harmony/`, `stru
 `lyrics/`, `semantic_text/`, optional `semantic_audio/` and `basic_pitch/`, plus
 `song_map/song_map.json` and `summary.json`).
 
+## Find DanceRudiments matching candidates from each stem
+
+Install the separately maintained **optional** native package with
+`python -m pip install -e ".[rudiments]"`. StemLab calls
+[`dancerudiments.catalogue()` and `dancerudiments.sample()`](https://github.com/kieransimkin/DanceRudiments)
+directly—no cloned movement functions or bundled catalogue. It extracts per-stem
+RMS attack peaks, maps them onto detected beats, and ranks 16-beat windows
+against position/speed/acceleration salience of actual native motion samples.
+Scores are **comparative similarities**, not probabilities or guarantees of a good motion.
+
+```sh
+# Match the mix plus every saved stem without running separation again.
+stemlab rudiments ./analysis-master --top 20
+# Limit an existing analysis to two stems, or choose one of six official collections.
+stemlab rudiments ./analysis-master --stem drums --stem bass --collection club
+# Include matching as an opt-in part of a new full analysis.
+stemlab analyze master.wav --output ./analysis-master --rudiments
+# The bundled Arcadians MP3 has a documented BPM but no pre-separated stems.
+stemlab rudiments 'examples/arcadians/Arcadians - 320kbps.mp3' \
+  --bpm 145 --collection initial --top 28 --output ./arcadians-rudiments
+```
+
+### Measured Arcadians benchmark
+
+The mix-only offline benchmark found **1,821** energy-rise peaks and **15 candidate
+patterns at ≥0.68** similarity among the authentic 28-pattern DanceRudiments
+initial collection, led by `groove_b_played` (0.739), `groove_b_grid` (0.737),
+and `lfo_morph` (0.724). The benchmark read DanceRudiments' officially compiled
+sample tables through an **offline adapter**; the native C++-extension test is
+separate and skips when that optional package is not installed. The BPM grid
+starts at zero with **unverified beat phase**. No stem separation was claimed.
+
+These are **actual Chromium screenshots** of the measured local HTML report,
+not schematic illustrations or captures of the main React timeline.
+
+![Actual Arcadians audio attack peaks overlaid with a matching DanceRudiments motion descriptor in local report](docs/screenshots/arcadians-rudiments-report.png)
+
+![Actual ranked Arcadians DanceRudiments candidate table captured in Chromium](docs/screenshots/arcadians-rudiments-ranked.png)
+
+The analysis writes `deep/rudiments/report.json`, `index.html`, and `overview.png`.
+See **[method, score caveats, provenance, examples and screenshot reproduction](docs/rudiments.md)**.
+
+**Native CI coverage:** the main GitHub Actions `CI` workflow now has a dedicated
+Python 3.10/3.11 job that installs the official DanceRudiments *binary wheel*,
+requires the actual C++ module, and runs the Arcadians test with skipping disabled.
+Fewer than **12 real-audio matches** fails CI; passing runs publish the JSON,
+HTML and measured overlay PNG as downloadable CI artifacts. See the
+[native CI validation instructions](docs/rudiments.md#native-github-actions-gate).
+
 ## Timeline analysis gallery
 
 The browser workspace is intended to make the analysis output inspectable, not just downloadable. The illustrations below explain the main analysis families using the same shared timeline vocabulary as the frontend: one clock, one playhead, zoomable lanes, and consistent section alignment across spectrogram, beat, lyric and deep-analysis layers.
@@ -368,6 +419,16 @@ exported WAVs and writes no files. **Zoom to loop** focuses the shared timeline.
 See [the complete loop workflow](docs/loops.md) for installation of both patches,
 sample indexing, thresholds, limitations and reproducible screenshot examples.
 
+For line-complete alternatives when a musically satisfying restart is the goal,
+use `stemlab phrase-loops analysis-master --feedback artist-ratings.json --export-audio`.
+This opt-in search compares the musical context around both cuts, preserves
+canonical lyric occurrences, uses explicit artist feedback and selects diverse
+passages. Suggestions remain separate from strict accepted loops. See
+[phrase-loop methodology, feedback format and synthetic example](docs/phrase-loops.md).
+For longer excerpts, add `--min-seconds 20 --max-seconds 30`; optional
+`--max-bar-phase-error 0.125` also screens out mismatched measured bar positions.
+These filters suggest auditions and do not establish seamless or listening approval.
+
 ![Loop selection and playback in the existing analysis frontend](docs/screenshots/loops-playing.png)
 
 ## Audio-to-MIDI model comparison
@@ -611,6 +672,10 @@ analysis-master/
     lyrics/
     semantic_text/
     song_map/
+    rudiments/             # optional native DanceRudiments candidate report
+      report.json
+      index.html
+      overview.png
     summary.json
   sonic_visualiser/
     session.sv

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/src/danceflow_stemlab.egg-info/SOURCES.txt

@@ -69,8 +69,10 @@ src/stemlab/analysis/__init__.py
 src/stemlab/analysis/harmony.py
 src/stemlab/analysis/loops.py
 src/stemlab/analysis/lyrics.py
+src/stemlab/analysis/phrase_loops.py
 src/stemlab/analysis/registry.py
 src/stemlab/analysis/rhythm.py
+src/stemlab/analysis/rudiment_matches.py
 src/stemlab/analysis/runner.py
 src/stemlab/analysis/semantic_audio.py
 src/stemlab/analysis/semantic_text.py
@@ -120,7 +122,9 @@ src/stemlab/web/style.css
 src/stemlab/web/timeline.css
 tests/test_analysis_registry.py
 tests/test_arcadians_fixture.py
+tests/test_arcadians_rudiments.py
 tests/test_audio_normalization.py
+tests/test_bar_phase.py
 tests/test_beat_consensus.py
 tests/test_beat_this_bootstrap.py
 tests/test_beatnet_bootstrap.py
@@ -152,7 +156,9 @@ tests/test_midi_extraction.py
 tests/test_midi_integration.py
 tests/test_midi_registry.py
 tests/test_models.py
+tests/test_phrase_loops.py
 tests/test_repository_hygiene.py
+tests/test_rudiment_matches.py
 tests/test_server.py
 tests/test_song_map.py
 tests/test_sonic_visualiser.py

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/src/danceflow_stemlab.egg-info/requires.txt

@@ -106,6 +106,9 @@ psutil>=5.9
 transkun==2.0.1
 setuptools<81
 
+[rudiments]
+dancerudiments<1,>=0.2.4
+
 [semantic-nc]
 muq
 

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/src/stemlab/__init__.py

@@ -7,4 +7,4 @@ Created by Kieran Simkin — https://kieransimkin.co.uk/
 Music catalogue — https://kieransimkin.co.uk/my-songs/
 """
 
-__version__ = "1.3.4"
+__version__ = "1.4.1"

{danceflow_stemlab-1.3.4 → danceflow_stemlab-1.4.1}/src/stemlab/analysis/loops.py

@@ -264,6 +264,38 @@ def grid_metrics(beats: np.ndarray, down_indices: np.ndarray, first: int, last:
                 last_interval_seconds=float(intervals[-1]))
 
 
+def detected_bar_phase_metrics(beats: np.ndarray, down_indices: np.ndarray,
+                               start_seconds: float, end_seconds: float) -> dict:
+    """Compare cut positions on one measured bar grid without assuming 4/4."""
+    try:
+        beats = _ordered_times(beats)
+        indices = np.asarray(down_indices)
+        if (indices.ndim != 1 or len(indices) < 2 or indices.dtype.kind not in 'iu'
+                or np.any(indices < 0) or np.any(indices >= len(beats))
+                or np.any(indices[1:] <= indices[:-1])):
+            raise ValueError('Need ordered, distinct measured downbeat indices')
+        if (not np.isfinite([start_seconds, end_seconds]).all()
+                or not 0 <= start_seconds < end_seconds):
+            raise ValueError('Need finite ordered cut times')
+        downbeats = beats[indices]
+        if start_seconds < downbeats[0] or end_seconds > downbeats[-1]:
+            raise ValueError('Cuts lack enclosing measured downbeats')
+        first = max(0, int(np.searchsorted(downbeats, start_seconds, side='right'))-1)
+        last = max(0, int(np.searchsorted(downbeats, end_seconds, side='left'))-1)
+        counts = np.diff(indices)[first:last+1]
+        if not len(counts) or np.any(counts != counts[0]) or not 2 <= counts[0] <= 12:
+            raise ValueError('Detected beats per bar are unsupported or change across the cut')
+        coordinates = np.interp([start_seconds, end_seconds], downbeats,
+                                np.arange(len(downbeats)))
+        span = float(coordinates[1]-coordinates[0])
+        return dict(available=True, detected_beats_per_bar=int(counts[0]),
+            fractional_bar_count=span, bar_phase_error=abs(span-round(span)),
+            start_bar_coordinate=float(coordinates[0]), end_bar_coordinate=float(coordinates[1]),
+            interpretation='Measured relative bar position; not artist-confirmed meter or loop approval')
+    except (ValueError, TypeError, IndexError) as exc:
+        return dict(available=False, reason=str(exc))
+
+
 def optimize_join(audio: np.ndarray, sr: int, start: int, end: int,
                   lower: int, upper: int, cfg: LoopConfig, *, allow_failed: bool = False) -> dict | None:
     """Same offset at both cuts keeps length fixed. Score every channel."""
@@ -546,11 +578,9 @@ def _inside(root: Path, value: str) -> Path:
     return path
 
 
-def analyze_existing_loops(root: Path, *, export_audio: bool = False,
-                           config: LoopConfig | None = None) -> dict:
-    """Reuse saved models. Also works after canonical section/timing edits."""
+def load_loop_evidence(root: Path) -> dict:
+    """Load verified native master and saved evidence for both search strategies."""
     from .song_map import _choose_sections
-    from stemlab.manifest import write_manifest
 
     root = root.expanduser().resolve()
     analysis = _read(root / "analysis.json")
@@ -577,21 +607,38 @@ def analyze_existing_loops(root: Path, *, export_audio: bool = False,
             stems.append(StemArtifact(str(item["model"]), str(item["stem"]), _inside(root, item["path"])))
         for item in model.get("normalization", []):
             gains[str(_inside(root, item["path"]))] = float(item.get("gain_db", 0.0))
-    report = analyze_loops(master, root / "deep/loops", song_map=song_map, beat_results=results,
-                           stems=stems, whisper_result=_read(root / "speech/whisper.json"),
-                           lyrics_result=_read(root / "deep/lyrics/lyrics.json"), canonical=canonical,
-                           normalization_gains=gains, export_audio=export_audio, config=config)
+    return dict(audio_path=master, song_map=song_map, beat_results=results, stems=stems,
+                whisper_result=_read(root / "speech/whisper.json"),
+                lyrics_result=_read(root / "deep/lyrics/lyrics.json"), canonical=canonical,
+                normalization_gains=gains)
+
+
+def index_loop_report(root: Path, name: str, relative_path: str) -> None:
+    """Refresh existing analysis discovery and hashes after an explicit rescan."""
+    from stemlab.manifest import write_manifest
+
+    analysis = _read(root / "analysis.json")
     summary_path = root / "deep/summary.json"
     summary = _read(summary_path)
-    summary.setdefault("analyses", {})["loops"] = {"available": True, "path": "deep/loops/loops.json"}
+    summary.setdefault("analyses", {})[name] = {"available": True, "path": relative_path}
     _write_json(summary_path, summary)
     if not isinstance(analysis.get("deep_analysis"), dict):
         analysis["deep_analysis"] = {}
-    analysis["deep_analysis"].setdefault("analyses", {})["loops"] = summary["analyses"]["loops"]
+    analysis["deep_analysis"].setdefault("analyses", {})[name] = summary["analyses"][name]
     _write_json(root / "analysis.json", analysis)
     old_manifest = _read(root / "manifest.json")
     write_manifest(root, extra={k: v for k, v in old_manifest.items()
                                 if k not in {"generated_at", "platform", "python", "files"}})
+
+
+def analyze_existing_loops(root: Path, *, export_audio: bool = False,
+                           config: LoopConfig | None = None) -> dict:
+    """Reuse saved models. Also works after canonical section/timing edits."""
+    root = root.expanduser().resolve()
+    evidence = load_loop_evidence(root)
+    report = analyze_loops(output_dir=root / "deep/loops", **evidence,
+                           export_audio=export_audio, config=config)
+    index_loop_report(root, "loops", "deep/loops/loops.json")
     return report