Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio video: spool encoded stream chunks instead of holding a second raw clip (#17066)
Daniel Han87b7acb9f11f
diff --git a/studio/backend/core/inference/video_stream_encode.py b/studio/backend/core/inference/video_stream_encode.pyindex c14babe86c9..06eb92f1f52 100644--- a/studio/backend/core/inference/video_stream_encode.py+++ b/studio/backend/core/inference/video_stream_encode.py@@ -3,7 +3,11 @@"""Encodes a Wan or MiniMax-H3 clip while its VAE decodes; the streamed mp4 is used only if itsframes equal the final frames bit for bit, else re-encoded; H3 declares audio up front (as-encode_x264) and muxes it last; UNSLOTH_STUDIO_VIDEO_STREAM_ENCODE=0 disables."""+encode_x264) and muxes it last; UNSLOTH_STUDIO_VIDEO_STREAM_ENCODE=0 disables.++Each encoded chunk is spooled to an unlinked temp file and its host (often pinned) copy dropped, so the raw frames+held for the final compare stay bounded by the queue instead of growing to a second full clip;+UNSLOTH_VIDEO_STREAM_SHARED_OUTPUT=0 keeps every chunk in memory as before."""from __future__ import annotations@@ -27,6 +31,8 @@ _STOP = object()STREAM_COMPARE_ENV = "UNSLOTH_STUDIO_VIDEO_STREAM_COMPARE_SLICED"# 128 KiB bool scratch stays under numpy's 4 MiB hugepage madvise threshold._COMPARE_WORDS = 1 << 17+SHARED_OUTPUT_ENV = "UNSLOTH_VIDEO_STREAM_SHARED_OUTPUT"+_SPOOL_READ = _COMPARE_WORDS * 8STATS = {"streamed": 0, "fallback": 0, "last": ""}@@ -39,6 +45,29 @@ def _sliced_compare_enabled() -> bool:return os.environ.get(STREAM_COMPARE_ENV, "").strip().lower() not in ("0", "false", "no", "off")+def _spool_enabled() -> bool:+ return os.environ.get(SHARED_OUTPUT_ENV, "").strip().lower() not in ("0", "false", "no", "off")+++class _Chunk:+ """One streamed range of frames: ``host`` until the encoder spooled it (then ``offset`` into the spool)."""++ __slots__ = ("host", "done", "frames", "offset", "spool")++ def __init__(+ self,+ host: Any,+ done: Any,+ frames: int,+ spool: bool = True,+ ) -> None:+ self.host = host+ self.done = done+ self.frames = frames+ self.offset = None+ self.spool = spool++def _frames_equal(a: Any, b: Any, scratch: Any) -> bool:"""Sliced ``np.array_equal`` for uint8 arrays: a chunk-sized hugepage bool temp stalled 115-152 s on fragmented hosts."""import numpy as np@@ -115,6 +144,9 @@ class StreamEncode:)self._side = Noneself.chunks: list = []+ self._spool: Any = None+ self._spool_on = _spool_enabled()+ self._spool_lock = threading.Lock()self.reason = ""self.valid = Trueself._decoding = False@@ -180,13 +212,14 @@ class StreamEncode:x.record_stream(self._side)else:host = x.cpu() if device.type != "cpu" else x- self.chunks.append((host, done))+ chunk = _Chunk(host, done, int(x.shape[0]))+ self.chunks.append(chunk)if self._thread is None:self._thread = threading.Thread(target = self._encode, name = "video-stream-encode", daemon = True)self._thread.start()- self._queue.put((host, done))+ self._queue.put(chunk)@contextlib.contextmanagerdef hooks(self) -> Iterator[None]:@@ -264,7 +297,7 @@ class StreamEncode:breakif self._failed or not self.valid:continue- host, done = item+ host, done = item.host, item.doneif done is not None:done.synchronize()frames = host.numpy()@@ -281,6 +314,10 @@ class StreamEncode:for frame in frames:for packet in stream.encode(av.VideoFrame.from_ndarray(frame, format = "rgb24")):container.mux(packet)+ # the last ``frame`` is a view that would pin the whole chunk+ frames = host = frame = None+ if item.spool:+ self._spool_chunk(item)if container is not None and self.valid and not self._failed:for packet in stream.encode():container.mux(packet)@@ -299,6 +336,61 @@ class StreamEncode:except Exception: # noqa: BLE001self._failed = True+ def _spool_chunk(self, chunk: "_Chunk") -> None:+ """Move an encoded chunk's frames to the spool and drop the host copy; on any failure keep it in memory."""+ if not self._spool_on:+ return+ try:+ frames = chunk.host.numpy()+ with self._spool_lock:+ if self._spool is None:+ # unlinked at once on POSIX, deleted on close on Windows+ self._spool = tempfile.TemporaryFile(dir = os.path.dirname(self.path) or None)+ spool = self._spool+ spool.seek(0, os.SEEK_END)+ offset = spool.tell()+ spool.write(memoryview(frames.reshape(-1)))+ # a full disk must fail here, while the chunk is still in memory, not at the compare's seek+ spool.flush()+ chunk.offset = offset+ chunk.host = None+ chunk.done = None+ except Exception: # noqa: BLE001 - a full disk keeps the chunks in memory, the old way+ self._spool_on = False++ def _spool_equal(self, offset: int, theirs: Any, scratch: Any) -> bool:+ """The spooled bytes at ``offset`` equal ``theirs`` (uint8 frames), read back 1 MiB at a time."""+ import numpy as np++ size = theirs.size+ window = np.empty(min(size, _SPOOL_READ), dtype = np.uint8)+ frame = int(np.prod(theirs.shape[1:])) if theirs.ndim > 1 else 1+ flat = theirs.reshape(-1) if theirs.flags.c_contiguous else None+ pos = 0+ with self._spool_lock:+ spool = self._spool+ spool.seek(offset)+ while pos < size:+ part = window[: min(size - pos, window.size)]+ if spool.readinto(memoryview(part)) != part.size:+ return False+ if flat is not None:+ want = flat[pos : pos + part.size]+ else:+ # strided clip: copy only this window's frames+ first, last = pos // frame, (pos + part.size - 1) // frame+ span = np.ascontiguousarray(theirs[first : last + 1]).reshape(-1)+ want = span[pos - first * frame : pos - first * frame + part.size]+ same = (+ np.array_equal(part, want)+ if scratch is None+ else _frames_equal(part, want, scratch)+ )+ if not same:+ return False+ pos += part.size+ return True+def _join(self) -> None:if self._thread is not None:self._queue.put(_STOP)@@ -321,11 +413,7 @@ class StreamEncode:if not self.chunks:self.invalidate("no chunks")return False- for _, done in self.chunks:- if done is not None:- done.synchronize()- streamed = [host for host, _ in self.chunks]- count = sum(len(h) for h in streamed)+ count = sum(chunk.frames for chunk in self.chunks)if count > len(video_frames) or (count != len(video_frames) and not self._tail_ok):self.invalidate("frame count differs")return False@@ -334,18 +422,32 @@ class StreamEncode:final = video_frames.numpy()scratch = np.empty(_COMPARE_WORDS, dtype = np.bool_) if _sliced_compare_enabled() else Nonestart = 0- for host in streamed:- # numpy, not torch.equal: torch's parallel compare costs seconds on a loaded many-core host.- ours, theirs = host.numpy(), final[start : start + len(host)]- same = (- np.array_equal(ours, theirs)- if scratch is None- else _frames_equal(ours, theirs, scratch)- )+ for chunk in self.chunks:+ with self._spool_lock:+ # local refs: the encoder may spool the chunk meanwhile+ host, done, offset = chunk.host, chunk.done, chunk.offset+ theirs = final[start : start + chunk.frames]+ if host is None:+ try:+ same = self._spool_equal(offset, theirs, scratch)+ except Exception: # noqa: BLE001 - an unreadable spool: encode the clip normally+ self.invalidate("spool unreadable")+ return False+ else:+ if done is not None:+ done.synchronize()+ # numpy, not torch.equal: torch's parallel compare costs seconds on a loaded many-core host.+ ours = host.numpy()+ same = (+ np.array_equal(ours, theirs)+ if scratch is None+ else _frames_equal(ours, theirs, scratch)+ )+ del hostif not same:self.invalidate("frames differ")return False- start += len(host)+ start += chunk.framesreturn Truedef take(@@ -371,9 +473,11 @@ class StreamEncode:if self.valid and not self._decoded:self.invalidate("no decode")if self.valid and self._matches(video_frames):- streamed = sum(len(host) for host, _ in self.chunks)+ streamed = sum(chunk.frames for chunk in self.chunks)if streamed < len(video_frames):- self._queue.put((video_frames[streamed:], None))+ # the caller's frames: never spooled+ tail = video_frames[streamed:]+ self._queue.put(_Chunk(tail, None, len(tail), spool = False))self._join()if audio is not None and not self._failed and self.valid:try:@@ -407,6 +511,13 @@ class StreamEncode:self._join()self._close_container()self.chunks = []+ with self._spool_lock:+ spool, self._spool = self._spool, None+ if spool is not None:+ try:+ spool.close()+ except Exception: # noqa: BLE001+ passtry:os.unlink(self.path)except OSError:diff --git a/studio/backend/tests/test_video_stream_encode.py b/studio/backend/tests/test_video_stream_encode.pyindex 5b2373244f1..7b5f0e07997 100644--- a/studio/backend/tests/test_video_stream_encode.py+++ b/studio/backend/tests/test_video_stream_encode.py@@ -444,7 +444,7 @@ def test_h3_streamed_mp4_matches_the_x264_export(tmp_path):session = _h3_session(pipe)frames = _h3_render(pipe, session)assert isinstance(frames, torch.Tensor) and frames.dtype == torch.uint8- streamed = sum(len(host) for host, _ in session.chunks)+ streamed = sum(chunk.frames for chunk in session.chunks)# two clips stream while decoding; the final cross-fade tail comes from the exported clipassert 0 < streamed < len(frames)audio = _audio(len(frames))@@ -532,3 +532,148 @@ def test_encode_mp4_claims_an_h3_stream_with_its_soundtrack():with av.open(io.BytesIO(data)) as c:assert len(c.streams.audio) == 1assert vse._mp4_frame_count(data, frames.shape[1:3]) == len(frames)+++class _NoVae:+ config = None+ decoder = None+++def _spool_session(frames = 25):+ torch.manual_seed(3)+ clip = torch.rand(frames, 3, 24, 32)+ session = vse.StreamEncode(_NoVae(), None, 8)+ session._decoding = True+ for start in [0] + list(range(1, frames, 4)):+ session._push_uint8(clip[start : 1 if start == 0 else min(frames, start + 4)])+ session._decoding, session._decoded = False, True+ final = (clip * 255).round_().to(torch.uint8).permute(0, 2, 3, 1).contiguous()+ return session, final+++def _drained(session, spooled):+ import time++ deadline = time.monotonic() + 60+ while time.monotonic() < deadline:+ if all((chunk.host is None) is spooled for chunk in session.chunks):+ return True+ time.sleep(0.01)+ return False+++def test_encoded_chunks_are_spooled_and_released(tmp_path):+ session, final = _spool_session()+ assert len(session.chunks) == 7+ assert _drained(session, spooled = True)+ assert all(chunk.offset is not None for chunk in session.chunks)+ spool = session._spool+ data = session.take(final, 8)+ assert data is not None, vse.STATS["last"]+ assert len(_mp4_frames(data, tmp_path)) == len(final)+ assert spool.closed and session._spool is None++[email protected]("frame", [0, 3, -1])+def test_a_spooled_chunk_that_differs_falls_back(frame):+ session, final = _spool_session()+ assert _drained(session, spooled = True)+ final[frame, -1, -1, -1] ^= 1+ assert session.take(final, 8) is None+ assert vse.STATS["last"] == "frames differ"+++def test_shared_output_off_keeps_every_chunk(monkeypatch):+ monkeypatch.setenv(vse.SHARED_OUTPUT_ENV, "0")+ session, final = _spool_session()+ session._join()+ assert all(chunk.host is not None for chunk in session.chunks) and session._spool is None+ assert session._matches(final)+ session.close()+++def test_a_spool_that_cannot_be_written_keeps_the_chunks(monkeypatch):+ def refuse(*_a, **_k):+ raise OSError(28, "No space left on device")++ monkeypatch.setattr(vse.tempfile, "TemporaryFile", refuse)+ session, final = _spool_session()+ assert _drained(session, spooled = False)+ assert session.take(final, 8) is not None+ session, final = _spool_session()+ final[-1, 0, 0, 0] ^= 1+ assert session.take(final, 8) is None and vse.STATS["last"] == "frames differ"+++def _raw_bytes_held(session):+ """uint8 frame bytes reachable from the session's own containers, whatever shape its chunk records take."""+ seen, total, stack = set(), 0, [vars(session)]+ while stack:+ obj = stack.pop()+ if id(obj) in seen:+ continue+ seen.add(id(obj))+ if isinstance(obj, torch.Tensor):+ total += obj.numel() * obj.element_size() if obj.dtype == torch.uint8 else 0+ elif isinstance(obj, dict):+ stack.extend(obj.values())+ elif isinstance(obj, (list, tuple)):+ stack.extend(obj)+ elif hasattr(type(obj), "__slots__"):+ stack.extend(getattr(obj, name, None) for name in type(obj).__slots__)+ return total+++def test_the_session_holds_no_raw_frames_once_they_are_encoded():+ session, final = _spool_session()+ session._join()+ assert (+ _raw_bytes_held(session) == 0+ ), f"{_raw_bytes_held(session)} of {final.numel()} raw bytes still held"+ assert session._matches(final)+ session.close()+++class _FullDisk:+ """A spool whose writes are buffered and whose flush reports ENOSPC, like a filling temp filesystem."""++ def __init__(self):+ import io+ self.buf, self.closed = io.BytesIO(), False++ def write(self, data):+ return self.buf.write(data)++ def flush(self):+ raise OSError(28, "No space left on device")++ def seek(self, *a):+ raise OSError(28, "No space left on device")++ def tell(self):+ return self.buf.tell()++ def readinto(self, b):+ raise OSError(5, "Input/output error")++ def close(self):+ self.closed = True+++def test_a_spool_that_fills_on_flush_keeps_the_chunks(monkeypatch):+ monkeypatch.setattr(vse.tempfile, "TemporaryFile", lambda *a, **k: _FullDisk())+ session, final = _spool_session()+ session._join()+ assert all(chunk.host is not None for chunk in session.chunks)+ assert session._matches(final)+ session.close()+++def test_an_unreadable_spool_falls_back_instead_of_raising(monkeypatch):+ session, final = _spool_session()+ assert _drained(session, spooled = True)+ monkeypatch.setattr(+ session, "_spool_equal", lambda *a: (_ for _ in ()).throw(OSError(5, "EIO"))+ )+ assert session.take(final, 8) is None+ assert vse.STATS["last"] == "spool unreadable"diff --git a/studio/backend/tests/test_video_stream_encode_compare.py b/studio/backend/tests/test_video_stream_encode_compare.pyindex 3f1d2a47584..332f4599595 100644--- a/studio/backend/tests/test_video_stream_encode_compare.py+++ b/studio/backend/tests/test_video_stream_encode_compare.py@@ -63,7 +63,7 @@ def _session_with_chunks(chunks):config = type("C", (), {"patch_size": None})()session = vse.StreamEncode(_Vae(), None, 24)- session.chunks = [(torch.from_numpy(c), None) for c in chunks]+ session.chunks = [vse._Chunk(torch.from_numpy(c), None, len(c), spool = False) for c in chunks]return session