|
| 1 | +#!/usr/bin/env python3 |
| 2 | +"""Cache-only LTX-2.5 distilled video+audio runner for NVIDIA CUDA. |
| 3 | +
|
| 4 | +The Video Gen UI owns runtime installation and every Hugging Face download. |
| 5 | +This helper resolves the pinned split checkpoint only from the local cache, |
| 6 | +streams model blocks from disk on consumer GPUs, and writes one MP4. |
| 7 | +""" |
| 8 | + |
| 9 | +from __future__ import annotations |
| 10 | + |
| 11 | +import argparse |
| 12 | +import os |
| 13 | +import sys |
| 14 | +from pathlib import Path |
| 15 | + |
| 16 | +sys.path.insert(0, str(Path(__file__).resolve().parent)) |
| 17 | +from _runner_common import emit_runtime_fingerprint, establish_process_group, heartbeat # noqa: E402 |
| 18 | + |
| 19 | + |
| 20 | +MODEL_FILES = { |
| 21 | + "transformer": "diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors", |
| 22 | + "text_encoder": "text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors", |
| 23 | + "video_vae": "vae/ltx-2.5-video-vae-bf16.safetensors", |
| 24 | + "audio_vae": "vae/ltx-2.5-audio-vae-bf16.safetensors", |
| 25 | + "duration_head": "model_patches/ltx-2.5-duration-head-bf16.safetensors", |
| 26 | + "upsampler": "latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors", |
| 27 | +} |
| 28 | + |
| 29 | + |
| 30 | +def log(message: str) -> None: |
| 31 | + print(message, file=sys.stderr, flush=True) |
| 32 | + |
| 33 | + |
| 34 | +def parse_args() -> argparse.Namespace: |
| 35 | + parser = argparse.ArgumentParser(description=__doc__) |
| 36 | + parser.add_argument("--model-repo", required=True) |
| 37 | + parser.add_argument("--model-revision", required=True) |
| 38 | + parser.add_argument("--repo-file", action="append", default=[]) |
| 39 | + parser.add_argument("--prompt", required=True) |
| 40 | + parser.add_argument("--negative-prompt") |
| 41 | + parser.add_argument("--width", type=int, required=True) |
| 42 | + parser.add_argument("--height", type=int, required=True) |
| 43 | + parser.add_argument("--num-frames", type=int, required=True) |
| 44 | + parser.add_argument("--fps", type=float, required=True) |
| 45 | + parser.add_argument("--steps", type=int, default=8) |
| 46 | + parser.add_argument("--seed", type=int, required=True) |
| 47 | + parser.add_argument("--image") |
| 48 | + parser.add_argument("--image-strength", type=float, default=1.0) |
| 49 | + parser.add_argument("--disable-audio", action="store_true") |
| 50 | + parser.add_argument("--output", required=True) |
| 51 | + return parser.parse_args() |
| 52 | + |
| 53 | + |
| 54 | +def validate_args(args: argparse.Namespace) -> None: |
| 55 | + missing = sorted(set(MODEL_FILES.values()) - set(args.repo_file)) |
| 56 | + if missing: |
| 57 | + raise SystemExit(f"LTX-2.5 model entry is missing required repo files: {', '.join(missing)}") |
| 58 | + if args.width % 64 or args.height % 64: |
| 59 | + raise SystemExit("The two-stage LTX-2.5 pipeline requires width and height divisible by 64.") |
| 60 | + if args.num_frames < 9 or args.num_frames % 8 != 1: |
| 61 | + raise SystemExit("LTX-2.5 num-frames must be at least 9 and satisfy frames % 8 == 1.") |
| 62 | + if args.steps != 8: |
| 63 | + raise SystemExit("The distilled LTX-2.5 schedule is fixed at 8 steps.") |
| 64 | + if not 0 <= args.image_strength <= 1: |
| 65 | + raise SystemExit("image-strength must be between 0 and 1.") |
| 66 | + |
| 67 | + |
| 68 | +def resolve_snapshot(args: argparse.Namespace) -> Path: |
| 69 | + from huggingface_hub import snapshot_download |
| 70 | + |
| 71 | + try: |
| 72 | + root = snapshot_download( |
| 73 | + repo_id=args.model_repo, |
| 74 | + revision=args.model_revision, |
| 75 | + allow_patterns=args.repo_file, |
| 76 | + local_files_only=True, |
| 77 | + ) |
| 78 | + except Exception as exc: |
| 79 | + raise RuntimeError( |
| 80 | + "The pinned LTX-2.5 files are not complete in the Hugging Face cache. " |
| 81 | + "Use Download or Repair on the Video Gen page." |
| 82 | + ) from exc |
| 83 | + snapshot = Path(root) |
| 84 | + unresolved = [relative for relative in MODEL_FILES.values() if not (snapshot / relative).is_file()] |
| 85 | + if unresolved: |
| 86 | + raise RuntimeError( |
| 87 | + "The pinned LTX-2.5 snapshot is incomplete: " + ", ".join(unresolved) |
| 88 | + ) |
| 89 | + return snapshot |
| 90 | + |
| 91 | + |
| 92 | +def main() -> None: |
| 93 | + establish_process_group() |
| 94 | + args = parse_args() |
| 95 | + validate_args(args) |
| 96 | + log("STAGE:resolve-cache") |
| 97 | + snapshot = resolve_snapshot(args) |
| 98 | + |
| 99 | + # LTX's documented allocator setting reduces fragmentation on cards that |
| 100 | + # sit close to the model's supported VRAM floor. It must be set before |
| 101 | + # importing torch so CUDA reads it during allocator initialization. |
| 102 | + os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True") |
| 103 | + import torch |
| 104 | + from ltx_core.model.video_vae import AUTO_TILING, get_video_chunks_number |
| 105 | + from ltx_core.quantization.fp8_cast import build_policy as build_fp8_cast_policy |
| 106 | + from ltx_pipelines.distilled import DistilledPipeline |
| 107 | + from ltx_pipelines.utils.args import ImageConditioningInput |
| 108 | + from ltx_pipelines.utils.media_io import encode_video |
| 109 | + from ltx_pipelines.utils.model_paths import ModelPaths |
| 110 | + from ltx_pipelines.utils.types import OffloadMode |
| 111 | + |
| 112 | + if not torch.cuda.is_available(): |
| 113 | + raise RuntimeError("LTX-2.5 CUDA needs a visible NVIDIA device. Repair the runtime from Video Gen.") |
| 114 | + emit_runtime_fingerprint( |
| 115 | + "ltx25_cuda", |
| 116 | + ["torch", "ltx-core", "ltx-pipelines", "transformers", "accelerate", "huggingface-hub"], |
| 117 | + ) |
| 118 | + paths = {key: str(snapshot / relative) for key, relative in MODEL_FILES.items()} |
| 119 | + model_paths = ModelPaths.from_split( |
| 120 | + transformer_path=paths["transformer"], |
| 121 | + text_encoder_path=paths["text_encoder"], |
| 122 | + video_vae_path=paths["video_vae"], |
| 123 | + audio_vae_path=paths["audio_vae"], |
| 124 | + duration_head_path=paths["duration_head"], |
| 125 | + ) |
| 126 | + |
| 127 | + log("STATUS:LTX-2.5 CUDA disk-streamed loading (FP8 transformer cache)") |
| 128 | + log("STAGE:load-pipeline") |
| 129 | + with heartbeat("ltx25-cuda-load"): |
| 130 | + pipe = DistilledPipeline( |
| 131 | + model_paths=model_paths, |
| 132 | + spatial_upsampler_path=paths["upsampler"], |
| 133 | + loras=[], |
| 134 | + device=torch.device("cuda"), |
| 135 | + quantization=build_fp8_cast_policy(paths["transformer"]), |
| 136 | + # CPU mode pins a model-sized prefetch buffer. The 24 GB VRAM / |
| 137 | + # 32 GB system-RAM tier can exhaust that buffer while Gemma is |
| 138 | + # resident; DISK is upstream's lowest-memory streaming mode. |
| 139 | + offload_mode=OffloadMode.DISK, |
| 140 | + ) |
| 141 | + images = [] |
| 142 | + if args.image: |
| 143 | + images.append(ImageConditioningInput(args.image, 0, args.image_strength)) |
| 144 | + log("STAGE:inference") |
| 145 | + with heartbeat("ltx25-cuda-inference"): |
| 146 | + video, audio, resolved_frames, tiling = pipe( |
| 147 | + prompt=args.prompt, |
| 148 | + seed=args.seed, |
| 149 | + height=args.height, |
| 150 | + width=args.width, |
| 151 | + num_frames=args.num_frames, |
| 152 | + frame_rate=args.fps, |
| 153 | + images=images, |
| 154 | + tiling_config=AUTO_TILING, |
| 155 | + ) |
| 156 | + if args.disable_audio: |
| 157 | + audio = None |
| 158 | + |
| 159 | + output = Path(args.output) |
| 160 | + output.parent.mkdir(parents=True, exist_ok=True) |
| 161 | + log("STAGE:mux") |
| 162 | + encode_video( |
| 163 | + video=video, |
| 164 | + fps=int(args.fps), |
| 165 | + audio=audio, |
| 166 | + output_path=str(output), |
| 167 | + video_chunks_number=int(get_video_chunks_number(resolved_frames, tiling)), |
| 168 | + ) |
| 169 | + if not output.is_file(): |
| 170 | + raise RuntimeError(f"LTX-2.5 completed but did not write {output}.") |
| 171 | + log(f"STATUS:LTX-2.5 saved {output.name} ({resolved_frames} frames)") |
| 172 | + |
| 173 | + |
| 174 | +if __name__ == "__main__": |
| 175 | + main() |
0 commit comments