video-master-adapt/STANDALONE_QUICK_START.md

Video Matcher Standalone Application - Quick Start Guide

What Was Created

I've transformed your Video Matcher tool into a standalone desktop application that users can run with a simple double-click. Here's what's new:

New Files Created

1. launcher.py - Main entry point that starts the Flask server and opens the browser
2. templates/standalone.html - Beautiful UI for folder selection and matching
3. video_matcher.spec - PyInstaller configuration for building the executable
4. build.py - Automated build script
5. README_STANDALONE.md - Comprehensive documentation

Modified Files

1. app.py - Added standalone mode support and local file system endpoints:
   • /local/browse - Browse local folders
   • /local/scan-masters - Scan master folder
   • /local/add-masters - Add masters to database
   • /local/scan-adaptations - Scan adaptation folders
   • /local/match - Match videos from local paths

How to Use Right Now (Development Mode)

You can test the standalone application immediately without building:

# Run the launcher
python launcher.py

This will:

1. Start a local Flask server (http://localhost:5000 or next available port)
2. Automatically open your browser
3. Show the folder selection interface

User Workflow

1. Select Master Folder

   • Browse your filesystem
   • Select folder with master videos
   • System scans and fingerprints them

2. Select Adaptation Folder(s)

   • Browse and select adaptation folders
   • Can select multiple folders (e.g., different countries)

3. Process & View Results

   • Click "Start Matching"
   • View results with match confidence
   • Export as CSV

How to Build for Distribution

When you're ready to share with others who don't have Python installed:

Step 1: Install PyInstaller

pip install pyinstaller

Step 2: Run Build Script

python build.py

This creates a dist/VideoMatcher/ folder with everything needed.

Step 3: Distribute

# Create a zip file
cd dist
zip -r VideoMatcher.zip VideoMatcher/

# Share VideoMatcher.zip with users

What Users Will See

VideoMatcher/
├── VideoMatcher (or VideoMatcher.exe on Windows)
├── data/
├── tmp/
└── README.txt

Users simply:

1. Extract the zip
2. Double-click VideoMatcher
3. Browser opens automatically
4. Select folders and match videos

Key Features

✅ No Server Required

• Everything runs locally on user's machine
• No hosting costs
• No file uploads needed

✅ Large File Support

• Masters stay on local disk
• No size limits (unlike web uploads)
• Direct file system access

✅ Simple Distribution

• Single zip file
• No installation wizard
• Works on macOS, Windows, Linux

✅ Optional Box Integration

• Box.com support still available if needed
• Can mix local folders and Box downloads

✅ Clean User Interface

• Step-by-step wizard
• Visual folder browser
• Progress indicators
• Export results

Architecture Overview

┌─────────────────────────────────────┐
│  User Double-Clicks Executable      │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  launcher.py                        │
│  - Sets STANDALONE_MODE=1           │
│  - Starts Flask server              │
│  - Opens browser automatically      │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  Browser (http://localhost:5000)    │
│  - Shows standalone.html            │
│  - Folder selection UI              │
│  - Results display                  │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  Flask App (app.py)                 │
│  - Authentication disabled          │
│  - Local file endpoints enabled     │
│  - Direct file system access        │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  Video Matcher Service              │
│  - Fingerprinting                   │
│  - Matching logic                   │
│  - Results generation               │
└─────────────────────────────────────┘

Testing Checklist

Before distributing to users, test:

• Master folder selection works
• Adaptation folder selection works
• Multiple adaptation folders can be added
• Fingerprinting completes successfully
• Matching produces correct results
• CSV export works
• "Start Over" resets properly
• Application runs on target OS (Windows/macOS/Linux)

File Sizes to Expect

• Executable: ~80-150 MB (includes Python runtime)
• Master fingerprints: ~1-5 MB each (cached after first run)
• Total distribution zip: ~100-200 MB

Comparison: Before vs After

Before (Current Setup)

• Masters in local folder: To Exclude/Masters transcoded/
• Adaptations in local folder: To Exclude/1011A Spring Fashion/
• Run via: python batch_match.py or web app
• Sharing: Requires Python setup for others

After (Standalone App)

• Masters: User selects any folder on first run
• Adaptations: User selects any folder(s) on each run
• Run via: Double-click VideoMatcher
• Sharing: Send zip file, users extract and run

Configuration Options

Environment Variables (Optional)

Users can create .env file in app directory:

# Force specific port
PORT=5000

# Enable debug logging
FLASK_ENV=development

# Custom data directory
DATA_DIR=/path/to/data

Command Line Options

The launcher can be modified to accept arguments:

./VideoMatcher --port 8080
./VideoMatcher --debug

Troubleshooting

"Port already in use"

The launcher automatically finds an available port (5000-5009).

"FFmpeg not found"

Users need FFmpeg installed:

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

"Permission denied" (macOS)

• System Preferences > Security & Privacy
• Allow the application

Windows Defender warning

• Click "More info" > "Run anyway"

Next Steps

1. Test Now: Run python launcher.py to test the interface
2. Build: Run python build.py to create executable
3. Test Built App: Run dist/VideoMatcher/VideoMatcher
4. Distribute: Zip and share with users

Support

For detailed documentation, see:

• README_STANDALONE.md - Complete guide
• build.py - Build script with comments
• launcher.py - Launcher with inline docs

Summary

You now have:

• ✅ Standalone desktop application
• ✅ Browser-based UI with folder selection
• ✅ Local file processing (no uploads)
• ✅ Easy distribution (single zip file)
• ✅ Cross-platform support
• ✅ Optional Box.com integration still available

The application prompts for folders on every run (as you requested) and processes everything locally on the user's machine. Perfect for handling large uncompressed master files without server storage concerns!