# How to Use HDR/EXR Input and Output with LTX-2 Pipelines: Complete Guide

> Learn how to use HDR EXR input and output with LTX-2 pipelines. This guide covers color space flags, EXR data loading, and metadata preservation for seamless HDR conditioning.

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

---

**LTX-2 supports HDR conditioning through OpenEXR files by declaring a color space flag, loading EXR data through dedicated conditioning functions, and optionally writing EXR output with preserved color metadata.**

The **Lightricks/LTX-2** model enables professional video generation workflows with **high dynamic range (HDR)** and **OpenEXR** support. This guide explains how to configure HDR/EXR input and output in LTX-2 pipelines based on the actual source code implementation.

## Declaring the HDR Color Space for EXR Input

Before loading any EXR file, you must specify its color space using the `--hdr` CLI flag. This requirement is enforced by the `_verify_media_path_args` function in [[`packages/ltx-pipelines/src/ltx_pipelines/utils/args.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/args.py)](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/args.py#L74-L84). Without this flag, the CLI raises an explicit error: `EXR input requires --hdr …`.

The available color space options are defined in `add_hdr_args` ([`args.py:27-45`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/args.py#L27-L45)):

- **`SRGB_LINEAR`** – Linear sRGB primaries with gamma 1.0
- **`ACESCG`** – ACEScg working space (linear AP1 primaries)
- **`ACESCCT`** – Already in ACEScct log encoding (no transfer needed)

```bash
ltx-pipelines ti2vid_one_stage \
    --image ./plate.exr 0 1.0 \
    --hdr SRGB_LINEAR \
    --height 512 --width 512

```

## Loading EXR Data for Conditioning

The pipeline distinguishes between **still image conditioning** and **video sequence conditioning** with separate code paths in the media I/O layer.

### Still Image EXR Loading

When `load_image_and_preprocess` in [[`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/decode.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/decode.py)](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/decode.py#L56-L73) detects the `.exr` suffix, it routes to `load_exr_image_conditioning_hdr`. This function:

1. Reads the EXR file using OpenImageIO
2. Applies the color space transfer defined in [[`color_config.py`](https://github.com/Lightricks/LTX-2/blob/main/color_config.py)](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/color_config.py#L15-L50)
3. Resizes and pads to the target resolution
4. Converts to the VAE's expected input range

### EXR Sequence Loading

For folders of EXR frames, use `load_exr_conditioning_hdr` or `load_exr_folder_conditioning_hdr` from [[`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/exr.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/exr.py)](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/exr.py#L60-L81). These functions handle temporal indexing and maintain consistent color processing across the sequence.

```bash
ltx-pipelines ti2vid_two_stages \
    --video-conditioning ./exr_seq/ 0.8 \
    --hdr ACESCCT \
    --frame-rate 30 \
    --num-frames 33

```

## Color Space Transfer Logic

The core color handling lives in [[`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/color_config.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/color_config.py)](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/color_config.py#L15-L50). The `HDRColorSpace` enum determines the transformation path:

| Source Space | `is_log_working` | Processing Step |
|-------------|------------------|-----------------|
| `SRGB_LINEAR`, `ACESCG` | `False` | Transfer to ACEScct via `HDRTransfer.ACESCCT`, then clamp and map to VAE range |
| `ACESCCT` | `True` | Direct clamp and map to VAE range (already in working space) |

This design ensures that all HDR inputs normalize to the same internal working space before VAE encoding, regardless of source encoding.

## Writing EXR Output

To save generated frames as HDR EXR files, use `save_exr_tensor` from [[`packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/exr.py`](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/exr.py)](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/exr.py#L66-L84). The function preserves color metadata by writing:

- Image primaries (e.g., `Primaries.ACESCG`)
- Color space attribute (e.g., `"ACEScct"`)

```python
from ltx_pipelines.utils.media_io.exr import save_exr_tensor
from ltx_pipelines.utils.media_io.color_config import Primaries
import torch

# Decode VAE latents to image space

vae_output = model.decode(latents)  # [C, H, W] in VAE range

# Save with HDR metadata for downstream compositing

save_exr_tensor(
    tensor=vae_output,
    file_path="generated.exr",
    half=True,                           # 16-bit half-float

    primaries=Primaries.ACESCG,
    color_space="ACEScct"
)

```

## Complete CLI Examples

### Text-to-Video with HDR Still Image

```bash
ltx-pipelines ti2vid_one_stage \
    --prompt "A sunrise over a misty forest" \
    --output-path ./result.mp4 \
    --image ./plate.exr 0 1.0 \
    --hdr SRGB_LINEAR \
    --height 512 \
    --width 512 \
    --num-frames 17

```

### Video-to-Video with EXR Sequence

```bash
ltx-pipelines ti2vid_two_stages \
    --prompt "Add cinematic fireworks" \
    --output-path ./edited.mp4 \
    --video-conditioning ./exr_seq/ 0.8 \
    --hdr ACESCCT \
    --frame-rate 30 \
    --height 720 \
    --width 1280 \
    --num-frames 33

```

## Key Source Files

Understanding these implementation files helps debug HDR workflows:

- **[`ltx_pipelines/utils/args.py`](https://github.com/Lightricks/LTX-2/blob/main/ltx_pipelines/utils/args.py)** — CLI flag definitions and EXR validation
- **[`ltx_pipelines/utils/media_io/color_config.py`](https://github.com/Lightricks/LTX-2/blob/main/ltx_pipelines/utils/media_io/color_config.py)** — `HDRColorSpace`, `HDRTransfer`, and `Primaries` enums; color space transfer logic
- **[`ltx_pipelines/utils/media_io/exr.py`](https://github.com/Lightricks/LTX-2/blob/main/ltx_pipelines/utils/media_io/exr.py)** — `load_exr_conditioning_hdr`, `load_exr_folder_conditioning_hdr`, `save_exr_tensor`
- **[`ltx_pipelines/utils/media_io/decode.py`](https://github.com/Lightricks/LTX-2/blob/main/ltx_pipelines/utils/media_io/decode.py)** — Routing logic for EXR detection and HDR conditioning dispatch
- **[`ltx_pipelines/utils/media_io/resize.py`](https://github.com/Lightricks/LTX-2/blob/main/ltx_pipelines/utils/media_io/resize.py)** — `resize_and_reflect_pad` and `resize_and_center_crop` used in conditioning pipelines

## Summary

- **Always specify `--hdr`** with `SRGB_LINEAR`, `ACESCG`, or `ACESCCT` when using EXR input; the CLI enforces this in `_verify_media_path_args`
- **Still EXR images** route through `load_image_and_preprocess` → `load_exr_image_conditioning_hdr` in [`decode.py`](https://github.com/Lightricks/LTX-2/blob/main/decode.py)
- **EXR sequences** use `load_exr_folder_conditioning_hdr` from [`exr.py`](https://github.com/Lightricks/LTX-2/blob/main/exr.py) with folder paths
- **Color space transfer** automatically converts non-log sources to ACEScct working space per [`color_config.py`](https://github.com/Lightricks/LTX-2/blob/main/color_config.py)
- **EXR output** preserves primaries and color space metadata via `save_exr_tensor` for professional compositing pipelines

## Frequently Asked Questions

### Why does LTX-2 require the `--hdr` flag for EXR files?

The `--hdr` flag is mandatory because EXR files encode linear or log-encoded floating-point data without embedded color space tags that the pipeline can reliably parse. The `_verify_media_path_args` function in [`args.py`](https://github.com/Lightricks/LTX-2/blob/main/args.py) enforces this to ensure correct color interpretation. Without explicit declaration, the VAE would receive incorrectly normalized data, producing inaccurate colors in generated output.

### What is the difference between `ACESCG` and `ACESCCT` for HDR input?

`ACESCG` specifies linear ACEScg primaries (AP1), which requires transfer to the ACEScct log working space before VAE encoding. `ACESCCT` indicates the source is already in ACEScct log encoding, so the pipeline only clamps and maps to VAE range. Choose `ACESCCT` when your source footage or renders are already log-encoded to avoid double-transfer artifacts.

### Can I mix SDR and HDR conditioning in the same LTX-2 pipeline?

The current implementation processes one conditioning type per invocation. The `--hdr` flag applies globally to all EXR inputs detected in that run. For workflows requiring both SDR (standard dynamic range) images and HDR EXR sequences, run separate pipeline stages or preprocess SDR content to match the HDR color space before combining in external compositing tools.