Skip to main content

​
Prerequisites

Before installing the video synchronization tool, ensure you have the following prerequisites:

Python 3.11+

This project requires Python 3.11 or higher due to dependencies in scipy and pandas.Check your Python version:
python --version
# or
python3 --version
Expected output:
Python 3.12.0
The project was developed and tested on Python 3.12. If you need to install or upgrade Python, visit python.org.
FFmpeg is required for audio extraction and video manipulation. It must be accessible in your system PATH.Verify FFmpeg installation:
ffmpeg -version
Expected output:
ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers
...
Install via Homebrew:
brew install ffmpeg
If FFmpeg is not in your PATH, the application will fail during audio extraction and video synchronization.

​
Installation Steps

1

Clone the Repository

Download the project source code:
git clone <repo-url>
cd video_synchronization
Replace <repo-url> with the actual repository URL.
2

Create Virtual Environment

Create an isolated Python environment for the project:
python -m venv venv
source venv/bin/activate
You should see (venv) prefix in your terminal prompt.
Using a virtual environment keeps project dependencies isolated from your system Python installation.
3

Install Dependencies

Install all required Python packages:
pip install -r requirements.txt
Required packages (from requirements.txt):
flask
opencv-python
numpy
scipy
matplotlib
tqdm
pandas
psutil
  • flask: Web UI framework for the synchronization wizard
  • opencv-python: Video frame extraction and motion analysis
  • numpy: Numerical operations and array processing
  • scipy: Signal processing, FFT, and optimization algorithms
  • matplotlib: Visualization of motion signals and sync indicators
  • tqdm: Progress bars for long-running operations
  • pandas: Data handling in the evaluation suite
  • psutil: Resource monitoring (CPU, memory usage)
Installation time: Approximately 2-5 minutes depending on your internet connection.
4

Verify Installation

Test that everything is installed correctly:
python -c "import cv2, scipy, flask, numpy; print('All dependencies installed successfully!')"
Expected output:
All dependencies installed successfully!
If you see this message, your installation is complete!

​
Project Structure

After installation, your project directory should look like this: 
video_synchronization/
├── main.py                  # Application entry point
├── requirements.txt         # Python dependencies
├── src/
│   ├── config.py           # Configuration settings
│   ├── ui.py               # Flask web interface
│   ├── visual_sync.py      # Motion-based synchronization
│   ├── audio_sync.py       # Audio-based synchronization
│   ├── video_sync.py       # Video offset application
│   ├── sync_indicators.py  # Visual sync indicators
│   ├── preprocess.py       # Audio extraction utilities
│   └── utils.py            # Helper functions
├── evaluation/             # Evaluation suite (optional)
│   ├── offset_generation.py
│   ├── run_batch.py
│   ├── compute_metrics.py
│   └── visualize_results.py
└── logs/                   # Application logs (auto-created)
The evaluation/ directory is optional and only needed if you want to assess synchronization accuracy on synthetic test data.

​
Configuration

The synchronization method is configured in src/config.py:
src/config.py
# Sync method: "visual" (motion-based) or "audio" (GCC-PHAT)
SYNC_METHOD = "visual"

# Directories (uses system temp directory)
TEMP_BASE = os.path.join(tempfile.gettempdir(), "video_synchronization")
VIDEO_DIR = os.path.join(TEMP_BASE, "raw")
OUTPUT_DIR = os.path.join(TEMP_BASE, "synced")
AUDIO_DIR = os.path.join(TEMP_BASE, "audio")

Visual Sync

Best for:
  • Silent videos
  • Noisy environments
  • Different camera angles
SYNC_METHOD = "visual"

Audio Sync

Best for:
  • Videos with clear audio
  • High-precision alignment
  • Similar audio across all cameras
SYNC_METHOD = "audio"
You must restart the application after changing SYNC_METHOD in src/config.py. The sync method cannot be changed from the web UI.

​
Troubleshooting

Error message:
FileNotFoundError: FFmpeg not found in system PATH
Solution:
  1. Verify FFmpeg installation: ffmpeg -version
  2. If not installed, follow the FFmpeg installation steps
  3. Restart your terminal after installation
  4. Verify it’s in PATH: which ffmpeg (macOS/Linux) or where ffmpeg (Windows)
Error message:
ERROR: Package requires a different Python: 3.10.0 not in '>=3.11'
Solution:
  1. Install Python 3.11 or higher from python.org
  2. Create a new virtual environment with the correct version: 
    python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Error message:
ImportError: libGL.so.1: cannot open shared object file
Solution (Linux only):
sudo apt-get update
sudo apt-get install libgl1-mesa-glx
Error message:
PermissionError: [Errno 13] Permission denied: '/var/folders/...'
Solution: The app uses your system’s temp directory. If you encounter permissions issues, modify src/config.py:
TEMP_BASE = os.path.expanduser("~/video_sync_temp")

​
Next Steps

Quick Start

Learn how to synchronize your first set of videos

Configuration

Customize sync parameters and processing options
Installation complete! Run python main.py to start the web interface.

Build docs developers (and LLMs) love

Get started for freeTalk to us