video-master-adapt/README_STANDALONE.md

Video Matcher - Standalone Application Guide

Overview

This guide explains how to build and distribute the Video Matcher as a standalone desktop application that users can run with a simple double-click.

Features

• ✅ No Installation Required: Single executable with all dependencies bundled
• ✅ Local Processing: All videos processed on user's machine
• ✅ Browser-Based UI: Familiar and easy-to-use interface
• ✅ Folder Selection: Simple file browser to select master and adaptation folders
• ✅ Export Results: Download matching results as CSV
• ✅ Cross-Platform: Works on macOS, Windows, and Linux

Prerequisites for Building

System Requirements

• Python 3.8+ installed
• FFmpeg installed and accessible in PATH
• PyInstaller for building the executable

Install Build Dependencies

# Install all Python dependencies
pip install -r requirements.txt

# Install PyInstaller
pip install pyinstaller

# Verify FFmpeg is installed
ffmpeg -version

Building the Standalone Application

Option 1: Automated Build Script (Recommended)

# Run the build script
python build.py

This will:

1. Check dependencies
2. Clean previous builds
3. Build the executable with PyInstaller
4. Create distribution folder with data directories
5. Generate README for end users

Option 2: Manual Build

# Clean previous builds
rm -rf build dist

# Build with PyInstaller
pyinstaller video_matcher.spec --clean

# Create data directories
cd dist/VideoMatcher
mkdir -p data/fingerprints data/jobs tmp/video_downloads
echo "[]" > data/masters.json

Distribution Package Structure

After building, your dist/VideoMatcher/ folder will contain:

VideoMatcher/
├── VideoMatcher              # Main executable (macOS/Linux)
├── VideoMatcher.exe          # Main executable (Windows)
├── VideoMatcher.app/         # macOS app bundle (optional)
├── data/                     # Application data
│   ├── masters.json         # Master video database
│   ├── fingerprints/        # Video fingerprint cache
│   └── jobs/                # Job history
├── tmp/                     # Temporary files
├── templates/               # Web UI templates
├── static/                  # Web UI assets
├── src/                     # Core matching logic
└── README.txt              # User instructions

How Users Run the Application

macOS

# Option 1: Double-click
VideoMatcher (or VideoMatcher.app)

# Option 2: Terminal
./VideoMatcher

Windows

Double-click: VideoMatcher.exe

Linux

chmod +x VideoMatcher  # First time only
./VideoMatcher

User Workflow

1. Launch Application

   • Double-click the executable
   • Browser automatically opens to http://localhost:5000

2. Select Master Folder

   • Browse to folder containing master videos
   • System scans and fingerprints masters (cached for future use)

3. Select Adaptation Folder(s)

   • Browse and select one or more folders with adaptations
   • Can select multiple country folders (e.g., AT, CH, DE, NL, SI)

4. Process & View Results

   • Application matches adaptations against masters
   • View results in browser with match confidence scores
   • Export results as CSV

5. Start Over

   • Click "Start Over" to match new videos
   • Or close browser and application

Distribution Methods

Method 1: Zip Archive (Simple)

cd dist
zip -r VideoMatcher.zip VideoMatcher/

Share VideoMatcher.zip with users. They extract and run.

Method 2: Installer (Professional)

Create an installer using:

• macOS: Create DMG with create-dmg or dmgbuild
• Windows: Use Inno Setup or NSIS
• Linux: Create .deb or .rpm packages

Method 3: Network Share

Place the VideoMatcher folder on a network drive. Users can run directly from the network location (may be slower for large master files).

Configuration Options

Environment Variables

Users can create a .env file in the application directory:

# Optional: Disable authentication (already default in standalone)
DISABLE_AUTH=1

# Optional: Custom port
PORT=5000

# Optional: Enable debug mode
FLASK_ENV=development

Port Selection

The launcher automatically finds an available port if 5000 is in use (tries 5000-5009).

Troubleshooting

Build Issues

PyInstaller Not Found

pip install pyinstaller

Missing Dependencies

pip install -r requirements.txt

FFmpeg Not Found

• macOS: brew install ffmpeg
• Windows: Download from https://ffmpeg.org/download.html
• Linux: sudo apt-get install ffmpeg

Runtime Issues

Application Won't Start

• Check FFmpeg is installed: ffmpeg -version
• Check console output for error messages
• Ensure Python dependencies were bundled correctly

Permission Errors (macOS)

• Go to System Preferences > Security & Privacy
• Allow the application to run

Windows Defender Warning

• Click "More info" > "Run anyway"
• Or add exception for the executable

Port Already in Use

• The app auto-selects an available port
• Or manually specify port in .env file

File Size Considerations

Typical Build Sizes

• Executable Only: ~80-150 MB (includes Python runtime + dependencies)
• With Master Fingerprints: +1-5 MB per master (depending on length)
• Total Distribution: ~100-200 MB

Reducing Build Size

1. Remove Unused Dependencies

   # In video_matcher.spec, add to excludes:
   excludes=['matplotlib', 'pandas', 'scipy', ...]
   

2. Use UPX Compression

   # Already enabled in spec file
   upx=True
   

3. Strip Debug Symbols

   # Already enabled in spec file
   strip=True
   

Advanced Customization

Adding an Application Icon

1. Create icon files:

   • macOS: .icns file
   • Windows: .ico file
   • Linux: .png file

2. Update video_matcher.spec:

   exe = EXE(
       ...
       icon='path/to/icon.ico',  # Windows
   )
   
   app = BUNDLE(
       ...
       icon='path/to/icon.icns',  # macOS
   )
   

Customizing the UI

Edit templates/standalone.html to:

• Change colors and branding
• Modify workflow steps
• Add company logo
• Update text and labels

Console vs GUI Mode

Show Console (Default)

# In video_matcher.spec
console=True  # Shows terminal window with logs

Hide Console (GUI Only)

# In video_matcher.spec
console=False  # No console window (cleaner but harder to debug)

Comparison: Standalone vs Web App

Feature	Standalone App	Web App (Hosted)
Installation	Download & run	None (browser only)
File Upload	No (direct access)	Yes (large uploads)
Processing Location	User's machine	Server
Authentication	Optional	Required
Master Storage	User's machine	Server storage
Distribution	Zip file	URL
Updates	Redistribute	Automatic
Best For	Large local files	Team collaboration

Security Considerations

Standalone App

• ✅ No data leaves user's machine
• ✅ No authentication needed (local only)
• ✅ No network requirements (except initial download)
• ⚠️ Users must trust the executable

Code Signing (Recommended for Distribution)

macOS

codesign --force --deep --sign "Developer ID" dist/VideoMatcher.app

Windows

signtool sign /f certificate.pfx /p password VideoMatcher.exe

Support & Maintenance

Updating the Application

1. Make code changes
2. Rebuild: python build.py
3. Redistribute new version
4. Users replace old folder with new one

Version Management

Add version info to launcher.py:

APP_VERSION = "1.0.0"
print(f"Video Matcher v{APP_VERSION}")

User Data Persistence

When users update to a new version:

• Keep: data/ folder (masters and fingerprints)
• Replace: Everything else

FAQ

Q: Can users run multiple instances? A: Yes, each instance will use a different port automatically.

Q: How do users uninstall? A: Simply delete the VideoMatcher folder. No system files are modified.

Q: Can this work offline? A: Yes, completely offline except for optional Box.com integration.

Q: What about large master files? A: Masters stay on user's machine. Only fingerprints (small JSON files) are created.

Q: Can users share fingerprints? A: Yes, users can share the data/ folder to avoid re-fingerprinting.

License & Credits

Video Master-Adaptation Detection Tool Built with Python, Flask, OpenCV, and FFmpeg

---

Quick Start Checklist

• Install Python 3.8+
• Install FFmpeg
• Install PyInstaller: pip install pyinstaller
• Install dependencies: pip install -r requirements.txt
• Run build script: python build.py
• Test application: cd dist/VideoMatcher && ./VideoMatcher
• Zip for distribution: zip -r VideoMatcher.zip VideoMatcher/
• Share with users!

---

Happy Matching! 🎬