How to Configure CFG and STG Guidance Scales in LTX-2

LTX-2 uses distinct CFG (Classifier-Free Guidance) and STG (Spatio-Temporal Guidance) scales to control prompt adherence and temporal consistency, configurable through ValidationConfig in config.py or CLI flags in args.py.

Configuring guidance scales in the Lightricks/LTX-2 video generation pipeline determines how the model balances text prompt fidelity against temporal coherence. The repository separates these concerns into two independent mechanisms: CFG manages conditional prediction strength, while STG perturbs transformer blocks to stabilize motion across frames. This article details the three configuration methods—YAML files, Python objects, and command-line arguments—based on the actual source implementation.

Understanding CFG and STG Guidance Mechanisms

LTX-2 implements two complementary guidance systems during validation and inference:

CFG (Classifier-Free Guidance) controls how strongly the model follows the provided text prompt. Defined in packages/ltx-trainer/src/ltx_trainer/config.py at lines 17-21, the guidance_scale parameter defaults to 4.0. A value of 1.0 effectively disables guidance, while higher values push generation closer to the conditioned prediction.

STG (Spatio-Temporal Guidance) improves temporal consistency by perturbing selected transformer blocks during denoising. Defined at lines 23-27 in the same config.py file, stg_scale defaults to 1.0 and can be disabled by setting it to 0. STG operates independently of CFG and includes additional configuration options for block selection and perturbation mode.

Three Methods to Configure Guidance Scales

YAML Configuration Files

The most common approach uses the validation section in your configuration YAML:

validation:
  seed: 42
  inference_steps: 50
  guidance_scale: 5.0          # CFG scale for video and audio

  stg_scale: 1.5               # STG scale for temporal consistency

  stg_blocks: [29]             # Transformer blocks to perturb

  stg_mode: stg_av             # Mode: "stg_av" or "stg_v"

These values map directly to the ValidationConfig dataclass fields in packages/ltx-trainer/src/ltx_trainer/config.py.

Python Configuration Objects

When building configurations programmatically, instantiate ValidationConfig directly:

from ltx_trainer.config import ValidationConfig, Config

cfg = Config(
    validation=ValidationConfig(
        guidance_scale=3.0,          # CFG scale

        stg_scale=0.8,               # STG scale

        stg_blocks=[29],
        stg_mode="stg_v",
    ),
    # ... other configuration sections ...

)

This approach is useful for automated experimentation or when integrating LTX-2 into larger Python workflows.

Command-Line Interface

Pipeline scripts expose override flags defined in packages/ltx-pipelines/src/ltx_pipelines/utils/args.py (lines 531-599):

python -m ltx_pipelines.ti2vid_one_stage \
    --video-cfg-guidance-scale 6.0 \
    --audio-cfg-guidance-scale 6.0 \
    --video-stg-guidance-scale 1.2 \
    --audio-stg-guidance-scale 1.2 \
    --prompt "A sunrise over a mountain lake"

CLI arguments take precedence over configuration file values. Omitting any flag falls back to the underlying config file or default values.

Implementation Details in the Source Code

ValidationConfig Structure

The configuration schema resides in packages/ltx-trainer/src/ltx_trainer/config.py. The ValidationConfig class declares both guidance parameters with type hints and defaults:

• guidance_scale: float = 4.0 (lines 17-21)
• stg_scale: float = 1.0 (lines 23-27)

Additional STG-specific fields include stg_blocks (list of integers) and stg_mode (string), allowing fine-grained control over which transformer layers receive perturbations.

Guider Classes

The core logic lives in packages/ltx-core/src/ltx_core/components/guiders.py:

CFGGuider (lines 90-95) implements the standard scale * (conditional - unconditional) formula. It receives the guidance_scale value during instantiation.

STGGuider (lines 202-208) applies the stg_scale multiplier and includes an enabled() method that returns False when the scale equals zero. This allows the validation runner to skip STG computations entirely when disabled.

Pipeline Integration

During validation runs, packages/ltx-trainer/src/ltx_trainer/validation_runner.py (lines 69-75) instantiates these guiders:

cfg = self._config
cfg_guider = CFGGuider(cfg.guidance_scale)      # CFG application

stg_guider = STGGuider(cfg.stg_scale)           # STG application

Both guiders are applied within the Euler denoising loop. The STG guider additionally receives the perturbation configuration (cfg.stg_blocks and cfg.stg_mode) to determine which transformer blocks to modify during the diffusion process.

Summary

• CFG scale (default 4.0) controls text prompt adherence via guidance_scale in ValidationConfig.
• STG scale (default 1.0) manages temporal consistency via stg_scale and disables at 0.
• Configure via YAML files, Python Config objects, or CLI flags (--video-cfg-guidance-scale, --video-stg-guidance-scale, etc.).
• Source implementations reside in config.py (definitions), guiders.py (logic), and validation_runner.py (runtime application).
• STG offers additional tuning through stg_blocks and stg_mode parameters for selective layer perturbation.

Frequently Asked Questions

What happens when I set the STG scale to zero?

Setting stg_scale: 0 in your configuration or passing --video-stg-guidance-scale 0 disables Spatio-Temporal Guidance entirely. According to the STGGuider implementation in guiders.py, the enabled() method returns False when the scale equals zero, causing the validation runner to skip STG computations and omit the perturbation logic from the denoising loop.

Can I use different CFG scales for video and audio generation?

Yes. The CLI flags in args.py separate video and audio guidance: --video-cfg-guidance-scale and --audio-cfg-guidance-scale. While the base ValidationConfig uses a single guidance_scale field, the pipeline scripts can override these separately for multimodal outputs, allowing distinct adherence levels for visual and auditory content.

How do I select which transformer blocks to perturb with STG?

Use the stg_blocks parameter in your YAML configuration or Python ValidationConfig object. This accepts a list of integers representing transformer block indices (e.g., stg_blocks: [29]). The stg_mode parameter further controls the perturbation strategy, accepting values like "stg_av" (audio-visual) or "stg_v" (video-only) to determine which modalities receive the temporal guidance signal.

Where are the default guidance values defined in the codebase?

Default values are hardcoded in packages/ltx-trainer/src/ltx_trainer/config.py. guidance_scale defaults to 4.0 at lines 17-21, and stg_scale defaults to 1.0 at lines 23-27. These defaults apply when running validation unless overridden by explicit configuration values or CLI arguments processed through packages/ltx-pipelines/src/ltx_pipelines/utils/args.py.

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