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

{danceflow_stemlab-1.4.1 → 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.1 → danceflow_stemlab-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: danceflow-stemlab
-Version: 1.4.1
+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
@@ -431,6 +431,18 @@ These filters suggest auditions and do not establish seamless or listening appro
 
 ![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.1 → danceflow_stemlab-1.4.2}/README.md

@@ -304,6 +304,18 @@ These filters suggest auditions and do not establish seamless or listening appro
 
 ![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.1 → danceflow_stemlab-1.4.2}/plugins/stemlab/.codex-plugin/plugin.json

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

@@ -141,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.1 → 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.1
+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
@@ -431,6 +431,18 @@ These filters suggest auditions and do not establish seamless or listening appro
 
 ![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.1 → 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
@@ -133,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.1 → 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.1"
+__version__ = "1.4.2"

{danceflow_stemlab-1.4.1 → 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")

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}

danceflow_stemlab-1.4.2/tests/test_clip_match.py

@@ -0,0 +1,103 @@
+from pathlib import Path
+
+import numpy as np
+import pytest
+import soundfile as sf
+from scipy.signal import resample_poly
+from typer.testing import CliRunner
+
+from stemlab.clip_match import decode_audio, match_clip, match_samples
+
+
+def recording(rate=4000, seconds=15):
+    rng = np.random.default_rng(4701)
+    return rng.normal(0, 0.1, (rate * seconds, 2))
+
+
+def test_unique_gain_fade_noise_and_stereo_phase():
+    rate = 4000
+    source = recording(rate)
+    source[:, 1] = -source[:, 0]
+    offset = 21251
+    clip = source[offset:offset + 4 * rate].copy() * 0.5
+    clip[:rate // 4] *= np.linspace(0, 1, rate // 4)[:, None]
+    clip[-rate // 4:] *= np.linspace(1, 0, rate // 4)[:, None]
+    clip += np.random.default_rng(5).normal(0, 0.0001, clip.shape)
+    report = match_samples(source, clip, rate)
+    assert report['status'] == 'matched'
+    assert report['mapping']['offset'] == offset / rate
+    assert report['mapping']['duration'] == 4
+    assert len(report['anchors']) == 5
+
+
+def test_identical_repeated_passage_stays_ambiguous():
+    rate = 4000
+    source = recording(rate)
+    source[8 * rate:12 * rate] = source[2 * rate:6 * rate]
+    report = match_samples(source, source[2 * rate:6 * rate], rate)
+    assert report['status'] == 'unresolved'
+    assert report['mapping'] is None
+    assert 'ambiguous' in report['reason']
+
+
+@pytest.mark.parametrize('kind', ['silence', 'constant', 'different', 'edit', 'rate'])
+def test_invalid_clock_relationship_is_not_auto_mapped(kind):
+    rate = 4000
+    source = recording(rate)
+    clip = source[2 * rate:6 * rate].copy()
+    if kind == 'silence':
+        clip[:] = 0
+    elif kind == 'constant':
+        clip[:] = 0.1
+    elif kind == 'different':
+        clip = np.random.default_rng(3).normal(0, 0.1, clip.shape)
+    elif kind == 'edit':
+        clip[2 * rate:] = source[10 * rate:12 * rate]
+    else:
+        clip = resample_poly(clip, 101, 100, axis=0)
+    result = match_samples(source, clip, rate)
+    assert result['status'] == 'unresolved'
+    assert result['mapping'] is None
+
+
+@pytest.mark.parametrize('value', [float('nan'), float('inf'), -1, 0])
+def test_invalid_thresholds(value):
+    with pytest.raises(ValueError):
+        match_samples(recording(), recording(seconds=3), 4000, min_correlation=value)
+
+
+def test_local_hashes_range_and_rate_conversion(tmp_path):
+    rate = 8000
+    source = recording(rate)
+    source_path, clip_path = tmp_path / 'source.wav', tmp_path / 'clip.wav'
+    sf.write(source_path, source, rate, subtype='FLOAT')
+    # One second of unrelated material before the matching four-second excerpt.
+    clip = np.concatenate([recording(rate, 1), source[5 * rate:9 * rate]])
+    sf.write(clip_path, resample_poly(clip, 3, 2, axis=0), 12000, subtype='FLOAT')
+    result = match_clip(source_path, clip_path, clip_start=1, clip_end=5)
+    assert result['status'] == 'matched'
+    assert result['mapping'] == {'offset': 5.0, 'duration': 4.0, 'playerStart': 1.0}
+    assert len(result['source']['sha256']) == len(result['clip']['sha256']) == 64
+    assert result['schema'] == 'stemlab.clip-match.v1'
+    with pytest.raises(ValueError):
+        match_clip(source_path, clip_path, clip_end=7)
+    with pytest.raises(ValueError):
+        decode_audio(Path('https://example.invalid/source.mp4'))
+    with pytest.raises(ValueError):
+        decode_audio(source_path, max_seconds=2)
+
+
+def test_cli_preserves_existing_inputs_and_reports_unresolved(tmp_path):
+    from stemlab.cli import app
+
+    source, clip, result = tmp_path / 'source.wav', tmp_path / 'clip.wav', tmp_path / 'match.json'
+    sf.write(source, recording(), 4000, subtype='FLOAT')
+    sf.write(clip, np.zeros((12000, 2)), 4000, subtype='FLOAT')
+    runner = CliRunner()
+    output = runner.invoke(app, ['match-clip', str(source), str(clip), '--output', str(result)])
+    assert output.exit_code == 2
+    assert result.is_file()
+    before = source.read_bytes()
+    output = runner.invoke(app, ['match-clip', str(source), str(clip), '--output', str(source)])
+    assert output.exit_code == 2
+    assert source.read_bytes() == before