add HDR support

Closes #40

Author: piemonte

README.md

@@ -10,11 +10,13 @@ The library provides customizable audio and video encoding options unlike `AVAss
 ### ✨ What's New in Swift 6
 
 - **🚀 Modern Async/Await API** - Native Swift concurrency support with `async/await` and `AsyncSequence`
+- **🌈 HDR Video Support** - Automatic detection and preservation of HLG and HDR10 content with 10-bit HEVC
 - **⚡ Better Performance** - Proper memory management with autoreleasepool in encoding loop
 - **🎯 QoS Configuration** - Control export priority to prevent thread priority inversion (PR #44)
 - **🔒 Swift 6 Strict Concurrency** - Full `Sendable` conformance and thread-safety
 - **📝 Enhanced Error Messages** - Contextual error descriptions with recovery suggestions
 - **♻️ Task Cancellation** - Proper cancellation support for modern Swift concurrency
+- **🛡️ Better Error Handling** - Fixed silent failures causing audio-only exports (#38)
 - **🔙 Backwards Compatible** - Legacy completion handler API still works for iOS 13+
 
 ### Requirements
@@ -283,6 +285,67 @@ exporter.export { renderFrame, presentationTime, resultBuffer in
 }
 ```
 
+### HDR Video Support
+
+NextLevelSessionExporter automatically detects and preserves HDR content (HLG and HDR10) from source videos:
+
+```swift
+// Automatic HDR preservation (default behavior)
+let exporter = NextLevelSessionExporter(withAsset: hdrAsset)
+exporter.outputURL = outputURL
+exporter.videoOutputConfiguration = [
+    AVVideoWidthKey: 1920,
+    AVVideoHeightKey: 1080
+]
+// HDR properties automatically detected and preserved ✨
+
+let result = try await exporter.export()
+// Output maintains HDR color space, transfer function, and 10-bit encoding
+```
+
+**Features:**
+- **Automatic Detection**: Detects HLG (Hybrid Log-Gamma) and HDR10 (PQ) transfer functions
+- **10-bit HEVC**: Automatically configures Main10 profile for 10-bit encoding
+- **Color Properties**: Preserves ITU-R BT.2020 color primaries and YCbCr matrix
+- **HDR Metadata**: Automatically inserts and preserves HDR metadata (iOS 14+)
+
+#### Force SDR Output
+
+To convert HDR to SDR, disable HDR preservation:
+
+```swift
+exporter.preserveHDR = false
+// Output will be 8-bit SDR
+```
+
+#### Explicit HDR Configuration
+
+Force HDR encoding even for SDR source, or override detected transfer function:
+
+```swift
+// Configure for HLG HDR
+exporter.configureForHDR(transferFunction: .hlg)
+
+// Or configure for HDR10 (PQ)
+exporter.configureForHDR(transferFunction: .hdr10)
+
+// Note: HEVC codec and appropriate dimensions required
+exporter.videoOutputConfiguration = [
+    AVVideoCodecKey: AVVideoCodecType.hevc,
+    AVVideoWidthKey: 1920,
+    AVVideoHeightKey: 1080
+]
+```
+
+**Requirements:**
+- iOS 15.0+ or macOS 12.0+
+- HEVC (H.265) codec required for HDR
+- Device must support 10-bit HEVC encoding
+
+**Supported HDR Formats:**
+- HLG (Hybrid Log-Gamma) - Broadcast standard, better for wide compatibility
+- HDR10 (PQ/SMPTE ST 2084) - Consumer HDR standard with static metadata
+
 ### Time Range Trimming
 
 Export only a portion of the video:

Sources/NextLevelSessionExporter.swift

@@ -23,9 +23,25 @@
 
 import Foundation
 import AVFoundation
+import VideoToolbox
 
 // MARK: - types
 
+/// HDR transfer function for video export.
+public enum HDRTransferFunction: String, Sendable {
+    case hlg = "ITU_R_2100_HLG"
+    case hdr10 = "SMPTE_ST_2084_PQ"
+
+    var avTransferFunction: String {
+        switch self {
+        case .hlg:
+            return AVVideoTransferFunction_ITU_R_2100_HLG
+        case .hdr10:
+            return AVVideoTransferFunction_SMPTE_ST_2084_PQ
+        }
+    }
+}
+
 /// Session export errors.
 public enum NextLevelSessionExporterError: LocalizedError, Sendable {
     case setupFailure(String)
@@ -111,6 +127,12 @@ open class NextLevelSessionExporter: NSObject, @unchecked Sendable {
     /// Audio output configuration dictionary, using keys defined in `<AVFoundation/AVAudioSettings.h>`
     public var audioOutputConfiguration: [String : Any]?
 
+    /// Automatically detect and preserve HDR content from source video.
+    /// When enabled, the exporter will detect HDR color space and transfer function
+    /// from the source asset and apply appropriate 10-bit HEVC encoding settings.
+    /// Set to `false` to force SDR output. Default is `true`.
+    public var preserveHDR: Bool = true
+
     /// Export session status state.
     public var status: AVAssetExportSession.Status {
         get {
@@ -170,6 +192,11 @@ open class NextLevelSessionExporter: NSObject, @unchecked Sendable {
     fileprivate var _videoSetupFailed: Bool = false
     fileprivate var _videoSetupError: Error?
 
+    fileprivate var _detectedHDR: Bool = false
+    fileprivate var _hdrTransferFunction: String?
+    fileprivate var _hdrColorPrimaries: String?
+    fileprivate var _hdrYCbCrMatrix: String?
+
     // MARK: - object lifecycle
 
     /// Initializes a session with an asset to export.
@@ -258,6 +285,10 @@ extension NextLevelSessionExporter {
         self._progress = 0
         self._videoSetupFailed = false
         self._videoSetupError = nil
+        self._detectedHDR = false
+        self._hdrTransferFunction = nil
+        self._hdrColorPrimaries = nil
+        self._hdrYCbCrMatrix = nil
 
         do {
             self._reader = try AVAssetReader(asset: asset)
@@ -379,6 +410,123 @@ extension NextLevelSessionExporter {
 
 }
 
+// MARK: - HDR support
+
+extension NextLevelSessionExporter {
+
+    /// Detects HDR color properties from the source video track.
+    ///
+    /// - Parameter videoTrack: The video track to inspect for HDR properties
+    /// - Returns: True if HDR content is detected
+    private func detectHDR(from videoTrack: AVAssetTrack) -> Bool {
+        guard self.preserveHDR else {
+            return false
+        }
+
+        guard let formatDescriptions = videoTrack.formatDescriptions as? [CMFormatDescription],
+              let formatDescription = formatDescriptions.first else {
+            return false
+        }
+
+        guard let extensions = CMFormatDescriptionGetExtensions(formatDescription) as? [String: Any] else {
+            return false
+        }
+
+        // Check for HDR transfer function (HLG or PQ)
+        if let transferFunction = extensions[kCVImageBufferTransferFunctionKey as String] as? String {
+            if transferFunction == kCVImageBufferTransferFunction_ITU_R_2100_HLG as String ||
+               transferFunction == kCVImageBufferTransferFunction_SMPTE_ST_2084_PQ as String {
+                self._hdrTransferFunction = transferFunction
+            }
+        }
+
+        // Check for wide color gamut primaries
+        if let colorPrimaries = extensions[kCVImageBufferColorPrimariesKey as String] as? String {
+            if colorPrimaries == kCVImageBufferColorPrimaries_ITU_R_2020 as String {
+                self._hdrColorPrimaries = colorPrimaries
+            }
+        }
+
+        // Check for YCbCr matrix
+        if let yCbCrMatrix = extensions[kCVImageBufferYCbCrMatrixKey as String] as? String {
+            if yCbCrMatrix == kCVImageBufferYCbCrMatrix_ITU_R_2020 as String {
+                self._hdrYCbCrMatrix = yCbCrMatrix
+            }
+        }
+
+        // HDR is detected if we have transfer function and color primaries
+        let isHDR = self._hdrTransferFunction != nil && self._hdrColorPrimaries != nil
+        self._detectedHDR = isHDR
+
+        return isHDR
+    }
+
+    /// Configures the exporter for explicit HDR output with the specified transfer function.
+    ///
+    /// Call this method to force HDR encoding even if the source is SDR, or to override
+    /// the detected HDR transfer function.
+    ///
+    /// - Parameter transferFunction: The HDR transfer function to use (.hlg or .hdr10)
+    ///
+    /// ## Example
+    /// ```swift
+    /// let exporter = NextLevelSessionExporter(withAsset: asset)
+    /// exporter.configureForHDR(transferFunction: .hlg)
+    /// ```
+    ///
+    /// - Note: This will be applied when you call `export()`. You must also ensure your
+    ///   `videoOutputConfiguration` uses HEVC codec and appropriate dimensions.
+    public func configureForHDR(transferFunction: HDRTransferFunction = .hlg) {
+        self._detectedHDR = true
+        self._hdrTransferFunction = transferFunction.avTransferFunction
+        self._hdrColorPrimaries = kCVImageBufferColorPrimaries_ITU_R_2020 as String
+        self._hdrYCbCrMatrix = kCVImageBufferYCbCrMatrix_ITU_R_2020 as String
+    }
+
+    /// Applies HDR color properties to the video output configuration.
+    ///
+    /// - Parameter videoConfig: The video output configuration dictionary to modify
+    /// - Returns: Modified configuration with HDR properties added
+    private func applyHDRProperties(to videoConfig: [String: Any]) -> [String: Any] {
+        guard self._detectedHDR,
+              let transferFunction = self._hdrTransferFunction,
+              let colorPrimaries = self._hdrColorPrimaries else {
+            return videoConfig
+        }
+
+        var config = videoConfig
+
+        // Ensure HEVC codec for HDR
+        if config[AVVideoCodecKey] == nil {
+            config[AVVideoCodecKey] = AVVideoCodecType.hevc
+        }
+
+        // Add color properties for HDR
+        var colorProperties: [String: Any] = [:]
+        colorProperties[AVVideoTransferFunctionKey] = transferFunction
+        colorProperties[AVVideoColorPrimariesKey] = colorPrimaries
+
+        if let yCbCrMatrix = self._hdrYCbCrMatrix {
+            colorProperties[AVVideoYCbCrMatrixKey] = yCbCrMatrix
+        }
+
+        config[AVVideoColorPropertiesKey] = colorProperties
+
+        // Add compression properties for 10-bit HEVC
+        var compressionProperties = config[AVVideoCompressionPropertiesKey] as? [String: Any] ?? [:]
+        compressionProperties[AVVideoProfileLevelKey] = kVTProfileLevel_HEVC_Main10_AutoLevel
+
+        // Add HDR metadata insertion mode (iOS 14+ / macOS 11+)
+        if #available(iOS 14.0, macOS 11.0, *) {
+            compressionProperties[kVTCompressionPropertyKey_HDRMetadataInsertionMode as String] = kVTHDRMetadataInsertionMode_Auto
+        }
+
+        config[AVVideoCompressionPropertiesKey] = compressionProperties
+
+        return config
+    }
+}
+
 // MARK: - setup funcs
 
 extension NextLevelSessionExporter {
@@ -390,7 +538,26 @@ extension NextLevelSessionExporter {
             return
         }
 
-        self._videoOutput = AVAssetReaderVideoCompositionOutput(videoTracks: videoTracks, videoSettings: self.videoInputConfiguration)
+        // Detect HDR from the first video track
+        if let firstVideoTrack = videoTracks.first {
+            let isHDR = self.detectHDR(from: firstVideoTrack)
+            if isHDR {
+                print("NextLevelSessionExporter, HDR content detected - will preserve HDR properties")
+            }
+        }
+
+        // Configure video input settings for HDR if detected
+        var videoInputSettings = self.videoInputConfiguration
+        if self._detectedHDR {
+            // For HDR, use 10-bit pixel format
+            if videoInputSettings == nil {
+                videoInputSettings = [:]
+            }
+            // Use 420YpCbCr10BiPlanarVideoRange for 10-bit HDR processing
+            videoInputSettings?[kCVPixelBufferPixelFormatTypeKey as String] = NSNumber(integerLiteral: Int(kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange))
+        }
+
+        self._videoOutput = AVAssetReaderVideoCompositionOutput(videoTracks: videoTracks, videoSettings: videoInputSettings)
         self._videoOutput?.alwaysCopiesSampleData = false
 
         if let videoComposition = self.videoComposition {
@@ -407,8 +574,14 @@ extension NextLevelSessionExporter {
         }
 
         // video input
-        if self._writer?.canApply(outputSettings: self.videoOutputConfiguration, forMediaType: AVMediaType.video) == true {
-            self._videoInput = AVAssetWriterInput(mediaType: AVMediaType.video, outputSettings: self.videoOutputConfiguration)
+        // Apply HDR properties to video output configuration if HDR was detected
+        var finalVideoOutputConfiguration = self.videoOutputConfiguration
+        if self._detectedHDR, let videoConfig = finalVideoOutputConfiguration {
+            finalVideoOutputConfiguration = self.applyHDRProperties(to: videoConfig)
+        }
+
+        if self._writer?.canApply(outputSettings: finalVideoOutputConfiguration, forMediaType: AVMediaType.video) == true {
+            self._videoInput = AVAssetWriterInput(mediaType: AVMediaType.video, outputSettings: finalVideoOutputConfiguration)
             self._videoInput?.expectsMediaDataInRealTime = self.expectsMediaDataInRealTime
         } else {
             // Mark video setup as failed - this will cause the export to fail with a clear error
@@ -427,7 +600,11 @@ extension NextLevelSessionExporter {
             // setup pixelbuffer adaptor
 
             var pixelBufferAttrib: [String : Any] = [:]
-            pixelBufferAttrib[kCVPixelBufferPixelFormatTypeKey as String] = NSNumber(integerLiteral: Int(kCVPixelFormatType_32RGBA))
+
+            // Use 10-bit pixel format for HDR, otherwise 8-bit RGBA for SDR
+            let pixelFormat = self._detectedHDR ? kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange : kCVPixelFormatType_32RGBA
+            pixelBufferAttrib[kCVPixelBufferPixelFormatTypeKey as String] = NSNumber(integerLiteral: Int(pixelFormat))
+
             if let videoComposition = self._videoOutput?.videoComposition {
                 pixelBufferAttrib[kCVPixelBufferWidthKey as String] = NSNumber(integerLiteral: Int(videoComposition.renderSize.width))
                 pixelBufferAttrib[kCVPixelBufferHeightKey as String] = NSNumber(integerLiteral: Int(videoComposition.renderSize.height))
@@ -762,6 +939,11 @@ extension NextLevelSessionExporter {
 
         self._videoSetupFailed = false
         self._videoSetupError = nil
+
+        self._detectedHDR = false
+        self._hdrTransferFunction = nil
+        self._hdrColorPrimaries = nil
+        self._hdrYCbCrMatrix = nil
     }
 
 }