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

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#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):

• 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)

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#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/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#L60-L81). These functions handle temporal indexing and maintain consistent color processing across the sequence.

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#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#L66-L84). The function preserves color metadata by writing:

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

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

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

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 — CLI flag definitions and EXR validation
• ltx_pipelines/utils/media_io/color_config.py — HDRColorSpace, HDRTransfer, and Primaries enums; color space transfer logic
• 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 — Routing logic for EXR detection and HDR conditioning dispatch
• 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
• EXR sequences use load_exr_folder_conditioning_hdr from exr.py with folder paths
• Color space transfer automatically converts non-log sources to ACEScct working space per 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}