# HDR images and video

> CoreIX supports HDR end to end: high dynamic range is preserved through decoding, editing, and output.

HDR (high dynamic range) lets highlights appear brighter than the white of a standard display while keeping more detail in the shadows. Most photos and videos shot on today's flagship phones are already HDR, but ordinary image processing often strips the HDR and can even leave images looking washed out. CoreIX fully preserves HDR throughout processing, and can also convert to SDR when you need it.

> **Note**
>
> Only HDR sources can produce HDR output. SDR sources are never turned into HDR.

## Supported sources

| Type                 | Recognized HDR sources                                                   |
| :------------------- | ------------------------------------------------------------------------ |
| Gain map photos      | JPEG (Ultra HDR), HEIC (including iPhone photos), AVIF                   |
| PQ / HLG images      | HEIC, AVIF, JPEG XL, PNG                                                 |
| Professional formats | Camera RAW (including Apple ProRAW), OpenEXR, JPEG XR                    |
| Video                | PQ, HLG, Dolby Vision (MP4, MOV); supports frame capture and transcoding |
| Live Photos          | HDR is preserved in the still image                                      |

HDR sources support all standard operations: crop, resize, rotate, compress, format conversion, and watermark. These operations are applied to the HDR information as well, so the output remains HDR.

## Default output

When you don't pass any HDR parameters, the output format determines the HDR form:

| Output format | HDR form                    | Bit depth | Compatibility                                            |
| :------------ | --------------------------- | :-------: | -------------------------------------------------------- |
| JPEG          | Gain map                    |     8     | Best: devices without HDR support automatically show SDR |
| HEIC          | Gain map                    |     8     | Same as above                                            |
| AVIF          | PQ                          |     10    | Modern browsers such as Chrome and Safari                |
| PNG           | PQ                          |     16    | Modern browsers                                          |
| JPEG XL       | PQ                          |     16    | Safari                                                   |
| WebP, GIF     | No HDR support; outputs SDR |     8     | –                                                        |

> **Tip**
>
> For distribution to a broad audience, we recommend JPEG: a single image works on both HDR and SDR devices. If file size and image quality matter most, choose AVIF.

## Parameters

| Parameter       | Description                                                                                                                                                                             |       Default       | Values                                     |
| :-------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------: | ------------------------------------------ |
| `hdr-rate`      | **HDR brightness**. As a percentage: keeps that proportion of the original image's HDR intensity. As a number: sets the peak brightness as a multiple of SDR white. `0` converts to SDR |   Same as original  | 0% to 100%, or 0 to 10                     |
| `hdr-fmt`       | **HDR form**. `gainmap`: gain map; `pq`: PQ; `hlg`: HLG; `keep`: match the original                                                                                                     |        `auto`       | `auto` / `gainmap` / `pq` / `hlg` / `keep` |
| `depth`         | **Maximum output bit depth**. Applies only to PQ / HLG output. Up to 12 for AVIF and up to 16 for JPEG XL and PNG; HEIC is fixed at 10                                                  | See the table above | 10 to 16                                   |
| `mark-hdr-rate` | **HDR brightness of the watermark**. See the watermark docs for details                                                                                                                 |         0.5         | 0 to 1                                     |

- `hlg` supports HEIC, AVIF, JPEG XL, and PNG. JPEG has no HLG form, so the default behavior applies.
- Frames captured from video carry no peak brightness information, so the percentage form of `hdr-rate` may have no effect. Use a number or `0` instead.

### Convert to SDR

Add `hdr-rate=0` to map HDR to a standard SDR image with natural color and brightness and no washed-out look. Use this when the target device or app doesn't support HDR. Processing is also faster.

### HDR video transcoding

HDR video transcoding keeps HDR by default (HEVC, 10-bit). When you specify `vcodec=h264`, the video is automatically mapped to SDR for compatibility with players that don't support HDR.

## HDR demo

> **Note**
>
> To see the HDR effect, you need:
>
> - An HDR-capable display (peak brightness of 600 nits or higher), such as a MacBook Pro, iPhone, or LG 32GQ950.
> - A browser that supports HDR, such as Chrome or Safari.

### Frames captured from HDR video

| HDR source                                                                       | CoreIX frame, HDR output (default)                                                                                                                                     | CoreIX frame, converted to SDR                                                                                                                                                                | Alibaba Cloud OSS: color and orientation lost                                                                                                                                                                                                                                     |
| :------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [rainbow.mov (recorded on iPhone)](https://demo.bitiful.com/hdr-img/rainbow.mov) | ![Rainbow: HDR frame](https://demo.bitiful.com/hdr-img/rainbow.mov?frame=5000&w=1200)[View full size](https://demo.bitiful.com/hdr-img/rainbow.mov?frame=5000\&w=2000) | ![Rainbow: SDR frame](https://demo.bitiful.com/hdr-img/rainbow.mov?frame=5000&w=1200&hdr-rate=0)[View full size](https://demo.bitiful.com/hdr-img/rainbow.mov?frame=5000\&w=2000\&hdr-rate=0) | ![Rainbow: Alibaba Cloud OSS frame](https://oss.ladydaily.com/hdr-img/rainbow.mov?x-oss-process=video/snapshot,t_4950,f_jpg,scaletype_crop,w_1200)[View full size](https://oss.ladydaily.com/hdr-img/rainbow.mov?x-oss-process=video/snapshot,t_4950,f_jpg,scaletype_crop,w_2000) |
| [foods.mov (recorded on iPhone)](https://demo.bitiful.com/hdr-img/foods.mov)     | ![Food: HDR frame](https://demo.bitiful.com/hdr-img/foods.mov?frame=5000&w=1200)[View full size](https://demo.bitiful.com/hdr-img/foods.mov?frame=5000\&w=2000)        | ![Food: SDR frame](https://demo.bitiful.com/hdr-img/foods.mov?frame=5000&w=1200&hdr-rate=0)[View full size](https://demo.bitiful.com/hdr-img/foods.mov?frame=5000\&w=2000\&hdr-rate=0)        | ![Food: Alibaba Cloud OSS frame](https://oss.ladydaily.com/hdr-img/foods.mov?x-oss-process=video/snapshot,t_4950,f_jpg,scaletype_crop,w_1200)[View full size](https://oss.ladydaily.com/hdr-img/foods.mov?x-oss-process=video/snapshot,t_4950,f_jpg,scaletype_crop,w_2000)        |
