How to Configure HDR Output with EXR Export and Color Spaces (SRGB_LINEAR, ACESCG, ACESCCT) in LTX-2

LTX-2 supports HDR output through the --hdr CLI flag with three color space options—SRGB_LINEAR, ACESCG, and ACESCCT—automatically exporting half-float EXR frames alongside HLG HEVC masters.

LTX-2 handles native HDR video generation through a unified color space policy defined by the HDRColorSpace enum. Whether you're working with EXR plates for image-to-video generation or building custom HDR pipelines, understanding how to configure the --hdr flag and color space options ensures proper linear workflow handling from input conditioning through final export.

HDRColorSpace Enum and VAE Behavior

The HDRColorSpace enum in packages/ltx-pipelines/src/ltx_pipelines/utils/media_io/color_config.py defines three color space options with distinct preprocessing behaviors:

Color Space	Description	VAE Input Handling
SRGB_LINEAR	Scene-linear Rec.709/sRGB-tagged EXR	Compressed to ACEScct before VAE encoding
ACESCG	Scene-linear ACEScg (wide gamut) EXR	Compressed to ACEScct before VAE encoding
ACESCCT	Already ACEScct log-encoded values	Passed directly to VAE without compression

Both SRGB_LINEAR and ACESCG require logarithmic compression to ACEScct because LTX-2's Video VAE operates in ACEScct log space. ACESCCT bypasses this step for workflows already producing log-encoded plates.

Source EXR inputs require --hdr to be explicitly set. The helper resolve_hdr_color_space() in the same module validates this constraint and raises an error if EXR files are detected without a color space declaration.

Command-Line HDR Configuration with --hdr Flag

Basic Image-to-Video with EXR Input

Pass a single EXR still and specify the source color space:

uv run python -m ltx_pipelines.distilled \
    --transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
    --text-encoder-path models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
    --video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
    --spatial-upsampler-path models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
    --num-frames 121 \
    --prompt "Rain starts falling on the cow in the pasture" \
    --image path/to/cow_pasture.exr 0 1.0 \
    --hdr SRGB_LINEAR \
    --output-path output/cow_rain.mp4

This command produces:

• output/cow_rain.mp4 — HLG HEVC master (BT.2020 color) for direct playback
• output/cow_rain_exr/ — Half-float EXR frame sequence tagged with sRGB color space

Video-to-Video with EXR Frame Sequence

For retake workflows using EXR frame folders:

uv run python -m ltx_pipelines.retake \
    --transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
    --text-encoder-path models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
    --video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
    --video-path path/to/source_exr_frames/ \
    --frame-rate 24 \
    --prompt "The cow morphs into a moose" \
    --hdr ACESCG \
    --output-path output/retake.mp4

The --hdr ACESCG declaration ensures proper gamut handling for ACEScg source material and tags output EXR frames accordingly.

HDR IC-LoRA Pipeline for Direct Linear Output

The HDRICLoraPipeline in packages/ltx-pipelines/src/ltx_pipelines/hdr_ic_lora.py provides scene-linear HDR float output for custom tonemapping workflows. Unlike standard pipelines, this returns raw float32 tensors rather than encoded video.

python -m ltx_pipelines.hdr_ic_lora \
    --input ./videos/ \
    --output-dir ./hdr-output \
    --distilled-checkpoint-path /models/ltx-2.3-22b-distilled.safetensors \
    --spatial-upsampler-path /models/ltx-2.3-spatial-upscaler-x2-1.0.safetensors \
    --hdr-lora /path/to/hdr_lora.safetensors \
    --text-embeddings /path/to/hdr_scene_emb.safetensors \
    --num-frames 161 \
    --hdr ACESCCT

Key characteristics of this pipeline:

• Returns linear HDR float32 tensor with shape [frames, height, width, channels]
• Automatically applies LogC3 inverse transform during latent decoding
• Still requires --hdr color space flag for EXR conditioning inputs
• Caller responsibility: EXR serialization and custom tonemapping

Python API for Programmatic HDR Control

Embed HDR configuration directly in Python scripts using utilities from ltx_pipelines.utils.media_io:

from ltx_pipelines.utils.media_io import (
    HDRColorSpace, encode_video, resolve_hdr_color_space, vae_dtype_for_hdr
)
import torch

# Validate inputs and resolve color space

hdr = resolve_hdr_color_space(
    images=my_image_list,
    video_paths=my_video_paths,
    hdr=HDRColorSpace.ACESCG
)

# HDR forces float32 VAE decode; SDR uses BF16 default

vae_dtype = vae_dtype_for_hdr(hdr, default=torch.bfloat16)

# After generation, export both HLG master and EXR frames

encode_video(
    video_chunks=decoded_frame_chunks,
    fps=24,
    audio=None,
    output_path="output/my_hdr_sequence.mp4",
    num_chunks=len(decoded_frame_chunks),
    color_space=hdr  # Triggers automatic EXR export alongside HLG

)

Core HDR Utility Functions

Function	Purpose	Location
HDRColorSpace	Enum with color space definitions and metadata	utils/media_io/color_config.py
resolve_hdr_color_space()	Validates EXR inputs require --hdr flag	utils/media_io/color_config.py
vae_dtype_for_hdr()	Returns torch.float32 for HDR, default otherwise	utils/media_io/color_config.py
encode_video()	Writes HLG HEVC + half-float EXR frames	utils/media_io/video_io.py

Color Space Selection Guidelines

Choose SRGB_LINEAR when working with:

• Standard VFX plates from most renderers
• Display-referred linear workflows
• sRGB/Rec.709 gamut source material

Choose ACESCG when working with:

• Wide-gamut ACEScg render outputs
• ACES pipeline integration
• P3 or BT.2020 source content

Choose ACESCCT when working with:

• Pre-logged ACEScct footage
• Camera raw workflows (ARRI, RED) natively outputting ACEScct
• Minimizing color space transformations for quality preservation

Summary

• HDR activation: Use --hdr CLI flag with any of three color space values: SRGB_LINEAR, ACESCG, or ACESCCT
• Automatic export: Standard pipelines generate both HLG HEVC masters and half-float EXR frame sequences
• VAE preprocessing: SRGB_LINEAR and ACESCG compress to ACEScct; ACESCCT passes through unchanged
• Linear workflow: HDRICLoraPipeline provides raw float32 tensors via LogC3 inverse transform for custom processing
• Validation layer: resolve_hdr_color_space() enforces that EXR inputs require explicit HDR configuration

Frequently Asked Questions

What happens if I omit --hdr when using EXR inputs?

The pipeline raises an error. According to resolve_hdr_color_space() in color_config.py, EXR file detection without a corresponding --hdr flag triggers validation failure. This prevents accidental SDR processing of HDR source material. Mixing EXR and SDR inputs in the same command is also rejected.

Does --hdr affect the output video format or just the EXR sidecar?

The --hdr flag affects both outputs. The HEVC master uses HLG transfer function with BT.2020 color primaries for HDR-compatible playback. Simultaneously, half-float EXR frames export to a _exr/ subdirectory with color space tags matching your selected HDRColorSpace.

What is the difference between standard pipelines and HDRICLoraPipeline?

Standard pipelines (distilled, retake) handle the complete workflow: generation, VAE decode, color space conversion, and dual export. HDRICLoraPipeline stops after VAE decode with LogC3 inverse applied, returning a scene-linear float32 tensor. This serves advanced workflows requiring custom tonemapping or integration with external color management systems before final export.

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