mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* 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>
79 lines
3.4 KiB
Plaintext
79 lines
3.4 KiB
Plaintext
---
|
||
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)
|