[tests] refactor ltx2 dfr pipeline tests (#14655)

* Add LTX-2.5 DFR pipeline with generated keyframe slots

Ports DFRPipeline from the Lightricks reference. Stage 1 generates video plus
single-pixel-frame keyframe slots at a fraction of the requested resolution on
a VAE-aligned segment grid; both are spatially latent-upsampled and stage 2
re-denoises at twice that resolution with the slots re-attached and an optional
spatial detailing IC-LoRA active for that stage only. Optional temporal x2/x4
refine rounds tile the canvas at shared keyframes and densify with ancestral
Euler. With spatial_upscalings=2 a full-resolution detailing epilogue follows
the rounds.

The transformer already stored keyframes_abs_pos_embedding for load/save; this
wires it into the forward through a new video_keyframes_mask argument, which
only a keyframes-aware pipeline passes, so other pipelines are unaffected.

The epilogue denoises the whole canvas in one loop and tiles the transformer
call inside it, so every Euler step steps a canvas whose tiles have already
agreed on their overlaps. Spatial tiles blend under a trapezoidal mask, since
neither side of a height or width border holds a known answer. Temporal tiles
are cut on the keyframe seams the last refine round stitched on: both windows
reproduce a shared keyframe there, so the later one drops its run-up under a
rectangular mask rather than averaging it. Conditionings are attached once on
the whole canvas and filtered per tile at the token level, and a keyframe two
windows share is one token they both read.

The epilogue is handed its keyframes rather than asked to generate them. Each
carry plane is decoded on its own -- the VAE is causal, so a stacked decode
would bleed neighbours -- then Lanczos-stretched x2 in RGB and encoded again at
the output resolution, and pinned fully clean. Only the video latent is
spatially upsampled.

Conditioning fps is snapped to 60 above 30 rather than merely capped there, at
every stage. RoPE time is pixel_frame / fps, and the transformer is trained
around 24/25/30 and 60; a temporal round taking 24 fps to 48 lands between
those, and it shows as stutter at the latent borders. Playback fps is
unchanged, so 24 fps with one round still ships 48 fps.

A condition's index is read on the canvas num_frames asks for, and the moment
it names is carried onto each refine round's longer canvas by scaling its pixel
position by 2**round. The scaled position does not generally land on a latent
boundary, so it travels as a pixel index rather than through the public latent
index; a keyframe conditioning is appended as extra tokens instead of being
spliced into the base grid, so it does not need to.

height and width must be divisible by 2**spatial_upscalings times the VAE's
spatial compression ratio, which makes 4K 3840x2176 rather than 3840x2160. That
rule is checked ahead of the looser one every LTX-2 pipeline applies, so the
error names the divisor a DFR caller actually has to satisfy.

Four details are easy to get wrong, and each is covered by a test after showing
up as a visible seam at a tile handover:

- The ancestral step injects noise into every token, so the conditioning blend
  has to be re-applied afterwards. Skipping it lets the strength-0.95 anchor
  keyframes erode over the schedule, and those anchors are the only thing
  pinning adjacent tiles onto the same content.
- Velocity is converted to x0 with each token's own noise level, not the scalar
  schedule sigma: a token held at strength s sits at (1 - s) * sigma.
- Each tile draws its ancestral noise from a generator seeded
  seed + 1000 * round + tile, kept separate from the main generator so the
  draws do not consume state the next tile's initial noising reads.
- Two tiles invent the slot that falls in the later one's dropped lead-in. The
  stitch keeps the earlier tile's frames there, so the earlier tile's copy is
  the one the canvas holds, and the one the next round must anchor on.

* Split the DFR pipeline into composable stages

Addresses the review on #14567: use the same compose pattern as the other LTX
two-stage pipelines, get ancestral Euler from an existing scheduler, and put the
temporal rounds in their own pipeline so the schedule is not switched mid-call.

`LTX2DFRPipeline.__call__` is now one denoise pass at `height` x `width`. Callers
compose stage 1, `LTX2LatentUpsamplePipeline`, stage 2 and each temporal round,
and a documented recipe is the copy-paste 1080p path. The recipe knobs
(`spatial_upscalings`, `temporal_upscalings`, `detailing_lora_adapter_name`) and
the required upsampler components are gone; `height`/`width` are this pass, not
the final output.

`ancestral_euler_step` is replaced by `LTXEulerAncestralRFScheduler.step` plus a
re-application of the conditioning blend, which ancestral noise would otherwise
erode on the strength-0.95 seam anchors. The new `LTX2DFRTemporalRefinePipeline`
owns that scheduler and one round; stage 1, stage 2 and the epilogue stay on
`FlowMatchEulerDiscreteScheduler`. It refuses any other scheduler rather than
silently taking a deterministic step and returning a softer canvas.

Pack/unpack, `prepare_latents`, `denoise` and `encode_conditions` move to
`LTX2DFRCoreMixin` so neither pipeline subclasses the other. Public latents are
raw on both sides of every boundary, `output_type="latent"` returns the untrimmed
canvas so a slot on the pad is not dropped, and `trim_canvas` does the trim
before decode. `LTX2DFRPipelineOutput` carries `keyframes` and
`keyframe_positions`, which cannot be re-derived after a round.

Verified against the pre-split implementation: bit-exact on dummy components in
fp32 and bf16, with and without the IC-LoRA reference, over one and two rounds;
and within one bf16 ulp on the real checkpoint, where the only difference is that
the split normalizes upsampled latents in fp32 rather than bf16.

Also in this pass:

- `__call__` takes `video_tiles` (the `epilogue_tiles` layout) instead of a
  resolved token plan. Resolving one needs the RoPE coordinates that only exist
  once `prepare_latents` has run, so a caller could not build the plan at all.
- `rebuild_epilogue_keyframes` is public and takes and returns raw latents. The
  composed epilogue needs it, so it was public API in practice while named
  private, and its normalized return forced callers into `_denormalize_latents`.
- Drop prompt enhancement and `num_videos_per_prompt` from the temporal pipeline.
  Enhancement belongs to stage 1 -- re-running it would denoise the canvas under
  a different prompt than the one that generated it -- and the batch is set by
  the incoming latent canvas, so `num_videos_per_prompt > 1` only ever raised.
- Fix the docs recipe: `requested_frames` counted latent frames where
  `trim_canvas` wants pixel frames, truncating a 241-frame render to 25; the
  three pipelines share components, so place them together instead of offloading
  one and leaving `temporal_latent_upsampler` off the device; and the detailing
  IC-LoRA is applied at 0.5, the strength the reference hardcodes.

- Pass `crf=0` on the conditions in the refine-round test. The default CRF sends
  the image through H.264 re-compression, which needs PyAV, so the test failed on
  any environment without it while testing nothing about re-compression.

* Drop LTX2DFRCoreMixin in favor of # Copied from

Each DFR pipeline now owns pack/unpack, prepare_latents, and denoise so the
classes stay self-contained. Shared helpers copy from LTX2Pipeline /
LTX2ConditionPipeline, and DFR-specific methods copy from LTX2DFRPipeline.
dfr_core.py keeps only the constants and canvas helpers.

* inline _finalize_output

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* remove dfr_core.py

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* make return_dict=False return a tuple of 4, consistent with diffusers convention; update docs and pipeline output accordingly

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* small refactors to the ltx2 dfr testing suite

* save

* remove dfr_dummies.py.

* remove tests/pipelines/ltx2/test_ltx2_dfr_layout.py

---------

Co-authored-by: aartyomov <aartyomov@lightricks.com>
Co-authored-by: dg845 <58458699+dg845@users.noreply.github.com>
Co-authored-by: YiYi Xu <yixu310@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 5 people

tests/pipelines/ltx2/dfr_dummies.py

@@ -16,13 +16,13 @@
 import torch
 
 from diffusers import (
-    AutoencoderKLLTX2Video,
     FlowMatchEulerDiscreteScheduler,
     LTX2VideoDiffusionDecodePipeline,
     LTX2VideoDiffusionDecoderModel,
 )
 
 from ...testing_utils import enable_full_determinism, torch_device
+from .testing_utils import get_dummy_vae
 
 
 enable_full_determinism()
@@ -56,25 +56,10 @@ def _build(with_vae: bool = False):
     vae = None
     if with_vae:
         torch.manual_seed(0)
+        # Wider latents than the shared default, to match the decoder, and the causal decoder this pipeline
+        # is exercised with.
         vae = (
-            AutoencoderKLLTX2Video(
-                in_channels=3,
-                out_channels=3,
-                latent_channels=DECODER_CONFIG["latent_channels"],
-                block_out_channels=(8,),
-                decoder_block_out_channels=(8,),
-                layers_per_block=(1,),
-                decoder_layers_per_block=(1, 1),
-                spatio_temporal_scaling=(True,),
-                decoder_spatio_temporal_scaling=(True,),
-                decoder_inject_noise=(False, False),
-                downsample_type=("spatial",),
-                upsample_residual=(False,),
-                upsample_factor=(1,),
-                timestep_conditioning=False,
-                patch_size=1,
-                patch_size_t=1,
-            )
+            get_dummy_vae(latent_channels=DECODER_CONFIG["latent_channels"], decoder_causal=True)
             .to(torch_device)
             .eval()
         )

tests/pipelines/ltx2/test_ltx2_diffusion_decode.py

@@ -17,7 +17,6 @@
 
 from diffusers import LTX2ImageToVideoPipeline
 from diffusers.pipelines.ltx2 import LTX2LatentUpsamplePipeline
-from diffusers.pipelines.ltx2.latent_upsampler import LTX2LatentUpsamplerModel
 
 from ...testing_utils import assert_tensors_close, enable_full_determinism, torch_device
 from ..testing_utils import PipelineTesterMixin
@@ -26,6 +25,7 @@
     LTX2LoraMemoryTesterMixin,
     LTX2LoraTesterMixin,
     LTX2MemoryTesterMixin,
+    get_dummy_latent_upsampler,
 )
 
 
@@ -48,13 +48,6 @@ class LTX2ImageToVideoPipelineTesterConfig(LTX2BaseTesterConfig):
     )
     batch_input_params = frozenset(["prompt", "negative_prompt", "image"])
 
-    def get_dummy_upsample_component(self, in_channels=4, mid_channels=32, num_blocks_per_stage=1):
-        return LTX2LatentUpsamplerModel(
-            in_channels=in_channels,
-            mid_channels=mid_channels,
-            num_blocks_per_stage=num_blocks_per_stage,
-        )
-
     def get_dummy_inputs(self):
         generator = self.get_generator(0)
         image = torch.rand((1, 3, 32, 32), generator=generator)
@@ -183,7 +176,7 @@ def test_two_stages_inference_with_upsampler(self):
         assert audio_latent.shape == (1, 2, 5, 2)
         assert audio_latent.shape[1] == pipe.vocoder.config.out_channels
 
-        upsampler = self.get_dummy_upsample_component(in_channels=video_latent.shape[1])
+        upsampler = get_dummy_latent_upsampler(in_channels=video_latent.shape[1])
         upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=upsampler)
         upscaled_video_latent = upsample_pipe(latents=video_latent, output_type="latent", return_dict=False)[0]
         assert upscaled_video_latent.shape == (1, 4, 3, 32, 32)