video-master-adapt/PERFORMANCE_NOTES.md

Video Matcher - Performance Notes

Performance Optimization for Standalone Mode

The standalone application now runs in FAST MODE by default, which significantly improves processing speed.

What Changed

Before (Server Mode)

• AKAZE enabled: Advanced computer vision feature extraction
  • Takes ~1-2 minutes per video
  • Very accurate for complex matches
• AI Vision enabled: OpenAI GPT-4V API calls
  • Requires API key and internet
  • Costs money per API call
  • Slow due to network latency
• Total time for 46 masters: ~60-90 minutes (first time)

After (Standalone/Fast Mode)

• AKAZE disabled: Uses basic frame hashing
  • Takes ~5-10 seconds per video
  • Still very accurate for most matches
• AI Vision disabled: No API calls needed
  • No internet required
  • No API costs
  • Much faster
• Total time for 46 masters: ~5-10 minutes (first time)

Processing Times

First Time Setup (Fingerprinting Masters)

When you select a master folder for the first time:

• Fast Mode (Standalone): ~5-10 seconds per video
  • 46 videos: ~5-10 minutes total
• Full Mode (Server): ~1-2 minutes per video
  • 46 videos: ~60-90 minutes total

Subsequent Runs

• Fingerprints are cached
• Selecting the same master folder: Instant (just loads from cache)
• Only new videos need fingerprinting

Matching Adaptations

When matching adaptation videos:

• Fast Mode: ~5-10 seconds per adaptation
• Full Mode: ~30-60 seconds per adaptation

What's Still Accurate in Fast Mode?

Fast mode uses:

• ✅ Audio fingerprinting (Chromaprint) - Very accurate
• ✅ Frame hashing - Good for exact or near-exact matches
• ✅ Metadata filtering - Duration, aspect ratio matching
• ❌ AKAZE features - Disabled (not needed for most cases)
• ❌ AI Vision - Disabled (not needed for same-aspect matches)

When Fast Mode Works Well

• ✅ Matching adaptations with same aspect ratio as masters
• ✅ Exact or near-exact visual matches
• ✅ Videos with clear audio tracks
• ✅ Most typical use cases

When You Might Need Full Mode

• ⚠️ Cross-aspect ratio matching (16:9 → 9:16, etc.)
• ⚠️ Heavily edited adaptations
• ⚠️ Silent videos (no audio)

Monitoring Progress

Terminal Output

When running python launcher.py, watch the terminal for:

INFO - Processing master: video_name.mp4
INFO - Fingerprinting completed: video_name.mp4
INFO - Added master: master_id

UI Feedback

• Button shows: "⏳ Fingerprinting X video(s)..."
• Message reminds: "Check terminal for progress"
• Alert shows: "✓ Successfully added X masters"

Tips for Best Performance

1. Use the Same Master Folder

• Fingerprints are cached by file path
• Reusing the same folder = instant loading
• Moving files = need to re-fingerprint

2. Pre-Fingerprint Masters Once

On first run:

1. Select your master folder
2. Let it fingerprint all videos (5-10 min)
3. Masters are now cached forever
4. Future runs will be instant

3. Check Existing Fingerprints

ls -l data/fingerprints/master_*.json

If you see your masters already there, they won't be re-fingerprinted.

4. Watch Terminal for Issues

If fingerprinting seems stuck:

• Check terminal for errors
• Look for "ERROR" or "WARNING" messages
• Common issues:
  • FFmpeg not installed
  • Corrupt video file
  • Insufficient disk space

Enabling Full Mode (If Needed)

If you need AKAZE and AI Vision for better accuracy:

Option 1: Edit app.py

Change line 93-94:

enable_ai_vision=False,  # Change to True
use_akaze=False          # Change to True

Option 2: Use Server Mode

Run the full Flask app instead:

export STANDALONE_MODE=0
python app.py

Requirements for Full Mode

• OpenAI API Key: Set OPENAI_API_KEY in .env
• More Time: 10-20x slower
• API Costs: ~$0.01-0.05 per video (GPT-4V)

Disk Space

Fingerprint Cache Sizes

• Audio fingerprint: ~1-2 KB per video
• Frame hashes (Fast): ~5-10 KB per video
• AKAZE features (Full): ~50-200 KB per video
• Total for 46 masters:
  • Fast mode: ~300-500 KB
  • Full mode: ~5-10 MB

Temporary Files

• Adaptations are NOT cached (processed on-the-fly)
• No temp files accumulate in standalone mode
• Safe to run multiple times

Troubleshooting Slow Performance

If Fingerprinting Takes Forever

Check 1: Is AKAZE disabled?

# Look for this line in terminal output:
INFO - VideoMatcherService initialized (mode=FAST, ...)

Should say mode=FAST. If it says mode=FULL, AKAZE is enabled.

Check 2: Are you re-fingerprinting?

# Check if masters already exist
ls data/fingerprints/master_*.json | wc -l

Should match number of master videos. If not, they're being processed.

Check 3: FFmpeg issues?

# Test FFmpeg
ffmpeg -version

Should show version info. If error, install FFmpeg.

Check 4: Disk space?

df -h .

Need at least 10 GB free for video processing.

If Matching Takes Forever

Check 1: How many adaptations?

• Fast mode: 10 videos = ~1-2 minutes
• Fast mode: 100 videos = ~10-20 minutes

Check 2: Terminal output Should show progress:

INFO - Processing video 1/39: video.mp4
INFO - Found 1 matches for video.mp4

Check 3: Network issues?

• Fast mode doesn't need internet
• If hanging, check if AI vision accidentally enabled

Summary

Feature	Fast Mode (Standalone)	Full Mode (Server)
AKAZE	❌ Disabled	✅ Enabled
AI Vision	❌ Disabled	✅ Enabled
Speed	⚡ Fast	🐌 Slow
Accuracy	✅ Good	✅✅ Excellent
Internet	❌ Not needed	✅ Required
API Costs	$0	Variable
Best For	Local matching	Complex matching

---

Bottom Line: Standalone mode is 10-20x faster and works great for most use cases. Only enable full mode if you need cross-aspect ratio matching or have heavily edited adaptations.