conversion_project/4K_HDR_CLI_REFERENCE.md

# 4K HDR Mode - Command Line Reference

## Quick Start

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

## New Resolution Option

### `--r 2160` (New)
- **Purpose**: Enable 4K/HDR content processing
- **Validation**: Source MUST be actual 4K (≥2160p height)
- **Non-4K Sources**: Automatically skipped with notification
- **Behavior**: 
  - Preserves source resolution if ≥2160p
  - No upscaling
  - Enables HDR detection and color profiles
  - Uses `movie_2160` CQ settings from config
  - Allows 8-channel audio + high bitrate

### Original Resolution Options (Unchanged)
```bash
--r 480    # Force 480p (lowest quality, smallest files)
--r 720    # Force 720p (good balance)
--r 1080   # Force 1080p (default if source >1080p and no --r specified)
           # Auto-preserves if source ≤1080p
```

## Examples by Scenario

### 1. Process 4K HDR Movies
```bash
# Basic
python main.py "P:\movies\4K_HDR" --r 2160

# With CQ override
python main.py "P:\movies\4K_HDR" --r 2160 --cq 25

# With AV1 encoder (8-bit for 4K)
python main.py "P:\movies\4K_HDR" --r 2160 --encoder av1

# With HEVC encoder (10-bit for 4K HDR)
python main.py "P:\movies\4K_HDR" --r 2160 --encoder hevc
```

### 2. Batch Process Mixed Content (4K + 1080p)
Create `batch.txt`:
```
P:\movies\4K_HDR --r 2160 --cq 25
P:\movies\1080p_Collection --r 1080 --cq 28
P:\tv\anime --r 720 --cq 30
```

Then run:
```bash
python main.py --paths-file batch.txt
```

Output:
```
[BATCH 1] Processing 4K_HDR
  Source: 3840x2160, 4K mode, HDR detected
  ✓ Encoded at 4K with HDR color profiles
  
[BATCH 2] Processing 1080p_Collection  
  Source: 1920x1080, Standard 1080p mode
  ✓ Encoded at 1080p, medium audio bitrate
  
[BATCH 3] Processing anime
  Source: 1280x720, Standard 720p mode
  ✓ Encoded at 720p, stereo audio
```

### 3. Test 4K Content (First File Only)
```bash
python main.py "P:\movies\4K_Test" --r 2160 --test
```

Output:
```
📋 MODE: Smart (Try CQ first, retry with Bitrate if needed)
🎬 Processing: 4K_Movie.mkv
  Source: 3840x2160p 10-bit
  HDR content detected (BT.2020 + SMPTE2084)
  Target: 2160p (4K passthrough)
  Audio: 6ch → 8ch | EAC3 640kbps
  Video: HEVC NVENC (CQ=25) | 4K | 10-bit
  HDR color profile: BT.2020 + SMPTE2084 (HDR10)
✓ Test mode: Processed first 15 minutes only
  Original: 15.2 GB | Encoded: 4.3 GB | Ratio: 28.3%
```

### 4. Convert 4K to 1080p (Downscale)
```bash
# Force 4K content to downscale to 1080p (default without --r 2160)
python main.py "P:\movies\4K_HDR"

# Same as:
python main.py "P:\movies\4K_HDR" --r 1080

# Explicit downscale with CQ override
python main.py "P:\movies\4K_HDR" --r 1080 --cq 28
```

### 5. Try 4K on Non-4K Source (Will Skip)
```bash
python main.py "P:\movies\1080p_Content" --r 2160
```

Output:
```
📁 Processing: Movie_1080p.mkv
  Source: 1920x1080p
⏭️  Skipping: --r 2160 requested but source is only 1080p (not 4K)
✓ Skipped 1 file
```

### 6. Travel Mode with 4K (Downscale + Folder)
```bash
# Travel mode forces 720p and CQ+2
python main.py "P:\movies\4K_HDR" --travel --output "D:\Travel"

# Travel mode overrides --r 2160 (always uses 720p)
# Output structure: D:\Travel\4K_HDR\Movie1_[EHX].mkv
```

### 7. 4K with Custom Audio Settings
```bash
# Force specific audio streams and channels
python main.py "P:\movies\4K_HDR" --r 2160 \
  --audio-select 0,2 \
  --audio-titles "0:English,2:Commentary" \
  --audio-channels "0:8,2:2"

# This will:
# - Keep streams 0 and 2 only
# - Name stream 0 "English", stream 2 "Commentary"
# - Encode stream 0 as 8-channel, stream 2 as 2-channel stereo
# - Stream 0: 8ch @ 640kbps high (allowed on 4K)
# - Stream 2: 2ch @ 128kbps low (comment tracks always low)
```

### 8. 4K with Bitrate Mode (Instead of CQ)
```bash
# Use bitrate-based encoding instead of CQ
python main.py "P:\movies\4K_HDR" --r 2160 --m bitrate

# Smart mode will try CQ first, then retry with bitrate if needed
python main.py "P:\movies\4K_HDR" --r 2160
```

## What Happens with `--r 2160`?

### Validation Phase
1. ✅ Source resolution detected
2. ✅ If ≥2160p: Proceed to 4K processing
3. ❌ If <2160p: Skip with user notification

### Processing Phase (if 4K detected)
1. ✅ Detect HDR (BT.2020 + SMPTE2084)
2. ✅ Use `movie_2160` CQ settings
3. ✅ Allow 8-channel audio (max for 4K)
4. ✅ Allow high bitrate (640 kbps) for multi-channel
5. ✅ Apply HDR color profiles (if detected)
6. ✅ Log: "HDR content detected" or HDR absent

### Output Quality
- 4K HDR: Preserves UHD resolution + color metadata
- 4K SDR: Preserves UHD resolution (no special color profile)
- Original files: Never upscaled

## Configuration Tips

### Default CQ Values (from config.xml)
```
movie_2160 = 29 (AV1) / 25 (HEVC)  ← Used for 4K
movie_1080 = 32 (AV1) / 28 (HEVC)  ← Used for 1080p
```

Adjust in config.xml if needed:
```xml
<hevc>
  <movie_2160>24</movie_2160>  <!-- Increase quality for 4K -->
  <movie_1080>28</movie_1080>
</hevc>
```

### Audio Bitrate Tips
For 4K HDR with 8-channel audio:
```xml
<multi_channel>
  <high>640000</high>  <!-- ← This is now used for 4K -->
</multi_channel>
```

Reduce if files too large:
```xml
<multi_channel>
  <high>512000</high>  <!-- 512 kbps for smaller 4K files -->
</multi_channel>
```

## Troubleshooting

### Error: "Source is only 1080p (not 4K)"
- Means: You used `--r 2160` on 1080p content
- Solution: Remove `--r 2160` or change to `--r 1080`

### No "HDR content detected" message
- Means: 4K source is SDR (standard dynamic range)
- This is OK: Will still encode at 4K, just without HDR colors

### File size larger than expected
- Check audio settings: 4K allows high bitrate (640 kbps)
- Reduce: Use `--m bitrate` instead of CQ mode
- Or adjust config.xml multi_channel.high value

### Stuck on "Skipping" messages
- Running on non-4K folder with `--r 2160`
- Ensure folder contains actual 4K files (≥2160p)

## Performance Notes

- **Encoding Time**: 4K ≈ 4-6x slower than 1080p (larger resolution)
- **File Size**: 4K HDR typically 2-3x smaller than original (with 8ch audio)
- **Disk Space**: Ensure temp processing folder has enough space
- **VRAM**: NVENC 4K needs ≥ 4GB VRAM (HEVC/AV1 encoders)