Metadata-Version: 2.4
Name: audio-video-sync
Version: 0.4.3
Summary: Auto-sync video with separately recorded audio using cross-correlation
Project-URL: Homepage, https://github.com/sanjeed5/audio-video-sync
Project-URL: Repository, https://github.com/sanjeed5/audio-video-sync
Author: Sanjeed
License-Expression: MIT
License-File: LICENSE
Keywords: audio,cover,ffmpeg,music,sync,thumbnail,video
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: librosa>=0.10.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pillow>=10.1.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: typer>=0.13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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)
- **Low confidence warning** detects mismatched files
- **Manual offset / dry-run** for when you already know the sync point
- **Thumbnail generation** from video frames with styled text overlay

## Installation

```bash
# 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

```bash
# 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

# Detect only (no encode)
avsync sync video.mp4 audio.wav --dry-run

# Skip detection with a known offset (seconds)
avsync sync video.mp4 audio.wav --offset 17.2

# Analyze more audio / disable hardware encode
avsync sync video.mp4 audio.wav --analyze 60 --no-hwaccel
```

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

### Generate thumbnails

```bash
# 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

# JPEG output, open after generation
avsync thumb video.mp4 "Song Title" "Artist" -o cover.jpg --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). Output is resized to a 1280px long edge by default (YouTube-friendly).

## How It Works

1. **Extract audio** from video using ffmpeg
2. **Cross-correlate** using two methods with comparable confidence scores:
   - **Waveform correlation**: Compares raw audio. Precise when recordings are similar.
   - **Chromagram correlation**: Compares pitch content band-by-band. Robust to EQ, compression, reverb.
3. **Pick the best method** based on normalized confidence
4. **Merge & trim** video with synced audio (sample-accurate trim), 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 and ffprobe installed and in PATH

## License

MIT
