# Batch Matching & HTML Reports - Quick Guide

## 🚀 Quick Start

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

```bash
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
```bash
# Verify all adaptations match expected masters
python cli.py batch-match "deliverables/final_cuts/" -t 0.7
```

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

### 3. Asset Management
```bash
# 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:

```bash
# 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
```bash
# 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
```bash
# Use descriptive filenames
python cli.py batch-match "Q4_2024_deliverables/" \
  -o "reports/Q4_2024_master_usage.html"
```

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

### 4. Batch Multiple Folders
```bash
# 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**
   ```bash
   python bulk_add_masters.py "masters/" -r
   python cli.py list-masters  # Verify
   ```

2. **Test on Small Set**
   ```bash
   # 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**
   ```bash
   mkdir -p reports/{2024,2025}
   python cli.py batch-match "folder/" \
     -o "reports/2024/Q4_report.html"
   ```

5. **Version Control Reports**
   ```bash
   # 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:
```bash
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*