Export HDR media in your app with AVFoundation

Highlight

At WWDC 2020 Apple opened HDR export to developers: HEVC and Apple ProRes presets in AVAssetExportSession preserve HLG/HDR10 source formats, and AVAssetWriter can configure codec, color properties, and Main10 profile through sourceFormatHint or AVOutputSettingsAssistant.

Core Content

When video apps exported media, they mainly cared about resolution, bitrate, frame rate, and container format. HDR adds hard requirements: SDR is typically limited to 100 nits while HDR can reach 10,000 nits; HDR is often tied to Wide Color gamut and 10-bit delivery. Dropping transfer function, color primaries, or profile during export shifts highlights, shadow detail, and color away from the source.

This session splits the problem into two paths. The first is AVAssetExportSession, suited to file transcoding, simple sharing, timeline composition with AVComposition, and spatial composition with AVVideoComposition. Apple upgraded HEVC and Apple ProRes presets: HDR10 sources export as HDR10, HLG sources as HLG, SDR sources remain SDR.

The second path is AVAssetWriter. It fits apps that need control over codec, bit rate, frame rate, size, color space, dynamic range, and even a specific encoder on multi-encoder Macs. The session’s advice is direct: pass the source video’s videoFormatDescription as a hint, or use AVOutputSettingsAssistant to generate defaults close to AVAssetExportSession, then tweak a few fields for product needs.

Detailed Content

1. Decide the HDR export target first (06:15)

AVFoundation supports HLG and HDR10 on the export side. HLG has no extra HDR metadata and is designed with SDR compatibility in mind; HDR10 uses a PQ transfer function and can carry static metadata. Dolby Vision is explained in the session as a dynamic-metadata format conceptually, but export support explicitly lists HLG and HDR10.

Key settings:

• Choose HEVC or Apple ProRes for the codec.
• Choose HLG or PQ for the transfer function.
• HDR content commonly uses Wide Color gamut; the transcript mentions BT.2020.
• HEVC HDR export requires HEVC_Main10_AutoLevel; 8-bit HEVC HDR is not supported.

2. Preserve source HDR with AVAssetExportSession (09:02)

If export needs are close to file transcoding, AVAssetExportSession is the shortest path. The session’s point: with HEVC or Apple ProRes presets, HDR export needs no extra code changes.

guard let exportSession = AVAssetExportSession(asset: sourceAsset,
                      presetName: AVAssetExportPresetHEVCHighestQuality) else {
    // Handle error
}

exportSession.outputURL = outputURL
exportSession.outputFileType = AVFileTypeQuickTimeMovie

exportSession.exportAsynchronouslyWithCompletionHandler {
    // Handle completion
}

Key points:

• AVAssetExportPresetHEVCHighestQuality selects the high-quality HEVC preset; the session says existing HEVC presets preserve source HDR format.
• outputURL and outputFileType are export targets; the example uses QuickTime movie.
• exportAsynchronouslyWithCompletionHandler starts async export; completion handling stays in the app.
• To convert HDR to SDR, the session recommends H.264 presets for better backward compatibility.

With mixed sources, AVAssetExportSession inspects all source assets. If any HDR content is found, the output file is HDR and SDR sources are converted to HDR. When different HDR formats are mixed, the default strategy favors HLG first, then HDR formats with metadata.

3. Simplify configuration with AVAssetWriter and sourceFormatHint (13:24)

AVAssetWriter gives more control but output settings dictionaries are easier to get wrong. The first simplification passes the source asset’s videoFormatDescription to AVAssetWriterInput.

let assetWriter = try AVAssetWriter(url: outputURL, fileType: AVFileTypeQuickTimeMovie)

let outputSettings: [String: AnyObject] = [
            AVVideoCodecKey: AVVideoCodecTypeHEVC
        ]

let assetWriterInput = AVAssetWriterInput(mediaType: AVMediaTypeVideo,
                                     outputSettings: outputSettings,
                                   sourceFormatHint: videoFormatDescription)

assetWriter.add(assetWriterInput)

guard assetWriter.startWriting() else {
    throw assetWriter.error!
}

Key points:

• AVAssetWriter still specifies output URL and QuickTime movie file type.
• outputSettings only explicitly sets AVVideoCodecKey.
• sourceFormatHint passes the source video format description; AVAssetWriter fills reasonable defaults from source characteristics.
• When startWriting() fails, read assetWriter.error; this example does not hide error handling.

4. Generate an editable settings template with AVOutputSettingsAssistant (14:13)

The second simplification is AVOutputSettingsAssistant. Its presets resemble AVAssetExportSession but return a settings dictionary for AVAssetWriterInput.

let assetWriter = try AVAssetWriter(url: outputURL, fileType: AVFileTypeQuickTimeMovie)

let settingsAssistant = AVOutputSettingsAssistant(
                                     preset: AVOutputSettingsPreset.hevc1920x1080)

settingsAssistant.sourceVideoFormat = videoFormatDescription

let newVideoSettings = settingsAssistant.videoSettings

// Modify a few fields in newVideoSettings here

let assetWriterInput = AVAssetWriterInput(mediaType: AVMediaTypeVideo,
                                     outputSettings: newVideoSettings)

assetWriter.add(assetWriterInput)
guard assetWriter.startWriting() else {
    throw assetWriter.error!
}

Key points:

• hevc1920x1080 provides an HEVC dimension preset.
• Set sourceVideoFormat before reading videoSettings; the transcript stresses combining source characteristics with the preset.
• videoSettings can be used as-is or as a starting point to change size, bit rate, and other fields.
• This path suits exporters that want behavior close to AVAssetExportSession defaults with a few custom controls.

5. Check HDR-related outputSettings (15:36)

The transcript explicitly calls out three key groups for HDR export.

Key	What to verify
AVVideoCodecKey	HDR export supports HEVC and Apple ProRes. HEVC suits delivery; ProRes suits professional video workflows.
AVVideoColorPropertiesKey	Includes transfer function, color primaries, and YCbCr matrix. HLG and PQ are supported HDR transfer functions; HDR content commonly uses BT.2020.
AVVideoCompressionPropertiesKey	For HEVC HDR export, VideoProfileLevelKey must be HEVC_Main10_AutoLevel. This key does not apply to ProRes export.

HDR10 can also carry two metadata items: MasteringDisplayColorVolume describes the mastering display, and ContentLightLevelInfo describes overall clip light levels. The session recommends providing both when possible because missing metadata forces decoders to assume default EOTF behavior.

6. Remember platform boundaries (20:44)

On iOS, devices with Apple A10 Fusion or newer support HEVC hardware encoding. Examples in the session include iPhone 7, iPads released in 2018, and the 2019 iPod touch.

On Mac, all Macs have HEVC and Apple ProRes software encoders. HEVC hardware encoding generally appears on 2017 and newer Macs running recent macOS; hardware encoding makes export much faster.

Core Takeaways

• What to do: Add an “export HDR as-is” option to your video editing app. Why it’s worth it: HEVC and Apple ProRes presets in AVAssetExportSession preserve HDR10 or HLG source format. How to start: Reuse your existing export flow, switch the preset to HEVC or Apple ProRes, and verify output format against source type after export.

• What to do: Add HDR clip export to camera apps. Why it’s worth it: AVAssetWriter can write files directly from camera-captured frames and control codec, frame rate, size, and dynamic range. How to start: Create AVAssetWriter, pass the captured video’s videoFormatDescription as sourceFormatHint, and initially set only AVVideoCodecKey explicitly.

• What to do: Build a mixed SDR/HDR export preview warning. Why it’s worth it: AVAssetExportSession biases toward HDR output in mixed compositions and converts SDR sources to HDR. How to start: Scan dynamic range of timeline assets and show in the export panel whether output will be HDR, HLG, or a metadata-bearing format.

• What to do: Provide an “HDR10 parameter check” panel for pro users. Why it’s worth it: HDR10 output depends on PQ, BT.2020, Main10 profile, and can be affected by MDCV and CLLI metadata. How to start: List codec, transfer function, color primaries, matrix, profile level, and metadata status on the AVAssetWriter settings page before export.

• What to do: Offer both HDR and SDR share versions. Why it’s worth it: The session recommends H.264 presets to convert HDR to SDR for better compatibility on older devices. How to start: Run two exports from the same source—one with HEVC or ProRes to preserve HDR, another with H.264 for an SDR share file.

Related Sessions

• Edit and play back HDR video with AVFoundation — See how HDR media is edited and previewed in AVVideoComposition, Core Image, and custom compositors first.
• Author fragmented MPEG-4 content with AVAssetWriter — Continue with AVAssetWriter fragmented MPEG-4 output for HLS segment files.
• Optimize the Core Image pipeline for your video app — Useful for pre-export video filter pipelines, CIContext, and Metal performance.
• Decode ProRes with AVFoundation and VideoToolbox — Complements ProRes export choices with decode and display pipeline details.