conversion_project/IMPLEMENTATION_SUMMARY_4K_HDR.md

# 4K HDR Implementation Summary

## Overview
Implemented comprehensive 4K HDR content support with intelligent audio channel management and dynamic color profiles. The system maintains backward compatibility with existing 480p/720p/1080p logic while adding opt-in 4K HDR capabilities.

## Key Features Implemented

### 1. **2160p Resolution Support with Validation** (`--r 2160` flag)
- **File**: `main.py`, `core/video_handler.py`, `core/process_manager.py`
- **Changes**:
  - Added `2160` as valid resolution choice in argparse
  - Updated `determine_target_resolution()` to handle 2160p with source validation
  - 4K mode requires actual 4K source (>= 2160p height)
  - Non-4K sources are skipped with user notification (returns special "2160_SKIP" signal)
  - Default behavior (no flag): 4K still downscales to 1080p (backward compatible)

**Behavior**:
```
python main.py /path/to/4k/content --r 2160
  ✓ If source is 4K (2160p+): Passes through at 4K
  ✓ If source is 1080p: Skips with message "Source is only 1080p (not 4K)"
  ✓ No upscaling: Prevents accidental upscaling
```

### 2. **HDR Detection** (`is_hdr()` function)
- **File**: `core/video_handler.py`
- **New Function**: `is_hdr(input_file: Path) -> bool`
- **Detection Method**: Checks video stream color characteristics
  - BT.2020 color space (wide gamut)
  - SMPTE ST 2084 (PQ) tone mapping transfer
  - Skips attached pictures and cover art
- **Not all 4K is HDR**: HDR detection is separate from resolution
  - 4K SDR content: Passes 4K check but marked as non-HDR
  - 4K HDR content: Both 4K check and HDR flag enabled

**Output**:
```
🎬 HDR content detected (BT.2020 + SMPTE2084)
```

### 3. **Dynamic Audio Channel Management**
- **File**: `core/audio_handler.py`
- **Channel Limits by Resolution**:
  - 720p: Max 2 channels (stereo)
  - 1080p: Max 6 channels (5.1)
  - 4K (2160p): Max 8 channels

**Implementation**: Updated `choose_audio_bitrate()` function signature:
```python
def choose_audio_bitrate(
    channels: int, 
    bitrate_kbps: int, 
    audio_config: dict, 
    is_1080_class: bool, 
    is_commentary: bool = False,
    resolution: str = "1080"  # NEW parameter
) -> tuple:
```

Returns: `(codec, target_bitrate_bps, output_channels)`
- Third return value is the clamped channel count

### 4. **Resolution-Aware Audio Bitrate Selection**
- **File**: `core/audio_handler.py`
- **Logic**:

#### 1080p Multi-Channel (6 channels max)
- Low bitrate: 384 kbps
- Medium bitrate: 448 kbps (default cap)
- High bitrate: NOT USED (reserved for 4K)

#### 4K Multi-Channel (8 channels max)
- Low bitrate: 384 kbps
- Medium bitrate: 448 kbps
- High bitrate: 640 kbps (NEW - now allowed for 6/8 channel audio on 4K)

**Benefits**:
- 4K: Can use up to 640 kbps for 6 or 8 channel audio
- 1080p: Capped at 448 kbps to balance quality/file size
- Backward compatible: 720p/1080p unchanged

### 5. **HDR Color Profile Support**
- **File**: `core/encode_engine.py`
- **Implementation**: Added `is_hdr` parameter to `run_ffmpeg()` function
- **ffmpeg Options Applied** (when HDR detected):
  ```bash
  -color_space bt2020_ncl       # BT.2020 color space (narrow range)
  -color_primaries bt2020       # BT.2020 primaries
  -color_trc smpte2084          # SMPTE ST 2084 PQ tone mapping (HDR10)
  ```

**Output**:
```
🎬 HDR color profile: BT.2020 + SMPTE2084 (HDR10)
```

### 6. **Encoder Selection (Existing but Enhanced)**
- **File**: `core/process_manager.py`
- Auto-selection logic maintained:
  - 10-bit+ source: HEVC NVENC (10-bit)
  - 8-bit source: AV1 NVENC (8-bit)
- **New**: Uses `movie_2160` CQ settings for 4K content

## Files Modified

### 1. `main.py`
- Updated argparse to accept `"2160"` as resolution choice
- Updated help text to explain 2160 mode requires actual 4K source

### 2. `core/video_handler.py`
- **New Function**: `is_hdr()` - Detects HDR via color space/transfer characteristics
- **Modified Function**: `determine_target_resolution()` - Adds 2160p special handling with validation

### 3. `core/audio_handler.py`
- **Modified Function**: `choose_audio_bitrate()` 
  - Added `resolution` parameter
  - Added channel clamping logic (720p=2, 1080p=6, 4K=8)
  - Returns 3-tuple including final output channels
  - Allows "high" bitrate for 4K multi-channel (6/8ch)

### 4. `core/encode_engine.py`
- **Modified Function**: `run_ffmpeg()`
  - Added `is_hdr: bool = False` parameter
  - Added HDR color profile flags when `is_hdr=True`
  - Updated audio bitrate calls to pass resolution string
  - Uses `final_channels` from `choose_audio_bitrate()` return

### 5. `core/process_manager.py`
- **Import**: Added `is_hdr` to video_handler imports
- **New Logic**: 
  - Calls `is_hdr()` to detect HDR content
  - Checks for "2160_SKIP" signal and skips non-4K sources
  - Logs HDR detection in console
  - Passes `is_hdr_content` to run_ffmpeg calls
  - Stores `is_hdr` in failed_cq_files for Phase 2 retries

## Backward Compatibility

✅ **Fully Backward Compatible**
- Default behavior (no `--r 2160`): 4K still downscales to 1080p
- Existing flags (`--r 480`, `--r 720`, `--r 1080`): Unchanged
- Existing audio logic: Preserved for non-4K content
- All config.xml existing values: Work as before

## Testing Results

All test cases passed:

### Resolution Logic
- ✅ 4K with no flag → downscale to 1080p
- ✅ 4K with `--r 2160` → passthrough at 4K
- ✅ 1080p with `--r 2160` → skip (2160_SKIP signal)
- ✅ 1080p with `--r 1080` → preserve 1080p

### Audio Channel Logic
- ✅ 2ch stereo on 1080p → 2 channels
- ✅ 6ch on 1080p → 6 channels max, medium bitrate
- ✅ 8ch on 1080p → downmix to 6 channels (1080p max)
- ✅ 8ch on 4K → 8 channels, high bitrate allowed
- ✅ 6ch on 4K → 6 channels, high bitrate allowed
- ✅ 2ch on 720p → 2 channels (stereo)

### Module Imports
- ✅ All modules import successfully
- ✅ No circular import issues
- ✅ All syntax checks pass

## Usage Examples

### Basic 4K Encoding (with HDR support auto-detection)
```bash
python main.py "P:\movies\4K_Movie" --r 2160
```

### 4K with Specific CQ Value
```bash
python main.py "P:\movies\4K_HDR" --r 2160 --cq 25
```

### Batch Processing with 4K
```bash
python main.py --paths-file batch.txt
# batch.txt contains:
# P:\movies\4K_Content --r 2160
# P:\movies\1080p_Content --r 1080
```

### Travel Mode (unchanged)
```bash
python main.py "P:\movies\HDR_4K" --travel --output "D:\Travel" --r 2160
```

## Console Output Example

```
🎬 Processing: Movie_4K_HDR.mkv
=====================================================
📊 Source: 3840x2160p 10-bit
🎬 HDR content detected (BT.2020 + SMPTE2084)
📋 Target: 2160p (4K passthrough)
🎙️  Audio Streams (2):
    - Stream #0: 6ch→8ch | eng | Detected: EAC3 640kbps | Output: EAC3 640kbps (ENC)
    - Stream #1: 2ch→2ch | eng (Commentary) | Detected: AAC 128kbps | Output: AAC 128kbps (COPY)
🎬 Encoding: Movie_4K_HDR - [EHX].mkv
📹 Video: AV1 NVENC (CQ=29) | 2160p | 8-bit (yuv420p)
    HDR color profile: BT.2020 + SMPTE2084 (HDR10)
```

## Future Enhancements (Not Implemented)

- HDR metadata extraction (MaxCLL, MaxFALL)
- Tone mapping for HDR to SDR conversion (reverse process)
- Dolby Vision support detection
- HDR10+ metadata preservation
- Scene-based quality adjustments for HDR content

## Notes

1. **Color Profile Preservation**: The implementation ensures HDR color metadata is preserved in the output file
2. **No Upscaling**: The system never upscales content - it preserves source resolution
3. **Fallback Behavior**: If ffmpeg doesn't support HDR flags in encode, the fallback bitrate mode still works
4. **Resolution String**: Used for bitrate selection (720/1080/2160) - allows future expansion