conversion_project/4K_HDR_CLI_REFERENCE.md

4K HDR Mode - Command Line Reference

Quick Start

Enable 4K HDR Processing

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)

--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

# 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:

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)

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)

# 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)

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)

# 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

# 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)

# 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:

<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:

<multi_channel>
  <high>640000</high>  <!-- ← This is now used for 4K -->
</multi_channel>

Reduce if files too large:

<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)