How to Generate HDR Video Output with LTX-2

LTX-2 generates HDR video through the HDRICLoraPipeline class, which applies LogC3-based decoding and HDR-aware conditioning to produce linear HDR float tensors saved as EXR frames.

LTX-2 is an open-source video generation framework developed by Lightricks that supports high dynamic range (HDR) output through a specialized inference pipeline. To generate HDR video output with LTX-2, you must use the dedicated HDR IC-LoRA pipeline that extends the standard two-stage diffusion process with HDR-specific transforms and metadata handling. This guide walks through the architecture, prerequisites, and implementation methods using the official source code.

HDR Pipeline Architecture

LTX-2 produces HDR content via a modified two-stage generation flow implemented in packages/ltx-pipelines/src/ltx_pipelines/hdr_ic_lora.py. The pipeline first generates low-resolution latents, upsamples them to full resolution, and then decodes the result into a linear HDR color space.

The architecture relies on LogC3-based HDR decoding. After the diffusion stages complete, the VideoDecoder outputs latent representations that undergo post-processing via apply_hdr_decode_postprocess in packages/ltx-core/src/ltx_core/hdr.py. This function applies the inverse LogC3 transform to expand compressed values back into a linear HDR float tensor. Simultaneously, conditioning videos are preprocessed using load_video_conditioning_hdr from packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py, ensuring input frames live in the same HDR color space as the output.

Key Components for HDR Generation

The HDRICLoraPipeline Class

The HDRICLoraPipeline orchestrates the entire HDR workflow according to the Lightricks/LTX-2 source code. During initialization, it loads the distilled checkpoint, spatial upsampler, and HDR LoRA weights. It also parses HDR metadata—specifically hdr_transform and reference_downscale_factor—from the LoRA file using read_hdr_lora_config(). If this metadata is missing, the pipeline cannot enable HDR mode and will raise an error when HDR-specific functions are invoked.

LogC3 Transform and Decoding

HDR recovery depends on the LogC3 compression scheme. During training, linear HDR values are compressed into a bounded [0, 1] range using LogC3. During inference, apply_hdr_decode_postprocess reverses this transform, converting the decoded latent into a linear HDR float tensor with shape [frames, height, width, channels]. This tensor contains unbounded float32 values representing true HDR luminance.

HDR Conditioning

The load_video_conditioning_hdr function handles video inputs differently than standard inference. It applies the LogC3 transform to conditioning frames, performs reflection padding, and supports optional tiling. This ensures temporal consistency between the input reference videos and the generated HDR output.

Prerequisites and HDR Metadata

To enable HDR generation, you must provide an HDR LoRA file containing specific metadata fields. According to the source in hdr_ic_lora.py, the LoRA .safetensors file must include:

• hdr_transform: Typically set to "logc3" to specify the color space transform.
• reference_downscale_factor: An optional integer controlling conditioning resolution.

You can verify these fields programmatically using the read_hdr_lora_config utility:

from ltx_pipelines.hdr_ic_lora import read_hdr_lora_config

cfg = read_hdr_lora_config("/models/hdr_lora.safetensors")
if cfg:
    print(f"HDR transform: {cfg.hdr_transform}")
    print(f"Reference downscale factor: {cfg.reference_downscale_factor}")
else:
    print("No HDR metadata – the LoRA file is not HDR-aware.")

How to Generate HDR Video via CLI

The fastest way to generate HDR video output with LTX-2 is through the command-line interface provided in hdr_ic_lora.py. This method automatically handles resolution alignment, conditioning loading, and EXR frame export.

python -m ltx_pipelines.hdr_ic_lora \
    --input ./my_clips/ \
    --output-dir ./hdr_output \
    --hdr-lora /models/hdr_lora.safetensors \
    --text-embeddings /models/hdr_text_emb.safetensors \
    --distilled-checkpoint-path /models/ltx-2.3-22b-distilled.safetensors \
    --spatial-upsampler-path /models/ltx-2.3-spatial-upscaler-x2-1.0.safetensors \
    --num-frames 161 \
    --seed 42 \
    --high-quality

The CLI initializes the HDRICLoraPipeline with the four required checkpoints, processes each input video through the two-stage diffusion flow, and saves individual frames as EXR files. Unless you specify --skip-mp4, it also encodes an sRGB MP4 preview for quick inspection.

Programmatic HDR Generation with Python

For custom workflows, instantiate the pipeline directly in Python. This approach returns a raw linear HDR tensor, leaving tonemapping and format conversion to you.

from pathlib import Path
import torch
from ltx_pipelines.hdr_ic_lora import HDRICLoraPipeline
from ltx_pipelines.utils.media_io import save_exr_tensor

# Initialize pipeline

pipeline = HDRICLoraPipeline(
    distilled_checkpoint_path=Path("/models/ltx-2.3-22b-distilled.safetensors"),
    spatial_upsampler_path=Path("/models/ltx-2.3-spatial-upscaler-x2-1.0.safetensors"),
    hdr_lora=Path("/models/hdr_lora.safetensors"),
    text_embeddings_path=Path("/models/hdr_text_emb.safetensors"),
    offload_mode="none",  # Use "cpu" or "disk" for low-VRAM GPUs

)

# Generate 4K HDR video (width must be divisible by 32)

hdr_tensor = pipeline(
    seed=123,
    height=2160,
    width=3840,
    num_frames=121,
    frame_rate=30.0,
    video_conditioning=[("/path/to/conditioning.mp4", 1.0)],
    high_quality_hdr=True,
)

# Save as EXR sequence

for i, frame in enumerate(hdr_tensor):
    save_exr_tensor(
        frame.cpu(), 
        f"./out/frame_{i:05d}.exr", 
        exr_half=False
    )

The video_conditioning parameter accepts a list of tuples containing file paths and strength values. Each conditioning video is processed via load_video_conditioning_hdr to ensure proper HDR color space alignment.

High-Quality HDR Mode

LTX-2 offers an optional high-quality HDR mode that reduces temporal flicker at the cost of approximately double the compute time. When you set high_quality_hdr=True (or pass --high-quality via CLI), the pipeline internally generates 2 × N − 1 frames, duplicates the conditioning frames to match, and keeps every other frame after decoding. This temporal supersampling produces smoother motion in the final HDR output.

Summary

• Use the HDRICLoraPipeline class in packages/ltx-pipelines/src/ltx_pipelines/hdr_ic_lora.py to orchestrate HDR generation.
• Provide an HDR LoRA file containing hdr_transform metadata (typically "logc3") to enable the pipeline.
• The LogC3 inverse transform in packages/ltx-core/src/ltx_core/hdr.py converts decoded latents into linear HDR float tensors.
• Conditioning videos must be loaded with load_video_conditioning_hdr to ensure color space consistency.
• Enable high_quality_hdr to generate 2× frames and reduce temporal artifacts, doubling inference time.
• Output is returned as a float32 tensor; use save_exr_tensor to write standard HDR EXR files.

Frequently Asked Questions

What file format does LTX-2 use for HDR output?

LTX-2 returns HDR data as a linear float32 tensor. The pipeline saves individual frames as OpenEXR (.exr) files via save_exr_tensor in packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py. The CLI also generates an sRGB MP4 preview for non-HDR displays, but the primary HDR product is the EXR sequence.

Do I need specific hardware to generate HDR videos with LTX-2?

You need a CUDA-capable GPU with sufficient VRAM to hold the distilled 22B parameter model, spatial upsampler, and HDR LoRA weights simultaneously. For GPUs with limited memory, set offload_mode="cpu" or offload_mode="disk" when initializing HDRICLoraPipeline to offload inactive components, though this increases generation time.

How does the LogC3 transform affect color accuracy?

The LogC3 transform compresses high-dynamic-range linear values into a bounded range suitable for the diffusion model during training. The inverse transform applied by apply_hdr_decode_postprocess mathematically expands these values back to linear HDR space. This process is lossy but preserves relative luminance relationships necessary for professional HDR grading workflows.

Can I use standard LTX-2 checkpoints for HDR generation?

No. Standard checkpoints lack the HDR LoRA weights and metadata required for HDR decoding. You must use a checkpoint specifically trained or adapted for HDR, provided via the --hdr-lora argument, which contains the hdr_transform configuration and compatible weight adaptations for the diffusion stages.

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