# How to Implement HDR/EXR Output Workflows with LTX-2: Complete Developer Guide

> Unlock HDR/EXR output workflows with LTX-2. This guide details using the CLI flag and HDRICLoraPipeline for advanced HDR transformations and EXR generation. Get your HDR video output today.

- Repository: [Lightricks/LTX-2](https://github.com/Lightricks/LTX-2)
- Tags: how-to-guide
- Published: 2026-08-14

---

**LTX-2 supports HDR video generation through the native `--hdr` CLI flag for automatic EXR and HLG output, and through the `HDRICLoraPipeline` class for advanced IC-LoRA-based HDR transformations with manual post-processing control.**

HDR (high-dynamic-range) video generation in LTX-2 is built on two complementary mechanisms. Both enable half-float EXR output and BT.2020/HLG encoding, but they serve different production needs. The native `--hdr` flag provides streamlined, end-to-end HDR workflows in standard pipelines, while `HDRICLoraPipeline` offers granular control for video-to-video HDR transformations requiring custom colour grading or log-curve adjustments.

This guide covers implementation details, configuration options, and runnable code examples based on the official Lightricks/LTX-2 source code.

## Native HDR Output with the `--hdr` Flag

The simplest path to HDR output uses the `--hdr` flag available in all standard LTX-2 pipelines: `DistilledPipeline`, `DFRPipeline`, `TI2VidPipeline`, and others. This mode automatically handles colour-space conversion, float32 diffusion decoding, and dual-format output.

### Supported Colour Spaces

The `--hdr` flag accepts three colour-space options that map to the `HDRColorSpace` enum in [`packages/ltx-pipelines/src/ltx_pipelines/utils/types.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/types.py):

| Flag Value | Description |
|------------|-------------|
| `SRGB_LINEAR` | Linear sRGB primaries, common for VFX plates |
| `ACESCG` | ACEScg (AP1 primaries), standard for modern colour workflows |
| `ACESCCT` | ACEScct with log curve, for ACES pipeline compatibility |

The selected space is resolved internally via `resolve_hdr_color_space()` and determines how EXR input data is transformed before VAE encoding.

### Input Requirements

HDR mode accepts two input types, enforced by validation in [`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py):

- **EXR still image**: Single frame used as conditioning with `--image path/to/plate.exr 0 1.0`
- **EXR frame directory**: Folder of sequentially named EXR files with `--video-path path/to/frames/`

**Critical constraint**: All conditioning media must be uniformly EXR or uniformly SDR. Mixing formats triggers a pipeline error.

### Processing Pipeline

When `--hdr` is specified, the pipeline executes these steps:

1. **Colour-space conversion** — EXR data is transformed to VAE-compatible space (compressing to ACEScct when needed)
2. **Float32 diffusion** — The decoder runs in `float32` instead of default `bf16`, preserving HDR dynamic range
3. **Dual output** — `encode_video` writes:
   - Half-float EXR frames to `<output_stem>_exr/`
   - 10-bit BT.2020/HLG HEVC to `--output-path`

### CLI Example: Native HDR Generation

```bash
uv run python -m ltx_pipelines.distilled \
    --transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
    --video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
    --image path/to/plate.exr 0 1.0 \
    --hdr SRGB_LINEAR \
    --output-path output/cow_rain.mp4

```

## HDR IC-LoRA Pipeline for Advanced Workflows

For productions requiring custom HDR transformations—colour grading, log-curve adjustments, or scene-specific tonemapping—LTX-2 provides `HDRICLoraPipeline` in [`packages/ltx-pipelines/src/ltx_pipelines/hdr_ic_lora.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/hdr_ic_lora.py). This class implements a two-stage generation (low-resolution base → upsampled output) and returns raw linear HDR tensors for full post-processing control.

### Core Architecture

The pipeline differs from native HDR mode in several key ways:

- **Tensor output** — Returns `float32` tensor with shape `[frames, height, width, channels]` in linear HDR space
- **Manual post-processing** — Caller handles tonemapping, EXR serialization, and preview encoding
- **LoRA-driven conditioning** — HDR behaviour is defined by metadata in the IC-LoRA file

### HDR Metadata and Transfer Functions

The pipeline reads HDR configuration from LoRA file metadata (key `hdr_transform`) or defaults to `HDRTransfer.LOGC3`. Available transfers include camera-native curves and standard scene-referred formats. Query the active transfer at runtime:

```python
from ltx_pipelines.hdr_ic_lora import HDRICLoraPipeline

pipeline = HDRICLoraPipeline.from_pretrained(...)
print(pipeline.hdr_transform)  # e.g., <HDRTransfer.LOGC3: 'logc3'>

```

### Video Conditioning with HDR Transfers

Load conditioning video using `load_video_conditioning_hdr()` from [`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py). This utility applies the same colour-space transfer as the pipeline (`self.hdr_transform`), ensuring consistent handling between input and generation:

```python
from ltx_pipelines.utils.media_io import load_video_conditioning_hdr

conditioning = load_video_conditioning_hdr(
    video_path="./source_hdr/",
    target_resolution=(1080, 1920),
    hdr_transform=pipeline.hdr_transform,
    num_frames=161
)

```

### High-Quality HDR Mode

Enable `--high-quality` (CLI) or `high_quality_hdr=True` (Python) for reduced temporal artefacts:

- **Mechanism**: Generates at 2× frame count internally, keeps every other frame
- **Trade-off**: ~2× runtime for cleaner motion

### Output Handling

The pipeline returns a linear HDR tensor. Save to EXR and create H.264 previews using utilities from [`media_io.py`](https://github.com/Lightricks/LTX-2/blob/main/media_io.py):

```python
from ltx_pipelines.utils.media_io import save_exr_tensor, encode_exr_sequence_to_mp4

# Save half-float EXR sequence

save_exr_tensor(hdr_tensor, output_dir="./hdr-output/frames/")

# Create SDR preview for editorial

encode_exr_sequence_to_mp4(
    exr_dir="./hdr-output/frames/",
    output_path="./hdr-output/preview.mp4",
    tonemap="aces"
)

```

### CLI Example: HDR IC-LoRA Generation

```bash
uv run python -m ltx_pipelines.hdr_ic_lora \
    --input ./videos/ \
    --output-dir ./hdr-output \
    --distilled-checkpoint-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
    --spatial-upsampler-path models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
    --hdr-lora /path/to/hdr_lora.safetensors \
    --text-embeddings /path/to/hdr_scene_emb.safetensors \
    --num-frames 161 \
    --high-quality

```

## Utility Functions in media_io.py

Both HDR workflows rely on [`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py) for colour-space and I/O operations:

| Function | Purpose |
|----------|---------|
| `HDRColorSpace` | Enum defining `SRGB_LINEAR`, `ACESCG`, `ACESCCT` |
| `resolve_hdr_color_space()` | Maps CLI strings to enum values |
| `vae_dtype_for_hdr()` | Returns `float32` for HDR, `bf16` for SDR |
| `load_video_conditioning_hdr()` | Loads EXR frames with HDR transfer applied |
| `encode_video()` | Writes EXR sequences and HLG HEVC master |
| `save_exr_tensor()` | Saves float tensor as half-float EXR files |
| `encode_exr_sequence_to_mp4()` | Tonemaps and encodes EXR to H.264 preview |

## Workflow Comparison

| Aspect | Native `--hdr` | `HDRICLoraPipeline` |
|--------|--------------|---------------------|
| **Use case** | Straightforward HDR generation | Custom HDR transformations, grading |
| **Input** | EXR still or frame folder | Pre-computed embeddings + LoRA file |
| **Colour space** | Explicit CLI selection (`SRGB_LINEAR`, `ACESCG`, `ACESCCT`) | LoRA metadata (default `LOGC3`) |
| **Output** | Auto-generated EXR + HLG HEVC | Linear HDR tensor (manual post-process) |
| **Control** | Fixed pipeline | Full control over tonemapping, encoding |
| **Runtime** | Standard | 2× with `--high-quality` |

## Summary

- **Native `--hdr` flag**: Add `--hdr {SRGB_LINEAR,ACESCG,ACESCCT}` to any standard LTX-2 pipeline for automatic half-float EXR and BT.2020/HLG output
- **HDR IC-LoRA pipeline**: Use `HDRICLoraPipeline` for video-to-video HDR with custom LoRA-based conditioning and manual post-processing control
- **Critical implementation file**: [`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py) provides shared colour-space utilities and VAE dtype selection
- **HDR VAE requirement**: HDR pipelines automatically use `float32` instead of `bf16` to preserve dynamic range
- **Quality optimization**: Enable `high_quality_hdr=True` in IC-LoRA mode for reduced temporal artefacts at 2× computational cost

## Frequently Asked Questions

### What colour space should I use for VFX plates in LTX-2 HDR workflows?

Use `SRGB_LINEAR` for plates generated in linear sRGB workflows, or `ACESCG` if your pipeline uses ACES 1.3 with AP1 primaries. The `ACESCCT` option applies a log curve and is primarily for compatibility with legacy ACES pipelines. All three map to the `HDRColorSpace` enum in [`packages/ltx-pipelines/src/ltx_pipelines/utils/types.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/types.py).

### Can I mix SDR conditioning with HDR output in LTX-2?

No. The pipeline enforces uniform media types—all conditioning inputs must be EXR for HDR mode, or all SDR for standard output. Mixing triggers a validation error in `load_video_conditioning_hdr()`. Convert SDR plates to half-float EXR before conditioning if HDR output is required.

### How do I create a preview from HDR IC-LoRA output without external tools?

Use `encode_exr_sequence_to_mp4()` from [`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py). This utility tonemaps the linear HDR tensor and encodes to H.264. Specify the tonemapping operator (`aces`, `reinhard`, etc.) based on your editorial requirements. For final delivery, export the raw EXR frames to your colour-grading system.

### Why does HDR mode use float32 instead of bf16?

The VAE and diffusion decoder run in `float32` during HDR generation to preserve the extended dynamic range and prevent banding in highlight and shadow regions. The `vae_dtype_for_hdr()` helper in [`media_io.py`](https://github.com/Lightricks/LTX-2/blob/main/media_io.py) automatically selects this dtype when HDR mode is detected, trading memory efficiency for precision.