diff --git a/tools/audio-offset/README.md b/tools/audio-offset/README.md new file mode 100644 index 0000000..01aa0b8 --- /dev/null +++ b/tools/audio-offset/README.md @@ -0,0 +1,63 @@ +# 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 + +```bash +# macOS +brew install ffmpeg + +# Ubuntu/Debian +sudo apt install ffmpeg + +# Windows (via scoop) +scoop install ffmpeg +``` + +### fpcalc (Chromaprint) + +```bash +# 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 + +```bash +pip install -r requirements.txt +``` + +## Usage + +```bash +# 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.