conversion_project/QUICK_REFERENCE.md

# 4K HDR Quick Reference Card

## 🎬 New Feature Summary

| Feature | Status | Details |
|---------|--------|---------|
| `--r 2160` flag | ✅ NEW | Enable 4K/HDR mode with source validation |
| HDR detection | ✅ NEW | Auto-detects BT.2020 + SMPTE2084 color space |
| 8-channel audio | ✅ NEW | Allowed on 4K (max for 2160p) |
| High bitrate (640k) | ✅ NEW | Available for 4K multi-channel audio |
| Color profiles | ✅ NEW | HDR10 flags applied to ffmpeg output |
| Default 4K downscale | ✅ UNCHANGED | Still downscales to 1080p without flag |
| 720p/1080p audio | ✅ UNCHANGED | Logic preserved as-is |

---

## ⚡ Quick Commands

### Enable 4K Processing
```bash
python main.py "path\to\4k" --r 2160
```

### Test 4K File (15 min)
```bash
python main.py "path\to\4k" --r 2160 --test
```

### Batch Process Mixed Content
```bash
python main.py --paths-file batch.txt
# batch.txt:
#   P:\4k_content --r 2160
#   P:\1080p_content --r 1080
```

### With CQ Override
```bash
python main.py "path\to\4k" --r 2160 --cq 25
```

---

## 🔍 Detection Logic

### When Processing with `--r 2160`

```
Source Resolution     | Decision          | Output
─────────────────────────────────────────────────────
≥ 2160p (4K+)         | ✅ Process 4K     | 4K output
< 2160p (1080p, etc)  | ⏭️  SKIP          | Not encoded
```

### HDR Detection

```
Color Space          | Transfer           | HDR? | Notes
─────────────────────────────────────────────────────
BT.2020              | SMPTE2084 (PQ)     | ✅   | HDR10
BT.2020              | Other              | ❌   | 4K SDR
rec709               | Any                | ❌   | Standard
```

---

## 📊 Audio Channel Limits

```
Resolution  │ Max Channels │ Examples
─────────────┼──────────────┼─────────────────────────
720p        │ 2            │ Stereo only
1080p       │ 6            │ 5.1, 6.0, reduced 7.1→6
4K (2160p)  │ 8            │ 7.1, 8 channels, full
```

---

## 💾 Audio Bitrate Caps

```
Resolution  │ Stereo (2ch)  │ Multi-ch (6ch) │ Multi-ch (8ch)
─────────────┼───────────────┼────────────────┼──────────────
720p        │ 192 kbps      │ —              │ —
1080p       │ 192 kbps      │ 448 kbps max   │ —
4K          │ 192 kbps      │ 640 kbps max   │ 640 kbps max
```

---

## 🎥 Encoder Selection (Auto)

```
Source Bit Depth     | Selected Encoder | Profile
──────────────────────────────────────────────────
≤ 8-bit             | AV1 NVENC        | 8-bit yuv420p
≥ 10-bit            | HEVC NVENC       | 10-bit p010le
```

---

## 🌈 HDR Color Profile Application

When HDR detected and source is 4K:

```
ffmpeg flags added:
  -color_space bt2020_ncl       (BT.2020 color space)
  -color_primaries bt2020       (BT.2020 primaries)  
  -color_trc smpte2084          (PQ tone mapping)
```

Result: **HDR10 compatible output**

---

## ✅ Validation Flow

```
--r 2160 specified?
    ↓
    YES → Check source height ≥ 2160p?
    │        ↓
    │        YES → ✅ Process as 4K
    │        │       Detect HDR
    │        │       Allow 8ch audio
    │        │       Allow 640kbps
    │        ↓
    │        NO → ⏭️ Skip (notify user)
    │
    NO → Use default/explicit resolution
             (backward compatible)
```

---

## 📋 Console Output Signs

### ✅ 4K Processing Active
```
🎬 HDR content detected (BT.2020 + SMPTE2084)
📋 Target: 2160p (4K passthrough)
🎙️  Stream #0: 8ch→8ch | Output: EAC3 640kbps
📹 Video: HEVC NVENC | 2160p
    HDR color profile: BT.2020 + SMPTE2084 (HDR10)
```

### ⚠️ Skipping Non-4K
```
⏭️  Skipping: --r 2160 requested but source is only 1080p (not 4K)
```

### 📊 4K SDR (No HDR)
```
📋 Target: 2160p (4K passthrough)
🎙️  Stream #0: 8ch→8ch | Output: EAC3 640kbps
📹 Video: HEVC NVENC | 2160p
(No HDR color profile message = SDR content)
```

---

## 🚫 Common Mistakes

### ❌ Using `--r 2160` on 1080p
```bash
python main.py "path\to\1080p" --r 2160
# Result: ⏭️ Skipped "not 4K"
```
**Fix**: Omit `--r 2160` or use `--r 1080`

### ❌ Expecting automatic 4K
```bash
python main.py "path\to\4k"
# Result: 🎬 Encoded as 1080p (default)
```
**Fix**: Add `--r 2160` to enable 4K mode

### ❌ 8-channel on 1080p
```python
# Config allows 640kbps high bitrate
# But 1080p limits to 448kbps + 6ch max
```
**Result**: Automatically downmixed to 6ch at 448kbps

---

## 🎯 Decision Tree

```
Is source 4K?
    ├─ NO → Use default logic (downscale to 1080p)
    └─ YES → Want 4K output?
            ├─ NO → Omit --r 2160 (downscale to 1080p)
            └─ YES → Use --r 2160
                    ├─ Detect HDR color space
                    ├─ Apply HDR profiles (if detected)
                    ├─ Allow 8-channel audio
                    ├─ Allow 640kbps bitrate
                    └─ ✅ Encode at 4K
```

---

## 📈 Performance Notes

| Task | Approx Time | Notes |
|------|------------|-------|
| 1080p encode | 30-60 min | Single movie |
| 4K encode | 2-3 hours | 4-6x slower than 1080p |
| 4K test mode | 15 min | First 15 minutes only |

---

## 🔧 Config Adjustment (Optional)

### For Higher 4K Quality
```xml
<cq>
  <hevc>
    <movie_2160>23</movie_2160>  <!-- Lower = better, slower -->
  </hevc>
</cq>
```

### For Smaller 4K Files
```xml
<multi_channel>
  <high>512000</high>  <!-- Reduce from 640000 -->
</multi_channel>
```

---

## 📚 Documentation Files

| File | Purpose |
|------|---------|
| `IMPLEMENTATION_COMPLETE.md` | Full technical summary |
| `IMPLEMENTATION_SUMMARY_4K_HDR.md` | Feature details |
| `AUDIO_CONFIG_GUIDE.md` | Audio bitrate guide |
| `4K_HDR_CLI_REFERENCE.md` | CLI examples |
| (this file) | Quick reference |

---

## ✨ Key Points to Remember

1. ✅ **Opt-in**: Use `--r 2160` to enable 4K (not automatic)
2. ✅ **Validated**: Non-4K sources automatically skipped
3. ✅ **Smart Audio**: Channels/bitrate auto-optimized per resolution
4. ✅ **HDR Aware**: Detects & preserves HDR color metadata
5. ✅ **Compatible**: Works with all existing features
6. ✅ **No Breaking Changes**: All previous commands work unchanged

---

**Last Updated**: 2026-05-17  
**Status**: Production Ready ✅