Files
hyperframes/docs/guides/hdr.mdx
T
andybpanandClaude Opus 5.5 758ad7f585 fix(hdr): bound HDR image decode and resample sizes (#7917)
* fix(hdr): bound HDR image decode and resample sizes

The native HDR image path sized its host buffers from the PNG header and
the element's page-measured layout box, with no ceiling.

- PNG decode checks IHDR dimensions and bit depth before allocating,
  inflates with maxOutputLength = height * (stride + 1), and rejects image
  data whose inflated length does not match the header.
- HDR images are limited to 8192x8192 pixels; resampleRgb48leObjectFit
  refuses targets above that.
- A layout box larger than the output frame is shrunk uniformly to fit it.
- Decoded and resampled HDR image buffers count against the HDR extraction
  budget (HDR_EXTRACTION_MAX_BYTES / cgroup limit) for the render's lifetime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* build(engine): raise the packed size budget to 510000 bytes

The PNG header checks and bounded inflate add about 500 bytes to the
packed engine, which was already within a few hundred bytes of its
1% tolerance over the 500000-byte budget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 03:15:55 +00:00

79 lines
3.4 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Render HDR video
description: Preserve BT.2020 PQ or HLG sources in a 10-bit H.265 MP4.
---
import { DocsVideo } from "/snippets/docs-video.jsx";
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.
<DocsVideo
title="What HDR rendering produces, measured rather than simulated"
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/hdr-render-demo-v2.mp4"
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/hdr-render-demo-v1.jpg"
/>
You are reading this on an SDR screen, so nothing above can show you HDR
brightness — and it does not try. It shows the `ffprobe` verdict on a real render
and a brightness round-trip: 4000 nits authored, 4012 measured back out.
## Render and verify
```bash
npx hyperframes render --output final-hdr.mp4
```
Check the result:
```bash
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
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.
- Native HDR still images can be up to 8192×8192 pixels. An HDR image whose box is larger than the video frame is drawn shrunk to fit inside it, keeping its aspect ratio.
- 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)