danceflow-stemlab 1.4.0__tar.gz → 1.4.2__tar.gz

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/AGENTS.md

@@ -7,3 +7,9 @@
 - Keep credentials, account data, private media and rights records out of source, fixtures, logs and packages. Use synthetic fixtures or explicitly authorised public examples and preserve their provenance/licences.
 - Use [CONTRIBUTING.md](CONTRIBUTING.md) for review. Maintainers publish accepted, validated improvements as a fresh matching GitHub release and verify configured registry destinations. Preserve existing tags and release assets; publication and deployment remain subject to applicable authorisation.
 - Website: https://kieransimkin.co.uk/danceflow/
+
+## Keep README documentation current
+
+- Whenever a feature is added or changed, update the relevant README.md in the same change to reflect the resulting behaviour. This applies to every feature addition or modification, including APIs, commands, configuration, defaults, integrations and removals.
+- Update affected feature descriptions, usage instructions, options, examples and limitations. For tools or packages with their own README.md, update that README as well as the repository README when its overview or usage is affected.
+- Check the README against the implemented and verified behaviour before committing, opening or merging a PR, publishing a release or handing off the work. A feature change is incomplete until its README documentation is current; a changelog or other documentation does not replace this requirement.

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: danceflow-stemlab
-Version: 1.4.0
+Version: 1.4.2
 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
@@ -425,9 +425,24 @@ 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)
 
+## Recover a Short or video's source timing
+
+`stemlab match-clip master.wav published-original.mp4 --output new-match.json`
+locates a contiguous soundtrack excerpt without running models or downloading
+anything. It retains both original hashes, timing precision, competing source
+positions and independent window checks. Matched reports provide source offset,
+soundtrack duration and player start for synchronised consumers. Short fades and
+compression are tolerated; ambiguous repetition, edit jumps, different recordings
+and rate changes remain unresolved. Use `--clip-start` / `--clip-end` for an
+explicit known soundtrack interval. FFmpeg is required for video decoding.
+See [clip matching](docs/clip-matching.md) for limitations and a synthetic example.
+
 ## Audio-to-MIDI model comparison
 
 MIDI extraction is an **optional, independent model pass**. It adds Transkun V2

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/README.md

@@ -298,9 +298,24 @@ 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)
 
+## Recover a Short or video's source timing
+
+`stemlab match-clip master.wav published-original.mp4 --output new-match.json`
+locates a contiguous soundtrack excerpt without running models or downloading
+anything. It retains both original hashes, timing precision, competing source
+positions and independent window checks. Matched reports provide source offset,
+soundtrack duration and player start for synchronised consumers. Short fades and
+compression are tolerated; ambiguous repetition, edit jumps, different recordings
+and rate changes remain unresolved. Use `--clip-start` / `--clip-end` for an
+explicit known soundtrack interval. FFmpeg is required for video decoding.
+See [clip matching](docs/clip-matching.md) for limitations and a synthetic example.
+
 ## Audio-to-MIDI model comparison
 
 MIDI extraction is an **optional, independent model pass**. It adds Transkun V2

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/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.4.0",
+  "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.4.0",
+      "version": "1.4.1",
       "runtimeHint": "uvx",
       "runtimeArguments": [
         {

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/plugins/stemlab/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "stemlab",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "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.4.0 → danceflow_stemlab-1.4.2}/plugins/stemlab/README.md

@@ -30,6 +30,12 @@ optional separation/speech/beat backends must already be installed for new infer
 No model is downloaded at plugin installation. The existing `all` extra does not
 include the opt-in MuQ or Basic Pitch routes.
 
+The installed runtime also includes the model-free CLI
+`stemlab match-clip SOURCE CLIP --output NEW.json` for hash-bound Short/video
+soundtrack timing recovery. It runs locally and does not add a separate MCP tool
+or change the timeline. Review competing matches and unresolved states before
+using a result; see the repository's `docs/clip-matching.md`.
+
 `configure` records only a workspace and resource limits in the platform's
 user-configuration directory (`stemlab/codex.json`). It does not change Codex
 settings or grant approvals. Use `--replace` only after reviewing an existing file.

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/plugins/stemlab/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "stemlab",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "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.4.0 → danceflow_stemlab-1.4.2}/plugins/stemlab/skills/stemlab/SKILL.md

@@ -42,6 +42,8 @@ Created by Kieran Simkin — https://kieransimkin.co.uk/my-songs/
 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.
@@ -139,4 +141,13 @@ readiness, and these outputs never rewrite canonical lyrics, sections or beat gr
 
 ## Improve StemLab
 
+For existing video/Short soundtrack provenance, use the local CLI
+`stemlab match-clip SOURCE CLIP --output NEW.json` before running learned models.
+It preserves stereo phase, source/clip hashes and independent timing windows.
+`--clip-start` / `--clip-end` select a known soundtrack interval. A matched report
+provides offset, duration and player start; ambiguous repetition, edits or rate
+changes remain unresolved. It does not grant track identity, artist approval or
+publication rights. See `docs/clip-matching.md`; this CLI is separate from the
+plugin's existing timeline and asynchronous analysis tools.
+
 Inspect and use the available StemLab capabilities, and look for useful improvements wherever possible. Submit improvements with relevant tests, documentation and a reproducible example as PRs to https://github.com/kieransimkin/stemlab/pulls. Follow the repository's AGENTS.md and CONTRIBUTING.md.

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/src/danceflow_stemlab.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: danceflow-stemlab
-Version: 1.4.0
+Version: 1.4.2
 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
@@ -425,9 +425,24 @@ 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)
 
+## Recover a Short or video's source timing
+
+`stemlab match-clip master.wav published-original.mp4 --output new-match.json`
+locates a contiguous soundtrack excerpt without running models or downloading
+anything. It retains both original hashes, timing precision, competing source
+positions and independent window checks. Matched reports provide source offset,
+soundtrack duration and player start for synchronised consumers. Short fades and
+compression are tolerated; ambiguous repetition, edit jumps, different recordings
+and rate changes remain unresolved. Use `--clip-start` / `--clip-end` for an
+explicit known soundtrack interval. FFmpeg is required for video decoding.
+See [clip matching](docs/clip-matching.md) for limitations and a synthetic example.
+
 ## Audio-to-MIDI model comparison
 
 MIDI extraction is an **optional, independent model pass**. It adds Transkun V2

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/src/danceflow_stemlab.egg-info/SOURCES.txt

@@ -48,6 +48,8 @@ src/stemlab/bootstrap.py
 src/stemlab/branding.py
 src/stemlab/canonical.py
 src/stemlab/cli.py
+src/stemlab/clip_cli.py
+src/stemlab/clip_match.py
 src/stemlab/cue_cli.py
 src/stemlab/cues.py
 src/stemlab/lyric_lrc.py
@@ -124,6 +126,7 @@ 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
@@ -132,6 +135,7 @@ tests/test_branding.py
 tests/test_bsroformer_adapter.py
 tests/test_canonical.py
 tests/test_canonical_extended.py
+tests/test_clip_match.py
 tests/test_codex_bridge.py
 tests/test_codex_jobs.py
 tests/test_codex_package.py

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/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.4.0"
+__version__ = "1.4.2"

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/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."""

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/src/stemlab/analysis/phrase_loops.py

@@ -15,7 +15,8 @@ import soundfile as sf
 
 from stemlab.util import sha256_file
 from .loops import (LoopConfig, _gates, _grid, _vocal_intervals, _write_json,
-                    index_loop_report, load_loop_evidence, optimize_join, spectral_context)
+                    detected_bar_phase_metrics, index_loop_report, load_loop_evidence,
+                    optimize_join, spectral_context)
 from .rudiment_matches import extract_peak_events
 
 
@@ -26,6 +27,7 @@ class PhraseLoopConfig:
     min_lines: int = 4
     top: int = 6
     max_overlap: float = 0.60
+    max_bar_phase_error: float | None = None
 
     def __post_init__(self):
         for key in ("min_seconds", "max_seconds", "max_overlap"):
@@ -38,6 +40,11 @@ class PhraseLoopConfig:
             raise ValueError("Require 0 < min_seconds <= max_seconds")
         if not 0 <= self.max_overlap < 1:
             raise ValueError("max_overlap must be in [0, 1)")
+        if self.max_bar_phase_error is not None:
+            value = self.max_bar_phase_error
+            if (isinstance(value, bool) or not isinstance(value, (float, int))
+                    or not math.isfinite(value) or not 0 <= value <= .5):
+                raise ValueError('max_bar_phase_error must be None or finite in [0, .5]')
         for key, upper in (("min_lines", 128), ("top", 64)):
             value = getattr(self, key)
             if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= upper:
@@ -178,7 +185,7 @@ def analyze_phrase_loops(audio_path: Path, output_dir: Path, *, canonical: dict,
     source_hash = sha256_file(audio_path)
     lines = _canonical_lines(canonical, len(audio)/sr)
     ratings, excluded = _feedback(feedback, source_hash, len(audio), lines, sr)
-    model, beats, _down, errors = _grid(beat_results, len(audio)/sr)
+    model, beats, down, errors = _grid(beat_results, len(audio)/sr)
     strict_cfg = LoopConfig(snap_ms=0)
     gates, vocal_errors = _gates(stems, len(audio)/sr, strict_cfg, normalization_gains or {})
     intervals, timing_sources = _vocal_intervals(whisper_result, lyrics_result, canonical)
@@ -208,6 +215,14 @@ def analyze_phrase_loops(audio_path: Path, output_dir: Path, *, canonical: dict,
             if not phase["available"]:
                 rejected["missing_grid"] += 1
                 continue
+            bar_phase = detected_bar_phase_metrics(beats, down, a/sr, b/sr)
+            if cfg.max_bar_phase_error is not None:
+                if not bar_phase['available']:
+                    rejected['missing_bar_phase'] += 1
+                    continue
+                if bar_phase['bar_phase_error'] > cfg.max_bar_phase_error+1e-12:
+                    rejected['bar_phase_mismatch'] += 1
+                    continue
             context = musical_restart_context(audio, sr, a, b,
                                                phase["local_period_seconds"], events)
             if not context["available"]:
@@ -233,7 +248,7 @@ def analyze_phrase_loops(audio_path: Path, output_dir: Path, *, canonical: dict,
             pool.append(dict(start_sample=a,end_sample=b,duration_samples=b-a,
                 start_seconds=a/sr,end_seconds=b/sr,duration_seconds=duration,
                 included_lyrics=lines[i:j+1],canonical_line_indices=[i,j],
-                restart_context=context,phase=phase,join=join,
+                restart_context=context,phase=phase,detected_bar_phase=bar_phase,join=join,
                 vocal_clear=all(acoustic_clear) and all(timing_clear),
                 acoustic_clear=acoustic_clear,timing_clear=timing_clear,
                 failed_gates=failed,ranking_cost=cost,feedback_duration_cost=duration_cost,
@@ -275,6 +290,7 @@ def analyze_phrase_loops(audio_path: Path, output_dir: Path, *, canonical: dict,
             "Bad section passages and exact canonical-word repeats excluded; all rated near-duplicates suppressed.",
             "Missing attack similarity stays null; available context weights are reported.",
             "Strict loop search and its acceptance gates are unchanged.",
+            "Optional detected bar-phase filter uses enclosing downbeats and consistent measured beats per bar; it does not prove meter, harmony or listening quality.",
             "Native audio slices only; no snap, fade, crossfade, stretch or normalisation."])
     _write_json(output_dir/"phrase_loops.json",report)
     return report

{danceflow_stemlab-1.4.0 → danceflow_stemlab-1.4.2}/src/stemlab/cli.py

@@ -14,6 +14,7 @@ from rich.table import Table
 from .analysis.registry import ACTIONS
 from .bootstrap import bootstrap as do_bootstrap
 from .branding import AUTHOR_NAME, AUTHOR_SITE, MY_SONGS_URL, PROJECT_DESCRIPTION, REPOSITORY_URL
+from .clip_cli import register_clip_commands
 from .cue_cli import print_cue_review, register_cue_commands
 from .models import MODEL_REGISTRY, profile as resolve_profile
 from .pipeline import run_pipeline
@@ -23,6 +24,7 @@ from .util import device_string
 app = typer.Typer(no_args_is_help=True, pretty_exceptions_show_locals=False, help=PROJECT_DESCRIPTION)
 console = Console()
 register_cue_commands(app, console)
+register_clip_commands(app, console)
 
 
 @app.command("repair-spectrograms")
@@ -274,6 +276,8 @@ def find_phrase_loops(
     max_seconds: Annotated[float, typer.Option("--max-seconds", min=0.001)] = 30.0,
     min_lines: Annotated[int, typer.Option("--min-lines", min=1, max=128)] = 4,
     top: Annotated[int, typer.Option("--top", min=1, max=64)] = 6,
+    max_bar_phase_error: Annotated[float | None, typer.Option("--max-bar-phase-error", min=0, max=.5,
+        help="Optional maximum cut-position mismatch as a fraction of a measured bar")] = None,
     export_audio: Annotated[bool, typer.Option("--export-audio")] = False,
 ):
     """Suggest line-complete phrases by musical restart; never accept strict loops."""
@@ -284,7 +288,8 @@ def find_phrase_loops(
         ratings = json.loads(feedback.read_text(encoding="utf-8")) if feedback else None
         report = analyze_existing_phrase_loops(results, feedback=ratings, export_audio=export_audio,
             config=PhraseLoopConfig(min_seconds=min_seconds,max_seconds=max_seconds,
-                                    min_lines=min_lines,top=top))
+                                    min_lines=min_lines,top=top,
+                                    max_bar_phase_error=max_bar_phase_error))
     except (ValueError, TypeError, KeyError, OSError) as exc:
         raise typer.BadParameter(str(exc)) from exc
     console.print(f"{report['candidate_count']} phrase audition candidate(s); "

danceflow_stemlab-1.4.2/src/stemlab/clip_cli.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+
+def register_clip_commands(app, console):
+    @app.command("match-clip")
+    def match_clip_command(
+        source: Annotated[Path, typer.Argument(exists=True, dir_okay=False)],
+        clip: Annotated[Path, typer.Argument(exists=True, dir_okay=False)],
+        output: Annotated[Path, typer.Option("--output", "-o", help="New evidence JSON file")],
+        sample_rate: Annotated[int, typer.Option("--sample-rate", min=2000, max=24000)] = 8000,
+        clip_start: Annotated[float, typer.Option("--clip-start", min=0)] = 0.0,
+        clip_end: Annotated[float | None, typer.Option("--clip-end", min=0)] = None,
+    ):
+        """Locate a contiguous audio/video excerpt in its source; no models run."""
+        from .clip_match import match_clip
+        from .util import write_json
+
+        if output.exists() or output.resolve() in (source.resolve(), clip.resolve()):
+            raise typer.BadParameter("Output must be a new file, separate from the inputs")
+        try:
+            report = match_clip(source, clip, sample_rate=sample_rate,
+                                clip_start=clip_start, clip_end=clip_end)
+        except (OSError, ValueError) as exc:
+            raise typer.BadParameter(str(exc)) from exc
+        write_json(output, report)
+        console.print(f"{report['status']}: {report['reason']}")
+        console.print(str(output))
+        if report["status"] != "matched":
+            raise typer.Exit(2)

danceflow_stemlab-1.4.2/src/stemlab/clip_match.py

@@ -0,0 +1,190 @@
+"""Find a contiguous recording excerpt on its source clock, without models.
+
+Matching proves a measured waveform relationship, never public-use rights or
+artist approval. AAC/MP3 encoding and fades are tolerated; ambiguous repetition,
+edit jumps, silence, different performances and rate changes remain unresolved.
+"""
+from __future__ import annotations
+
+import math
+import shutil
+import subprocess
+from pathlib import Path
+
+import numpy as np
+from scipy.signal import correlate, resample_poly
+
+from .util import sha256_file
+
+
+def _samples(value: np.ndarray) -> np.ndarray:
+    value = np.asarray(value, dtype=np.float64)
+    if value.ndim == 1:
+        value = value[:, None]
+    if value.ndim != 2 or not value.size or not np.all(np.isfinite(value)):
+        raise ValueError("Audio must contain finite frames with one or two channels")
+    if value.shape[1] not in (1, 2):
+        raise ValueError("Only mono and stereo inputs are supported")
+    return value
+
+
+def _correlation(source: np.ndarray, query: np.ndarray) -> np.ndarray:
+    """Sliding, channel-preserving, zero-mean normalised correlation."""
+    if source.shape[1] != query.shape[1]:
+        if source.shape[1] == 1:
+            source = np.repeat(source, query.shape[1], axis=1)
+        else:
+            query = np.repeat(query, source.shape[1], axis=1)
+    n = len(query)
+    query = query - query.mean(axis=0)
+    energy = float(np.sum(query * query))
+    if energy <= 1e-12:
+        return np.zeros(len(source) - n + 1)
+    numerator = np.zeros(len(source) - n + 1)
+    variance = np.zeros_like(numerator)
+    for channel in range(source.shape[1]):
+        signal = source[:, channel]
+        numerator += correlate(signal, query[:, channel], mode="valid", method="fft")
+        total = np.concatenate(([0.0], np.cumsum(signal)))
+        square = np.concatenate(([0.0], np.cumsum(signal * signal)))
+        sums = total[n:] - total[:-n]
+        variance += square[n:] - square[:-n] - sums * sums / n
+    norm = np.sqrt(np.maximum(variance, 0) * energy)
+    return np.clip(np.divide(numerator, norm, out=np.zeros_like(norm), where=norm > 1e-12), -1, 1)
+
+
+def match_samples(source: np.ndarray, clip: np.ndarray, sample_rate: int, *,
+                  min_correlation: float = 0.90, min_margin: float = 0.02,
+                  tolerance_seconds: float = 0.002) -> dict:
+    """Return conservative timing evidence for already decoded equal-rate PCM."""
+    source, clip = _samples(source), _samples(clip)
+    if not isinstance(sample_rate, int) or sample_rate < 1:
+        raise ValueError("sample_rate must be a positive integer")
+    if (not math.isfinite(min_correlation) or not 0 < min_correlation <= 1 or
+            not math.isfinite(min_margin) or not 0 <= min_margin <= 1 or
+            not math.isfinite(tolerance_seconds) or tolerance_seconds <= 0):
+        raise ValueError("Invalid matching thresholds")
+    report = {"status": "unresolved", "mapping": None, "candidates": [], "anchors": [],
+              "analysis_sample_rate": sample_rate, "precision_seconds": 1 / sample_rate,
+              "source_duration_seconds": len(source) / sample_rate,
+              "clip_duration_seconds": len(clip) / sample_rate,
+              "thresholds": {"min_correlation": min_correlation, "min_margin": min_margin,
+                             "offset_tolerance_seconds": tolerance_seconds}}
+    if len(clip) < 2 * sample_rate or len(clip) > len(source):
+        return {**report, "reason": "Clip needs at least two seconds and must fit in the source"}
+    edge = min(round(0.25 * sample_rate), len(clip) // 10)
+    query = clip[edge:len(clip) - edge]
+    if np.std(query) < 1e-7:
+        return {**report, "reason": "Silent or constant clip has insufficient timing information"}
+    scores = _correlation(source, query)
+    remaining = scores.copy()
+    exclusion = max(1, round(0.5 * sample_rate))
+    for _ in range(min(5, len(scores))):
+        index = int(np.argmax(remaining))
+        if not np.isfinite(remaining[index]):
+            break
+        report["candidates"].append({"offset_samples": index - edge,
+                                     "offset_seconds": (index - edge) / sample_rate,
+                                     "correlation": float(scores[index])})
+        remaining[max(0, index - exclusion):index + exclusion + 1] = -np.inf
+    best = report["candidates"][0]
+    offset = best["offset_samples"]
+    second = report["candidates"][1]["correlation"] if len(report["candidates"]) > 1 else 0
+    report["correlation_margin"] = best["correlation"] - second
+    if best["correlation"] < min_correlation:
+        return {**report, "reason": "No strong contiguous waveform match"}
+    if offset < 0 or offset + len(clip) > len(source):
+        return {**report, "reason": "Matched interval extends outside the source; inspect clip range"}
+    anchor_frames = min(sample_rate, len(query) // 3)
+    starts = np.linspace(edge, len(clip) - edge - anchor_frames, 5).round().astype(int)
+    search_radius = max(1, round(0.05 * sample_rate))
+    for start in starts:
+        expected = offset + int(start)
+        left = max(0, expected - search_radius)
+        right = min(len(source), expected + anchor_frames + search_radius)
+        section = clip[start:start + anchor_frames]
+        if np.std(section) < 1e-7:
+            report["anchors"].append({"clip_time": start / sample_rate, "correlation": 0.0,
+                                       "informative": False, "offset_error_seconds": None})
+            continue
+        anchor_scores = _correlation(source[left:right], section)
+        index = int(np.argmax(anchor_scores))
+        actual_offset = left + index - int(start)
+        report["anchors"].append({"clip_time": start / sample_rate, "informative": True,
+                                   "correlation": float(anchor_scores[index]),
+                                   "offset_seconds": actual_offset / sample_rate,
+                                   "offset_error_seconds": (actual_offset - offset) / sample_rate})
+    reliable = [a for a in report["anchors"] if a["informative"]]
+    if len(reliable) < 3 or any(a["correlation"] < min_correlation or
+                               abs(a["offset_error_seconds"]) > tolerance_seconds for a in reliable):
+        return {**report, "reason": "Independent windows disagree; possible edit, speed change or mismatch"}
+    if report["correlation_margin"] < min_margin:
+        return {**report, "reason": "Repeated audio gives ambiguous source positions"}
+    return {**report, "status": "matched", "reason": "Unique contiguous match with consistent independent windows",
+            "mapping": {"offset": offset / sample_rate, "duration": len(clip) / sample_rate,
+                        "playerStart": 0.0}}
+
+
+def decode_audio(path: Path, sample_rate: int = 8000, *, max_seconds: float = 1800) -> np.ndarray:
+    """Decode a local audio/video file; retain stereo phase and bound memory/time."""
+    import soundfile as sf
+
+    path = Path(path)
+    if not path.is_file():
+        raise ValueError("Expected an existing local audio or video file")
+    if not isinstance(sample_rate, int) or not 2000 <= sample_rate <= 24000:
+        raise ValueError("Analysis rate must be an integer from 2000 to 24000 Hz")
+    if not math.isfinite(max_seconds) or not 2 <= max_seconds <= 7200:
+        raise ValueError("Decode limit must be between two seconds and two hours")
+    try:
+        info = sf.info(str(path))
+    except (sf.LibsndfileError, RuntimeError):
+        info = None
+    if info is not None:
+        if info.duration > max_seconds or info.channels not in (1, 2):
+            raise ValueError("Audio exceeds the decode limit or is not mono/stereo")
+        data, native_rate = sf.read(str(path), dtype="float32", always_2d=True)
+        if native_rate != sample_rate:
+            divisor = math.gcd(native_rate, sample_rate)
+            data = resample_poly(data, sample_rate // divisor, native_rate // divisor, axis=0)
+        return _samples(data)
+    ffmpeg = shutil.which("ffmpeg")
+    if ffmpeg is None:
+        raise ValueError("FFmpeg is required to decode this local video/audio format")
+    result = subprocess.run([ffmpeg, "-nostdin", "-v", "error", "-i", str(path),
+                             "-map", "0:a:0", "-vn", "-t", str(max_seconds + 0.1),
+                             "-ac", "2", "-ar", str(sample_rate), "-f", "f32le", "pipe:1"],
+                            capture_output=True, timeout=120, check=True)
+    data = np.frombuffer(result.stdout, dtype="<f4")
+    if data.size % 2 or data.size > max_seconds * sample_rate * 2:
+        raise ValueError("Decoded audio is incomplete or exceeds the decode limit")
+    return _samples(data.reshape(-1, 2))
+
+
+def match_clip(source_path: Path, clip_path: Path, *, sample_rate: int = 8000,
+               clip_start: float = 0.0, clip_end: float | None = None,
+               min_correlation: float = 0.90, min_margin: float = 0.02) -> dict:
+    """Analyse immutable local files and return hash-bound source/player timing."""
+    source_path, clip_path = Path(source_path), Path(clip_path)
+    source_hash, clip_hash = sha256_file(source_path), sha256_file(clip_path)
+    source = decode_audio(source_path, sample_rate)
+    clip = decode_audio(clip_path, sample_rate)
+    if not math.isfinite(clip_start) or clip_start < 0:
+        raise ValueError("clip_start must be a finite non-negative time")
+    if clip_end is not None and (not math.isfinite(clip_end) or clip_end <= clip_start):
+        raise ValueError("clip_end must be finite and later than clip_start")
+    first = round(clip_start * sample_rate)
+    last = len(clip) if clip_end is None else round(clip_end * sample_rate)
+    if first >= len(clip) or last > len(clip):
+        raise ValueError("Selected clip interval must fit in the decoded audio")
+    report = match_samples(source, clip[first:last], sample_rate,
+                           min_correlation=min_correlation, min_margin=min_margin)
+    if report["mapping"] is not None:
+        report["mapping"]["playerStart"] = first / sample_rate
+    from . import __version__
+    if source_hash != sha256_file(source_path) or clip_hash != sha256_file(clip_path):
+        raise ValueError("An input file changed during matching; discard this result")
+    return {"schema": "stemlab.clip-match.v1", "stemlab_version": __version__,
+            "source": {"path": str(source_path), "sha256": source_hash},
+            "clip": {"path": str(clip_path), "sha256": clip_hash},
+            "clip_range_seconds": [first / sample_rate, last / sample_rate], **report}