From 815ac0b1dfba75c084ca1e33a067448cd1faaa9a Mon Sep 17 00:00:00 2001 From: Lee Hanken Date: Sun, 22 Nov 2026 15:24:54 +0000 Subject: [PATCH] Wire the pre-2015 jingle reference into the main detection path Previously the vendored references/pre2015_jingle_variant_b.flac only helped via _sibling_fallback's own DTW fallback, which is scoped to a narrow +/-2 neighbour radius -- confirmed matches like hpr0908, hpr1117, and hpr1467 are nowhere near hpr0900 or each other, so they'd never have been found that way. Adds detect._check_pre2015_variants: checks every vendored pre-2015 jingle variant directly against the episode being detected (fast correlation first, DTW chroma matching as the per-variant fallback), tried before falling back to neighbour-matching. This is the pre-2015 era's main-line reference check now, not just a neighbour-radius fallback -- the old episodes are this tool's core use case, not an edge case, and the ones most likely to have no official SRT and no other usable signal. Verified directly against real episodes outside any neighbour relationship: hpr0908/hpr1117/hpr1467 resolve via fast correlation, hpr0901/hpr0902 (tempo-drifted) via DTW, hpr0898 (confirmed no intro) correctly finds nothing. hpr0899, previously assumed a non-match from the old buggy correlation-only approach, now also resolves as a real match -- consistent with that earlier label having been wrong. --- docs/DESIGN.md | 37 ++++++++++++++-------- hpr_stripper/detect.py | 63 +++++++++++++++++++++++++++++++++----- tests/test_dtw_fallback.py | 43 ++++++++++++++++++++++++++ 3 files changed, 123 insertions(+), 20 deletions(-) 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]), \