tyler/conversion_project

Fork 0

TylerCG ebe1615e15 currently working

2026-08-20 10:51:14 -04:00

8.9 KiB

Raw Blame History

4K HDR Implementation - Complete Change Summary

✅ Implementation Complete

All requirements have been successfully implemented, tested, and validated.

📋 Changes Overview

Core Features Added

✅ 4K Resolution Support with source validation (--r 2160)
✅ HDR Detection (BT.2020 + SMPTE2084 color space)
✅ Intelligent Audio Channel Management (720p=2ch, 1080p=6ch, 4K=8ch)
✅ Resolution-Aware Bitrate Selection (4K allows high bitrate for 6/8ch audio)
✅ Dynamic HDR Color Profiles for ffmpeg encoding

Backward Compatibility

✅ 100% Backward Compatible

Default behavior unchanged (4K still downscales to 1080p)
All existing flags work as before
Audio logic for 1080p and lower unchanged
No config changes required

📁 Files Modified

1. main.py

Added "2160" to resolution choices in argparse
Updated help text for --r flag

2. core/video_handler.py

✨ NEW: is_hdr() function for HDR detection
ENHANCED: determine_target_resolution() with 2160p validation
Returns special "2160_SKIP" signal for non-4K sources with --r 2160

3. core/audio_handler.py

ENHANCED: choose_audio_bitrate() function signature
Added resolution parameter
Added channel clamping logic per resolution
Returns 3-tuple: (codec, bitrate, output_channels)
Allows high bitrate (640kbps) for 4K multi-channel

4. core/encode_engine.py

ENHANCED: run_ffmpeg() function
Added is_hdr parameter
Added HDR color profile ffmpeg flags
Updated audio processing to use resolution string
Uses final_channels from choose_audio_bitrate()

5. core/process_manager.py

Added is_hdr import from video_handler
Detects HDR content before encoding
Validates 4K source (skips non-4K with --r 2160)
Passes is_hdr_content through encoding pipeline
Stores HDR flag in failed_cq_files for retries

🎯 Key Behaviors

Resolution Handling

Input: 3840x2160 (4K), no flag
Output: 1920x1080 (1080p) ← Default downscale (backward compatible)

Input: 3840x2160 (4K), --r 2160
Output: 3840x2160 (4K) ← Passthrough
        + HDR detection + color profiles (if detected)

Input: 1920x1080 (1080p), --r 2160
Output: SKIPPED ← "Source is only 1080p (not 4K)"

Audio Channel Limits

Resolution  │ Max Channels │ Max Bitrate (Multi-channel)
─────────────┼──────────────┼────────────────────────────
720p        │ 2 (stereo)   │ 160 kbps (stereo high)
1080p       │ 6 (5.1)      │ 448 kbps (medium) ⚠️
4K (2160p)  │ 8 (7.1+)     │ 640 kbps (high) ✨ NEW

Audio Bitrate Resolution

Example: 8-channel audio on 1080p
1. Source channels: 8
2. 1080p max channels: 6
3. Downmix: 8 → 6 channels
4. Max bitrate: 448 kbps (medium only)
5. Output: 6-channel EAC3 at 448 kbps

Example: 8-channel audio on 4K
1. Source channels: 8
2. 4K max channels: 8
3. No downmix needed: 8 → 8 channels
4. Max bitrate: 640 kbps (high allowed)
5. Output: 8-channel EAC3 at 640 kbps

HDR Detection and Application

Source: 4K with BT.2020 + SMPTE2084
1. Detected: HDR = True
2. ffmpeg flags applied:
   -color_space bt2020_ncl
   -color_primaries bt2020
   -color_trc smpte2084
3. Output: HDR10 compatible file

Source: 4K without HDR color space
1. Detected: HDR = False
2. No special color flags
3. Output: Standard 4K file

🧪 Test Results

All Test Cases Passed ✅

Resolution Logic Tests:
  ✅ 4K default behavior (downscale to 1080p)
  ✅ 4K with --r 2160 (passthrough at 4K)
  ✅ 1080p with --r 2160 (skip signal)
  ✅ 1080p with --r 1080 (preserve)

Audio Channel Tests:
  ✅ 2ch stereo on all resolutions
  ✅ 6ch on 1080p (max for 1080p)
  ✅ 8ch on 1080p (downmix to 6ch)
  ✅ 8ch on 4K (full 8ch + high bitrate)
  ✅ 6ch on 4K (full 6ch + high bitrate)

Module Integration Tests:
  ✅ All imports successful
  ✅ No syntax errors
  ✅ No circular dependencies

📊 Configuration Example

The existing config.xml is fully compatible:

<encode>
  <cq>
    <hevc>
      <movie_2160>25</movie_2160>    ← Used for 4K HEVC
      <movie_1080>28</movie_1080>    ← Used for 1080p
      <movie_720>30</movie_720>      ← Used for 720p
    </hevc>
    <av1>
      <movie_2160>29</movie_2160>    ← Used for 4K AV1
      <movie_1080>32</movie_1080>
      <movie_720>30</movie_720>
    </av1>
  </cq>
</encode>

<audio>
  <stereo>
    <low>128000</low>
    <medium>160000</medium>
    <high>192000</high>
  </stereo>
  <multi_channel>
    <low>384000</low>
    <medium>448000</medium>
    <high>640000</high>    ← Now used for 4K multi-channel
  </multi_channel>
</audio>

🚀 Usage Quick Start

Basic 4K Processing

python main.py "P:\movies\4K_HDR" --r 2160

Batch Mixed Content

# batch.txt
P:\movies\4K_HDR --r 2160 --cq 25
P:\movies\1080p --r 1080 --cq 28

python main.py --paths-file batch.txt

With Custom Audio

python main.py "P:\movies\4K" --r 2160 \
  --audio-channels "0:8,1:2" \
  --audio-titles "0:English,1:Commentary"

📝 Documentation Files

Created comprehensive documentation:

IMPLEMENTATION_SUMMARY_4K_HDR.md - Technical implementation details
AUDIO_CONFIG_GUIDE.md - Audio bucket configuration and bitrate usage
4K_HDR_CLI_REFERENCE.md - Command line examples and troubleshooting

🔄 Pipeline Summary

Encoding Pipeline (with new features)

Input Video File
    ↓
[Resolution Detection]
    ├─ Detect: width, height, bit depth
    ├─ Detect: HDR (color space + transfer)
    └─ Return: src_width, src_height, is_hdr
    ↓
[Resolution Scaling Decision]
    ├─ If --r 2160:
    │   ├─ If source ≥ 2160p: ✅ 4K mode
    │   └─ If source < 2160p: ⏭️  SKIP
    ├─ Else if explicit resolution:
    │   └─ Use as max (downscale only)
    └─ Else: Default (4K→1080p)
    ↓
[Audio Processing]
    ├─ Detect: channels, bitrate, language
    ├─ Clamp channels: 720p=2, 1080p=6, 4K=8
    ├─ Select codec: AAC (2ch) or EAC3 (6/8ch)
    └─ Select bitrate: Resolution-aware (4K allows high)
    ↓
[Video Encoding]
    ├─ Select encoder: HEVC (10-bit) or AV1 (8-bit)
    ├─ Set CQ: From config movie_XXXX settings
    ├─ Apply HDR: If is_hdr=True:
    │   ├─ -color_space bt2020_ncl
    │   ├─ -color_primaries bt2020
    │   └─ -color_trc smpte2084
    └─ Output: HDR10 compatible file
    ↓
Output Encoded File

✨ Key Improvements

No More 4K Surprises: Explicit --r 2160 flag prevents accidental 4K processing
Source Validation: Non-4K sources automatically skipped, no failed encodes
Smart Audio: Channels and bitrate automatically optimized per resolution
HDR Preservation: Detects and preserves HDR color metadata automatically
Flexible Config: Works with existing config.xml, no changes required
Quality Hierarchy: 4K gets best audio (up to 640 kbps), 1080p capped at 448 kbps

🎓 Learning Notes

For Future Enhancements

HDR metadata (MaxCLL, MaxFALL) could be extracted and logged
HDR10+ detection could expand beyond BT.2020+SMPTE2084
Dolby Vision support could be added (requires additional detection)
Scene-based quality adjustments for HDR could be implemented

Edge Cases Handled

Non-4K sources with --r 2160: Skipped automatically
8ch audio on 1080p: Downmixed to 6ch + bitrate capped
6ch audio on 4K: Kept at 6ch + bitrate upgraded to high
HDR detection: Skips attached pictures and cover art
Fallback to bitrate mode: Works even if HDR flags not recognized

📞 Integration Points

With Existing System

Uses existing config.xml structure (no new sections needed)
Uses existing CLI argument handling
Uses existing encoder selection logic
Integrates with smart CQ/Bitrate mode
Compatible with batch processing and travel mode

Resolution-Aware Config Lookup

# Auto-selects CQ based on target resolution
cq_key = f"movie_{target_resolution}"
# Examples: "movie_2160", "movie_1080", "movie_720"

encoder_cq_config = config["encode"]["cq"].get(selected_encoder, {})
content_cq = encoder_cq_config.get(cq_key, 32)

✅ Verification Checklist

✅ All syntax checks pass (Pylance)
✅ All imports successful
✅ Unit tests pass (resolution logic)
✅ Unit tests pass (audio bitrate selection)
✅ Backward compatibility verified
✅ 2160_SKIP signal works
✅ HDR detection functional
✅ Audio channel clamping works
✅ Resolution-aware bitrate works
✅ Documentation complete
✅ Code properly formatted
✅ No breaking changes

🎉 Summary

The 4K HDR implementation is complete, tested, and production-ready.

Key Takeaway: Intelligent, opt-in 4K support with automatic HDR detection, resolution-aware audio management, and 100% backward compatibility.

8.9 KiB Raw Blame History