RIFE 4.9 frame interpolation on ZeroGPU

.gitattributes

@@ -0,0 +1,37 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+.trt/
+__pycache__/
+*.pyc
+.gradio/

README.md

@@ -0,0 +1,151 @@
+---
+title: Flowframes
+emoji: 🎞️
+colorFrom: pink
+colorTo: green
+sdk: gradio
+sdk_version: 6.26.0
+python_version: "3.10"
+app_file: app.py
+pinned: false
+fullWidth: true
+license: mit
+short_description: RIFE frame interpolation, streams a clip of any length
+startup_duration_timeout: 1h
+---
+
+# Flowframes
+
+RIFE frame interpolation as a Space. Upload a clip, get it back at two or four
+times the frame rate.
+
+[Flowframes](https://github.com/n00mkrad/flowframes) does this job on Windows.
+That project is a C# GUI wrapping ffmpeg and a set of interpolation backends, so
+none of it ports directly. What I reimplemented is the orchestration, in one
+`app.py` over one ONNX model.
+
+## Length is free, pixels are not
+
+Nothing accumulates in memory. ffmpeg decodes raw frames into a pipe, two frames
+are held at a time, each pair is interpolated, and the results stream straight
+into a second ffmpeg. A 4K frame is about 100 MB as float32, so a five minute 4K
+source costs the same memory as a five second one. Only time scales.
+
+Time scales with pixels rather than seconds, which is why "Max height" is the
+control that matters most. Halving the height is roughly four times faster.
+
+## Segments
+
+Work is cut into segments sized from a per-frame rate measured on the hardware
+that is actually running, never from a table. On ZeroGPU each segment is its own
+GPU call, so the 120 s limit bounds a segment rather than the whole job and clip
+length stops being a constraint. On CPU the same seams act as checkpoints, so
+pressing Stop keeps everything already rendered.
+
+The Interpolate button carries the estimate and updates as you change the clip,
+the multiplier or Max height. It counts what you actually wait for, which is not
+the same as inference time: the per-segment overhead the plan under-charges, and
+on ZeroGPU the allocation queue, which for a short clip is the largest term of
+the three. A job needing more than six hours is refused up front with a suggested
+resolution, rather than discovering the problem hours in.
+
+If a segment overruns its plan badly, the remaining segments are re-cut from what
+that segment actually cost. A segment reports progress only when it finishes, so
+an oversized one freezes the log and adds its whole duration to how long Stop
+takes to respond.
+
+## What it costs, measured
+
+Every number here came off this Space.
+
+| clip | where | result |
+| --- | --- | --- |
+| 6 s, 1280x720, 2x | ZeroGPU | 180 -> 359 frames, 15 s end to end |
+| 2 min, 426x240, 2x | CPU, 12 threads | 3600 -> 7199 frames, 589 s, 47 segments |
+
+Per frame at 720p: 0.021 s on the GPU, 0.83 s on a Space CPU. The header quotes
+that number, and it is why the header says seconds on GPU hardware and minutes on
+CPU.
+
+That 0.021 was 0.130 until the model was converted from opset 19 to opset 18.
+Nothing else changed and the two graphs are bit identical, but at opset 19 the
+CUDA provider declined all 22 `Resize` nodes and ran them on the CPU, which
+forced a host round trip at each one. Profiling inside the GPU call showed it:
+
+```
+opset 19  MemcpyFromHost 34%, Resize 27%, Conv 19%   memcpy 44%, on CPU EP 28%
+opset 18  Conv 38%, Add 16%, LeakyRelu 8%            memcpy  0%, on CPU EP  0%
+```
+
+The copies were never input transfer. They were one op bouncing the graph between
+devices twenty two times per inference, and the fix was a version number.
+
+Frame counts are exact. A 47-segment run reassembles to 7199 frames, which is
+`3600 * 2 - 1` to the frame. Segment bounds carry a one-frame overlap and only
+the last segment writes its tail, so no seam duplicates or drops a frame. At 4x
+the same holds across ten segments, `(180 - 1) * 4 + 1 = 717`. Audio carries over
+from the source and survives the segment concat. Odd source dimensions round down
+to even, because yuv420p subsamples chroma 2x2 and x264 refuses an odd side.
+
+## Execution providers
+
+One model file, best available provider, in order.
+
+| provider | status |
+| --- | --- |
+| TensorRT | Registered, never selected, and deliberately not pursued. See below. |
+| CUDA, fp32 | what runs on GPU |
+| CPU, fp32 | no GPU |
+
+The TensorRT EP ships inside the ONNX Runtime wheel, so ORT always reports it as
+available, but it needs `libnvinfer.so.10`, TensorRT's own runtime, which is not
+in the image. Adding it is one pinned dependency. The reason I have not: a
+TensorRT engine compiles on first inference, which on ZeroGPU means inside the
+120 s window, and the engine cache lives on a filesystem that dies with the
+container. Every cold start would recompile and might time out. That trades a
+working 0.021 s/frame for a maybe-faster path that intermittently fails to start.
+The code probes for the library before attempting the provider, so a missing
+runtime costs nothing rather than a failed session construction on every GPU
+call, and the path lights up by itself if the image ever ships it.
+
+Providers are tried one at a time rather than as a single list, because ORT's
+list is all or nothing: a missing TensorRT takes CUDA down with it and lands on
+CPU. ORT also does not raise when a provider fails. It prints `EP Error`, falls
+back to CPU inside the constructor and hands back a valid session, so the code
+reads the selected provider back from the session and prints it in the header. A
+Space running fifty times slower than it should looks exactly like one that is
+not.
+
+fp16 is not used on the GPU either, and that was a measurement rather than an
+oversight. I converted the model to fp16 and A/B'd it against fp32 on the CUDA
+provider inside a single GPU allocation on one container: fp16 0.1096 s/frame
+against fp32 0.0306. Three and a half times slower. Cosine agreement was 0.99994,
+so a quality gate would have passed it straight through.
+
+On the CPU path fp16 is wrong for a different reason. Those cores have no half
+precision ALU, so every operation promotes to fp32 and you pay the conversion on
+top.
+
+Thread count comes from the cgroup, not `os.cpu_count()`, which reports the host.
+The ZeroGPU container's `cpu.max` reads `1600000 100000`, so sixteen CPUs, and
+the cap takes twelve of them: measured at 720p this graph stops scaling around
+twelve threads and thirty two run 4.3x slower. Sixteen is worth knowing because
+it is not the two vCPUs a free CPU Space gets, and sizing anything against two
+here would be wrong by a factor of six.
+
+## Model
+
+RIFE 4.9, ONNX, 21 MB, committed to this repo rather than downloaded at startup,
+so a wake costs nothing and no upstream repo can disappear from under it.
+
+Stored at opset 18, converted from the opset 19 export. The conversion is bit
+identical on this graph, verified across three resolutions and three timesteps,
+and it is what keeps `Resize` on the CUDA provider. Re-exporting at opset 19
+would silently cost a factor of five.
+
+## Credit
+
+[RIFE](https://github.com/hzwer/Practical-RIFE) by Huang et al. ONNX export from
+[yuvraj108c/rife-onnx](https://huggingface.co/yuvraj108c/rife-onnx).
+Orchestration modelled on [Flowframes](https://github.com/n00mkrad/flowframes) by
+n00mkrad.

app.py

@@ -0,0 +1,1301 @@
+"""Flowframes on Spaces: RIFE frame interpolation that runs on CPU or GPU.
+
+One code path, one model file. The execution provider is chosen at startup
+(TensorRT, else CUDA, else CPU) and whatever was actually selected is printed in
+the header, because a missing CUDA library drops ORT to CPU silently and a Space
+running 50x slower looks identical to one that is not.
+
+Work is cut into segments sized from a measured per-frame rate. On ZeroGPU each
+segment is its own GPU call, so the 120 s cap bounds a segment rather than the
+job and clip length stops being a limit. On CPU the same seams are checkpoints,
+so cancelling keeps the minutes already spent.
+"""
+
+import os
+import pathlib
+import re
+import shutil
+import sys
+import tempfile
+import threading
+import time
+import uuid
+
+# Gradio copies every file it serves into GRADIO_TEMP_DIR and never prunes it,
+# so each delivered output existed twice and only one copy was ever cleaned.
+# Point that cache somewhere sweepable. Must happen before gradio is imported.
+SCRATCH = pathlib.Path(tempfile.gettempdir()) / "flowframes"
+OUTDIR = SCRATCH / "out"
+CACHEDIR = SCRATCH / "gradio"
+for _d in (OUTDIR, CACHEDIR):
+    _d.mkdir(parents=True, exist_ok=True)
+os.environ.setdefault("GRADIO_TEMP_DIR", str(CACHEDIR))
+CACHEDIR = pathlib.Path(os.environ["GRADIO_TEMP_DIR"])   # setdefault may not have won
+
+import gradio as gr
+
+import rife_core as R
+
+try:
+    import spaces
+    GPU = spaces.GPU
+except Exception:                       # noqa: BLE001
+    def GPU(*_a, **_k):
+        return lambda f: f
+
+# The import above is NOT the test. `spaces` is in requirements.txt and installs
+# anywhere; off ZeroGPU its decorator simply no-ops, so `import spaces` succeeded
+# on cpu-basic too and every ZeroGPU branch was taken there: BUDGET_S 90 s
+# instead of 900, segments ten times smaller than intended, and a header
+# announcing a GPU. Only the environment knows. Read from the live container:
+#   SPACES_ZERO_GPU='1'  ZEROGPU_V2='true'  SPACES_ZERO_DEVICE_API_URL=...
+ZEROGPU = bool(os.environ.get("SPACES_ZERO_GPU"))
+
+HERE = pathlib.Path(__file__).parent
+LOG_LINES = 14
+CANCELLED: set[str] = set()      # session hashes that asked to stop
+LOCK = threading.Lock()
+OWNER: str | None = None         # session hash of the job currently holding LOCK
+
+# Built on CPU at import: on ZeroGPU there is no CUDA device until a @spaces.GPU
+# call is running, so a session created here could never see one.
+BACKEND = R.OnnxBackend(prefer_gpu=False)
+_GPU_BE = None
+# (height, width, device) -> (seconds per frame, backend name, build seconds).
+# Survives between jobs because it lives in the parent, not in a @spaces.GPU fork.
+_RATE_CACHE: dict[tuple[int, int, str], tuple[float, str, float]] = {}
+# Set when a GPU call fails on quota, cleared when one next succeeds. Module
+# level because the header is rendered per page load by visitors who are not
+# running a job, and a Space whose daily quota is gone was still announcing
+# "GPU (ZeroGPU), about 39s" while every job crawled along on CPU.
+GPU_DEAD = False
+# Whether NVENC actually encodes in a GPU fork. False until the first fork
+# reports back, because the parent process has no GPU and cannot find out.
+NVENC_OK = False
+
+
+def worker() -> R.Backend:
+    """The backend to actually infer with. Inside a GPU call this upgrades to
+    CUDA or TensorRT once, then stays."""
+    global _GPU_BE
+    if not ZEROGPU:
+        return BACKEND
+    if _GPU_BE is None:
+        t0 = time.time()
+        _GPU_BE = R.OnnxBackend(prefer_gpu=True, trt_cache=str(HERE / ".trt"))
+        print(f"[ff] BUILT gpu worker {_GPU_BE.name} in {time.time()-t0:.0f}s "
+              f"pid={os.getpid()}", flush=True)
+    else:
+        print(f"[ff] REUSED gpu worker pid={os.getpid()}", flush=True)
+    return _GPU_BE
+# Reference rate at 720p so the header can quote a real number rather than a table.
+REF_RATE = R.measure_rate(BACKEND, 720, 1280)
+# One GPU call must finish inside its ZeroGPU budget; CPU has no such cap but
+# still benefits from the checkpoint seams.
+#
+# 60, not 90, and not the 75 I first reasoned my way to. plan_gaps charges only
+# the inference term, so a segment costs more than it plans for. Measured on this
+# Space against a hard 120 s @spaces.GPU window:
+#
+#   852x480 f2   1.416x, 1.456x        360x640 f2   1.393x, 1.496x
+#   852x480 f4   1.566x   <-- worst
+#
+# I predicted f4 would be BELOW f2, on the theory that a fixed per-gap overhead
+# is diluted by three inferences instead of one. It came in highest. The overhead
+# is 0.0235 s/gap at f2 and 0.0957 at f4 - four times larger, not fixed - and per
+# generated frame it is superlinear too, so there is no model here, only a worst
+# case. At the worst observed 1.566x: 90 plans 141 s (killed), 75 plans 117 s
+# (2% of headroom, which is not headroom), 60 plans 94 s.
+#
+# The cost of being conservative is refunded by the re-cut below, which grows the
+# plan back when a segment proves cheaper than budgeted. CPU stays 900: no window
+# to overrun, and bigger segments mean fewer ffmpeg restarts.
+BUDGET_S = 60.0 if ZEROGPU else 900.0
+print(f"[ff] provider={BACKEND.provider} rate720p={REF_RATE:.3f}s/frame "
+      f"budget={BUDGET_S:.0f}s zerogpu={ZEROGPU}", flush=True)
+# Kept: if HF ever renames the marker, this line is how it gets noticed.
+print("[ff] env " + " ".join(sorted(k for k in os.environ if "ZERO" in k.upper())),
+      flush=True)
+# On GPU the plan-check ratio says 40-66% of a segment is decode, emit and x264
+# on two vCPUs rather than the model, so whether ffmpeg can offload any of that
+# is the largest open speed question. It depends on the image's ffmpeg build,
+# which nothing else here can see.
+R.report_ffmpeg_hw()
+# Whether the thread count came from the cgroup or from a failed read matters:
+# one is the container's real allowance, the other is the host's count and means
+# ORT is oversubscribing the two vCPUs a Space is supposed to have.
+print(f"[rife] threads={R.CPUS} from: {R.cgroup_report()}", flush=True)
+# One-shot: is the 12-thread cap right for THIS container? The sweep behind it
+# measured 12 against 32 on a dev box, and the ZeroGPU container allows 16, which
+# was never tested. Both measured in the same boot so the comparison is not
+# across two containers with different noise. Costs a few seconds once, against a
+# 1h startup budget, and the CPU path is what users hit when quota runs out.
+if ZEROGPU and R.container_cpus() > R.CPUS:
+    try:
+        _alt = R.OnnxBackend(prefer_gpu=False, threads=R.container_cpus())
+        _r_alt = R.measure_rate(_alt, 720, 1280)
+        del _alt
+        print(f"[rife] thread sweep at 720p: {R.CPUS} threads {REF_RATE:.3f}s/frame, "
+              f"{R.container_cpus()} threads {_r_alt:.3f}s/frame -> "
+              f"{'raise the cap' if _r_alt < REF_RATE * 0.95 else 'cap is right'}",
+              flush=True)
+    except Exception as _e:                                  # noqa: BLE001
+        print(f"[rife] thread sweep failed ({type(_e).__name__})", flush=True)
+
+
+def hms(s: float) -> str:
+    s = int(s)
+    return f"{s//3600}:{(s%3600)//60:02d}:{s%60:02d}" if s >= 3600 else f"{s//60}:{s%60:02d}"
+
+
+def plain(seconds: float) -> str:
+    """Wall clock the way a person says it, not seconds-per-frame."""
+    if seconds < 90:
+        return f"{int(seconds)}s"
+    if seconds < 5400:
+        return f"{seconds/60:.0f} min"
+    return f"{seconds/3600:.1f} h"
+
+
+# Measured at 1280x720 on the ZeroGPU device (RTX PRO 6000 Blackwell MIG 2g.48gb),
+# fp32 CUDA, by running a real job through this Space. Used only as the a-priori
+# number in the header before any job has run here, because there is no GPU at
+# import time to measure on. Quoted at 720p directly rather than scaled up from a
+# smaller measurement, so the header carries a number and not an extrapolation.
+GPU_REF_RATE_720P = 0.130
+
+
+def measured() -> tuple[float, str, int, int] | None:
+    """The rate this Space actually runs at, with the device that produced it.
+
+    One snapshot and one preference order, so the name and the number in the
+    header always describe the same device. Two independent lookups over this
+    dict used to disagree: the estimate preferred a GPU entry while the name took
+    whatever was inserted first, which on a Space that ran on CPU before the
+    quota reset printed a CPU backend beside a GPU rate.
+
+    The snapshot also matters: demo.load runs outside the queue on every page
+    load, so a job in another session can insert here mid-iteration.
+    """
+    snap = list(_RATE_CACHE.items())
+    devices = ("cpu",) if GPU_DEAD else ("gpu", "cpu")
+    # 1280x720 first, because "10s 720p clip" is the phrase a person can act on
+    # and the default Max height produces exactly that key on any 16:9 source,
+    # which is most video. Failing that, quote whatever WAS measured and name its
+    # size: a number that is true about an odd resolution beats a familiar one
+    # restated from a measurement taken somewhere else.
+    for exact in (True, False):
+        for want in devices:
+            for (h, w, dev), (rate, name, _b) in snap:
+                if dev == want and (not exact or (h, w) == (720, 1280)):
+                    return rate, name, h, w
+    return None
+
+
+def header() -> str:
+    """A 10 s 30fps clip at 2x is 300 generated frames.
+
+    The measured rate is quoted at the resolution it was measured at, never
+    restated at 720p. Scaling by pixel count looked exact from 640x360 (0.032
+    measured, 0.033 predicted) and was 15% out from 852x480 (0.067 measured
+    predicts 45 s; the directly measured 720p answer is 39 s), because a small
+    frame leaves the GPU idle. Naming the resolution costs nothing and means the
+    number is always something that was actually observed.
+    """
+    hit = measured()
+    if hit:
+        rate, name, h, w = hit
+        size = "720p" if (h, w) == (720, 1280) else f"{w}x{h}"
+        cost = f"about {plain(rate * 300)} for a 10s {size} clip at 2x"
+    elif ZEROGPU:
+        name = "GPU (ZeroGPU)"
+        cost = f"about {plain(GPU_REF_RATE_720P * 300)} for a 10s 720p clip at 2x"
+    else:
+        name = BACKEND.name
+        cost = f"about {plain(REF_RATE * 300)} for a 10s 720p clip at 2x"
+    return (f"[flowframes](https://github.com/n00mkrad/flowframes): "
+            f"RIFE 4.9 frame interpolation · **{name}** · **{cost}** · "
+            f"streams two frames at a time, so length costs time and not memory")
+
+
+class Log:
+    """Ring buffer with elapsed-time prefixes.
+
+    Every yield re-sends the whole joined string over SSE, so an unbounded log
+    grows each frame. Elapsed rather than wall clock because on a long job the
+    delta between two lines is the only ETA instrument the viewer has.
+    """
+
+    def __init__(self, cap: int = 400):
+        self.t0 = time.time()
+        self.lines: list[str] = []
+        self.cap = cap
+
+    def __call__(self, msg: str) -> str:
+        self.lines.append(f"[+{hms(time.time() - self.t0)}] {msg}")
+        if len(self.lines) > self.cap:
+            del self.lines[: self.cap // 2]
+        return "\n".join(self.lines[-LOG_LINES:])
+
+    @property
+    def text(self) -> str:
+        return "\n".join(self.lines[-LOG_LINES:])
+
+
+def stop(request: gr.Request):
+    """Cancel only the caller's own job.
+
+    This handler runs outside the queue, so a second visitor waiting behind the
+    first used to be able to kill the first visitor's run by pressing Stop, and
+    anyone could POST the endpoint directly. Cancellation is keyed on the session
+    that owns the running job.
+    """
+    me = getattr(request, "session_hash", None) or f"anon-{uuid.uuid4()}"
+    if OWNER is not None and me != OWNER:
+        return "That job belongs to another visitor. Yours has not started yet."
+    CANCELLED.add(me)
+    return "Stopping at the next frame boundary. The finished part is still saved."
+
+
+def _segment_duration(src, dst, start, gaps, factor, clip, crf, write_tail,
+                      me, tw, th) -> int:
+    """Ask for what this particular segment needs, not for the ceiling.
+
+    Takes the same arguments as the call it sizes, which is how a `duration`
+    callable is invoked. Reuses the planner's own arithmetic and the measured
+    `_OVERHEAD`, so a segment cut for a 60s budget asks for roughly 60s rather
+    than the 120s cap, and a one-gap segment asks for seconds.
+
+    Under-asking is not free: ZeroGPU kills a call that outlives its declaration.
+    That lands in the existing `is_timeout_error` path, which halves the segment
+    and retries up to four times, so it degrades into a slower job rather than a
+    failed one. Hence the 1.4x on top of an overhead figure that already carries
+    the measured 1.40-1.66 correction.
+    """
+    # A measurement of THIS shape beats the pooled mean. _PER_GAP holds the wall
+    # cost per gap of the last full segment at this (h, w, factor), which is the
+    # same quantity the re-cut sizes `gaps` from - so the declaration and the
+    # plan agree by construction instead of drifting apart with the mean.
+    seen = _PER_GAP.get((th, tw, int(factor), "gpu"))
+    if seen:
+        # 1.35, not 1.4: it gives every segment the same headroom the re-cut
+        # already assumes is enough. REAL_BUDGET_S is 0.75 of the cap, so a 25%
+        # swing - the deadband's own definition of ordinary - still lands under
+        # 119. A short tail segment then gets the same margin as a full one,
+        # instead of whatever the pooled mean happened to imply for it.
+        return max(15, min(GPU_MAX_S, int(gaps * seen * 1.35) + 5))
+    hit = _RATE_CACHE.get((th, tw, "gpu"))
+    if not hit:
+        return GPU_MAX_S                 # nothing measured yet, keep the ceiling
+    est = gaps * hit[0] * max(1, int(factor) - 1) * _OVERHEAD["gpu"]
+    return max(15, min(GPU_MAX_S, int(est * 1.4) + 5))
+
+
+@GPU(duration=_segment_duration)
+def _segment_gpu(src, dst, start, gaps, factor, clip, crf, write_tail, me, tw, th):
+    """One segment, start to finish, inside a single GPU allocation.
+
+    Returns (frames, seconds_inside). The caller times this call from the parent,
+    which means its clock also covers the ZeroGPU allocation queue - 45s on a
+    session's first call. That number is not the cost of the work, and using it
+    as one shrank the next segment ~2x and permanently skewed the overhead mean.
+    """
+    t0 = time.perf_counter()
+    n = R.interpolate_segment(src, dst, start, gaps, factor, worker(), clip,
+                              crf=crf, cancel=lambda: me in CANCELLED,
+                              write_tail=write_tail, out_w=tw, out_h=th,
+                              hw_encode=NVENC_OK)
+    return n, time.perf_counter() - t0
+
+
+def _segment_cpu(src, dst, start, gaps, factor, clip, crf, write_tail, me, tw, th):
+    """The same work without a GPU allocation, for when ZeroGPU quota is gone.
+
+    Same (frames, seconds_inside) shape as the GPU worker so the caller does not
+    branch on which one ran.
+    """
+    t0 = time.perf_counter()
+    n = R.interpolate_segment(src, dst, start, gaps, factor, BACKEND, clip,
+                              crf=crf, cancel=lambda: me in CANCELLED,
+                              write_tail=write_tail, out_w=tw, out_h=th)
+    return n, time.perf_counter() - t0
+
+
+# Two different failures used to share one bucket. "GPU task aborted" is what a
+# segment that overran its 120 s window looks like, and calling that quota
+# exhaustion moved the whole rest of the job to CPU, told the user the day's
+# budget was gone, and never mentioned the real fault. A timeout means the
+# segment was too big; only the quota messages mean there is no GPU left today.
+QUOTA_HINTS = ("exceeded your zerogpu", "zerogpu runs limit", "proxy token",
+               "no gpu available", "gpu quota")
+TIMEOUT_HINTS = ("gpu task aborted", "illegal duration", "exceeded the maximum",
+                 "timeout")
+
+
+def is_quota_error(e: BaseException) -> bool:
+    return any(h in str(e).lower() for h in QUOTA_HINTS)
+
+
+def is_timeout_error(e: BaseException) -> bool:
+    return any(h in str(e).lower() for h in TIMEOUT_HINTS)
+
+
+def cpu_rate(h: int, w: int) -> tuple[float, str, float]:
+    """Same caching for the CPU path. Measuring costs a few seconds of the two
+    vCPUs a job is about to need."""
+    key = (h, w, "cpu")
+    if key not in _RATE_CACHE:
+        _RATE_CACHE[key] = (R.measure_rate(BACKEND, h, w), BACKEND.name, 0.0)
+    return _RATE_CACHE[key]
+
+
+def gpu_rate(h: int, w: int) -> tuple[float, str, float]:
+    """Cached in the parent process, which survives between jobs even though each
+    @spaces.GPU call runs in a fork. ZeroGPU meters runs rather than seconds, so a
+    90 s measurement costs the same as a 90 s segment; paying it on every job was
+    spending a fifth of a short job's budget to re-learn a constant."""
+    global NVENC_OK
+    key = (h, w, "gpu")
+    if key not in _RATE_CACHE:
+        rate, name, build, nvenc = _gpu_rate(h, w)
+        # The cache stays a 3-tuple. measured() unpacks it as (rate, name, _b),
+        # and an element-count mismatch here has already cost one debugging
+        # session, so the new field rides beside the cache rather than inside it.
+        _RATE_CACHE[key] = (rate, name, build)
+        NVENC_OK = nvenc
+        print(f"[ff] nvenc usable in the GPU fork: {nvenc}", flush=True)
+    return _RATE_CACHE[key]
+
+
+# measure_rate times three samples. At keep-source 4K that is 3 x ~1.1s, plus a
+# session build the logs show landing in under a second once the CUDA libs are
+# preloaded. 90s was reserving a minute and a half of quota to spend four
+# seconds, on the one call whose queue wait the user actually sits through.
+@GPU(duration=30)
+def _gpu_rate(h: int, w: int) -> tuple[float, str, float]:
+    """Measure the per-frame rate where the work will actually happen.
+
+    Measuring outside a GPU call times the CPU session, and the segment planner
+    would then size GPU segments from a CPU number, making them far too small.
+    """
+    t0 = time.time()
+    be = worker()                       # first call in this worker builds the session
+    build = time.time() - t0
+    rate = R.measure_rate(be, h, w)
+    # Probed here because this fork HAS a GPU, and returned rather than cached,
+    # because a global set inside a fork dies with it. Riding the rate call keeps
+    # it free: a separate @spaces.GPU probe would burn a metered run on one bool.
+    # Printed, not returned: this goes to the container log, and adding a fifth
+    # element to the tuple is how the 3-vs-2 unpack bug happened once already.
+    # FIXED 720p, not the job's resolution. This runs inside _gpu_rate, which
+    # declares duration=30; profiling four extra inferences at a keep-source 4K
+    # would add ~5-8s plus a second session build to a probe that already spends
+    # ~4s measuring, and a probe that outlives its declared duration is KILLED -
+    # which would drop the whole job to CPU. The op MIX is what decides between
+    # CUDA graphs and IO binding, and that does not need the job's own size.
+    print(f"[ff] profile 1280x720: {R.profile_ops(720, 1280)}", flush=True)
+    return rate, be.name, build, R.nvenc_works()
+
+
+def example_run(video, factor, max_h, crf):
+    """Examples cache one value per output, so drain the generator and hand back
+    only the video and the final log. Routed through run() so a cached example is
+    the same code path the button takes."""
+    class _Anon:
+        session_hash = "example"
+    vid_out, log_out = None, ""
+    for v, lg, *_ in run(video, factor, max_h, crf, _Anon()):
+        vid_out, log_out = v or vid_out, lg
+    if vid_out is None:
+        # Raising keeps Gradio from writing the failure into the cache. Returning
+        # None here cached a null video permanently, so the example row stayed
+        # broken for every later visitor with nothing to explain why.
+        raise gr.Error(f"Example produced no video. {log_out.splitlines()[-1:]}")
+    return vid_out, log_out
+
+
+# 50 GB of non-persistent container disk, shared with the model, the upload and
+# every segment. Four is room for several 4K jobs and nowhere near the ceiling.
+DISK_BUDGET = 4 * 1024 ** 3
+SWEEP_MIN_AGE = 3600          # never touch anything younger than an hour
+SWEEP_KEEP = 3                # ...nor the newest few, whatever the budget says
+ABANDONED_AGE = 6 * 3600      # work dirs left by a kill, not by the finally
+
+
+VIDEO_NAME = re.compile(r"[\w.\-]+\.(?:mp4|webm|mkv|mov)")
+
+
+def pinned_names() -> set[str]:
+    """Filenames the lazily cached example row points at.
+
+    Gradio postprocesses the example's output through save_file_to_cache, so the
+    video is copied into GRADIO_TEMP_DIR and the cached_examples CSV stores that
+    path. The row is written once and never rewritten, so its mtime never moves
+    and it becomes the OLDEST file in the cache: precisely the first thing an
+    oldest-first sweep takes. Losing it breaks the example permanently, for
+    everyone, with nothing in the log to say why.
+
+    Matching on the bare filename over-protects at worst, which is the right way
+    to be wrong here.
+    """
+    names: set[str] = set()
+    try:
+        for csv in pathlib.Path(".gradio").rglob("*.csv"):
+            names.update(VIDEO_NAME.findall(
+                csv.read_text(encoding="utf-8", errors="replace")))
+    except OSError:
+        pass
+    return names
+
+
+def sweep_outputs(budget: int = DISK_BUDGET, protect: str | None = None) -> None:
+    """Hold finished outputs and Gradio's copies of them under a byte budget.
+
+    Counting files is the wrong unit: three 4K outputs are far more disk than
+    thirty 480p ones. Nothing pruned either directory before, so disk-full was
+    the expected end state of a busy day, and the first thing that fails when the
+    disk is full is the mkdtemp at the top of the next job.
+
+    Four things must survive regardless of the budget. `protect` is the source
+    video of the job doing the sweeping, pinned by resolved path: GRADIO_TEMP_DIR
+    is also Gradio's UPLOAD folder, and the age floor does NOT cover it. That
+    claim used to sit here and was wrong - SWEEP_MIN_AGE is one hour while this
+    code permits a six hour job, so an upload that sat for ninety minutes before
+    the user pressed Interpolate could be unlinked two lines before
+    `R.probe(video)` read it, and the failure surfaced as "ffmpeg cannot open
+    this file as a video", blaming the user's file. The cached example is pinned
+    by name. And the newest few are always kept, because a budget smaller than
+    one job's output would otherwise delete its own input.
+    """
+    now = time.time()
+    pinned = pinned_names()
+    safe = None
+    if protect:
+        try:
+            safe = os.path.realpath(protect)
+        except OSError:
+            safe = None
+    files = []
+    for root in (OUTDIR, CACHEDIR):
+        for f in root.rglob("*"):
+            try:
+                if f.is_file():
+                    st = f.stat()
+                    files.append((st.st_mtime, st.st_size, f))
+            except OSError:
+                pass
+    total = sum(sz for _, sz, _ in files)
+    files.sort()                                  # oldest first
+    keep = {f for _, _, f in files[-SWEEP_KEEP:]}
+    for mt, sz, f in files:
+        if total <= budget:
+            break
+        if f in keep or f.name in pinned or now - mt < SWEEP_MIN_AGE:
+            continue
+        if safe:
+            try:
+                if os.path.realpath(f) == safe:
+                    continue
+            except OSError:
+                pass
+        try:
+            f.unlink()
+            total -= sz
+        except OSError:
+            pass      # an open handle on Windows; still counted, so the next
+                      # candidate is tried rather than the entry being forgotten
+
+    # Work directories are removed by run()'s finally on every normal path, but
+    # not after a hard kill: an OOM, a container restart, a ZeroGPU teardown.
+    # Those hold a whole segment set, gigabytes for a 4K job, and were invisible
+    # to the accounting above, so the budget could report itself satisfied while
+    # the disk filled anyway.
+    for d in SCRATCH.glob("ff_*"):
+        try:
+            if d.is_dir() and now - d.stat().st_mtime > ABANDONED_AGE:
+                shutil.rmtree(d, ignore_errors=True)
+        except OSError:
+            pass
+
+
+def preflight(video):
+    """Reject before the buttons swap, never after."""
+    if video is None:
+        raise gr.Error("Upload a video first, or click the example row below.")
+    return BUSY
+
+
+# The heights the Max height control actually offers, descending. Advice about
+# that control reads the same list, so a suggestion can never name a value the
+# dropdown does not have - which it did: at 480p it proposed 240, and at 360p it
+# claimed 480 was "the smallest step" when 480 IS the smallest step.
+HEIGHTS = (1080, 720, 480)
+
+
+def next_lower_height(th: int) -> int | None:
+    """The largest offered height below the current one, or None at the floor."""
+    return next((h for h in HEIGHTS if h < th), None)
+
+
+# What the plan does NOT charge, seeded from this Space's own `plan-check` lines
+# and then re-fitted from every full segment that runs. plan_gaps budgets only
+# inference; a real segment also decodes, emits factor-1 frames per gap and runs
+# x264. Seeds are the medians of what was actually logged:
+#   gpu  1.400 1.417 1.456 1.566 1.663
+#   cpu  1.050 1.187 1.192 1.204 1.230
+# Not a model: a constant would be wrong, because the ratio moves with device and
+# resolution - an earlier additive attempt fitted three points and was falsified
+# by a fourth. This is a running mean of measured ratios and converges on
+# whatever this container actually does.
+# The gpu seed moved 1.46 -> 2.10 when the model went to opset 18 and Resize
+# stopped falling back to the CPU provider. Inference went from 0.105 to 0.021
+# s/frame, so ffmpeg - decode, emit, x264, none of which got faster - became the
+# dominant share of a segment and the ratio rose accordingly. Measured 2.120 and
+# 2.111 on two consecutive 179-gap 720p segments.
+#
+# Leaving it at 1.46 was not merely inaccurate: _segment_duration falls back to
+# `gaps * rate * overhead * 1.4` when no _PER_GAP measurement exists, so the
+# FIRST segment of a long clip would have declared ~85s for ~89s of work and been
+# killed by ZeroGPU. Making the model faster broke the duration declaration.
+_OVERHEAD = {"gpu": 2.10, "cpu": 1.19}
+_OVERHEAD_N = {"gpu": 5, "cpu": 5}
+
+# Wall seconds per gap of the last FULL segment at each (h, w, factor, device).
+# Set in the parent after a segment returns, read in the parent by the duration
+# callable, so no fork boundary is crossed. Empty until a segment completes,
+# which is why the reconstruction below it still has to exist.
+#
+# The DEVICE belongs in the key. The ratio moves with resolution and factor - the
+# note in plan_gaps is explicit about that - but the per-gap cost itself moves
+# with the hardware by roughly 4x, so a CPU-measured value would size a GPU
+# segment at four times its true length and hand it a duration to match.
+_PER_GAP: dict[tuple[int, int, int, str], float] = {}
+
+# The wait the estimate always ignored. A ZeroGPU allocation queues before it
+# forks: measured 45-46s for the first call of a session, then 1-2s per later
+# call. On a short clip that first wait is the LARGEST term - a real job logged
+# "estimate 0:26", did 31s of work and took 1:17 wall clock, and the 46s nobody
+# was accounting for is the whole difference.
+# Seeded from a COLD container, where the first allocation of a session queued
+# 45-46s. That is the worst case, not the normal one: a warm Space allocates in
+# ~1s, and a browser run whose button promised 59s finished in 22 - 39 phantom
+# seconds, all of them this constant. Now that `took - spent` measures the queue
+# directly, it is a running mean like _OVERHEAD rather than a guess.
+GPU_QUEUE_S = 45.0
+_QUEUE_N = 1
+GPU_ACQUIRE_S = 1.5
+
+# ZeroGPU's per-call ceiling. Declaring above a tier's cap does not run slower,
+# it is refused outright with "ZeroGPU illegal duration", so this is a hard limit
+# rather than a target and every duration is clamped to it.
+GPU_MAX_S = 119
+
+# What the RE-CUT aims a segment at, in wall-clock seconds.
+#
+# BUDGET_S is not this. plan_gaps charges it against measure_rate, which times
+# one bare inference, so BUDGET_S = 60 means 60s of INFERENCE - about 88s of wall
+# time once decode, emit and x264 are added. The re-cut divides a wall-clock
+# measurement, so it needs a wall-clock budget or it silently re-plans every job
+# down by the overhead factor: want = gaps_per / 1.46, which trips the 0.8
+# deadband on the first segment of every GPU job and then settles there. That put
+# segments at 60s inside a 119s window and cost 1.46x more GPU runs than
+# intended, reported in the log as ordinary adaptive behaviour.
+#
+# 0.75 of the cap restores the planner's own intent (~88s) with 30s of headroom.
+# Safe because real_per_gap is a measurement of the segment that just ran, not
+# the 1.566x worst case that forced BUDGET_S to half the cap - and an overrun
+# still lands in the halve-and-retry path at the cost of one run.
+REAL_BUDGET_S = 0.75 * GPU_MAX_S if ZEROGPU else 900.0
+
+
+def note_queue(seconds: float) -> None:
+    """Fold one observed allocation wait into the running mean.
+
+    Bounded below at 0 because a clock skew or a cancelled segment can make the
+    subtraction negative, and above at 120 because anything larger is not a queue
+    - it is a stall the estimate should not learn from.
+    """
+    global GPU_QUEUE_S, _QUEUE_N
+    if not 0.0 <= seconds <= 120.0:
+        return
+    _QUEUE_N = min(_QUEUE_N + 1, 20)
+    GPU_QUEUE_S += (seconds - GPU_QUEUE_S) / _QUEUE_N
+
+
+def note_overhead(dev: str, ratio: float) -> None:
+    """Fold one full segment's measured/assumed ratio into the running mean."""
+    if not 0.2 < ratio < 20:                 # a cancelled or starved segment
+        return
+    n = _OVERHEAD_N[dev] = min(_OVERHEAD_N[dev] + 1, 40)
+    _OVERHEAD[dev] += (ratio - _OVERHEAD[dev]) / n
+
+
+# How far pixel-linear scaling may be trusted before the estimate stops being a
+# single number. It was 15% out at 852x480, which is fine, and 31x out at
+# 3840x2160, which is not. Two is deliberately conservative: past it, say a
+# range rather than a number nobody can stand behind.
+TRUST_RATIO = 2.0
+
+
+def _rate_for(h: int, w: int, dev: str | None = None
+              ) -> tuple[float, bool, float] | None:
+    """Per-frame rate at this size, whether it was measured AT this size, and how
+    far the answer had to be extrapolated (target pixels / measured pixels)."""
+    if dev is None:
+        dev = "gpu" if (ZEROGPU and not GPU_DEAD) else "cpu"
+    hit = _RATE_CACHE.get((h, w, dev))
+    if hit:
+        return hit[0], True, 1.0
+    # Fall back to pixel-scaling from the nearest measurement on the same device.
+    # That model was measured 15% out at 852x480, which is why it only ever feeds
+    # a rounded label carrying a "~", and never the segment planner.
+    same = [(hh, ww, v[0]) for (hh, ww, d), v in list(_RATE_CACHE.items())
+            if d == dev]
+    if not same:
+        # Cold container: _RATE_CACHE is empty until a job runs, and seeding it
+        # here would be a bug - gpu_rate/cpu_rate treat a present key as measured
+        # and would plan the whole job off an a-priori number. So fall back the
+        # way header() already does, without writing anything back. REF_RATE was
+        # measured at import on THIS container; GPU_REF_RATE_720P is the only
+        # a-priori constant in the estimate, and it is replaced the moment a real
+        # GPU rate lands.
+        same = [(720, 1280, GPU_REF_RATE_720P if dev == "gpu" else REF_RATE)]
+    hh, ww, r = min(same, key=lambda t: abs(t[0] * t[1] - h * w))
+    ratio = (h * w) / (hh * ww)
+    return r * ratio, False, ratio
+
+
+def eta(clip: R.Clip, factor: int, max_h: int) -> tuple[float, float] | None:
+    """Wall clock from click to result, as (likely, worst) seconds.
+
+    The log's `estimate` line has always been rate x frames, so it promised less
+    than the user waits: it left out the per-segment overhead the plan
+    under-charges, and the ZeroGPU allocation queue entirely.
+
+    The two numbers differ only where the rate had to be extrapolated well past
+    anything measured on this container. A 3840x2160 job was quoted 13 min and
+    ran 3.5 h: the label scaled the measured 720p GPU rate up by pixel count
+    while the job itself fell back to the CPU, whose 4K cost the planner had
+    right all along. Past TRUST_RATIO the CPU price is therefore the honest
+    upper bound.
+    """
+    tw, th = scale_for(clip, int(max_h))
+    dev = "gpu" if (ZEROGPU and not GPU_DEAD) else "cpu"
+    hit = _rate_for(th, tw, dev)
+    if hit is None:
+        return None
+    rate, _exact, ratio = hit
+
+    def total_for(r: float, d: str) -> float:
+        t = r * clip.frames * (int(factor) - 1) * _OVERHEAD[d]
+        if d == "gpu":
+            gaps_per = max(1, R.plan_gaps(clip, int(factor), r, BUDGET_S))
+            segs = max(1, -(-(clip.frames - 1) // gaps_per))
+            t += segs * GPU_ACQUIRE_S
+            if (th, tw, "gpu") not in _RATE_CACHE:
+                t += GPU_QUEUE_S      # the cold probe the user waits through
+        return t
+
+    likely = total_for(rate, dev)
+    if ratio <= TRUST_RATIO or dev != "gpu":
+        return likely, likely
+    slow = _rate_for(th, tw, "cpu")
+    worst = total_for(slow[0], "cpu") if slow else likely
+    return likely, max(likely, worst)
+
+
+_ETA_PROBE: dict[str, R.Clip] = {}
+
+
+def button_label(video, factor, max_h):
+    """Put the cost in the control that starts it, recomputed as inputs change.
+
+    Never raises into the UI and never blocks it: a probe failure or an unknown
+    rate just leaves the plain label, because a button that cannot be clicked is
+    worse than a button with no number on it.
+    """
+    if not video:
+        return gr.update(value="Interpolate")
+    try:
+        clip = _ETA_PROBE.get(video)
+        if clip is None:
+            if len(_ETA_PROBE) > 32:
+                _ETA_PROBE.clear()
+            clip = _ETA_PROBE[video] = R.probe(video)
+        pair = eta(clip, factor, max_h)
+    except Exception:                                        # noqa: BLE001
+        return gr.update(value="Interpolate")
+    if not pair or not pair[0]:
+        return gr.update(value="Interpolate")
+    likely, worst = pair
+    if worst > likely * 1.5:
+        # Never a lone "~13 min" for a size nothing was measured at. The spread
+        # IS the message: it says the height cap is the lever worth moving.
+        return gr.update(value=f"Interpolate ({plain(likely)} - {plain(worst)})")
+    return gr.update(value=f"Interpolate (~{plain(likely)})")
+
+
+def scale_for(clip: R.Clip, max_h: int) -> tuple[int, int]:
+    """Both dimensions are forced even unconditionally: yuv420p subsamples chroma
+    2x2 and x264 refuses an odd side, so a 1920x1038 or phone-cropped source used
+    to die on the first frame written even though nothing else about it was hard."""
+    if max_h <= 0 or clip.height <= max_h:
+        return clip.width // 2 * 2, clip.height // 2 * 2
+    w = int(round(clip.width * max_h / clip.height)) // 2 * 2
+    return w, max_h // 2 * 2
+
+
+def run(video: str, factor: int, max_h: int, crf: float,
+        request: gr.Request, progress=gr.Progress()):
+    """Interpolate a video to a higher frame rate with RIFE.
+
+    Args:
+        video: Path to the source clip. Any container ffmpeg can read.
+        factor: Frame rate multiplier, 2 doubles the frame rate and 4 quadruples it.
+        max_h: Cap the output height, 0 keeps the source resolution. Lowering this is
+            the single biggest lever on runtime, since cost scales with pixels.
+        crf: x264 quality, lower is better and larger. 18 is visually lossless.
+    """
+    global OWNER, GPU_DEAD
+    log = Log()
+    me = getattr(request, "session_hash", None) or f"anon-{uuid.uuid4()}"
+    if not LOCK.acquire(blocking=False):
+        raise gr.Error("A job is already running. Two vCPUs, one job. "
+                       "Press Stop to cancel it.")
+    CANCELLED.discard(me)
+    OWNER = me
+    closing = False
+    stopped = ""                     # why the run ended early, if it did
+    out_path = None
+    parts: list[str] = []
+    work = None
+    try:
+        # Before the mkdtemp, because mkdtemp is the first thing that fails on a
+        # full disk. Inside the try, not before it: failing between acquire() and
+        # try: held the lock with nothing to release it, wedging every later job.
+        sweep_outputs(protect=video)
+        work = tempfile.mkdtemp(prefix="ff_", dir=str(SCRATCH))
+        clip = R.probe(video)
+        tw, th = scale_for(clip, int(max_h))
+        src = video
+
+        yield None, log(f"source {clip.width}x{clip.height} {clip.fps:.2f}fps "
+                        f"{clip.frames} frames {clip.duration:.1f}s"), *BUSY
+
+        if (tw, th) != (clip.width, clip.height):
+            yield None, log(f"scaling to {tw}x{th} inside each segment decoder, "
+                            f"no pre-transcode"), *BUSY
+
+        # Estimate from a measured rate at this resolution, before committing.
+        # Start from what the last job learned: a cached GPU rate never raises,
+        # so an optimistic retry costs a failed segment and a re-plan per job.
+        gpu_dead = GPU_DEAD
+        if ZEROGPU:
+            try:
+                rate, be_name, build_s = gpu_rate(th, tw)
+                # Clear what the LAST job learned. Without this, GPU_DEAD from an
+                # earlier quota-out job survived a successful probe: gpu_rate
+                # returned a GPU rate and name, the header and the estimate
+                # quoted them, and then every segment ran on _segment_cpu because
+                # gpu_dead was still True. Seen live on 2026-09-06 - "GPU CUDA:
+                # 0.053s/frame ... estimate 0:09" against a measured 57.4s, with
+                # the plan-check line labelling its own segment "cpu".
+                #
+                # The comment above this block already described the intended
+                # behaviour ("an optimistic retry costs a failed segment and a
+                # re-plan per job"); the retry just never happened. A cached rate
+                # does not re-prove the quota, so this is deliberately
+                # optimistic: the segment loop catches the quota error, sets the
+                # flag and re-cuts the rest for CPU. One failed segment is the
+                # price of not pinning the Space to CPU until it restarts, and it
+                # keeps the one invariant that matters - the rate that plans the
+                # job is the rate of the device that runs it.
+                gpu_dead = GPU_DEAD = False
+            except Exception as e:                           # noqa: BLE001
+                if not (is_quota_error(e) or is_timeout_error(e)):
+                    raise
+                gpu_dead = GPU_DEAD = True
+                # str(e), not type(e).__name__: ZeroGPU raises gradio's own
+                # Error, so the class name rendered as the literal "no usable
+                # GPU (Error)" - true, and carrying none of the quota message
+                # that tells the user when the GPU comes back.
+                why = " ".join(str(e).split())[:110] or type(e).__name__
+                yield None, log(f"no usable GPU ({why}), "
+                                f"running on CPU"), *BUSY
+                rate, be_name, build_s = cpu_rate(th, tw)
+        else:
+            rate, be_name, build_s = cpu_rate(th, tw)
+        new_frames = clip.frames * (int(factor) - 1)
+        est = rate * new_frames
+        if build_s > 1:
+            yield None, log(f"{be_name} session built in {build_s:.0f}s"), *BUSY
+        yield None, log(f"{be_name}: {rate:.3f}s/frame here, "
+                        f"{new_frames} frames to generate, estimate {hms(est)}"), *BUSY
+
+        if est > 6 * 3600:
+            # BACKEND is always the CPU session, built at import with
+            # prefer_gpu=False, so testing BACKEND.on_gpu here named the CPU
+            # ceiling on GPU hardware every time. Ask the flag that knows.
+            fits = int(clip.duration * (6 * 3600) / est)
+            raise gr.Error(
+                f"Estimated {hms(est)} at {tw}x{th}, past the 6 hour ceiling"
+                f"{' and well past a ZeroGPU day' if ZEROGPU else ''}. "
+                f"Lower 'Max height' to {min(720, max(240, th // 2))}, which is "
+                f"about 4x faster, or trim the clip to under "
+                f"{hms(max(1, fits))} at this size.")
+
+        # Plan segment 0 from a MEASUREMENT when this container has already run
+        # this shape on this device. plan_gaps charges BUDGET_S against a bare
+        # inference rate, so it deliberately mis-sizes the first segment and the
+        # re-cut then fires once to correct it - on every repeat job, forever.
+        #
+        # It also mis-states the plan LENGTH, and `len(plan) > 30` below is what
+        # gates the "you will run out of ZeroGPU quota, lower your resolution"
+        # warning. At a clean overhead of 1.26 a job that really needs 30 calls
+        # was announced as 35, so the user was told to halve their height for a
+        # limit they were not going to hit.
+        dev0 = "cpu" if gpu_dead else "gpu"
+        seen0 = _PER_GAP.get((th, tw, int(factor), dev0))
+        if seen0:
+            gaps_per = max(1, int(REAL_BUDGET_S / seen0))
+            budget_note = f"{REAL_BUDGET_S:.0f}s measured budget"
+        else:
+            # Charge the overhead here too. plan_gaps bills against measure_rate,
+            # which times bare inference, so BUDGET_S seconds of inference is
+            # BUDGET_S * overhead of WALL time - and the cap is on wall time.
+            #
+            # That gap widened when the model got five times faster: ffmpeg did
+            # not, so the ratio went 1.46 -> 1.85 and the same BUDGET_S = 60 went
+            # from 87.6s (74% of the 119s cap, the intent) to 111.0s (93%). The
+            # first segment of every job was being planned with 7% headroom, and
+            # the re-cut that would fix it only runs AFTER that segment lands.
+            #
+            # Billing rate * overhead against REAL_BUDGET_S puts the first
+            # segment on the same 75%-of-cap target the re-cut aims for, and it
+            # stays correct automatically as the ratio moves.
+            gaps_per = R.plan_gaps(clip, int(factor), rate * _OVERHEAD[dev0],
+                                   REAL_BUDGET_S)
+            budget_note = f"{REAL_BUDGET_S:.0f}s wall budget"
+        plan = R.segment_bounds(clip, gaps_per)
+        total_gaps = max(1, clip.frames - 1)
+        yield None, log(f"{len(plan)} segment(s) of up to {gaps_per} gaps "
+                        f"({gaps_per / clip.fps:.1f}s), inside the "
+                        f"{budget_note}"), *BUSY
+
+        # On ZeroGPU each segment is a separate allocation and the daily budget
+        # is counted in RUNS, so segment count - not estimated hours - is what
+        # decides whether a job can finish on the GPU. The 6 hour ceiling above
+        # is checked against the GPU estimate, so a 4K five minute clip at source
+        # resolution sails through it at ~2.8h and then needs ~165 allocations:
+        # quota dies partway, the CPU fallback takes over at roughly 6 s/frame,
+        # and the user who was shown "2:45" is waiting most of a day. Say so
+        # before any of it starts, with the number, rather than letting them find
+        # out hours in.
+        if ZEROGPU and not gpu_dead and len(plan) > 30:
+            # The remedy has to be an action the user can actually take. A
+            # suggestion to cap height at the height they are already using is
+            # not advice, and 240 is the floor of the dropdown - below that the
+            # only lever left is a shorter clip. Cost scales with pixels, so
+            # halving the height is ~4x fewer calls; say the number either way.
+            lower = next_lower_height(th)
+            if lower:
+                # Cost scales with pixels, so the saving is the area ratio.
+                saved = max(1, int(len(plan) * (lower / th) ** 2))
+                remedy = (f"Capping 'Max height' at {lower} (from {th}) would "
+                          f"cut it to about {saved} calls.")
+            else:
+                fits = clip.duration * 30 / len(plan)
+                # Reached when no offered cap is BELOW the current height -
+                # either it is already the lowest option, or the source is
+                # smaller than every option. Saying "the control's lowest" would
+                # be wrong in the second case, so say what is true in both.
+                remedy = (f"no lower cap is available for a {th}p source, so the "
+                          f"lever left is length: about "
+                          f"{hms(max(1, int(fits)))} of this clip fits in "
+                          f"30 calls.")
+            yield None, log(
+                f"heads up: {len(plan)} GPU calls needed, and ZeroGPU meters a "
+                f"daily number of them. This will likely run out partway and "
+                f"finish on CPU, which is far slower. " + remedy), *BUSY
+
+        done = 0
+        cursor = 0                       # gaps already rendered
+        i = 0
+        shrinks = 0                      # GPU-window overruns absorbed so far
+        while cursor < total_gaps:
+            if me in CANCELLED:
+                # Set `stopped` like every other early exit. Without it the
+                # summary read "done: 121 frames" on a job that expected 599 -
+                # the word done, and a number with nothing to compare it to.
+                # Cancel is the most frequently taken of the early exits and was
+                # the only one not marking the result partial.
+                stopped = "cancelled at your request"
+                yield None, log("cancelled, keeping what finished"), *BUSY
+                break
+            if i >= len(plan):
+                # Never silent. cursor advancing without a segment to consume it
+                # is a planner bug, and the two guards below cover the ways it
+                # has actually happened; this catches any third.
+                stopped = (f"the plan ran out at {cursor} of {total_gaps} gaps")
+                yield None, log(f"stopped early: {stopped}"), *BUSY
+                break
+            t0, gaps, is_last = plan[i]
+            part = os.path.join(work, f"seg{i:04d}.mp4")
+            t_seg = time.perf_counter()
+            try:
+                worker_fn = _segment_cpu if gpu_dead else _segment_gpu
+                n, inside = worker_fn(src, part, t0, gaps, int(factor), clip,
+                                      int(crf), is_last, me, tw, th)
+            except Exception as e:                           # noqa: BLE001
+                # ZEROGPU gates this: only there is there a window to overrun,
+                # and TIMEOUT_HINTS is broad enough to match ordinary ffmpeg
+                # errors that retrying cannot help.
+                overran = ZEROGPU and not gpu_dead and is_timeout_error(e)
+                if overran and shrinks < 4 and gaps_per > 1:
+                    # The segment was too big for its GPU window, not the day's
+                    # budget. measure_rate times one bare inference while a real
+                    # segment also runs factor-1 encodes and emits per gap, and
+                    # at 4x that overhead is where a 90 s plan meets a 120 s cap.
+                    # Halve and retry the same range rather than abandoning the
+                    # GPU for the rest of the job.
+                    shrinks += 1
+                    gaps_per = max(1, gaps_per // 2)
+                    plan = plan[:i] + R.segment_bounds(clip, gaps_per, cursor)
+                    yield None, log(f"segment overran its GPU window, re-cut to "
+                                    f"{gaps_per} gaps and retrying "
+                                    f"({len(plan) - i} segments left)"), *BUSY
+                    continue
+                if gpu_dead or not (overran or is_quota_error(e)):
+                    raise
+                # Two ways to get here. Quota exhausted, or a single gap that
+                # cannot fit the GPU window even after shrinking - which used to
+                # kill the job outright, the one case where the GPU truly cannot
+                # proceed being the one case that refused the existing fallback.
+                why = ("one gap will not fit the GPU window" if overran
+                       else "ZeroGPU quota exhausted")
+                #
+                # Re-cutting the remainder is the part that matters. These
+                # segments were sized from a GPU rate, so one of them is roughly
+                # six times more work than the CPU budget allows: a segment
+                # yields once, at the end, so an over-sized one freezes progress,
+                # gives Stop that much latency, and stops the seams being
+                # checkpoints at all. Caching the GPU rate made this the common
+                # path, because a cached rate never raises the quota error that
+                # used to be caught before any planning happened.
+                gpu_dead = GPU_DEAD = True
+                rate, be_name, _ = cpu_rate(th, tw)
+                gaps_per = R.plan_gaps(clip, int(factor), rate, BUDGET_S)
+                plan = plan[:i] + R.segment_bounds(clip, gaps_per, cursor)
+                left = rate * (total_gaps - cursor) * max(1, int(factor) - 1)
+                yield None, log(f"{why}. Finishing on {be_name} at "
+                                f"{rate:.3f}s/frame: re-cut the rest into "
+                                f"{len(plan) - i} segments, about {hms(left)} to "
+                                f"go. Frames so far are kept."), *BUSY
+                continue
+            # plan_gaps budgets rate*(factor-1) per gap from measure_rate, which
+            # times one bare inference. A real segment also runs `factor` emit
+            # passes and `factor` x264 frames per gap. That overhead is roughly
+            # fixed per gap while the inference term scales with the device, so
+            # the plan under-charges least on CPU and most on a fast GPU - which
+            # is exactly where the 120 s cap lives. Logged rather than guessed,
+            # so any real job on any device reports its own correction factor.
+            took = time.perf_counter() - t_seg      # wall, includes the queue
+            spent = inside                          # what the work actually cost
+            assumed = gaps * rate * max(1, int(factor) - 1)
+            if assumed > 0:
+                # Only a segment that rendered its whole assignment describes the
+                # overhead. A cancelled or starved one returns early and logs
+                # ratios like 0.399x, which would drag the mean toward nonsense.
+                if n // max(1, int(factor)) >= gaps:
+                    note_overhead("gpu" if (ZEROGPU and not gpu_dead) else "cpu",
+                                  spent / assumed)
+                    if ZEROGPU and not gpu_dead:
+                        note_queue(took - spent)
+                    if gaps > 0:
+                        _PER_GAP[(th, tw, int(factor),
+                                  "cpu" if gpu_dead else "gpu")] = spent / gaps
+                print(f"[ff] plan-check seg{i} {gaps} gaps f{factor} {tw}x{th} "
+                      f"{'gpu' if (ZEROGPU and not gpu_dead) else 'cpu'}: "
+                      f"assumed {assumed:.2f}s "
+                      f"measured {spent:.2f}s ratio {spent / assumed:.3f}x "
+                      f"(wall {took:.2f}s, queue {took - spent:.2f}s)",
+                      flush=True)
+            if not gpu_dead:
+                GPU_DEAD = False          # a GPU segment landed, quota is back
+            if n:                         # a cancelled segment writes no file
+                parts.append(part)
+            done += n
+            # A segment cancelled part-way returns fewer frames than its gap
+            # assignment. Crediting the whole assignment made the last line of a
+            # cancelled job overstate progress: 60 of 179 gaps reported against
+            # 156 frames, which at 4x is 39 gaps of real work. Each gap writes
+            # `factor` frames, so the frames are the honest count.
+            got_gaps = min(gaps, n // max(1, int(factor)))
+            cursor += got_gaps
+            i += 1
+            if got_gaps < gaps and me not in CANCELLED:
+                # The decoder handed back fewer frames than this segment covers,
+                # and nobody cancelled: the source is shorter than its header
+                # claims. On CPU nothing re-cuts the plan, so cursor stopped
+                # short of total_gaps while i walked past the last entry, and the
+                # next pass raised "IndexError: list index out of range" - which
+                # is what the live Space showed for a truncated upload while this
+                # machine's ffmpeg raised the clean starved-decoder error before
+                # ever reaching here. Same file, two decoders, one path untested.
+                stopped = (f"source ended early: this segment covers {gaps} gaps "
+                           f"but the decoder supplied {got_gaps}. The file is "
+                           f"probably truncated or corrupt - its header claims "
+                           f"{clip.frames} frames.")
+                yield None, log(f"stopped early: {stopped}"), *BUSY
+                break
+
+            # Re-cut from what this segment ACTUALLY cost, not from a constant.
+            # The plan charges only inference, so it is optimistic by a fixed
+            # per-gap amount that is a bigger fraction the faster the device is -
+            # measured 1.456x at 852x480 on the GPU against 1.03x on CPU. That
+            # ratio cannot be bounded ahead of time: a smaller frame makes
+            # inference cheaper without making ffmpeg cheaper, so it climbs as
+            # resolution drops, and four measurements were neither constant nor
+            # pixel-linear. So do not model it - measure it here and shrink the
+            # rest of the plan if the segment that just ran says the next one
+            # would not fit the window. Costs nothing when the plan is right.
+            # Every device, not just the GPU. The gate used to read
+            # `ZEROGPU and not gpu_dead`, on the reasoning that only a GPU has a
+            # window to overrun - but a segment 5x its plan is a problem on any
+            # device, because a segment yields once at the END. A 2290x1708 job
+            # planned at 59s a segment took 318s and showed the user a frozen log
+            # for 5m18s with no progress line, no ETA and 5 minutes of Stop
+            # latency (2026-09-06). The 120 s cap is why the GPU MUST re-cut; the
+            # seams being checkpoints at all is why everything else should.
+            #
+            # Cheap when the plan is right: the measured CPU under-charge is
+            # 1.05-1.23x, which lands inside the 20% deadband and re-cuts nothing.
+            if gaps > 0 and cursor < total_gaps:
+                real_per_gap = spent / gaps
+                # Both directions. Shrinking keeps a segment inside the window;
+                # growing refunds a conservative BUDGET_S when the plan turns out
+                # pessimistic, so starting safe does not cost a GPU run per
+                # segment for the whole job. real_per_gap already contains the
+                # under-charge, so this is a measurement and not a correction
+                # factor. The 20% deadband stops one noisy segment churning the
+                # plan, and BUDGET_S sits at half the hard cap, so even a segment
+                # twice as slow as the one just measured still lands inside it.
+                want = max(1, int(REAL_BUDGET_S / real_per_gap))
+                if want < gaps_per * 0.8 or want > gaps_per * 1.25:
+                    grew = want > gaps_per
+                    gaps_per = want
+                    plan = plan[:i] + R.segment_bounds(clip, gaps_per, cursor)
+                    yield None, log(f"segment cost {real_per_gap:.3f}s/gap against "
+                                    f"{rate * max(1, int(factor) - 1):.3f}s planned; "
+                                    f"{'widened' if grew else 're-cut'} the rest into "
+                                    f"{len(plan) - i} segments"), *BUSY
+            progress(cursor / total_gaps, desc=f"{cursor}/{total_gaps} gaps")
+            yield None, log(f"[{cursor}/{total_gaps} gaps] {n} frames, "
+                            f"{done} total"), *BUSY
+    except GeneratorExit:
+        # Tab closed or SSE torn down. Yielding from finally here would raise
+        # "generator ignored GeneratorExit" and block teardown while ffmpeg muxes.
+        closing = True
+        CANCELLED.add(me)
+        raise
+    except gr.Error as e:
+        # Mirror the generic handler below. This clause exists so a validation
+        # error raised BEFORE any work reaches the user as a clean toast, and
+        # with no parts that is still exactly what happens. But ZeroGPU itself
+        # raises gr.Error, so a mid-job GPU failure whose text matches neither
+        # QUOTA_HINTS nor TIMEOUT_HINTS lands here with segments already on disk:
+        # the finally delivered them labelled "done", for a job that produced a
+        # fraction of its frames, with the log replaced by an Error badge.
+        if not parts:
+            raise
+        stopped = f"{type(e).__name__}: {e}"
+        yield None, log(f"stopped early: {stopped}"), *IDLE
+    except Exception as e:                                   # noqa: BLE001
+        if parts:
+            # Segments landed, so there IS a result. Raising here would hand
+            # Gradio an errored generator, and verified in Chrome on 2026-09-06
+            # against truncated.mp4 that means: the video the finally yields
+            # survives and stays downloadable, but the log component is replaced
+            # by a bare "Error" badge. The user gets a silently truncated clip
+            # with the one line explaining it wiped off the screen. Record the
+            # reason and let the finally deliver both.
+            stopped = f"{type(e).__name__}: {e}"
+            yield None, log(f"stopped early: {stopped}"), *IDLE
+        else:
+            yield None, log(f"failed: {type(e).__name__}: {e}"), *IDLE
+            raise
+    finally:
+        # Package from finally so cancel, error and success all hand back the
+        # frames that were actually produced. The flag is re-derived here because
+        # a GeneratorExit raised at the yield inside `except Exception` is a
+        # sibling of the GeneratorExit handler and never reaches it.
+        closing = closing or sys.exc_info()[0] is GeneratorExit
+        try:
+            if closing:
+                # Do not YIELD - that raises "generator ignored GeneratorExit"
+                # and blocks teardown. But keeping is a separate decision from
+                # yielding, and the inner finally is about to rmtree `work` with
+                # every finished segment inside it. Concat into OUTDIR so the
+                # result survives the cleanup and is recoverable from the log,
+                # instead of a dropped SSE costing a 40 minute job outright.
+                if parts:
+                    try:
+                        fd, sv = tempfile.mkstemp(suffix=".mp4", dir=str(OUTDIR))
+                        os.close(fd)
+                        R.concat(parts, sv)
+                        print(f"[ff] stream closed mid-job; kept {len(parts)} "
+                              f"segments at {sv}", flush=True)
+                    except Exception as e:                   # noqa: BLE001
+                        # Best effort on a path that is already unwinding.
+                        print(f"[ff] stream closed mid-job and the salvage "
+                              f"failed: {type(e).__name__}: {e}", flush=True)
+            elif parts:
+                # Guarded for the same reason the probe below is: describing OR
+                # packaging the result must never be able to discard it. A raise
+                # from concat, mkstemp or the copy escapes this finally so
+                # nothing is yielded, REPLACES the exception already in flight -
+                # overwriting a segment failure already recorded in `stopped` -
+                # and still reaches the inner finally that deletes `work`. The
+                # parts would be destroyed by cleanup for a delivery that never
+                # happened. Falling back to the largest single segment keeps most
+                # of the job rather than none of it.
+                out_path = None
+                try:
+                    joined = os.path.join(work, "joined.mp4")
+                    R.concat(parts, joined)
+                    fd, out_path = tempfile.mkstemp(suffix=".mp4", dir=str(OUTDIR))
+                    os.close(fd)
+                    if not R.mux_audio(joined, video, out_path):
+                        shutil.copy(joined, out_path)
+                except Exception as e:                       # noqa: BLE001
+                    stopped = stopped or f"{type(e).__name__}: {e}"
+                    big = max(parts, key=lambda p: os.path.getsize(p)
+                              if os.path.exists(p) else 0)
+                    try:
+                        fd, out_path = tempfile.mkstemp(suffix=".mp4",
+                                                        dir=str(OUTDIR))
+                        os.close(fd)
+                        shutil.copy(big, out_path)
+                        log(f"could not join the segments ({e}); handing back the "
+                            f"longest one instead")
+                    except Exception:                        # noqa: BLE001
+                        out_path = None
+                if out_path is None:
+                    # No `return` here: a return inside a finally DISCARDS an
+                    # exception that is still propagating. An else instead, so
+                    # the summary below cannot run on a None path and probe it.
+                    yield None, log("the frames were rendered but could not be "
+                                    "packaged; nothing to hand back"), *IDLE
+                else:
+                    # Describing the result must never be able to discard it.
+                    # probe raises when it cannot establish a frame count, and
+                    # this call happens after the work is finished and written.
+                    head = "partial" if stopped else "done"
+                    try:
+                        got = R.probe(out_path)
+                        summary = (f"{head}: {got.width}x{got.height} "
+                                   f"{got.fps:.2f}fps {got.frames} frames")
+                        if stopped:
+                            summary += (f" of the "
+                                        f"{(clip.frames - 1) * int(factor) + 1} "
+                                        f"expected - the download below is the "
+                                        f"part that finished")
+                    except Exception as e:                   # noqa: BLE001
+                        summary = (f"{head}, {done} frames written "
+                                   f"({type(e).__name__})")
+                    yield out_path, log(summary), *IDLE
+            else:
+                yield None, log("no frames produced"), *IDLE
+        finally:
+            if work:
+                shutil.rmtree(work, ignore_errors=True)
+            OWNER = None
+            LOCK.release()
+
+
+BUSY = (gr.update(visible=False), gr.update(visible=True))
+IDLE = (gr.update(visible=True), gr.update(visible=False))
+
+CSS = """
+footer{display:none}
+.gradio-container{padding:4px !important;max-width:100% !important}
+.form{gap:2px !important}
+#hdr{max-height:34px}
+#hdr p{margin:0 !important;font-size:.82em;opacity:.75}
+#log textarea{font-family:ui-monospace,monospace;font-size:.78em}
+#vid video{max-height:190px}
+:where(button,input,textarea,select,[role="button"],[tabindex]):focus-visible{
+  outline:2px solid var(--color-accent) !important;outline-offset:2px}
+@media (prefers-reduced-motion:reduce){*,*::before,*::after{
+  animation-duration:.01ms !important;transition-duration:.01ms !important}}
+"""
+
+with gr.Blocks(title="Flowframes", fill_width=True) as demo:
+    hdr = gr.Markdown(header(), elem_id="hdr")
+    with gr.Row():
+        with gr.Column(scale=4):
+            vid = gr.Video(label="Source clip", elem_id="vid", height=190)
+            go = gr.Button("Interpolate", variant="primary")
+            halt = gr.Button("Stop", variant="stop", visible=False)
+            # label with show_label=False: hidden visually, still the control's
+            # accessible name. Without it this is the one element on the page a
+            # screen reader announces as just "Textbox", and it is the element
+            # carrying every progress line, the ETA and every error message.
+            status = gr.Textbox(lines=8, max_lines=LOG_LINES + 2, autoscroll=True,
+                                label="Progress log", show_label=False,
+                                container=False, elem_id="log")
+        with gr.Column(scale=2):
+            factor = gr.Radio([2, 4], value=2, label="Frame rate multiplier",
+                              info="4x generates three frames per gap, so it costs "
+                                   "three times 2x.")
+            max_h = gr.Dropdown(
+                [("Keep source resolution", 0)]
+                + [(f"Cap at {h}p" + (" (fastest)" if h == 720 else ""), h)
+                   for h in HEIGHTS],
+                value=720, label="Max height",
+                info="Cost scales with pixels. Halving height is roughly 4x faster.")
+            with gr.Accordion("Advanced", open=False):
+                crf = gr.Slider(12, 28, value=18, step=1, label="x264 CRF",
+                                info="Lower is better quality and a larger file.")
+        with gr.Column(scale=4):
+            out = gr.Video(label="Result", height=190, interactive=False)
+            dl = gr.DownloadButton("Download result", size="sm", interactive=False)
+
+    # Registered before the work handler and outside the queue, so the swap lands
+    # immediately rather than waiting behind a job that may run for hours.
+    # Validation lives in the swap handler, so a rejected click never swaps the
+    # buttons. Raising after the swap stranded the UI showing Stop forever.
+    # The trailing .then restores the buttons on paths that never reach run()'s
+    # final yield: the lock-busy gr.Error is raised before the try, so the swap
+    # that preflight already made would otherwise leave the page showing Stop
+    # forever. .then runs on failure too, which .success would not.
+    go.click(preflight, inputs=[vid], outputs=[go, halt], queue=False).then(
+        run, [vid, factor, max_h, crf], [out, status, go, halt]).then(
+        lambda: IDLE, outputs=[go, halt], queue=False)
+    out.change(lambda v: gr.update(value=v, interactive=v is not None),
+               inputs=out, outputs=dl, queue=False)
+    # queue=False so the label never waits behind a running job, which under
+    # concurrency_limit=1 would mean the number arrives after the work finishes.
+    for _c in (vid, factor, max_h):
+        _c.change(button_label, [vid, factor, max_h], [go], queue=False)
+    halt.click(stop, outputs=status, queue=False)
+    # Recomputed per page load, so the first real job replaces the reference
+    # estimate with the rate measured on the hardware actually serving this Space.
+    demo.load(header, outputs=[hdr], queue=False)
+
+    ex = HERE / "examples" / "sample.mp4"
+    if ex.exists():
+        # Cached so the first visitor is not asked to supply a video before they
+        # can see anything work. Lazy, not eager: eager runs the whole pipeline
+        # before the Space serves its first request, and on ZeroGPU that would
+        # also spend quota on every rebuild. Cached after the first click, then
+        # instant for everyone.
+        gr.Examples(examples=[[str(ex), 2, 480, 20]],
+                    inputs=[vid, factor, max_h, crf],
+                    outputs=[out, status],
+                    fn=example_run,
+                    cache_examples=True, cache_mode="lazy",
+                    label="Example (cached after first run)")
+
+if __name__ == "__main__":
+    demo.queue(max_size=4, default_concurrency_limit=1).launch(css=CSS, show_error=True)

cli.py

@@ -0,0 +1,52 @@
+"""Headless end-to-end check. Runs before app.py exists, and keeps working after."""
+import argparse, pathlib, sys, time
+sys.path.insert(0, str(pathlib.Path(__file__).parent))
+import rife_core as R
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("src")
+    ap.add_argument("-o", "--out", default="out.mp4")
+    ap.add_argument("-x", "--factor", type=int, default=2)
+    ap.add_argument("--budget", type=float, default=100.0, help="seconds per segment")
+    a = ap.parse_args()
+
+    clip = R.probe(a.src)
+    print(f"[probe]  {clip.width}x{clip.height} {clip.fps:.3f}fps "
+          f"{clip.frames} frames {clip.duration:.2f}s")
+
+    be = R.OnnxBackend()
+    print(f"[backend] {be.name}, {R.CPUS} threads")
+    rate = R.measure_rate(be, clip.height, clip.width)
+    new_frames = clip.frames * (a.factor - 1)
+    print(f"[rate]   {rate:.3f} s/frame -> est {rate*new_frames:.1f}s "
+          f"for {new_frames} generated frames")
+
+    seg_s = R.plan_segments(clip, a.factor, rate, a.budget)
+    nseg = max(1, int(clip.duration / seg_s + 0.999))
+    print(f"[plan]   {nseg} segment(s) of {seg_s:.2f}s")
+
+    parts, t0 = [], time.time()
+    tmpdir = pathlib.Path(a.out).parent / "_segs"
+    tmpdir.mkdir(exist_ok=True)
+    total = 0
+    for i in range(nseg):
+        p = str(tmpdir / f"seg{i:04d}.mp4")
+        n = R.interpolate_segment(a.src, p, i * seg_s, seg_s, a.factor, be, clip)
+        total += n
+        parts.append(p)
+        print(f"[+{time.time()-t0:6.1f}s] [{i+1}/{nseg}] {n} frames -> {pathlib.Path(p).name}")
+    R.concat(parts, a.out)
+    print(f"[done]   {total} frames in {time.time()-t0:.1f}s -> {a.out}")
+
+    got = R.probe(a.out)
+    print(f"[verify] {got.width}x{got.height} {got.fps:.3f}fps {got.frames} frames "
+          f"{got.duration:.2f}s")
+    ok = abs(got.fps - clip.fps * a.factor) < 0.5 and got.frames >= clip.frames * a.factor * 0.8
+    print(f"[verify] fps x{a.factor} and frame count plausible: {ok}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

examples/sample.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4d612ca50fbac3481c7b03bddc5b9789e9458923f748787cef509a0ee0bd04c7
+size 2971056

models/rife49.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d42a41188d5c23291f18295da726671423d245b674ef086661c9ab2b0921e5dd
+size 21459539

requirements.txt

@@ -0,0 +1,8 @@
+gradio
+numpy
+spaces
+# The cu12 nvidia pins that used to live here were the bug, not the fix: they
+# forced pip to resolve an older CUDA-12 build of onnxruntime-gpu, which then
+# reported "Require cuDNN 9.* and CUDA 12.*" against an image where torch 2.11
+# ships cu13. The extras pull the matching CUDA 13 runtime instead.
+onnxruntime-gpu[cuda,cudnn]

rife_core.py

@@ -0,0 +1,999 @@
+"""Streaming RIFE frame interpolation.
+
+Two frames are resident at a time, never the clip. ffmpeg decodes raw RGB into a
+pipe, each consecutive pair is interpolated, and the results go straight out to a
+second ffmpeg encoding a segment. Memory is therefore O(1) in clip length, so a
+5 minute 4K source costs time and nothing else.
+
+Work is always cut into segments. On ZeroGPU that keeps each GPU call inside its
+duration budget; on CPU the same seams act as checkpoints, so a cancel keeps the
+minutes already spent. Segment length is derived from a measured per-frame rate
+rather than a guess.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import json
+import os
+import pathlib
+import queue
+import shutil
+import statistics
+import subprocess
+import threading
+import tempfile
+import time
+from dataclasses import dataclass
+from typing import Callable
+
+import numpy as np
+
+HERE = pathlib.Path(__file__).parent
+MODEL = HERE / "models" / "rife49.onnx"
+# fp16 IS NOT USED, ON EITHER PATH, AND THE SELECTION CODE IS GONE ON PURPOSE.
+# Converting to fp16 and running it on the CUDA EP was predicted at ~1.8x faster
+# and came out 3.6x SLOWER, A/B'd inside a single GPU allocation on the same
+# container: fp16 0.1096 s/frame vs fp32 0.0306 s/frame. keep_io_types inserts
+# Cast nodes throughout, and GridSample/Resize appear to have no fp16 CUDA
+# kernel, so the graph thrashes between precisions. The cosine gate PASSED at
+# 0.99994549, so quality checks alone would have shipped the regression.
+# On CPU it is a trap for a different reason: those cores have no half ALU, so
+# every op promotes back to fp32 and you pay the conversion on top.
+# This used to be a path guarded by a filename that deliberately did not exist,
+# which is a disable that a later tidy-up "fixes" by accident. Re-adding it means
+# re-running that A/B first.
+ALIGN = 32          # RIFE downsamples 5 times; both dims must be a multiple of 32
+FFMPEG = shutil.which("ffmpeg") or "ffmpeg"
+FFPROBE = shutil.which("ffprobe") or "ffprobe"
+
+
+# Set False by container_cpus() when every cgroup read fails, meaning the count
+# is the HOST's and only a guess at this container's allowance.
+CPUS_TRUSTED = True
+
+
+def cgroup_report() -> str:
+    """What the cgroup actually says, for the startup line.
+
+    `container_cpus` returning 12 is ambiguous on its own: it means either the
+    container really may use 12, or every cgroup read failed and it fell back to
+    the host's count clamped by THREAD_CAP. Those are opposite situations and
+    only one of them is a bug, so print the raw values.
+    """
+    bits = []
+    for path in ("/sys/fs/cgroup/cpu.max",
+                 "/sys/fs/cgroup/cpu/cpu.cfs_quota_us",
+                 "/sys/fs/cgroup/cpu/cpu.cfs_period_us",
+                 os.environ.get("ZEROGPU_PROC_SELF_CGROUP_PATH", "")):
+        if not path:
+            continue
+        try:
+            bits.append(f"{path}={pathlib.Path(path).read_text().strip()[:40]}")
+        except Exception as e:                                   # noqa: BLE001
+            bits.append(f"{path}=<{type(e).__name__}>")
+    bits.append(f"os.cpu_count()={os.cpu_count()}")
+    return " ".join(bits)
+
+
+def container_cpus(default: int = 2) -> int:
+    """CPUs this container may actually use. os.cpu_count() reports the host, so
+    on a Spaces box it over-reports badly and ORT would spawn threads that only
+    fight each other for the two vCPUs the container is allowed."""
+    for quota_p, period_p in (("/sys/fs/cgroup/cpu.max", None),
+                              ("/sys/fs/cgroup/cpu/cpu.cfs_quota_us",
+                               "/sys/fs/cgroup/cpu/cpu.cfs_period_us")):
+        try:
+            raw = pathlib.Path(quota_p).read_text().split()
+            quota = raw[0]
+            period = raw[1] if period_p is None else pathlib.Path(period_p).read_text().strip()
+            if quota != "max" and int(quota) > 0:
+                return max(1, int(quota) // int(period))
+        except Exception:
+            continue
+    # Reached only when no cgroup file answered. That is the case this function
+    # exists to catch, so say so rather than silently returning the host count:
+    # ZeroGPU sets ZEROGPU_PROC_SELF_CGROUP_PATH, which hints the cgroup is not
+    # where this looks, and an over-reported count means ORT spawns threads that
+    # only fight each other.
+    global CPUS_TRUSTED
+    CPUS_TRUSTED = False
+    n = max(1, os.cpu_count() or default)
+    print(f"[rife] cgroup cpu quota unreadable, falling back to os.cpu_count()"
+          f"={n}; if this container is smaller than that, threads are "
+          f"oversubscribed", flush=True)
+    return n
+
+
+# Measured sweep at 720p: this graph scales to about 12 threads and then falls
+# apart, 32 threads being 4.3x slower than 12. A Space gets 2 vCPUs so the cgroup
+# read decides it there; the cap only stops a fat host oversubscribing.
+# Two different jobs, previously conflated into one cap of 12.
+#
+# When the cgroup answers, it states this container's real allowance and should
+# be believed: ZeroGPU reports 16, and measured in one boot at 720p, 16 threads
+# run 0.637 s/frame against 12 threads' 0.790 - 19% faster. The old cap of 12
+# came from a sweep on a dev box that compared 12 with 32 and never tried 16.
+#
+# When no cgroup answers we are reading the HOST's core count, which on a fat
+# machine over-reports badly, and ORT would spawn threads that only fight each
+# other. That is the case the 12 was really protecting against, and it still
+# does, because the same sweep showed 32 threads running 4.3x slower than 12.
+_raw_cpus = container_cpus()
+CPUS = _raw_cpus if CPUS_TRUSTED else min(_raw_cpus, 12)
+
+# intra_op_num_threads governs ORT's pool only. OpenMP and the BLAS backends size
+# themselves from the host core count, which on a Spaces box is dozens of cores
+# the container will never get. Must be set before onnxruntime is imported.
+for _v in ("OMP_NUM_THREADS", "MKL_NUM_THREADS", "OPENBLAS_NUM_THREADS"):
+    os.environ.setdefault(_v, str(CPUS))
+
+
+@dataclass
+class Clip:
+    width: int
+    height: int
+    fps: float
+    frames: int
+    duration: float
+
+
+def probe(path: str) -> Clip:
+    # avg_frame_rate must be REQUESTED. Reading st.get("avg_frame_rate") without
+    # naming it here returned None on every call, so the whole VFR fix silently
+    # fell through to r_frame_rate and did nothing. Nothing raised.
+    #
+    # Bounded, too: this runs on every job before the first yield, with the lock
+    # held and no Stop button in existence yet, so a malformed container that
+    # sends ffprobe into a long analyzeduration scan would otherwise block the
+    # whole Space with nothing on screen.
+    try:
+        out = subprocess.run(
+            [FFPROBE, "-v", "error", "-select_streams", "v:0", "-show_entries",
+             "stream=width,height,r_frame_rate,avg_frame_rate,nb_frames"
+             ":format=duration",
+             "-of", "json", path],
+            capture_output=True, text=True, check=True, timeout=30).stdout
+    except subprocess.TimeoutExpired:
+        # Not "Ffprobe ...": the tool's name is lowercase, so capitalising it to
+        # open the sentence looks like a typo. Reword instead.
+        raise RuntimeError("Could not read this file within 30s (ffprobe timed "
+                           "out). It may be malformed; try re-muxing it, for "
+                           "example ffmpeg -i in -c copy out.mp4") from None
+    except subprocess.CalledProcessError as e:
+        # An upload ffprobe rejects outright used to escape as CalledProcessError,
+        # whose str() is the full argv, so the user was shown an absolute path to
+        # ffprobe.EXE on someone else's machine and no hint that their FILE is the
+        # problem. Keep ffprobe's own last line, drop the command.
+        why = " ".join((e.stderr or "").split())[-160:]
+        raise RuntimeError("ffmpeg cannot open this file as a video"
+                           + (f" ({why})" if why else "")
+                           + ". Upload a normal video container such as mp4, "
+                             "mkv or webm.") from None
+    d = json.loads(out)
+    if not d.get("streams"):
+        raise RuntimeError("This file has no video stream that ffmpeg will read "
+                           "(is it audio only?)")
+    st = d["streams"][0]
+    # avg_frame_rate is the real cadence; r_frame_rate is the smallest tick that
+    # times every frame, which on a VFR source is the MAXIMUM rate. Segment start
+    # times are seconds computed from this while frame counts come from
+    # -frames:v, so a wrong fps slides the seek a frame earlier every ~1000
+    # frames and each segment then re-renders content the previous one covered.
+    num, _, den = (st.get("avg_frame_rate") or "0/0").partition("/")
+    fps = (float(num) / float(den)) if float(den or 0) and float(num) else 0.0
+    if fps <= 0:
+        num, _, den = st["r_frame_rate"].partition("/")
+        den_f = float(den) if den else 1.0
+        fps = float(num) / den_f if den_f else 0.0
+    if fps <= 0:
+        # Every consumer of fps divides by it, so failing here names the file
+        # instead of surfacing an opaque ZeroDivisionError inside the planner.
+        raise RuntimeError("Could not determine a frame rate for this file "
+                           "(ffprobe reports 0/0). Re-mux it, for example "
+                           "ffmpeg -i in -c copy out.mp4")
+    dur = float(d.get("format", {}).get("duration") or 0.0)
+    n = int(st.get("nb_frames") or 0) or int(round(fps * dur))
+    if n == 1:
+        raise RuntimeError("This file has a single frame, so there is no gap to "
+                           "interpolate. Use a clip with at least two frames.")
+    if n < 2:
+        # nb_frames and format.duration are both absent on raw h264 and some
+        # mkv/webm. n then fell to 0, the planner made one segment of one gap,
+        # and a two frame file came back reported as a success. Counting is slow,
+        # so it is the fallback and not the default.
+        try:
+            cnt = subprocess.run(
+                [FFPROBE, "-v", "error", "-select_streams", "v:0", "-count_frames",
+                 "-show_entries", "stream=nb_read_frames", "-of", "json", path],
+                capture_output=True, text=True, timeout=120).stdout
+        except subprocess.TimeoutExpired:
+            cnt = ""
+        try:
+            n = int(json.loads(cnt)["streams"][0]["nb_read_frames"])
+        except Exception:                                   # noqa: BLE001
+            n = 0
+        if n < 2:
+            raise RuntimeError(
+                f"Could not determine a frame count for this file "
+                f"(container reports {n} frames). Re-mux it, for example "
+                f"ffmpeg -i in -c copy out.mp4")
+        if dur <= 0 and fps > 0:
+            dur = n / fps
+    if dur > 0 and n > 0 and abs(n / dur - fps) / fps > 0.02:
+        print(f"[rife] {path}: declared {fps:.3f}fps but {n} frames over "
+              f"{dur:.2f}s averages {n / dur:.3f}fps. Variable rate source: the "
+              f"output is stamped on a uniform grid, so it is retimed.",
+              flush=True)
+    return Clip(int(st["width"]), int(st["height"]), fps, n, dur)
+
+
+# ---------------------------------------------------------------- backends
+
+class Backend:
+    """Common shape: infer(img0, img1, t) on NCHW float32 in 0..1."""
+    name = "none"
+    def infer(self, a: np.ndarray, b: np.ndarray, t: float) -> np.ndarray:  # pragma: no cover
+        raise NotImplementedError
+
+
+def preload_cuda_libs() -> int:
+    """dlopen the CUDA runtime libraries so ONNX Runtime can find them.
+
+    ORT reports "Require cuDNN 9.* and CUDA 12.*" whenever any of them is missing
+    from the loader path, and then silently runs on CPU. The libraries do exist in
+    the image (torch ships them under site-packages/nvidia) but nothing puts that
+    directory on the path, and LD_LIBRARY_PATH cannot help because glibc reads it
+    once at process start. dlopening them RTLD_GLOBAL into this process does.
+
+    cuDNN 9 is split across several sub-libraries and libcudnn.so.9 depends on
+    them, so ordering matters: dependencies first, aggregate last.
+    """
+    import ctypes, glob, sysconfig
+    site = sysconfig.get_paths().get("purelib", "")
+    root = os.path.join(site, "nvidia")
+    found = sorted(glob.glob(os.path.join(root, "*", "lib", "*.so*")))
+    print(f"[rife] nvidia .so files present: {len(found)}", flush=True)
+    if found:
+        names = sorted({os.path.basename(f).split(".so")[0] for f in found})
+        print(f"[rife] libs: {', '.join(names)}", flush=True)
+
+
+    # Dependencies before the aggregates that link them.
+    order = ["cudart", "cublasLt", "cublas", "cufft", "curand", "cusparse",
+             "cusolver", "nvrtc", "nvJitLink",
+             "cudnn_graph", "cudnn_engines_precompiled", "cudnn_engines_runtime_compiled",
+             "cudnn_heuristic", "cudnn_ops", "cudnn_adv", "cudnn_cnn", "cudnn"]
+    loaded, failed = [], []
+    for stem in order:
+        for so in sorted(glob.glob(os.path.join(root, "*", "lib", f"lib{stem}.so*"))):
+            try:
+                ctypes.CDLL(so, mode=ctypes.RTLD_GLOBAL)
+                loaded.append(os.path.basename(so))
+            except OSError as e:
+                failed.append(f"{os.path.basename(so)}: {str(e)[:60]}")
+    print(f"[rife] preloaded {len(loaded)} cuda libs, {len(failed)} failed", flush=True)
+    for f in failed[:5]:
+        print(f"[rife]   FAILED {f}", flush=True)
+    return len(loaded)
+
+
+def report_ffmpeg_hw() -> None:
+    """What this image's ffmpeg can offload, printed once at startup.
+
+    The pip nvidia listing above cannot answer this: NVENC and NVDEC come from
+    the driver (libnvidia-encode, libnvcuvid) plus ffmpeg's own build flags, not
+    from site-packages. Bounded and swallowed, because a diagnostic must never be
+    able to stop the Space from starting.
+    """
+    try:
+        enc = subprocess.run([FFMPEG, "-hide_banner", "-encoders"],
+                             capture_output=True, text=True, timeout=20).stdout
+        dec = subprocess.run([FFMPEG, "-hide_banner", "-decoders"],
+                             capture_output=True, text=True, timeout=20).stdout
+        acc = subprocess.run([FFMPEG, "-hide_banner", "-hwaccels"],
+                             capture_output=True, text=True, timeout=20).stdout
+    except Exception as e:                                   # noqa: BLE001
+        print(f"[rife] ffmpeg hw probe failed ({type(e).__name__})", flush=True)
+        return
+    nvenc = sorted({ln.split()[1] for ln in enc.splitlines()
+                    if "nvenc" in ln and len(ln.split()) > 1})
+    nvdec = sorted({ln.split()[1] for ln in dec.splitlines()
+                    if ("cuvid" in ln or "_qsv" in ln) and len(ln.split()) > 1})
+    hw = [w for w in acc.split() if w not in ("Hardware", "acceleration",
+                                              "methods:")]
+    print(f"[rife] ffmpeg hwaccels: {hw or 'none'}", flush=True)
+    print(f"[rife] ffmpeg nvenc encoders: {nvenc or 'none'}", flush=True)
+    print(f"[rife] ffmpeg hw decoders: {nvdec or 'none'}", flush=True)
+
+
+def have_lib(soname: str) -> bool:
+    """Can the dynamic loader find this shared object right now?
+
+    ctypes.CDLL does the real search - loader cache, LD_LIBRARY_PATH as it was at
+    process start, and anything already dlopened RTLD_GLOBAL - which is exactly
+    what ORT will do a moment later.
+    """
+    try:
+        ctypes.CDLL(soname)
+        return True
+    except OSError:
+        return False
+
+
+class OnnxBackend(Backend):
+    """One model, best available execution provider.
+
+    Providers are tried one at a time. ORT's own provider list is all or nothing:
+    if the first entry fails to load it falls back to CPU alone and discards the
+    rest, so asking for TensorRT and CUDA together means a missing TensorRT takes
+    CUDA down with it. Whatever is finally selected is reported rather than
+    assumed, because a Space that quietly runs on CPU looks exactly like one that
+    does not.
+
+    fp32 on both paths; see the fp16 note at the top of this file.
+    """
+
+    def __init__(self, threads: int = CPUS, prefer_gpu: bool = False,
+                 trt_cache: str | None = None):
+        import onnxruntime as ort
+        o = ort.SessionOptions()
+        o.intra_op_num_threads = threads
+        o.inter_op_num_threads = 1
+        o.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+        # The other three session knobs were measured at 736x1280, best of 12,
+        # and every alternative to the defaults lost: ORT_PARALLEL +61%,
+        # enable_mem_pattern=False +59%, enable_cpu_mem_arena=False +78%.
+        # ORT_PARALLEL losing badly is the useful one - it says this graph is a
+        # deep sequential chain with nothing to overlap, so an inter-op pool only
+        # buys synchronisation. Same story as the spin-wait measurement below.
+        # Spin-wait stays ON. Disabling it looks right on a 2 vCPU box (one core
+        # burned between ops) and measured the opposite: 1.171s vs 2.797s at two
+        # threads, 58% worse. RIFE is many small ops and the context-switch
+        # latency between them costs far more than the spin.
+
+        chain: list = []
+        if prefer_gpu:
+            preload_cuda_libs()
+            # No importlib.reload here. onnxruntime is a C extension and the CPU
+            # session built at import already holds bindings into it; reloading
+            # leaves that session pointing at a stale module. ORT resolves its
+            # provider shared objects lazily when a session is created, so the
+            # RTLD_GLOBAL preload above is already visible to it.
+            avail = set(ort.get_available_providers())
+            # Registered is not the same as usable. ORT ships the TensorRT EP
+            # inside the wheel, so it is always "available", but it dlopens
+            # libnvinfer.so.10 - TensorRT's own runtime, which this image does
+            # not have. Attempting it anyway cost a failed session construction
+            # on every fork, and ZeroGPU forks per GPU call. Look for the library
+            # first: still free if the image ever ships it, free if it does not.
+            if "TensorrtExecutionProvider" in avail and not have_lib("libnvinfer.so.10"):
+                print("[rife] TensorRT EP registered but libnvinfer.so.10 is "
+                      "absent, skipping it", flush=True)
+                avail.discard("TensorrtExecutionProvider")
+            if "TensorrtExecutionProvider" in avail:
+                trt = {"trt_fp16_enable": True, "trt_engine_cache_enable": True}
+                if trt_cache:
+                    os.makedirs(trt_cache, exist_ok=True)
+                    trt["trt_engine_cache_path"] = trt_cache
+                chain.append([("TensorrtExecutionProvider", trt),
+                              ("CUDAExecutionProvider", {})])
+            if "CUDAExecutionProvider" in avail:
+                chain.append([("CUDAExecutionProvider", {})])
+            print(f"[rife] ORT sees providers: {sorted(avail)}", flush=True)
+        chain.append([("CPUExecutionProvider", {})])
+
+        model = str(MODEL)
+
+        self.s = None
+        for attempt in chain:
+            want = attempt[0][0]
+            try:
+                use = model if want != "CPUExecutionProvider" else str(MODEL)
+                sess = ort.InferenceSession(use, o, providers=attempt)
+            except Exception as e:                      # noqa: BLE001
+                print(f"[rife] {want} raised: {str(e)[:110]}", flush=True)
+                continue
+            # ORT does not raise when a provider fails to initialise. It prints
+            # "EP Error", quietly falls back to CPU inside the constructor and
+            # hands back a perfectly valid session. Constructing without error is
+            # therefore no evidence the provider was used: ask what it picked.
+            got = sess.get_providers()[0]
+            if got != want and want != "CPUExecutionProvider":
+                print(f"[rife] asked {want}, got {got}, trying next", flush=True)
+                del sess
+                continue
+            self.s = sess
+            break
+        if self.s is None:
+            raise RuntimeError("No usable execution provider")
+
+        self.provider = self.s.get_providers()[0]
+        self.name = {
+            "TensorrtExecutionProvider": "GPU TensorRT",
+            "CUDAExecutionProvider": "GPU CUDA",
+            "CPUExecutionProvider": f"CPU ONNX fp32 x{threads}",
+        }.get(self.provider, self.provider)
+        self.on_gpu = self.provider != "CPUExecutionProvider"
+        # Names are converter artifacts. Interrogate, never hardcode.
+        self.inames = [i.name for i in self.s.get_inputs()]
+
+    def infer(self, a, b, t):
+        return self.s.run(None, {self.inames[0]: a, self.inames[1]: b,
+                                 self.inames[2]: np.array([t], dtype=np.float32)})[0]
+
+
+
+
+
+class Buffers:
+    """Preallocated padded frame buffers for the streaming loop.
+
+    The naive path costs five full-size passes per frame: frombuffer, transpose,
+    astype, divide, ascontiguousarray, then np.pad again because 480, 720 and
+    1080 are none of them multiples of 32. At 1080p that is well over 100 MB of
+    memory traffic per decoded frame on a box with two vCPUs, and it is pure
+    serial overhead that the model rate measurement never sees.
+
+    Here the padded buffers are allocated once per segment and reused. Decoded
+    bytes are scaled straight into the interior view in a single pass, and only
+    the edge strips are re-replicated rather than the whole frame.
+    """
+
+    def __init__(self, h: int, w: int):
+        self.h, self.w = h, w
+        self.ph = (h + ALIGN - 1) // ALIGN * ALIGN
+        self.pw = (w + ALIGN - 1) // ALIGN * ALIGN
+        # uint8 NHWC: exactly what the decoder emits and what the graph now
+        # takes, so a frame is copied once and never converted on this CPU.
+        self.a = np.zeros((1, self.ph, self.pw, 3), dtype=np.uint8)
+        self.b = np.zeros((1, self.ph, self.pw, 3), dtype=np.uint8)
+        self._u8 = np.empty((h, w, 3), dtype=np.uint8)
+
+    def load(self, dst: np.ndarray, raw: bytes) -> np.ndarray:
+        """Copy decoded RGB straight into dst's interior, then fix the edges.
+
+        No scaling and no transpose any more: the graph takes uint8 NHWC and does
+        both on the device. This was 0.42 s of a 3.44 s segment at 852x480.
+
+        The decoder stays on packed rgb24 deliberately. Asking it for gbrp would
+        remove this transpose, but `yuv420p -> gbrp` and `yuv420p -> rgb24` are
+        different chroma upsampling paths in swscale and disagree by up to 154
+        on a colour-bar source, mean 1.87, with no dither or rounding flag
+        closing the gap. That is a change to what the user gets, for 0.74 s a
+        segment. The encoder half IS free, but it cannot be taken alone: the
+        source-frame pass-through writes decoder bytes straight to the encoder,
+        so the two pipes must agree on a format. See emit() for the full result.
+        """
+        src = np.frombuffer(raw, dtype=np.uint8).reshape(self.h, self.w, 3)
+        dst[0, :self.h, :self.w, :] = src          # one contiguous copy
+        if self.ph > self.h:                       # replicate bottom edge
+            dst[0, self.h:, :self.w, :] = dst[0, self.h - 1:self.h, :self.w, :]
+        if self.pw > self.w:                       # replicate right edge
+            dst[0, :, self.w:, :] = dst[0, :, self.w - 1:self.w, :]
+        return dst
+
+    def emit(self, x: np.ndarray) -> bytes:
+        """Pack the model's uint8 NCHW output into the rgb24 the encoder wants.
+
+        The scale, round and clip used to happen here: three float passes over
+        2.76 M elements per frame, on two vCPUs, while the GPU finished the whole
+        frame in 21 ms. Measured on the Space that was 1.13-1.20 s of the 2.3 s
+        of non-model time in a 179-gap segment, the largest term after inference.
+        Mul/Add/Clip/Cast now live in the graph and run on the device, verified
+        bit identical against this function's old output on real model results.
+        What is left is the NCHW to HWC pack the encoder's rgb24 requires.
+
+        Planar (gbrp) on both pipes would remove this and the matching transpose
+        in load(), worth ~1.5 s of the 1.94 s of non-model time in a segment. It
+        was measured and declined: the ENCODER side is byte identical with gbrp
+        (max diff 0 feeding the same pixels both ways), but the DECODER is not -
+        `yuv420p -> gbrp` and `yuv420p -> rgb24` take different chroma upsampling
+        paths in swscale and disagree by up to 154 on a colour-bar source, mean
+        1.87, with no dither or rounding flag closing it. And the two pipes
+        cannot disagree: the source-frame pass-through writes decoder bytes
+        straight to the encoder, so a packed decoder with a planar encoder feeds
+        packed pixels into a planar pipe. Both formats or neither.
+        """
+        # The model emits uint8 now. A float32 array here would truncate to
+        # near-black without raising, which is the kind of failure that reaches
+        # a user as a corrupt video and no error at all.
+        assert x.dtype == np.uint8, f"emit expects uint8 from the model, got {x.dtype}"
+        self._u8[...] = x[0, :, :self.h, :self.w].transpose(1, 2, 0)
+        return self._u8.tobytes()
+
+
+def measure_rate(be: Backend, h: int, w: int, samples: int = 3) -> float:
+    """Seconds per interpolated frame at this resolution, measured on this box.
+
+    Everything downstream is estimated from this rather than from a table, so a
+    slower vCPU or a faster GPU changes the plan instead of surprising the user.
+    """
+    ph, pw = (h + ALIGN - 1) // ALIGN * ALIGN, (w + ALIGN - 1) // ALIGN * ALIGN
+    # NOT np.zeros. A freshly calloc'd array can sit on the shared zero page, and
+    # reusing one across samples reads it straight out of cache: measured at
+    # 640x360, reused zeros time at 0.1415 s against 0.2130 s for real decoded
+    # frames, 33% low. The single-sample version escaped that only by allocating
+    # fresh arrays each call. Sampling over one buffer would have walked into it
+    # and made every estimate optimistic. Random data times like real data
+    # (0.2130 vs 0.2130) and is reproducible.
+    rng = np.random.default_rng(0)
+    a = rng.integers(0, 256, (1, ph, pw, 3), dtype=np.uint8)
+    b = rng.integers(0, 256, (1, ph, pw, 3), dtype=np.uint8)
+    be.infer(a, b, 0.5)                       # warm
+    # Median of a few, not one. plan_gaps sizes every segment from this number,
+    # so its variance is a correctness property: a single sample at 640x360 was
+    # observed from 0.157 to 0.232 s across runs, a 1.5x spread, and a plan built
+    # on the low end makes segments 1.5x larger than intended - which on ZeroGPU
+    # is how a 90 s budget overruns a 120 s cap. At 1280x720 the spread is ~6%,
+    # so the error is worst where frames are small, but this is the foundation of
+    # every estimate the user is shown.
+    ts = []
+    for _ in range(max(1, samples)):
+        t0 = time.perf_counter()
+        be.infer(a, b, 0.5)
+        ts.append(time.perf_counter() - t0)
+    return statistics.median(ts)
+
+
+def profile_ops(h: int, w: int, samples: int = 4) -> str:
+    """One-line breakdown of where an inference goes, from ORT's own profiler.
+
+    Builds a SECOND session with profiling on rather than turning it on for the
+    live one: the profiler adds per-op bookkeeping, and measuring a session while
+    slowing it down is how you get numbers that describe the measurement.
+    """
+    import glob
+    import onnxruntime as ort
+    try:
+        o = ort.SessionOptions()
+        o.enable_profiling = True
+        o.profile_file_prefix = os.path.join(tempfile.gettempdir(), "ffprof")
+        o.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+        sess = ort.InferenceSession(str(MODEL), o, providers=[("CUDAExecutionProvider", {})])
+        if sess.get_providers()[0] != "CUDAExecutionProvider":
+            return "profile skipped: session did not land on CUDA"
+        rng = np.random.default_rng(0)
+        a = rng.integers(0, 256, (1, h, w, 3), dtype=np.uint8)
+        b = rng.integers(0, 256, (1, h, w, 3), dtype=np.uint8)
+        t = np.array([0.5], dtype=np.float32)
+        for _ in range(samples):
+            # The only hardcoded input names in the file; everything else binds
+            # off session.get_inputs(). They move with the graph.
+            sess.run(None, {"img0_u8": a, "img1_u8": b, "timestep": t})
+        path = sess.end_profiling()
+        del sess
+        with open(path, encoding="utf-8") as f:
+            ev = json.load(f)
+        tot, by, on_cpu, cpu_by = 0, {}, 0, {}
+        for e in ev:
+            if e.get("cat") != "Node" or "dur" not in e:
+                continue
+            args = e.get("args", {}) or {}
+            kind = args.get("op_name", "?")
+            by[kind] = by.get(kind, 0) + e["dur"]
+            # Which EP actually ran it. 38% memcpy has two possible causes and
+            # they need opposite fixes: inputs arriving on the host (fix by
+            # shrinking what crosses, or by IO binding), or an op with no CUDA
+            # kernel splitting the graph and forcing a round trip mid-inference
+            # (fix by replacing that op). Bucketing by provider tells them apart,
+            # and it is also how a uint8 input graph would be caught failing -
+            # ORT can place the leading Cast on the CPU EP, in which case the
+            # host casts to float32 and ships the same bytes as before, plus
+            # extra nodes.
+            if "CPU" in args.get("provider", ""):
+                on_cpu += e["dur"]
+                cpu_by[kind] = cpu_by.get(kind, 0) + e["dur"]
+            tot += e["dur"]
+        for f in glob.glob(o.profile_file_prefix + "*"):
+            try:
+                os.remove(f)
+            except OSError:
+                pass
+        if not tot:
+            return "profile produced no node events"
+        top = sorted(by.items(), key=lambda kv: -kv[1])[:6]
+        copies = sum(v for k, v in by.items() if "Memcpy" in k)
+        return ("ops " + ", ".join(f"{k} {v * 100 // tot}%" for k, v in top)
+                + f" | memcpy {copies * 100 // tot}%"
+                + f" | on CPU EP {on_cpu * 100 // tot}%"
+                + (" [" + ", ".join(
+                    f"{k} {v * 100 // tot}%" for k, v in
+                    sorted(cpu_by.items(), key=lambda kv: -kv[1])[:5]) + "]"
+                   if cpu_by else "")
+                + f" | {tot / 1000 / samples:.1f} ms/run")
+    except Exception as e:                                   # noqa: BLE001
+        return f"profile failed ({type(e).__name__}: {str(e)[:80]})"
+
+
+def nvenc_works() -> bool:
+    """Can this process actually ENCODE with NVENC right now?
+
+    `ffmpeg -encoders` listing h264_nvenc proves only that ffmpeg was built with
+    it. The runtime needs libnvidia-encode and a real device, and on ZeroGPU the
+    parent process has neither - a GPU exists only inside a @spaces.GPU fork. So
+    this has to run in the fork, and it has to encode something rather than ask.
+    """
+    try:
+        r = subprocess.run(
+            [FFMPEG, "-v", "error", "-f", "lavfi", "-i", "nullsrc=s=256x256:d=0.1",
+             "-c:v", "h264_nvenc", "-f", "null", "-"],
+            capture_output=True, timeout=30)
+        return r.returncode == 0
+    except Exception:                                        # noqa: BLE001
+        return False
+
+
+# NVENC only pays above roughly 2 MP. Measured against x264 veryfast pinned to
+# 2 threads, which is what the Space actually has, at MATCHED SSIM rather than
+# matched knob number:
+#   720p  0.9 MP  0.86x speed  1.02x size   <- slower, so do not
+#   1080p 2.1 MP  1.14x speed  0.92x size
+#   1440p 3.7 MP  1.27x speed  0.85x size
+#   2160p 8.3 MP  1.51x speed  0.82x size
+# The threshold sits between the first two rows.
+NVENC_MIN_PIXELS = 1_400_000
+
+# cq is NOT crf. Passing crf straight through produced files 2.5-2.8x larger at
+# the same number. Matching SSIM instead put the offset at +2: nvenc cq22 scores
+# at or above x264 crf20 everywhere measured. Picking the offset by FILE SIZE
+# would have said +6, and cq26 is a real quality drop (SSIM 0.941 against 0.967)
+# that looks like a win on the size column alone.
+NVENC_CQ_OFFSET = 2
+
+
+def encoder_args(crf: int, hw: bool) -> list[str]:
+    """x264, or NVENC when it is actually the faster of the two.
+
+    `-b:v 0` is required or vbr silently targets a bitrate and ignores -cq.
+    """
+    if not hw:
+        return ["-c:v", "libx264", "-preset", "veryfast", "-crf", str(crf)]
+    cq = max(0, min(51, crf + NVENC_CQ_OFFSET))
+    return ["-c:v", "h264_nvenc", "-preset", "p4", "-tune", "hq",
+            "-rc", "vbr", "-cq", str(cq), "-b:v", "0"]
+
+
+def interpolate_segment(src: str, dst: str, start: float, gaps: int, factor: int,
+                        be: Backend, clip: Clip, crf: int = 18,
+                        cancel: Callable[[], bool] | None = None,
+                        on_frame: Callable[[int], None] | None = None,
+                        write_tail: bool = True,
+                        out_w: int = 0, out_h: int = 0,
+                        hw_encode: bool = False) -> int:
+    """Interpolate one time slice straight from decoder pipe to encoder pipe.
+
+    Segments overlap by exactly one source frame. A segment owns the GAPS that
+    start inside it, so it emits `prev` plus the generated frames for each gap and
+    leaves the trailing frame to whoever owns the next gap. Without that, every
+    seam would both duplicate a source frame and lose the frame belonging in the
+    gap across it; only the final segment writes its tail.
+
+    Two decoded frames are resident at a time, plus at most four more in the
+    encoder queue and the writer - about 100 MB at 4K rather than 50. Still O(1)
+    in clip length at any resolution, which is the property that matters; only
+    the constant grew when the writer thread arrived.
+    """
+    w = out_w or clip.width
+    h = out_h or clip.height
+    fsize = w * h * 3
+    need = gaps + 1                               # frames required to close them
+
+    # Scaling here rather than in a pre-pass: a whole-clip transcode before the
+    # first segment costs an extra encode AND decode over the entire source, is
+    # serial time before any progress shows, and adds a generation-loss hop.
+    vf = ([] if (w, h) == (clip.width, clip.height)
+          else ["-vf", f"scale={w}:{h}:flags=bicubic"])
+    # stderr goes to temp FILES, not pipes. A pipe nobody drains fills at ~64 KB,
+    # at which point ffmpeg blocks writing stderr, stops producing on stdout, and
+    # the unbounded dec.stdout.read() below waits forever. "-v error" hides
+    # warnings but not per-frame decode errors, and a slightly corrupt upload is
+    # routine input here, so that pipe filling is a question of when.
+    dec_err = tempfile.TemporaryFile()
+    enc_err = tempfile.TemporaryFile()
+    dec = subprocess.Popen(
+        [FFMPEG, "-v", "error", "-ss", f"{start:.6f}", "-i", src,
+         "-frames:v", str(need), *vf, "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+        stdout=subprocess.PIPE, stderr=dec_err, bufsize=fsize * 2)
+    # -preset veryfast is MEASURED, not picked. Stage profiling puts the encoder
+    # at 1-2% of a CPU job and ~11% of a GPU one (ffmpeg does not get faster when
+    # the model does), so it is only worth anything on GPU, and only then if the
+    # trade is good. It is not. Benchmarked on real frames at fixed crf 20:
+    #   720p   ultrafast -6.5% time  +195% size   superfast +20% time +100% size
+    #   2160p  ultrafast -13% time   +209% size   superfast -14% time +102% size
+    # Three times the download to shave 13% off a stage that is a ninth of the
+    # job, about 1.5% overall. The slower presets cost 26-89% more time and did
+    # not come back smaller either. veryfast is the right point on this curve.
+    enc = subprocess.Popen(
+        [FFMPEG, "-v", "error", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24",
+         "-s", f"{w}x{h}", "-r", f"{clip.fps * factor:.6f}", "-i", "-",
+         *encoder_args(crf, hw_encode and w * h >= NVENC_MIN_PIXELS),
+         "-pix_fmt", "yuv420p", dst],
+        stdin=subprocess.PIPE, stderr=enc_err)
+
+    written = 0
+    starved = False
+    # Stage accumulators. perf_counter calls are ~100 ns, so at a few per frame
+    # this is far below the millisecond effects being measured.
+    t_read = t_load = t_inf = t_emit = t_put = 0.0
+    bufs = Buffers(h, w)
+    prev_p, cur_p = bufs.a, bufs.b        # ping-pong, no per-frame allocation
+
+    # The encoder gets its own thread so x264 overlaps inference instead of
+    # stalling it. A 4K frame is ~25 MB against a 64 KB default pipe buffer, so
+    # without this every write waits for ffmpeg to drain the last one.
+    wq: queue.Queue = queue.Queue(maxsize=3)
+    werr: list[BaseException] = []
+
+    def _writer():
+        while True:
+            item = wq.get()
+            if item is None:
+                return
+            try:
+                enc.stdin.write(item)
+            except BaseException as e:            # noqa: BLE001
+                werr.append(e)
+                return                            # stop; put() notices below
+
+    wt = threading.Thread(target=_writer, daemon=True)
+    wt.start()
+
+    def put(b: bytes) -> None:
+        """Hand a frame to the writer, refusing to block forever if it died."""
+        while True:
+            try:
+                wq.put(b, timeout=1.0)
+                return
+            except queue.Full:
+                if not wt.is_alive() or werr:
+                    raise RuntimeError(
+                        "the encoder stopped accepting frames"
+                        + (f": {werr[0]}" if werr else ""))
+    try:
+        raw_prev = dec.stdout.read(fsize)
+        if len(raw_prev) < fsize:
+            # Returning 0 from inside the try skipped the encoder check below and
+            # let concat splice straight over the gap: a jump cut whose only
+            # trace was one line in a 14-line ring buffer. A segment that decodes
+            # nothing is a bug in the bounds or a truncated source, so say so.
+            starved = True
+        else:
+            bufs.load(prev_p, raw_prev)
+        while not starved:
+            if cancel is not None and cancel():
+                break
+            _t = time.perf_counter()
+            raw_cur = dec.stdout.read(fsize)
+            t_read += time.perf_counter() - _t
+            if len(raw_cur) < fsize:
+                break
+            _t = time.perf_counter()
+            bufs.load(cur_p, raw_cur)
+            t_load += time.perf_counter() - _t
+            # A SOURCE frame goes out as the bytes that came in. It used to be
+            # scaled to float32 by load(), then scaled back by emit() - multiply,
+            # add, clip, transpose, copy - to reproduce what was already in hand.
+            # Verified byte-identical for all 256 levels: u/255 in float32, then
+            # clip(v*255 + 0.5), returns u exactly, so this changes no output.
+            # At factor 2 it is HALF of all emit work, at factor 4 a quarter.
+            _t = time.perf_counter()
+            put(raw_prev)
+            t_put += time.perf_counter() - _t
+            written += 1
+            for i in range(1, factor):
+                _t = time.perf_counter()
+                out = be.infer(prev_p, cur_p, i / factor)
+                t_inf += time.perf_counter() - _t
+                _t = time.perf_counter()
+                blob = bufs.emit(out)
+                t_emit += time.perf_counter() - _t
+                _t = time.perf_counter()
+                put(blob)
+                t_put += time.perf_counter() - _t
+                written += 1
+                if on_frame is not None:
+                    on_frame(written)
+            prev_p, cur_p = cur_p, prev_p     # swap, never copy
+            raw_prev = raw_cur
+        if write_tail and not starved:
+            put(raw_prev); written += 1
+    finally:
+        # Drain before closing stdin, or the frames still queued are discarded
+        # and the segment silently comes up short. The sentinel is put without a
+        # timeout guard on purpose: if the writer is gone the queue has room.
+        try:
+            wq.put(None, timeout=5.0)
+        except Exception as e:                    # noqa: BLE001
+            # Not swallowed. A dropped sentinel means the writer never learns to
+            # stop, so frames may still be queued and unwritten - which would
+            # otherwise return a short segment as a complete one.
+            werr.append(RuntimeError(f"could not signal the writer to finish: {e}"))
+        wt.join(timeout=120.0)
+        if wt.is_alive():
+            # join() returns identically whether the thread finished or the
+            # timeout expired, so this has to be asked explicitly.
+            werr.append(RuntimeError("the encoder writer did not finish in 120s"))
+        if written > 1:
+            tot = t_read + t_load + t_inf + t_emit + t_put
+            print(f"[rife] stages {w}x{h} {written}f: infer {t_inf:.2f}s "
+                  f"read {t_read:.2f}s load {t_load:.2f}s emit {t_emit:.2f}s "
+                  f"put {t_put:.2f}s | non-model {(tot - t_inf) * 1000 / written:.1f} "
+                  f"ms/frame", flush=True)
+        for closer in (lambda: enc.stdin.close(), lambda: dec.stdout.close()):
+            try:
+                closer()
+            except Exception:
+                pass
+        rc = enc.wait()          # safe now: stderr is a file, so it cannot block
+        try:
+            dec.wait(timeout=10)
+        except Exception:
+            dec.kill()
+    try:
+        # Order matters, all three ways.
+        # Starvation first: it is decided by the very FIRST read, before any
+        # cancel check, so it is a property of the bounds or the source and never
+        # of the cancellation. Swallowing it under a cancel would lose the one
+        # diagnostic built for bad bounds exactly when a user interrupts a job
+        # that was already going wrong. It also makes the encoder exit non-zero
+        # for want of input, so checking rc ahead of it reported "encoder failed"
+        # for what is really a decode fault.
+        if werr:
+            # Raised HERE, not in the finally. Raising from inside the finally
+            # jumped over enc.stdin.close(), dec.stdout.close(), enc.wait() and
+            # dec.wait(), so a failed encoder left the DECODER alive, blocked
+            # writing into a pipe with no reader, holding fds on the source and
+            # on its stderr temp file - one orphan pair per failed segment, and
+            # the shrink-and-retry path can try the same range four times.
+            #
+            # Ordered after starvation because a starved segment never calls
+            # put(), so werr cannot be set there, and before the cancel check
+            # because a broken write means the file is incomplete whatever the
+            # user pressed.
+            raise RuntimeError(f"encoder write failed: {werr[0]}")
+        if starved:
+            raise RuntimeError(
+                f"Decoder produced no frames at {start:.3f}s of a "
+                f"{clip.duration:.3f}s source. The file is probably truncated "
+                f"or corrupt: its header claims more than it contains. "
+                f"ffmpeg said: {tail(dec_err)}")
+        # Then the clean stop. A cancel landing between the loop's own check and
+        # the first frame leaves the encoder with nothing, and rc below would be
+        # reporting that cancellation rather than a fault.
+        if written == 0 and cancel is not None and cancel():
+            return 0
+        # A dead encoder used to read as success: written was returned
+        # regardless, so concat later spliced a truncated part.
+        if rc != 0:
+            raise RuntimeError(f"Encoder failed (exit {rc}). "
+                               f"ffmpeg said: {tail(enc_err)}")
+    finally:
+        for f in (dec_err, enc_err):
+            try:
+                f.close()
+            except Exception:                       # noqa: BLE001
+                pass
+    return written
+
+
+def tail(f, n: int = 400) -> str:
+    """The last COMPLETE stderr line or two, for an error message.
+
+    Slicing the last n bytes lands mid-word: a truncated h264 file produced
+    "decoder produced no frames at 10.783s of a 20.000s source ze (2176 > 104)."
+    where "ze (2176 > 104)" is the tail of "Invalid NAL unit size (2176 > 104)".
+    ffmpeg also repeats the same complaint per frame, so the last couple of
+    distinct lines carry everything the earlier thousands do.
+    """
+    try:
+        f.seek(0)
+        raw = f.read()[-4096:].decode("utf-8", "replace")
+    except Exception:                               # noqa: BLE001
+        return ""
+    lines, seen = [], set()
+    for ln in reversed([l.strip() for l in raw.splitlines() if l.strip()]):
+        if ln in seen:
+            continue
+        seen.add(ln)
+        lines.append(ln)
+        if len(lines) == 2 or sum(map(len, lines)) > n:
+            break
+    return " | ".join(reversed(lines))[:n]
+
+
+# NOT corrected by a per-gap constant, and the measurements are why.
+#
+# plan_gaps charges `rate * (factor - 1)` per gap. A real segment also does a
+# decode read, two buffer passes and `factor` x264 frames, so it under-charges.
+# Measured, as measured/assumed on real segments:
+#
+#   CPU 1280x720 f2  inference 0.9103 s/frame  1.028x  -> 0.0258 s/gap missing
+#   CPU 1280x720 f4  inference 0.9103 s/frame  1.008x  -> 0.0217 s/gap missing
+#   GPU  852x480 f2  inference 0.0579 s/frame  1.456x  -> 0.0264 s/gap missing
+#   CPU  426x240 f2  inference 0.1023 s/frame  1.042x  -> 0.0043 s/gap missing
+#
+# A single additive 0.026 s/gap fits the first three to within 0.4%. It is 6x too
+# large for the fourth, where it would over-charge by 21% - and on ZeroGPU an
+# over-charge is not free either, since 21% more segments is 21% more GPU
+# allocations against a daily run budget. Four points that are neither constant
+# nor pixel-linear (480p and 720p agree despite 2.25x the pixels) are not a
+# model, so no constant is applied.
+#
+# What IS established: the under-charge is largest on a fast device, exactly
+# where the 120 s ZeroGPU cap lives. That is handled by sizing the budget for it
+# in app.py rather than by inventing a curve through four points. Every segment
+# now logs its own ratio, so the data to build a real model accumulates from
+# production instead of from one afternoon's harness.
+
+
+def plan_gaps(clip: Clip, factor: int, rate_s: float, budget_s: float) -> int:
+    """How many gaps one segment may own so it fits the compute budget.
+
+    Counted in gaps, not seconds. Second-based boundaries round against the frame
+    rate and the error accumulates across segments, which showed up as a handful
+    of extra frames on a seven segment run.
+    """
+    per_gap = rate_s * max(1, factor - 1)
+    if per_gap <= 0:
+        return max(1, clip.frames - 1)
+    return max(1, int(budget_s / per_gap))
+
+
+def segment_bounds(clip: Clip, gaps_per_seg: int,
+                   start_frame: int = 0) -> list[tuple[float, int, bool]]:
+    """(start_seconds, gaps_owned, is_last) for each segment, frame exact.
+
+    start_frame re-cuts only the tail of a clip, which is what a mid-job switch
+    from GPU to CPU needs: the segments already rendered keep their bounds and
+    the rest are re-sized for the slower device.
+    """
+    total = max(1, clip.frames - 1)
+    out: list[tuple[float, int, bool]] = []
+    f = start_frame
+    while f < total:
+        n = min(gaps_per_seg, total - f)
+        # Half a frame early, deliberately. -ss lands on the first frame whose
+        # pts >= the target, and the target is a float division, so a target that
+        # rounds a hair above frame f's true pts silently starts the segment at
+        # f+1. Aiming between f-1 and f cannot reach f+1 and cannot fall short of
+        # f, which removes the rounding question entirely.
+        out.append((max(0.0, (f - 0.5) / clip.fps), n, f + n >= total))
+        f += n
+    return out
+
+
+def concat(parts: list[str], dst: str) -> None:
+    lst = tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False)
+    for p in parts:
+        lst.write(f"file '{pathlib.Path(p).as_posix()}'\n")
+    lst.close()
+    try:
+        r = subprocess.run([FFMPEG, "-v", "error", "-y", "-f", "concat", "-safe",
+                            "0", "-i", lst.name, "-c", "copy", dst],
+                           capture_output=True)
+        if r.returncode != 0:
+            # check=True raises CalledProcessError, whose str() is the whole
+            # argv - an absolute path to ffmpeg and no reason. Same shape probe()
+            # was fixed to stop producing. Carry ffmpeg's own words instead.
+            why = " ".join((r.stderr or b"").decode("utf-8", "replace").split())
+            raise RuntimeError(
+                "could not join the finished segments"
+                + (f": {why[-200:]}" if why else " and ffmpeg said nothing"))
+    finally:
+        # In a finally: a failing concat used to leak its list file, and concat
+        # fails on exactly the runs where something else already went wrong.
+        try:
+            os.unlink(lst.name)
+        except OSError:
+            pass
+
+
+def mux_audio(video: str, original: str, dst: str) -> bool:
+    """Carry the original audio across. Interpolation changes frame rate, not
+    duration, so the track still lines up."""
+    r = subprocess.run(
+        [FFMPEG, "-v", "error", "-y", "-i", video, "-i", original,
+         "-c", "copy", "-map", "0:v:0", "-map", "1:a:0?", "-shortest", dst],
+        capture_output=True)
+    return r.returncode == 0 and os.path.exists(dst) and os.path.getsize(dst) > 0