Configuration

This guide covers all configurable settings in the Multi-Camera Video Synchronization tool. All configuration is centralized in src/config.py.

Configuration changes require restarting the application to take effect. The UI does not dynamically reload config values.

Configuration File Location

The configuration file is located at:

project_root/
└── src/
    └── config.py

Source: config.py:1-31

Synchronization Method

SYNC_METHOD

string

default:"visual"

Determines the algorithm used for detecting temporal offsets between videos.Options:

"visual": Motion-based synchronization (default)
"audio": GCC-PHAT audio cross-correlation

Location: config.py:8

Visual Synchronization (Motion-Based)

How Visual Sync Works

Algorithm:

Extract motion energy timeseries from video frames
Apply cross-correlation to find temporal offsets
Identify peak correlation as the optimal alignment

Advantages:

Robust against silent videos
Works in noisy audio environments
No audio extraction overhead

Disadvantages:

Requires visible motion in overlapping time periods
Less precise than audio (typically ±1-2 frames)

Use cases:

Action/sports videos with lots of movement
Outdoor recordings with wind noise
Cameras with no/poor audio recording

Audio Synchronization (GCC-PHAT)

How Audio Sync Works

Algorithm:

Extract audio tracks from all videos using FFmpeg
Apply GCC-PHAT (Generalized Cross-Correlation with Phase Transform)
Find sub-frame precision offsets based on audio alignment

Advantages:

Sub-frame accuracy (typically ±0.1 frames)
Works with static camera setups
High confidence scores for clean audio

Disadvantages:

Requires audible, synchronized sound events (claps, music, etc.)
Fails with silent videos
Sensitive to background noise

Use cases:

Studio recordings with synchronized audio
Concert/performance videos
Interview setups with shared microphones

Configuration Example

config.py

# For motion-based synchronization (default)
SYNC_METHOD = "visual"

# For audio-based synchronization
SYNC_METHOD = "audio"

If you’re unsure which method to use, start with "visual". The evaluation suite (see README.md:48-110) provides scripts to benchmark both methods on your specific videos.

Directory Configuration

All file paths are configurable through directory constants:

Temporary Base Directory

TEMP_BASE

string

default:"/tmp/video_synchronization"

Root directory for all temporary file storage during processing.Default behavior: Uses system temp directory via tempfile.gettempdir()Location: config.py:11Platform-specific defaults:

Linux/macOS: /tmp/video_synchronization
Windows: C:\Users\<username>\AppData\Local\Temp\video_synchronization

Changing TEMP_BASE to a non-temp directory (e.g., /home/user/videos/) will cause files to persist after system reboot. Ensure you have adequate disk space and implement cleanup policies.

Project Root

PROJECT_ROOT

string

default:"auto-detected"

Absolute path to the project directory (where main.py is located).Auto-detection logic:

os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

Location: config.py:14

You typically do not need to modify PROJECT_ROOT. It’s automatically calculated relative to src/config.py.

Working Directories

These directories are created automatically on startup:

VIDEO_DIR

string

default:"{TEMP_BASE}/raw"

Storage for uploaded original video files.Location: config.py:17Usage: Upload endpoint saves files here (ui.py:769)

OUTPUT_DIR

string

default:"{TEMP_BASE}/synced"

Output directory for synchronized videos.Location: config.py:18Filename pattern: {original_name}_synced.{ext}Usage: apply_video_offsets() writes synchronized videos here (ui.py:724)

AUDIO_DIR

string

default:"{TEMP_BASE}/audio"

Temporary storage for extracted audio tracks (only used when SYNC_METHOD = "audio").Location: config.py:19File format: .wav files with same basename as videosUsage: Audio extraction via FFmpeg (ui.py:664)

VISUAL_SYNC_OUTPUT_DIR

string

default:"{TEMP_BASE}/visual_sync_debug"

Debug output directory for motion analysis artifacts (e.g., energy timeseries plots).Location: config.py:20Usage: sync_videos_by_motion() saves debug visualizations here (ui.py:701)

RESULTS_DIR

string

default:"{PROJECT_ROOT}/results"

Persistent directory for sync indicator images (survives application restarts).Location: config.py:23Contents: Bounding box overlay images showing sync qualityUsage: generate_sync_indicators() saves images here (ui.py:713-717)

Directory Creation

All directories are created with exist_ok=True to prevent errors if they already exist:

config.py

os.makedirs(VIDEO_DIR, exist_ok=True)
os.makedirs(OUTPUT_DIR, exist_ok=True)
os.makedirs(AUDIO_DIR, exist_ok=True)
os.makedirs(VISUAL_SYNC_OUTPUT_DIR, exist_ok=True)
os.makedirs(RESULTS_DIR, exist_ok=True)

Source: config.py:26-30

Advanced Configuration

These settings are not exposed in config.py but can be modified by editing the source code:

Maximum Offset Window

max_offset_sec

float

default:"20.0"

Maximum temporal offset to search (in seconds).Location: ui.py:669 (audio), ui.py:696 (visual)Impact:

Larger values: Slower processing, more memory usage, but can detect larger time shifts
Smaller values: Faster processing, but may miss offsets if videos are far apart

Recommendation: Set to 1.5× your expected maximum offset

Minimum Confidence Threshold

min_confidence

float

default:"0.2"

Minimum confidence score required for audio sync.Location: ui.py:671Impact:

Higher values (0.5-1.0): Only accept high-quality matches, reject uncertain alignments
Lower values (0.1-0.3): Accept lower-quality matches, may produce incorrect sync

Note: Not currently used for visual sync method

Modifying these parameters requires editing ui.py directly. Future versions may expose them in config.py.

Log Retention

maxBytes

int

default:"10485760"

Maximum log file size before rotation (bytes).Default: 10MBLocation: ui.py:40

backupCount

int

default:"5"

Number of rotated log files to retain.Default: 5 backups (total ~60MB with defaults)Location: ui.py:40

maxlen

int

default:"500"

Maximum log entries stored in memory for UI display.Location: ui.py:75Impact: Higher values increase memory usage but provide more history in the log viewer

Allowed File Extensions

ALLOWED_EXTENSIONS

set

default:"{'.mp4', '.mov', '.avi'}"

Permitted video file extensions for upload.Location: ui.py:757Modification example:

ui.py

ALLOWED_EXTENSIONS = {'.mp4', '.mov', '.avi', '.mkv', '.webm'}

Adding unsupported formats may cause FFmpeg errors during processing. Test thoroughly before deploying.

Flask Server Settings

port

int

default:"5050"

HTTP port for the Flask web server.Location: ui.py:848Modification example:

ui.py

port = 8080  # Change to avoid conflicts

host

string

default:"127.0.0.1"

Network interface to bind.Default: 127.0.0.1 (localhost only)Location: ui.py:856To allow external access:

ui.py

app.run(host='0.0.0.0', port=port, ...)

Binding to 0.0.0.0 exposes the application to your network. Implement authentication before using in production.

Environment-Specific Configuration

Development vs. Production

For different deployment scenarios, consider creating environment-specific config files:

# Development: Use temp directory, verbose logging
SYNC_METHOD = "visual"
TEMP_BASE = "/tmp/video_sync_dev"
LOG_LEVEL = "DEBUG"

Load the appropriate config in main.py:

main.py

import os
if os.getenv('ENVIRONMENT') == 'production':
    from src import config_prod as config
else:
    from src import config

This pattern is not implemented in the current codebase but is a recommended practice for production deployments.

Configuration Best Practices

Test Changes Locally

After modifying config.py, restart the application and test with sample videos before deploying.

Document Custom Settings

Add comments to config.py explaining why you changed a value:

# Increased to 30s for long-form lecture videos
max_offset_sec = 30.0

Version Control

Commit your config.py changes with descriptive messages:

git commit -m "config: Switch to audio sync for studio recordings"

Monitor Disk Usage

If using custom TEMP_BASE, implement cleanup scripts to prevent disk exhaustion:

# Cron job: Delete files older than 7 days
find /var/app/video_sync -type f -mtime +7 -delete

Configuration Reference Table

Parameter	Type	Default	Modifiable	Requires Restart
`SYNC_METHOD`	string	`"visual"`	✅ config.py	✅
`TEMP_BASE`	string	`tempfile.gettempdir()`	✅ config.py	✅
`VIDEO_DIR`	string	`{TEMP_BASE}/raw`	✅ config.py	✅
`OUTPUT_DIR`	string	`{TEMP_BASE}/synced`	✅ config.py	✅
`AUDIO_DIR`	string	`{TEMP_BASE}/audio`	✅ config.py	✅
`RESULTS_DIR`	string	`{PROJECT_ROOT}/results`	✅ config.py	✅
`max_offset_sec`	float	`20.0`	⚠️ ui.py	✅
`min_confidence`	float	`0.2`	⚠️ ui.py	✅
`ALLOWED_EXTENSIONS`	set	`{'.mp4', '.mov', '.avi'}`	⚠️ ui.py	✅
`port`	int	`5050`	⚠️ ui.py	✅
`maxBytes` (logs)	int	`10485760`	⚠️ ui.py	✅
`backupCount` (logs)	int	`5`	⚠️ ui.py	✅

✅ = Easily modifiable in config.py
⚠️ = Requires editing source code

Troubleshooting Configuration Issues

Changes to config.py not taking effect

Cause: Flask cached the old config or application wasn’t restarted.Solution:

Fully stop the application (Ctrl+C)
Clear Python cache: find . -type d -name __pycache__ -exec rm -r {} +
Restart: python main.py

Permission denied when creating directories

Cause: TEMP_BASE points to a directory without write permissions.Solution: Change to a user-writable directory:

TEMP_BASE = os.path.expanduser("~/video_sync_temp")

Audio sync fails with SYNC_METHOD = 'audio'

Cause: FFmpeg not installed or videos have no audio tracks.Diagnosis: Check logs for “Audio extraction failed” messages.Solution:

Verify FFmpeg installation: ffmpeg -version
Check video audio tracks: ffprobe -show_streams input.mp4
Switch to visual sync if videos are silent

Next Steps

Using the UI

Learn how to navigate the web interface and upload videos

Interpreting Results

Understand confidence scores and validate synchronization quality

Get Started

Core Concepts

User Guide

Evaluation Suite

Configuration File Location

Synchronization Method

Visual Synchronization (Motion-Based)

Audio Synchronization (GCC-PHAT)

Configuration Example

Directory Configuration

Temporary Base Directory

Project Root

Working Directories

Directory Creation

Advanced Configuration

Maximum Offset Window

Minimum Confidence Threshold

Log Retention

Allowed File Extensions

Flask Server Settings

Environment-Specific Configuration

Development vs. Production

Configuration Best Practices

Configuration Reference Table

Troubleshooting Configuration Issues

Next Steps

Using the UI

Interpreting Results

Build docs developers (and LLMs) love

Get Started

Core Concepts

User Guide

Evaluation Suite

​Configuration File Location

​Synchronization Method

​Visual Synchronization (Motion-Based)

​Audio Synchronization (GCC-PHAT)

​Configuration Example

​Directory Configuration

​Temporary Base Directory

​Project Root

​Working Directories

​Directory Creation

​Advanced Configuration

​Maximum Offset Window

​Minimum Confidence Threshold

​Log Retention

​Allowed File Extensions

​Flask Server Settings

​Environment-Specific Configuration

​Development vs. Production

​Configuration Best Practices

​Configuration Reference Table

​Troubleshooting Configuration Issues

​Next Steps

Using the UI

Interpreting Results

Build docs developers (and LLMs) love

Configuration File Location

Synchronization Method

Visual Synchronization (Motion-Based)

Audio Synchronization (GCC-PHAT)

Configuration Example

Directory Configuration

Temporary Base Directory

Project Root

Working Directories

Directory Creation

Advanced Configuration

Maximum Offset Window

Minimum Confidence Threshold

Log Retention

Allowed File Extensions

Flask Server Settings

Environment-Specific Configuration

Development vs. Production

Configuration Best Practices

Configuration Reference Table

Troubleshooting Configuration Issues

Next Steps