video-master-adapt/BATCH_MATCHING_GUIDE.md

Batch Matching & HTML Reports - Quick Guide

🚀 Quick Start

Process an entire folder of adaptations and get a beautiful HTML report:

python cli.py batch-match "/path/to/adaptations/"

That's it! A timestamped HTML report will be generated automatically.

📋 Common Use Cases

1. Quality Control Check

# Verify all adaptations match expected masters
python cli.py batch-match "deliverables/final_cuts/" -t 0.7

2. Production Audit

# Generate audit trail with custom filename
python cli.py batch-match "Q4_adaptations/" -o Q4_audit_report.html

3. Asset Management

# Process with relaxed thresholds to find all potential matches
python cli.py batch-match "archive/" -t 0.3 -f 0.65

🎨 What You Get

HTML Report Includes:

📊 Summary Dashboard:

┌─────────────────────────────────────┐
│  10 Total  |  8 Matched  |  2 None │
└─────────────────────────────────────┘

🎬 Per-Adaptation Cards:

┌──────────────────────────────────────┐
│ adaptation_video.mp4           [2]   │
├──────────────────────────────────────┤
│ #1 master_20s_B  [HIGH]  20s  100%  │
│ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  │
│                                      │
│ #2 master_15s_C  [MED]   15s   85%  │
│ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░  │
└──────────────────────────────────────┘

Color-Coded Confidence:

• 🟢 Green = Very High/High (90%+)
• 🟡 Yellow = Medium (60-90%)
• 🔴 Red = Low/Very Low (<60%)

⚙️ Options

Option	Default	Description
-t, --threshold	0.3	Minimum % of frames to match (0-1)
-f, --frame-threshold	0.70	Frame similarity threshold (0-1)
-o, --output	Auto	Custom output filename

Examples:

# Strict matching (require 80% match, 75% similarity)
python cli.py batch-match "folder/" -t 0.8 -f 0.75

# Relaxed matching (catch more potential matches)
python cli.py batch-match "folder/" -t 0.2 -f 0.65

# Custom output location
python cli.py batch-match "folder/" -o "reports/$(date +%Y%m%d)_report.html"

📂 Folder Structure

Before:

adaptations/
├── adapt_A.mp4
├── adapt_B.mp4
├── adapt_C.mp4
└── adapt_D.mp4

After:

adaptations/
├── adapt_A.mp4
├── adapt_B.mp4
├── adapt_C.mp4
├── adapt_D.mp4
matching_report_20251010_153045.html  ← Generated!

🔍 Reading the Report

Summary Section

• Total Adaptations: How many videos were processed
• Matched: Videos that found at least one master
• No Matches: Videos with no matching masters
• Total Master Matches: Sum of all matches across all adaptations

Per Video Section

Each adaptation shows:

1. Filename - The adaptation video name
2. Match Count - Number of masters found (badge)
3. Master List - All matching masters ranked by confidence
4. Per-Master Details:
   • Duration of master
   • Video match percentage
   • Number of frames matched
   • Combined confidence score
   • Visual progress bar

Understanding Confidence

Badge	Score	Meaning
VERY HIGH	≥90%	Almost certain match
HIGH	75-90%	Strong match
MEDIUM	60-75%	Probable match
LOW	50-60%	Possible match
VERY LOW	<50%	Unlikely match

💡 Tips

1. Start Broad, Then Narrow

# First pass: see all potential matches
python cli.py batch-match "folder/" -t 0.3

# Review report, then run stricter
python cli.py batch-match "folder/" -t 0.7 -o strict_report.html

2. Save Reports with Context

# Use descriptive filenames
python cli.py batch-match "Q4_2024_deliverables/" \
  -o "reports/Q4_2024_master_usage.html"

3. Compare Over Time

# Weekly audit
python cli.py batch-match "current_week/" \
  -o "audits/week_$(date +%U)_report.html"

4. Batch Multiple Folders

# Process multiple folders with a script
for folder in campaign_A campaign_B campaign_C; do
  python cli.py batch-match "$folder/" -o "${folder}_report.html"
done

🐛 Troubleshooting

No videos found

❌ Problem: "No video files found in folder"
✅ Solution: Check path and ensure .mp4/.mov files exist

All adaptations show "No matches"

❌ Problem: No matches found above threshold
✅ Solution: Lower thresholds with -t 0.2 -f 0.65

Report opens blank

❌ Problem: HTML file corrupted or incomplete
✅ Solution: Re-run with --output to specify new filename

Processing errors

❌ Problem: "Error processing video.mp4"
✅ Solution: Check video file isn't corrupted, codec is supported

📊 Performance

Typical Processing Times:

Folder Size	Masters	Time
5 videos	50	~1 min
10 videos	50	~2 min
25 videos	50	~5 min
50 videos	50	~10 min
100 videos	50	~20 min

Time depends on video duration and system specs

🎯 Best Practices

1. Add All Masters First

   python bulk_add_masters.py "masters/" -r
   python cli.py list-masters  # Verify
   

2. Test on Small Set

   # Test with 2-3 videos first
   mkdir test_folder
   cp adapt_1.mp4 adapt_2.mp4 test_folder/
   python cli.py batch-match test_folder/
   

3. Use Consistent Naming

   • adaptations/ for all adaptation videos
   • masters/ for all master videos
   • reports/ for generated HTML reports

4. Keep Reports Organized

   mkdir -p reports/{2024,2025}
   python cli.py batch-match "folder/" \
     -o "reports/2024/Q4_report.html"
   

5. Version Control Reports

   # Add to git for tracking
   git add reports/*.html
   git commit -m "Add Q4 matching report"
   

🔗 See Also

• README.md - Quick start guide
• DOCUMENTATION.md - Full technical documentation
• cli.py - Single video matching
• bulk_add_masters.py - Adding multiple masters

📞 Need Help?

Check the full documentation:

python cli.py batch-match --help

Or see DOCUMENTATION.md section: "Batch Matching & HTML Reports"

---

Generated by Video Master-Adaptation Detection Tool Version 1.0.0