History

Claude 494e0d08ed Add setup guide for audio offset tool Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>		2026-04-14 23:21:26 +00:00
..
README.md	Add setup guide for audio offset tool	2026-04-14 23:21:26 +00:00
find_offset.py	Switch offset tool to Chromaprint fingerprint matching	2026-04-14 23:14:46 +00:00
requirements.txt	Switch offset tool to Chromaprint fingerprint matching	2026-04-14 23:14:46 +00:00

README.md

Audio Offset Tool

Finds the time offset between a local audio file and a YouTube video's audio using Chromaprint fingerprint matching. Generates stereo comparison WAV files for ear verification.

Prerequisites

ffmpeg

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows (via scoop)
scoop install ffmpeg

fpcalc (Chromaprint)

# macOS
brew install chromaprint

# Ubuntu/Debian
sudo apt install libchromaprint-tools

# Windows
# Download from https://acoustid.org/chromaprint — extract and add to PATH

Python dependencies

pip install -r requirements.txt

Usage

# Basic usage
python find_offset.py ../../public/songs/get-lucky/audio.ogg 5NV6Rdv1a3I

# Video IDs starting with '-'
python find_offset.py ../../public/songs/meet-me-halfway/audio.ogg --yt=-GY8MhHMxLM

# Custom output directory
python find_offset.py ../../public/songs/get-lucky/audio.ogg 5NV6Rdv1a3I --out-dir ./my-compare

# JSON output (for scripting)
python find_offset.py ../../public/songs/get-lucky/audio.ogg 5NV6Rdv1a3I --json

Output

The tool prints candidate offsets ranked by fingerprint similarity and writes stereo WAV files to the output directory.

Listen to each WAV with headphones:

Left ear = local audio
Right ear = YouTube audio (shifted by candidate offset)

The file where both ears are in sync has the correct offset.