> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-feat-thread-message-stack.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Render HDR video

> Preserve BT.2020 PQ or HLG sources in a 10-bit H.265 MP4.

HyperFrames detects HDR media during render. When an MP4 project contains a BT.2020 PQ or HLG source, the output uses 10-bit H.265 and keeps the HDR signal. Projects without HDR media stay SDR.

## Render and verify

```bash theme={null}
npx hyperframes render --output final-hdr.mp4
```

Check the result:

```bash theme={null}
ffprobe -v error -select_streams v:0 -show_entries \
  stream=codec_name,pix_fmt,color_space,color_primaries,color_transfer \
  final-hdr.mp4
```

A PQ output should report values equivalent to:

```text theme={null}
codec_name=hevc
pix_fmt=yuv420p10le
color_space=bt2020nc
color_primaries=bt2020
color_transfer=smpte2084
```

HLG reports `arib-std-b67` as the transfer.

## Control detection

| Command                    | Use it when                                                           |
| -------------------------- | --------------------------------------------------------------------- |
| `hyperframes render`       | Let source metadata decide between HDR and SDR                        |
| `hyperframes render --hdr` | Force HDR; without detected HDR media, HyperFrames uses HLG and warns |
| `hyperframes render --sdr` | Deliver an SDR version even when the project contains HDR media       |

The source files must contain correct color metadata. HyperFrames recognizes video tagged as BT.2020 with PQ (`smpte2084`) or HLG (`arib-std-b67`). It can also preserve supported HDR still images through the native HDR image path.

## Mixed compositions

You can place HTML text, CSS graphics, and SDR media over HDR footage. HyperFrames keeps native HDR layers outside the normal browser screenshot, converts the SDR DOM layer into the HDR color space, and composites the result before encoding.

This is why a lower third or animated interface can remain visually consistent over an HDR source instead of forcing the whole project through an SDR screenshot.

## Limits

* HDR output is MP4 only. MOV, WebM, GIF, PNG sequence, and alpha output fall back to SDR.
* HDR and `--resolution` supersampling cannot be combined in one render. Author at the target dimensions or resize in a separate step.
* Distributed AWS Lambda and Cloud Run renders are currently SDR.
* Hardware H.265 encoding carries the color tags but does not include the same static mastering metadata as the software `libx265` path. Use software encoding for HDR10 delivery.
* Browser playback depends on the host browser, display, and operating system; `<hyperframes-player>` does not add its own HDR playback pipeline.

If the file looks SDR, run `ffprobe` on both the source and output before changing the composition. Missing or incorrect source metadata is the most common cause.

## Related topics

* [Render from the command line](/guides/rendering)
* [Open every render flag](/packages/cli#render)
* [Render at 4K](/guides/4k-rendering)