TylerCG ebe1615e15 currently working

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

6.6 KiB

Raw Blame History

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

python main.py "path\to\4k" --r 2160

Test 4K File (15 min)

python main.py "path\to\4k" --r 2160 --test

Batch Process Mixed Content

python main.py --paths-file batch.txt
# batch.txt:
#   P:\4k_content --r 2160
#   P:\1080p_content --r 1080

With CQ Override

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

python main.py "path\to\1080p" --r 2160
# Result: ⏭️ Skipped "not 4K"

Fix: Omit --r 2160 or use --r 1080

❌ Expecting automatic 4K

python main.py "path\to\4k"
# Result: 🎬 Encoded as 1080p (default)

Fix: Add --r 2160 to enable 4K mode

❌ 8-channel on 1080p

# 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

<cq>
  <hevc>
    <movie_2160>23</movie_2160>  <!-- Lower = better, slower -->
  </hevc>
</cq>

For Smaller 4K Files

<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

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

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

6.6 KiB Raw Blame History