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

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:

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:

• 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

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. 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:

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. This utility applies the same colour-space transfer as the pipeline (self.hdr_transform), ensuring consistent handling between input and generation:

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:

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

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 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 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.

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. 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 automatically selects this dtype when HDR mode is detected, trading memory efficiency for precision.

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