audio-video-sync

Auto-sync video with separately recorded audio using cross-correlation.

Perfect for music covers where you record video on your phone and audio in a DAW separately.

Features

• Auto sync detection using cross-correlation (waveform + chromagram)
• Auto trim output to match replacement audio duration
• VFR to CFR conversion prevents sync drift on phone videos
• Hardware acceleration on macOS (VideoToolbox) - 4.7x faster
• Low confidence warning detects mismatched files
• Thumbnail generation from video frames with styled text overlay

Installation

# Requires FFmpeg
brew install ffmpeg  # macOS

# Install from PyPI
pip install audio-video-sync

# Or with uv
uv tool install audio-video-sync

Usage

Sync video with audio

# Auto-detects sync and creates video_synced.mp4
avsync sync video.mp4 audio.wav

# Specify output file
avsync sync video.mp4 audio.wav -o output.mp4

Output video will be automatically trimmed to match the replacement audio's duration.

Generate thumbnails

# Generate clean + gradient style thumbnails
avsync thumb video.mp4 "Song Title" "Artist"

# Pick a specific style and frame time
avsync thumb video.mp4 "Song Title" -s clean -t 15

# Open result after generation
avsync thumb video.mp4 "Song Title" "Artist" --open

Extracts a frame from the video, applies a soft blur, and overlays styled text. Two styles available: clean (text with glow shadow) and gradient (dark vignette band with white text).

How It Works

1. Extract audio from video using ffmpeg
2. Cross-correlate using two methods:
   • Waveform correlation: Compares raw audio. Precise when recordings are similar.
   • Chromagram correlation: Compares pitch content. Robust to EQ, compression, reverb.
3. Pick the best method based on confidence score
4. Merge & trim video with synced audio, converting VFR to CFR

Use Case

You recorded a cover:

• Phone video has your performance + room noise
• DAW export has clean, polished audio

This tool finds the exact offset, syncs them, and outputs a video matching your audio's timing.

Requirements

• Python 3.10+
• FFmpeg installed and in PATH

License

MIT