261 lines
6.7 KiB
Markdown
261 lines
6.7 KiB
Markdown
# 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*
|