Skip to main content
This guide will walk you through synchronizing your first set of multi-camera videos using the Flask web UI.

​
Prerequisites

Before you begin, make sure you have:
  • Python 3.11+ installed
  • FFmpeg installed and in your system PATH
  • Completed the installation steps
  • At least 2 video files to synchronize (.mp4, .mov, or .avi)

​
Choose Your Sync Method

The application supports two synchronization methods. You must choose one before starting the application by editing src/config.py:
src/config.py
SYNC_METHOD = "visual"
Best for:
  • Silent videos or poor audio quality
  • Videos with significant motion/activity
  • Noisy recording environments
How it works: Extracts motion energy from video frames and correlates motion patterns across cameras.
The sync method cannot be changed from the UI — you must set it in src/config.py before starting the application.

​
Synchronize Your Videos

1

Start the application

From the project root directory, run:
python main.py
You should see output indicating the Flask server is running:
* Running on http://127.0.0.1:5050
2

Access the web UI

Open your browser and navigate to:
http://127.0.0.1:5050
You’ll see a multi-step wizard interface.
3

Upload your videos

  1. Click the upload area or drag and drop your video files
  2. Select 2 or more videos (.mp4, .mov, or .avi formats)
  3. Wait for the uploads to complete
Files are staged in a temporary directory (/tmp/video_synchronization/raw/).
4

Run synchronization

  1. Click the Synchronize button
  2. The system will process your videos using the configured sync method
  3. Wait for processing to complete (time depends on video length and count)
You’ll see real-time logs showing the progress.
5

Review the results

Once sync completes, you’ll see:
  • A multi-video preview player
  • Universal seek bar controlling all videos simultaneously
  • Audio master toggle (only one video plays audio at a time)
  • Computed time offsets for each video
  • Confidence scores for the alignment
Use the preview to verify that the videos are properly synchronized.
6

Export synchronized videos

Click the Download button to export all synchronized videos as a ZIP archive.The output files will have _synced appended to their names and will be:
  • Time-aligned to a common reference frame
  • Padded to the same duration (with black frames and silence)
  • Re-encoded with FFmpeg for compatibility

​
Understanding the Output

​
Time Offsets

The system displays the computed time offset for each video:
​
offset
float
  • Positive offset (+2.5s): Video starts 2.5 seconds after the reference — black frames/silence added at the beginning
  • Negative offset (-1.2s): Video starts 1.2 seconds before the reference — first 1.2 seconds trimmed
  • Zero offset (0.0s): Video is the reference timeline

​
Confidence Scores

Each sync has a confidence score between 0.0 and 1.0:
ScoreInterpretation
> 0.7High confidence — reliable sync
0.3 - 0.7Medium confidence — verify in preview
< 0.3Low confidence — may be incorrect
If you see confidence scores below 0.3, review the synchronized videos carefully. Consider:
  • Switching sync methods (audio ↔ visual)
  • Checking if videos actually overlap in time
  • Ensuring videos have sufficient motion or audio content

​
Example Session

Here’s what a typical sync session looks like: 
# 1. Set sync method
$ vim src/config.py  # Set SYNC_METHOD = "visual"

# 2. Start application
$ python main.py
* Running on http://127.0.0.1:5050

# 3. Open browser to http://127.0.0.1:5050
# 4. Upload 3 videos: cam1.mp4, cam2.mp4, cam3.mp4
# 5. Click Synchronize

# Console output:
Starting Visual (Motion) Synchronization
Step 1: Extracting motion energy from 3 videos...
  Processing video: cam1.mp4
  Completed motion extraction: 9000 frames processed
  Processing video: cam2.mp4
  Completed motion extraction: 8950 frames processed
  Processing video: cam3.mp4
  Completed motion extraction: 9020 frames processed

Step 2: Computing pairwise correlations...
  cam1.mp4 <-> cam2.mp4: offset=+1.2s, conf=0.85
  cam1.mp4 <-> cam3.mp4: offset=+0.5s, conf=0.92
  cam2.mp4 <-> cam3.mp4: offset=-0.7s, conf=0.88

Step 3: Global Optimization...
  RMSE: 0.025s

FINAL OFFSETS:
  cam1.mp4: +0.0s
  cam2.mp4: +1.2s
  cam3.mp4: +0.5s

Applying video offsets...
Synchronization complete!

​
Next Steps

Using the UI

Learn about all UI features and advanced workflows

Configuration

Customize sync parameters and processing options

Core Concepts

Understand how the sync algorithms work

Interpreting Results

Learn how to interpret confidence scores and diagnostics

​
Troubleshooting

If you see errors about FFmpeg during sync or export:
  • macOS: brew install ffmpeg
  • Windows: Download from ffmpeg.org and add to PATH
  • Linux: sudo apt install ffmpeg
Verify installation: ffmpeg -version
If all confidence scores are below 0.3:
  1. Try the other sync method: Audio ↔ Visual
  2. Check video overlap: Ensure videos were recorded at the same time
  3. Verify content: Videos need sufficient motion (visual) or clear audio (audio method)
  4. Increase max_offset_sec: Edit src/audio_sync.py or src/visual_sync.py if videos have large offsets
For large videos or many files:
  1. Reduce processing resolution: Edit downsample parameter in src/visual_sync.py
  2. Use audio sync: Generally more memory-efficient than visual
  3. Process fewer videos: Sync in batches of 3-4 instead of all at once
To speed up processing:
  1. Reduce frame skip: Edit step parameter in src/visual_sync.py (default: 3)
  2. Limit audio window: Edit window_sec in src/audio_sync.py (default: 30s)
  3. Use audio sync: Typically faster than visual for videos under 10 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us