How to Configure the Timestep Shift Parameter for Flow Matching Schedulers in LongLive

Set model_kwargs.timestep_shift in your YAML configuration or pass timestep_shift directly to WanDiffusionWrapper to control noise distribution in the FlowMatchScheduler.

The timestep shift parameter controls how noise is distributed across diffusion timesteps in the NVlabs/LongLive flow-matching pipeline. This configuration value, exposed as timestep_shift in the Python API and shift internally within the scheduler, directly transforms the sigma schedule through a non-linear scaling operation defined in utils/scheduler.py.

Configuration Entry Points

LongLive exposes the timestep shift through three primary entry points:

YAML Configuration – Define model_kwargs.timestep_shift in training or inference config files. The loader in utils/config.py (lines 30‑33) merges this value into model_kwargs via the normalize_config helper. Example location: configs/train_ar.yaml (lines 12‑15).

Python API (Standard) – Pass timestep_shift to the WanDiffusionWrapper constructor in utils/wan_5b_wrapper.py (lines 78‑84). This wrapper defaults to 8.0 if unspecified.

Python API (Sequence Parallel) – For distributed inference using SPWanDiffusionWrapper5B, set the parameter in pipeline/causal_diffusion_inference_sp.py (lines 32‑36), which defaults to 5.0.

Technical Implementation

FlowMatchScheduler Core Logic

The scheduler implementation in utils/scheduler.py (lines 6‑31) defines the transformation:

class FlowMatchScheduler:
    def __init__(self, num_inference_steps=100, num_train_timesteps=1000,
                 shift: float = 3.0, sigma_max: float = 1.0,
                 sigma_min: float = 0.003 / 1.002, ...):
        self.shift = shift

During set_timesteps, the shift value transforms the raw sigma schedule:

self.sigmas = self.shift * self.sigmas / (1 + (self.shift - 1) * self.sigmas)

This formula compresses or expands the sigma curve. A larger shift value stretches the schedule toward high-noise regions, causing the diffusion process to take larger steps early and finer steps later.

Parameter Propagation Pipeline

Configuration values flow through the system in three stages:

1. Config Loading – utils/config.py (lines 30‑33) copies timestep_shift from the YAML into the runtime model_kwargs dictionary.

2. Wrapper Instantiation – The wrapper classes forward the value to the scheduler constructor:

self.scheduler = FlowMatchScheduler(
    shift=timestep_shift, sigma_min=0.0, extra_one_step=True
)

3. Runtime Override – Hydra command-line arguments like +model_kwargs.timestep_shift=7.2 merge into the config before wrapper construction.

Impact of Shift Values on Generation

The timestep_shift value determines the granularity of the diffusion process:

• 1.0 – No transformation applied; the scheduler uses a standard linear sigma schedule.
• > 1.0 – Compresses sigma values toward the high-noise end (t=0), resulting in larger denoising steps early in the process and slower refinement later. Values between 4.0 and 8.0 are typical for video generation.
• < 1.0 – Expands the low-noise region, yielding finer granularity at high timesteps (rarely used in practice).

Because LongLive uses flow-matching training with denoising_loss_type: flow, the shift parameter directly influences loss weighting across timesteps. Tuning this value allows explicit trade-offs between generation speed and output fidelity.

Code Examples

YAML Configuration (Training)

Define the parameter in your training config:

# configs/train_ar.yaml

model_kwargs:
  model_name: Wan2.2-TI2V-5B
  timestep_shift: 5.0
  num_frame_per_block: 8
  local_attn_size: -1

Command-Line Override

Override the config value at runtime using Hydra syntax:

python train.py \
  +model_kwargs.timestep_shift=7.2 \
  +model_kwargs.model_name=Wan2.2-TI2V-5B

Direct Python Usage

Instantiate the wrapper directly with a custom shift value:

from utils.wan_5b_wrapper import WanDiffusionWrapper

wrapper = WanDiffusionWrapper(
    model_name="Wan2.2-TI2V-5B",
    timestep_shift=4.5,
    is_causal=False,
)

# Verify the scheduler received the value

print("Shift:", wrapper.scheduler.shift)
print("Sigmas:", wrapper.scheduler.sigmas)

Inspecting the Scheduler State

After construction, verify the effective schedule:

print("Timesteps:", wrapper.scheduler.timesteps)
print("Sigma schedule shape:", wrapper.scheduler.sigmas.shape)

Summary

• The timestep shift controls noise distribution via the formula shift * sigmas / (1 + (shift - 1) * sigmas) in utils/scheduler.py.
• Set the value through model_kwargs.timestep_shift in YAML configs, command-line overrides, or direct constructor arguments to WanDiffusionWrapper.
• Default values differ by entry point: 3.0 (scheduler internal), 8.0 (standard wrapper), and 5.0 (sequence-parallel wrapper).
• Values greater than 1.0 compress the schedule toward high-noise timesteps, affecting the diffusion speed-fidelity trade-off.
• The parameter propagates through utils/config.py (lines 30‑33) before reaching the scheduler instantiation in utils/wan_5b_wrapper.py (lines 78‑84).

Frequently Asked Questions

What is the default timestep shift value in LongLive?

The default value depends on the entry point. The FlowMatchScheduler class itself defaults to 3.0, while WanDiffusionWrapper in utils/wan_5b_wrapper.py overrides this to 8.0. For sequence-parallel inference using SPWanDiffusionWrapper5B in pipeline/causal_diffusion_inference_sp.py, the default is 5.0.

How does the timestep shift parameter affect video generation quality?

The shift value alters the sigma schedule non-linearly. Values above 1.0 concentrate sampling steps in the high-noise (early) phase of diffusion, which can improve motion coherence in video generation by allowing larger updates during noisy phases, while values closer to 1.0 provide more uniform step distribution.

Can I change the timestep shift value for inference without modifying config files?

Yes, pass the value via Hydra command-line syntax when launching inference scripts: +model_kwargs.timestep_shift=6.0. This merges the override into the configuration dictionary processed by utils/config.py before the scheduler is instantiated.

Where is the shift parameter actually stored in the codebase?

The parameter is stored as self.shift inside the FlowMatchScheduler instance in utils/scheduler.py (line 10). It is passed during construction by the wrapper classes in utils/wan_5b_wrapper.py and pipeline/causal_diffusion_inference_sp.py, which read it from the model_kwargs dictionary prepared by utils/config.py.

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