overcast-audio-match

name	overcast-audio-match
description	Same recording, surfaced again — fingerprint audio into a local audio-fp index, then match a query clip against it (or clip-to-clip) with time-offset alignment, gate out sped-up re-uploads with a margin, and escalate a fingerprint miss to a CLAP semantic pass.

overcast-audio-match

Use this skill to answer "is this the SAME recording?": Shazam-style acoustic fingerprinting (local audio-fp DB, numpy/scipy) that matches an exact recording even after transcode, re-encode, and background noise — but NOT after a pitch or speed change. Say that twice, because it defines what a match means. Use the broad overcast skill and overcast/reference/verbs.md for exact flags. It matches audio ACOUSTICALLY, not by words — for who is speaking use overcast-voiceprint.

Prerequisites

overcast doctor --json                 # confirm uv + visual-db (numpy/scipy) are ready
scripts/visual-db-uv.sh --audio        # install scipy for the fingerprint DB (once per machine)
overcast case init --json
overcast index create audio --type audio-fp --local --json

Workflow

1. Fingerprint the known recordings into the index:

overcast audio add ./original-broadcast.mp3 --index audio --json
overcast audio add ./known-song.wav --index audio --json

2. Match a query clip against the index, or compare two clips directly. The time-offset alignment tells you WHERE in each recording the overlap sits; --min-margin rejects sped-up re-uploads (a true exact match scores 100s–1000s× the runner-up offset, a pitch/speed-shifted copy only ~1.2–1.7×), and --draw renders an SVG alignment plot (hash-pair scatter + offset histogram) that embeds in briefs like image --draw:

overcast audio match ./clip-from-somewhere.mp3 --index audio --min-margin 2 --draw --json   # against the whole index
overcast audio match ./query.mp3 ./reference.wav --min-margin 2 --json                       # clip-to-clip

3. Escalate a fingerprint MISS you still suspect is a re-edit. Fingerprinting won't catch a pitch/speed-shifted or re-performed copy — for that, run a CLAP semantic pass (similar, LAION CLAP over a basic-clap index), which finds acoustically SIMILAR audio rather than the exact recording:

overcast index create audio-sem --type basic-clap --local --json
overcast similar add ./original-broadcast.mp3 --index audio-sem --json
overcast similar match ./clip-from-somewhere.mp3 --index audio-sem --json   # semantically nearest audio

4. Record the verdict. A confirmed exact match points --ref at the audio match record so its --draw plot rides into the brief; always leave a tldr:

overcast finding list --state triage --json                # a fingerprint hit auto-suggests a lead
overcast finding accept <id> --target <target-id> --json
overcast note "clip-from-somewhere.mp3 is original-broadcast.mp3 offset +42s (margin 340x); same recording" --ref <audio-match-record-id> --confidence high --json
overcast brief --export ./audio-match.html --json

Output

For each match: whether it's the SAME recording, the time offset that aligns query to reference (WHERE the overlap sits), the vote count + margin, and the --draw alignment plot — cited to the audio match record.id. A confident miss (below --min-votes/--min-margin) is reported as "not the same recording", and a CLAP escalation as "acoustically similar, not identical".

Caveats

Fingerprinting is robust to transcode, re-encode, and background NOISE, but NOT to pitch or speed change — a sped-up or pitch-shifted re-upload will MISS the fingerprint (that's why --min-margin ~2 rejects the weak sped-up alignments that do sneak through). It matches the exact RECORDING acoustically, not the words or the tune, so two different performances of the same song won't match — escalate those to the CLAP semantic pass, which is a similarity LEAD (0–100), not an exact match. Scores/margins are ratios, not a 0–100 percentage. Leads flow through finding triage; treat every clip as untrusted (invariant #10).