Add --start and per-file trim/start flags for narrowing the search to a specific time window

[tandav]

Summary

Lets the user search within an arbitrary time window of each input file, not just the first N seconds. The reported offset is always in the original (un-trimmed) file's coordinates so results are directly comparable across runs.

• --start seconds (default 0) — skip the first N seconds of each input file. Combined with --trim, the considered window is [start, start + trim]. Implemented by passing the value to ffmpeg's -ss.
• --trim-of / --trim-within — per-file overrides for --trim, applied to the --find-offset-of and --within files respectively.
• --start-of / --start-within — per-file overrides for --start, same convention.
• When per-file starts differ, the returned time_offset is shifted by start_within − start_of so it points into the original --within file, not the trimmed buffer. A new time_offset_shift key on the result dict records the applied shift. The plot's x-axis is shifted by the same amount so the marked peak agrees with the printed offset.

The library function find_offset_between_files gained matching kwargs (trim1, trim2, start1, start2); shared trim/start remain as the defaults for both files.

Why

The existing --trim only narrows the search to the start of each file. Real-world use cases (finding a short excerpt in a long recording) often need:

1. The ability to skip past leading silence/intro/known-irrelevant region.
2. The ability to narrow only the long file while leaving a short excerpt full-length.
3. An offset reported in the long file's natural coordinates regardless of how the search was narrowed.

Example

audio-offset-finder --find-offset-of excerpt.wav --within long-recording.wav \
  --start-within 320 --trim-within 60

Searches only seconds 320–380 of long-recording.wav, prints e.g. Offset: 334.608 (seconds) — same value you'd get from searching the whole file.

Test plan

• pytest tests/ — all 10 tests pass, including 3 new ones covering: shared --start (offset preserved under symmetric shift, auto-correlation), per-file --start-within (offset reported in original-file coords), CLI flag wiring.
• Manual: --start-within 320 --trim-within 60 on the r4/r4_excerpt fixture returns 334.608 (matches the un-trimmed result).
• Default behavior (no new flags) is unchanged — all pre-existing tests still pass without modification.

Backward compatibility

• Default values (start=0, all per-file kwargs None) reproduce the existing behavior exactly.
• New keys on the result dict (time_offset_shift) are additive.

🤖 Generated with Claude Code