"""FastFrames-S Live: a real-time text-to-video stream that follows the prompt as you type. One held ZeroGPU session (like the Qwen-Image 2.1 Realtime Space) runs the official FastFrames-S per-frame rollout and streams it as 1 s segments. UI edits reach the running GPU process through a small per-session JSON file. * Every prompt edit regenerates the scene from frame 0 under the new prompt with the same seed, so the shot stays comparable and the new prompt is followed exactly. * While the prompt is idle the scene keeps going past the trained 5 s with a sink + rolling KV window (slot 0 keeps the first frame; when the 21-slot cache is full the oldest window frames are dropped and the remaining keys are re-rotated so RoPE positions stay in 0..20), and is regenerated with a fresh seed every REGEN_SECONDS to stop long-rollout drift. """ import json import os import random import subprocess import tempfile import threading import time import uuid from collections import deque from concurrent.futures import ThreadPoolExecutor from pathlib import Path import gradio as gr import spaces import torch from huggingface_hub import hf_hub_download, snapshot_download # Official inference code from github.com/apple-aiml-research/ml-fastframes (commit 6044a56), vendored unchanged. from fastframes.pipeline import MODELS, FastFrames, configure_backends, to_uint8 from fastframes.wan.causal_model import allocate_kv_cache FF_S_REVISION = "aa099efcedf1b65447106bf9004cde75821f7387" CF_REVISION = "2f8eb8bb6eeb1238da9d13e5420d342a74d634a6" WAN_REVISION = "37ec512624d61f7aa208f7ea8140a131f93afc9a" FPS = 16 WIDTH, HEIGHT = 832, 480 MAX_SEED = 2**31 - 1 MAX_CHARS = 1500 CHUNK = int(os.environ.get("CHUNK", 2)) # latent frames per streamed segment (2 = 0.5 s of video) ROLL_STRIDE = int(os.environ.get("ROLL_STRIDE", 4)) # window frames dropped each time the cache is full SINK = os.environ.get("SINK", "1") == "1" # keep frame 0 as an attention sink LEAD = float(os.environ.get("LEAD", 0.6)) # max seconds of video generated ahead of playback REGEN_SECONDS = int(os.environ.get("REGEN_SECONDS", 20)) # idle prompt: fresh scene after this much video DEBOUNCE = float(os.environ.get("DEBOUNCE", 0.0)) # a prompt must stay unchanged this long before it applies GPU_SIZE = os.environ.get("GPU_SIZE", "xlarge") SESSION_SECONDS = int(os.environ.get("SESSION_SECONDS", 90)) RT_WINDOW = SESSION_SECONDS - 6 # leave headroom under the @spaces.GPU duration DECODER_CONTEXT = 6 # pixel decoder's causal receptive field, in latent frames # ------------------------------------------------------------------------------------------- model SPEC = MODELS["ff-s"] CFG = SPEC.config CKPT = Path(snapshot_download("apple/FastFrames-S", revision=FF_S_REVISION, allow_patterns=["fastframes-s/*"])) DIT_PATH = hf_hub_download("zhuhz22/Causal-Forcing", "causal-forcing++/framewise-2step.pt", revision=CF_REVISION) WAN_DIR = Path(snapshot_download("Wan-AI/Wan2.1-T2V-1.3B", revision=WAN_REVISION, allow_patterns=["models_t5_umt5-xxl-enc-bf16.pth", "google/umt5-xxl/*"])) configure_backends(CFG) PIPE = FastFrames.from_pretrained(CFG, WAN_DIR, DIT_PATH, CKPT / SPEC.refiner, CKPT / SPEC.decoder) TOKENS = PIPE.frame_tokens CAP = CFG.num_frames # 21 cache slots = the trained RoPE range _c = (PIPE.dit.dim // PIPE.dit.num_heads) // 2 TEMPORAL_PAIRS = _c - 2 * (_c // 3) # complex RoPE pairs that carry the frame index print(f"[load] FastFrames-S ready: tokens/frame={TOKENS} cap={CAP} temporal_pairs={TEMPORAL_PAIRS}", flush=True) # ------------------------------------------------------------------------------------------- stream engine class LiveRollout: """FastFrames.rollout, one latent frame at a time, forever, with a sink + rolling KV window.""" def __init__(self, seed, kv): # one cache per session, reused across scenes: slots are overwritten in order and attention only # reads filled slots, so no clearing is needed self.kv = kv self.gen = torch.Generator(device=PIPE.device).manual_seed(int(seed)) self.used = 0 # occupied cache slots self.total = 0 # latent frames generated self.features = deque(maxlen=DECODER_CONTEXT + CHUNK) self.modulation = deque(maxlen=DECODER_CONTEXT + CHUNK) self.decoded = 0 # latent frames already turned into pixels self.rolls = 0 def _noise(self): return torch.randn((1, 1, 16, *CFG.latent_size), generator=self.gen, device=PIPE.device, dtype=torch.bfloat16) def _roll(self): """Drop ROLL_STRIDE window frames; shift the rest down and re-rotate their keys by -ROLL_STRIDE.""" keep_from = 1 if SINK else 0 src = (keep_from + ROLL_STRIDE) * TOKENS dst = keep_from * TOKENS n = (CAP - keep_from - ROLL_STRIDE) * TOKENS shift = PIPE.dit.freqs[:, :TEMPORAL_PAIRS][ROLL_STRIDE].conj().to(PIPE.device, torch.complex64) for layer in self.kv: k = layer["k"][:, src:src + n].float() k = torch.view_as_complex(k.unflatten(-1, (-1, 2)).contiguous()) k[..., :TEMPORAL_PAIRS] *= shift layer["k"][:, dst:dst + n] = torch.view_as_real(k).flatten(-2).to(layer["k"].dtype) layer["v"][:, dst:dst + n] = layer["v"][:, src:src + n].clone() self.used -= ROLL_STRIDE self.rolls += 1 @torch.inference_mode() def step(self, text_cache): if self.used == CAP: self._roll() slot = self.used schedule = CFG.first_frame_timesteps if slot == 0 else CFG.timesteps x = self._noise() for i, timestep in enumerate(schedule): x0, feature, mod = PIPE._predict(x, timestep, slot, text_cache, self.kv) if i + 1 < len(schedule): next_t = torch.full((1,), schedule[i + 1], device=PIPE.device, dtype=torch.float32) eps = self._noise()[:, 0] x = PIPE.scheduler.add_noise(x0.flatten(0, 1), eps, next_t).unflatten(0, x0.shape[:2]) if slot == 0: PIPE._predict(x0, 0.0, slot, text_cache, self.kv) # frame 0 gets a clean DiT pass else: PIPE._refine(x0, slot, self.kv) # later frames: KV refinement network self.features.append(feature) self.modulation.append(mod) self.used += 1 self.total += 1 @torch.inference_mode() def decode_pending(self): """uint8 frames for latent frames [decoded, total), decoded with up to 6 frames of causal history.""" new = self.total - self.decoded history = min(DECODER_CONTEXT, self.decoded, len(self.features) - new) feats = torch.cat(list(self.features)[-(new + history):], dim=1) mods = torch.cat(list(self.modulation)[-(new + history):], dim=1) h, w = CFG.latent_size grid = torch.tensor([[new + history, h // 2, w // 2]], device=PIPE.device, dtype=torch.long) with torch.autocast("cuda", dtype=torch.bfloat16): pixels = PIPE.decoder(feats, mods, grid)[0] pixels = pixels[4 * history:] if self.decoded == 0: pixels = pixels[3:] # the decoder's first three frames are dropped (84 -> 81 convention) self.decoded = self.total return to_uint8(pixels) _FFMPEG = ["ffmpeg", "-y", "-v", "error", "-f", "rawvideo", "-pix_fmt", "rgb24", "-s", f"{WIDTH}x{HEIGHT}", "-r", str(FPS), "-i", "-", "-c:v", "libx264", "-pix_fmt", "yuv420p"] class SegmentWriter: """Copies frames to host on a side stream and encodes MPEG-TS segments + a full recording off-thread.""" def __init__(self, out_dir): self.out_dir = Path(out_dir) self.pool = ThreadPoolExecutor(max_workers=1) self.stream = torch.cuda.Stream() self.count = 0 self.mp4 = self.out_dir / "fastframes_live.mp4" self.full = subprocess.Popen(_FFMPEG + ["-preset", "veryfast", "-crf", "18", "-movflags", "+faststart", str(self.mp4)], stdin=subprocess.PIPE) def _job(self, frames, ready, path): with torch.cuda.stream(self.stream): self.stream.wait_event(ready) data = frames.cpu().numpy().tobytes() self.full.stdin.write(data) subprocess.run(_FFMPEG + ["-preset", "ultrafast", "-tune", "zerolatency", "-crf", "20", "-f", "mpegts", str(path)], input=data, check=True) return str(path), frames.shape[0] def submit(self, frames): ready = torch.cuda.Event() ready.record() path = self.out_dir / f"seg{self.count:04d}.ts" self.count += 1 return self.pool.submit(self._job, frames, ready, path) def finish(self): self.pool.shutdown(wait=True) self.full.stdin.close() self.full.wait() return str(self.mp4) if self.mp4.exists() and self.mp4.stat().st_size > 0 else None # ------------------------------------------------------------------------------------------- session channel # @spaces.GPU runs in a forked process, so UI edits reach the running session through a JSON file. LIVE_DIR = Path(tempfile.gettempdir()) / "fastframes_live" LIVE_DIR.mkdir(exist_ok=True) def _channel(sid): return LIVE_DIR / f"{sid}.json" def _read(sid): try: return json.loads(_channel(sid).read_text()) except Exception: # noqa: BLE001 return None def _write(sid, **update): state = _read(sid) or {"ver": 0, "prompt": "", "seed": 0, "restart": 0, "stop": 0} state.update(update) state["ver"] = int(state.get("ver", 0)) + 1 tmp = _channel(sid).with_suffix(".tmp") tmp.write_text(json.dumps(state)) os.replace(tmp, _channel(sid)) def push_prompt(prompt, sid): """Send the current prompt to the running session (no GPU).""" if sid: _write(sid, prompt=(prompt or "")[:MAX_CHARS]) def push_regen(regen, sid): if sid: _write(sid, regen=int(regen)) def push_restart(sid): """New scene with a fresh seed in the running session.""" if sid: state = _read(sid) or {} _write(sid, restart=int(state.get("restart", 0)) + 1) def push_stop(sid): if sid: state = _read(sid) or {} _write(sid, stop=int(state.get("stop", 0)) + 1) # ------------------------------------------------------------------------------------------- GPU session @spaces.GPU(duration=SESSION_SECONDS, size=GPU_SIZE) def live_session(sid): """Hold the GPU and stream video that follows the session's prompt. Yields (kind, payload, status).""" deadline = time.time() + RT_WINDOW writer = SegmentWriter(tempfile.mkdtemp(prefix="ffl_")) req = _read(sid) or {} stop_mark, restart_mark = req.get("stop", 0), req.get("restart", 0) regen = int(req.get("regen", REGEN_SECONDS)) seed = random.randint(0, MAX_SEED) prompt, pending, pending_since = None, None, 0.0 text_cache, rollout = None, None pending_segments = deque() play_start, video_sent = None, 0.0 gen_times = deque(maxlen=8) scenes = 0 last_ver = -1 kv = allocate_kv_cache(PIPE.dit, CAP, TOKENS, device=PIPE.device) def new_scene(reason): nonlocal rollout, scenes rollout = LiveRollout(seed, kv) scenes += 1 print(f"[live] {sid[:6]} scene {scenes} ({reason}) seed={seed} {prompt[:60]!r}", flush=True) try: while time.time() < deadline: req = _read(sid) if req and req["ver"] != last_ver: last_ver = req["ver"] if req.get("stop", 0) != stop_mark: break regen = int(req.get("regen", regen)) new_prompt = (req.get("prompt") or "").strip() if new_prompt and new_prompt != prompt and new_prompt != pending: pending, pending_since = new_prompt, time.time() if req.get("restart", 0) != restart_mark: restart_mark = req.get("restart", 0) seed = random.randint(0, MAX_SEED) if text_cache is not None: new_scene("new scene") # apply a prompt once it has stopped changing (the first one right away) if pending and (prompt is None or time.time() - pending_since >= DEBOUNCE): with torch.inference_mode(): text_cache = PIPE.dit.text_cache(PIPE.encode_prompt(pending)) prompt, pending = pending, None new_scene("prompt") if text_cache is None: time.sleep(0.03) continue # idle prompt: refresh the scene before long-rollout drift sets in if rollout.total / 4 >= regen: seed = random.randint(0, MAX_SEED) new_scene("refresh") # pace generation against playback so edits show up quickly if play_start is not None and video_sent - (time.time() - play_start) > LEAD: time.sleep(0.01) else: torch.cuda.synchronize() t = time.perf_counter() rollout.step(text_cache) if rollout.total - rollout.decoded >= CHUNK: pending_segments.append(writer.submit(rollout.decode_pending())) torch.cuda.synchronize() gen_times.append(time.perf_counter() - t) while pending_segments and pending_segments[0].done(): path, n = pending_segments.popleft().result() if play_start is None: play_start = time.time() video_sent += n / FPS ms = 1000 * sum(gen_times) / max(len(gen_times), 1) status = (f"{250 / ms:.1f}x real time · scene {scenes}, {rollout.total / 4:.0f}/{regen} s · " f"{max(0, deadline - time.time()):.0f} s of GPU session left") yield "chunk", path, status finally: for fut in pending_segments: fut.result() recording = writer.finish() yield "final", recording, f"Session ended after {scenes} scenes." def go_live(prompt, regen, sid): if not (prompt or "").strip(): raise gr.Error("Enter a prompt first.") _write(sid, prompt=prompt[:MAX_CHARS], regen=int(regen)) yield gr.skip(), gr.skip(), "Starting the GPU session..." for kind, payload, status in live_session(sid): if kind == "chunk": yield payload, gr.skip(), status else: yield gr.skip(), payload, status + " Press Go live to keep going." # ------------------------------------------------------------------------------------------- UI EXAMPLES = { # chip label -> prompt "Beach run": "A corgi running along a sunny beach, waves rolling in, golden hour, cinematic tracking shot.", "Snow run": "A corgi running through deep fresh snow in a pine forest, snowflakes falling, cinematic tracking shot.", "Neon city": "A corgi running along a neon-lit city street at night in the rain, reflections on wet asphalt, " "cinematic tracking shot.", "Misty valley": "A drone shot gliding over a misty green valley with a winding river at sunrise.", "Red canyon": "A drone shot gliding over a red desert canyon with a winding river at sunset.", "Rainy café": "A cozy café at night, rain streaking down the window, warm lamps, a cup of coffee steaming.", "Watercolor ducks": "A watercolor painting of a mother duck leading her ducklings across a calm pond.", } DEFAULT_PROMPT = EXAMPLES["Beach run"] # Qwen-Image 2.1 Realtime look (Base + Inter + zinc, orange accent) with MiniMax H3 Image style buttons. ORANGE = gr.themes.Color( c50="#fff7ed", c100="#ffedd5", c200="#fed7aa", c300="#fdba74", c400="#fb923c", c500="#f97316", c600="#ea580c", c700="#c2410c", c800="#9a3412", c900="#7c2d12", c950="#431407", name="fflorange", ) THEME = gr.themes.Base( primary_hue=ORANGE, secondary_hue=ORANGE, neutral_hue="zinc", font=[gr.themes.GoogleFont("Inter"), "ui-sans-serif", "system-ui", "sans-serif"], font_mono=[gr.themes.GoogleFont("JetBrains Mono"), "ui-monospace", "monospace"], ).set( body_background_fill_dark="#0a0706", block_background_fill_dark="#15100b", background_fill_secondary_dark="#15100b", color_accent="#f97316", slider_color="#f97316", checkbox_background_color_selected="#f97316", checkbox_background_color_selected_dark="#f97316", button_primary_background_fill="#f97316", button_primary_background_fill_hover="#ea580c", button_primary_background_fill_dark="#f97316", button_primary_background_fill_hover_dark="#ea580c", button_primary_text_color="#ffffff", button_primary_text_color_dark="#ffffff", ) APPLE_SVG = ( '' ) CSS = """ .gradio-container {max-width: 1180px !important; margin: 0 auto !important;} /* brand row (H3 Image style, smaller logo) */ .ffl-brand {display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: 10px; margin: 14px auto 4px; min-width: 0;} .ffl-apple {width: 26px; height: 26px; flex: none; color: var(--body-text-color, #18181b);} .ffl-word {font-size: clamp(24px, 4vw, 30px); font-weight: 400; line-height: 1.1; letter-spacing: -0.01em; color: var(--body-text-color, #18181b); overflow-wrap: anywhere; min-width: 0;} .ffl-word b {font-weight: 600;} .ffl-grad {background: linear-gradient(90deg, #f97316, #e8197e); -webkit-background-clip: text; background-clip: text; color: transparent; font-weight: 500;} .ffl-sub {text-align: center; color: var(--body-text-color-subdued, #71717a); margin: 4px auto 10px !important; max-width: 70ch; overflow-wrap: anywhere; padding: 0 8px;} /* link pills (Qwen Realtime style) */ .ffl-pills {display: flex; flex-wrap: wrap; justify-content: center; gap: 8px; margin: 0 auto 6px;} .ffl-pills a, .ffl-pills a:link, .ffl-pills a:visited {font-size: .8rem; padding: 4px 12px; border-radius: 999px; background: #f97316; color: #fff !important; text-decoration: none !important; white-space: nowrap;} .ffl-pills a:hover {background: #ea580c;} /* cards */ .ffl-card {border: 1px solid var(--border-color-primary, #e4e4e7) !important; border-radius: 12px !important; padding: 16px !important; background: var(--block-background-fill, transparent) !important; min-width: 0; gap: 12px !important;} .ffl-stage video {max-width: 100%; object-fit: contain; background: #09090b; border-radius: 10px;} .ffl-status {min-height: 1.6em;} .ffl-status p {display: inline-block; max-width: 100%; margin: 0; padding: 4px 12px; border-radius: 999px; font-family: var(--font-mono, monospace); font-size: 12px; font-variant-numeric: tabular-nums; color: var(--body-text-color-subdued, #71717a); background: var(--background-fill-secondary, #f4f4f5); border: 1px solid var(--border-color-primary, #e4e4e7); overflow-wrap: anywhere;} .ffl-prompt textarea {font-size: 16px !important; line-height: 1.5; min-height: 110px;} /* buttons (H3 Image hx-primary / hx-chip) */ .ffl-go {border-radius: 8px !important; padding: 10px 28px !important; font-size: 16px !important; font-weight: 600 !important; min-width: 120px;} .ffl-ghost {border-radius: 8px !important; font-weight: 600 !important; min-width: 80px;} .ffl-chips {display: flex !important; flex-wrap: wrap !important; gap: 6px !important;} .ffl-chips > * {flex: 0 1 auto !important; min-width: 0 !important; width: auto !important;} .ffl-chip {min-width: 0 !important; padding: 4px 12px !important; font-size: 12.5px !important; font-weight: 500 !important; border-radius: 999px !important; white-space: nowrap; border: 1px solid var(--border-color-primary, #e4e4e7) !important; transition: border-color .15s;} .ffl-chip:hover {border-color: #f97316 !important;} .ffl-preview img {object-fit: cover; background: var(--background-fill-secondary, #f4f4f5);} .ffl-hint, .ffl-hint p {color: var(--body-text-color-subdued, #71717a); font-size: 12.5px; overflow-wrap: anywhere;} .ffl-footer {margin-top: 8px; text-align: center;} """ HEADER = f"""
Real-time text-to-video. Hit Go live and keep typing: the stream follows your prompt as it plays.
""" LICENSE_NOTE = ( "Runs the official [FastFrames](https://github.com/apple-aiml-research/ml-fastframes) inference code by Apple. " "Weights: [apple/FastFrames-S](https://huggingface.co/apple/FastFrames-S) " "([Apple ML Research Model license](https://huggingface.co/apple/FastFrames-S/blob/main/LICENSE), research use " "only) with the Causal Forcing++ generator ([zhuhz22/Causal-Forcing](https://huggingface.co/zhuhz22/Causal-Forcing), " "Apache-2.0) and the [Wan2.1](https://huggingface.co/Wan-AI/Wan2.1-T2V-1.3B) text encoder (Apache-2.0)." ) def chips(target): """One-click example prompts; setting the textbox fires its .change, which feeds the live session.""" with gr.Row(elem_classes="ffl-chips"): for label, text in EXAMPLES.items(): gr.Button(label, size="sm", variant="secondary", elem_classes="ffl-chip").click( lambda t=text: t, None, target, show_progress="hidden", api_visibility="private") with gr.Blocks(title="FastFrames-S Live") as demo: sid = gr.Textbox(visible=False) # per-browser session id (a Textbox so the API can pass it too) gr.HTML(HEADER, container=False, padding=False) with gr.Row(equal_height=False): with gr.Column(scale=3, min_width=320, elem_classes=["ffl-card", "ffl-stage"]): live = gr.Video(show_label=False, streaming=True, autoplay=True, interactive=False, height=460) status = gr.Markdown("", elem_classes="ffl-status") with gr.Column(scale=2, min_width=280, elem_classes="ffl-card"): prompt = gr.Textbox(label="Prompt", lines=4, max_length=MAX_CHARS, value=DEFAULT_PROMPT, placeholder="Describe a shot, then keep editing it...", elem_classes="ffl-prompt") chips(prompt) with gr.Row(): start = gr.Button("Go live", variant="primary", scale=3, min_width=120, elem_classes="ffl-go") stop = gr.Button("Stop", variant="secondary", scale=1, min_width=80, elem_classes="ffl-ghost") restart = gr.Button("New scene", variant="secondary", elem_classes="ffl-ghost") with gr.Accordion("Settings", open=False): regen = gr.Slider(10, 60, value=REGEN_SECONDS, step=5, label="Refresh the scene every (s)", info="When the prompt stays the same, start a fresh scene after this much video " "to avoid drift on long runs.") gr.Markdown( "The stream follows your prompt: each edit re-renders the scene under the new words, and an idle " f"prompt gets a fresh scene every {REGEN_SECONDS} s. A session holds a GPU for about " f"{RT_WINDOW} s.", elem_classes="ffl-hint") with gr.Accordion("Session recording", open=False): recording = gr.Video(show_label=False, interactive=False) gr.Markdown(LICENSE_NOTE, elem_classes=["ffl-hint", "ffl-footer"]) demo.load(lambda: uuid.uuid4().hex, None, sid, api_visibility="private") prompt.change(push_prompt, [prompt, sid], None, show_progress="hidden", api_name="push_prompt") regen.change(push_regen, [regen, sid], None, show_progress="hidden", api_visibility="private") start.click(go_live, [prompt, regen, sid], [live, recording, status], api_name="go_live", concurrency_limit=4) restart.click(push_restart, [sid], None, show_progress="hidden", api_name="restart") stop.click(push_stop, [sid], None, show_progress="hidden", api_name="stop") if __name__ == "__main__": demo.launch(theme=THEME, css=CSS)