diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 626db8b..c2aad4a 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -660,18 +660,31 @@ history and `tests/`, not duplicated here: content](images/pre2015_jingle_envelope_match.png) (2) is why chroma-feature DTW matching (`audio.dtw_chroma_match`) was - added as a last-resort fallback inside `_sibling_fallback`, tried only - when fixed-lag correlation finds nothing: DTW doesn't assume one global - alignment, so it isn't defeated by internal tempo drift, and its - warping-path end position gives a real intro_end estimate for the - candidate, not just a yes/no. Calibrated on real episodes: confirmed/ - likely matches (hpr0908, hpr1117, hpr1467, hpr0901, hpr0902) scored - normalized cost 0.09-0.17 against the reference; a confirmed non-match - (hpr0898, no intro at all) scored 0.94 — - `config.DTW_MATCH_THRESHOLD` (0.35) sits generously between the two. - This is the thing a plain chroma *classifier* (below) can't do: it's - matching against a *specific* reference clip, not asking "does this - sound musical in general." + added: DTW doesn't assume one global alignment, so it isn't defeated by + internal tempo drift, and its warping-path end position gives a real + intro_end estimate for the candidate, not just a yes/no. Calibrated on + real episodes: confirmed/likely matches (hpr0908, hpr1117, hpr1467, + hpr0901, hpr0902) scored normalized cost 0.09-0.17 against the + reference; a confirmed non-match (hpr0898, no intro at all) scored + 0.94 — `config.DTW_MATCH_THRESHOLD` (0.35) sits generously between the + two. This is the thing a plain chroma *classifier* (below) can't do: + it's matching against a *specific* reference clip, not asking "does + this sound musical in general." + + `detect._check_pre2015_variants` is the main-line check against every + vendored variant (fast correlation first, DTW as the per-variant + fallback), tried for *every* pre-2015 episode before falling back to + neighbour-matching — not confined to `_sibling_fallback`'s small ±2 + neighbour radius. This matters more than it might first appear: the + pre-2015 episodes are this tool's core use case, not an edge case — + they're the ones most likely to have no official SRT and no other + usable signal, so the detection needs to work for any one of them, not + just ones lucky enough to have a same-variant neighbour nearby. + Confirmed directly: hpr0908, hpr1117, and hpr1467 are nowhere near + hpr0900 or each other, so they'd never have been found through + `_sibling_fallback`'s radius at all — only through this direct check. + (`_sibling_fallback`'s own DTW fallback still exists underneath, for + whatever jingle variants aren't vendored yet.) Only one variant is vendored so far; a random 40-episode sample found it in ~5% of episodes (hpr0900, hpr0908, hpr1117, hpr1467), spread diff --git a/hpr_stripper/detect.py b/hpr_stripper/detect.py index 0a22b92..b967798 100644 --- a/hpr_stripper/detect.py +++ b/hpr_stripper/detect.py @@ -27,6 +27,7 @@ a flag rather than silently resolved in either direction. Nothing here ever guesses: an episode with no usable signal is flagged for manual review, never given a plausible-looking wrong answer. """ +import glob import os from dataclasses import dataclass from typing import Optional @@ -147,6 +148,48 @@ def _best_sibling_estimate(estimates, min_confident_seconds=2): return best, flag +def _pre2015_variant_paths(): + """Every vendored pre-2015 jingle variant, e.g. + references/pre2015_jingle_variant_b.flac -- there's only one so far, + but the naming is deliberately open-ended so more can be added the + same way they were found (see docs/DESIGN.md).""" + return sorted(glob.glob(os.path.join(config.REFERENCES_DIR, "pre2015_jingle_variant_*.flac"))) + + +def _check_pre2015_variants(audio_path): + """Checks audio_path's opening against every vendored pre-2015 jingle + variant: fast correlation first (cheap, catches an exact/near-exact + copy), falling back to DTW chroma matching per variant (tried only if + correlation found nothing for that variant -- see + audio.dtw_chroma_match's docstring for why fixed-lag correlation alone + isn't enough here). This is the pre-2015 era's main-line reference + check, not just a neighbour-radius fallback -- the old episodes are + this tool's core use case, and they're the ones most likely to have no + official SRT and no other usable signal, so this needs to work for any + episode, not just ones lucky enough to have a same-variant neighbour + within _sibling_fallback's small search radius. + + Returns (intro_end_seconds, method_label) for the first variant that + matches, or (None, None) if none do.""" + for variant_path in _pre2015_variant_paths(): + variant_name = os.path.splitext(os.path.basename(variant_path))[0] + try: + xcorr = audio.reference_prefix_match_seconds(audio_path, variant_path) + except Exception: + xcorr = None + if xcorr and xcorr > 2: + return xcorr, f"pre2015_reference_xcorr:{variant_name}" + try: + dtw_result = audio.dtw_chroma_match(variant_path, audio_path) + except Exception: + dtw_result = None + if dtw_result is not None: + cost, end_seconds = dtw_result + if cost <= config.DTW_MATCH_THRESHOLD: + return end_seconds, f"pre2015_reference_dtw:{variant_name}" + return None, None + + def _sibling_fallback(audio_path, duration, ep_id, cache_dir, settings, neighbour_audio_paths, suffix): """Shared by both the intro and outro sibling-correlation fallback -- they're symmetric except for which end of the clip is compared.""" @@ -320,15 +363,19 @@ def detect(ep_id, cache_dir, settings, neighbour_audio_paths=None): elif theme_xcorr and theme_xcorr > 2: result.intro_end, result.intro_method = theme_xcorr, "reference_xcorr" else: - median, flag, neighbour_audio_paths = _sibling_fallback( - audio_path, duration, ep_id, cache_dir, settings, neighbour_audio_paths, suffix=False) - if median is not None: - result.intro_end, result.intro_method = median, "sibling_xcorr_fallback" - if flag: - result.intro_flag = flag + variant_end, variant_method = _check_pre2015_variants(audio_path) + if variant_end is not None: + result.intro_end, result.intro_method = variant_end, variant_method else: - result.intro_method = "none" - result.intro_flag = "no_signal" + median, flag, neighbour_audio_paths = _sibling_fallback( + audio_path, duration, ep_id, cache_dir, settings, neighbour_audio_paths, suffix=False) + if median is not None: + result.intro_end, result.intro_method = median, "sibling_xcorr_fallback" + if flag: + result.intro_flag = flag + else: + result.intro_method = "none" + result.intro_flag = "no_signal" # --- Layer 2: metadata-duration arithmetic -------------------------- # eps.duration appears to hold the raw submitted (pre-intro/outro) diff --git a/tests/test_dtw_fallback.py b/tests/test_dtw_fallback.py index 04b0d12..ae4e1e2 100644 --- a/tests/test_dtw_fallback.py +++ b/tests/test_dtw_fallback.py @@ -39,6 +39,49 @@ class TestDtwChromaMatchResilience(unittest.TestCase): self.assertIsNone(result) +class TestCheckPre2015Variants(unittest.TestCase): + """detect._check_pre2015_variants is the pre-2015 era's main-line + reference check (not just the narrow ±2 neighbour-radius fallback in + _sibling_fallback) -- the old episodes are this tool's core use case, + and the most likely to have no official SRT and no other usable + signal, so this needs to work for any episode, not just ones lucky + enough to have a same-variant neighbour nearby.""" + + def test_uses_fast_correlation_when_it_finds_a_match(self): + with mock.patch("hpr_stripper.detect._pre2015_variant_paths", + return_value=["/refs/pre2015_jingle_variant_b.flac"]), \ + mock.patch("hpr_stripper.audio.reference_prefix_match_seconds", return_value=32.0), \ + mock.patch("hpr_stripper.audio.dtw_chroma_match") as dtw_mock: + end, method = detect._check_pre2015_variants("/tmp/ep.mp3") + dtw_mock.assert_not_called() + self.assertEqual(end, 32.0) + self.assertEqual(method, "pre2015_reference_xcorr:pre2015_jingle_variant_b") + + def test_falls_back_to_dtw_when_correlation_finds_nothing(self): + with mock.patch("hpr_stripper.detect._pre2015_variant_paths", + return_value=["/refs/pre2015_jingle_variant_b.flac"]), \ + mock.patch("hpr_stripper.audio.reference_prefix_match_seconds", return_value=0.0), \ + mock.patch("hpr_stripper.audio.dtw_chroma_match", return_value=(0.15, 31.1)): + end, method = detect._check_pre2015_variants("/tmp/ep.mp3") + self.assertEqual(end, 31.1) + self.assertEqual(method, "pre2015_reference_dtw:pre2015_jingle_variant_b") + + def test_no_variants_match_returns_none_none(self): + with mock.patch("hpr_stripper.detect._pre2015_variant_paths", + return_value=["/refs/pre2015_jingle_variant_b.flac"]), \ + mock.patch("hpr_stripper.audio.reference_prefix_match_seconds", return_value=0.0), \ + mock.patch("hpr_stripper.audio.dtw_chroma_match", return_value=(0.94, 2.0)): + end, method = detect._check_pre2015_variants("/tmp/ep.mp3") + self.assertIsNone(end) + self.assertIsNone(method) + + def test_no_vendored_variants_at_all_returns_none_none(self): + with mock.patch("hpr_stripper.detect._pre2015_variant_paths", return_value=[]): + end, method = detect._check_pre2015_variants("/tmp/ep.mp3") + self.assertIsNone(end) + self.assertIsNone(method) + + class TestSiblingFallbackDtwWiring(unittest.TestCase): def test_falls_through_to_dtw_when_correlation_finds_nothing(self): with mock.patch("hpr_stripper.audio.load_pcm_f32", return_value=[0.0]), \