Skip to content

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.

35.6 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Unit tests for the disk-backed video gallery: MP4 + JSON-sidecar round-trips,
listing order, safe id handling, orphan-pair skipping, and delete/clear."""

from __future__ import annotations

import json
import os
from pathlib import Path

import core.inference.gallery_flags as gallery_flags
import core.inference.video_gallery as gallery


import pytest


@pytest.fixture(autouse = True)
def _tmp_gallery(monkeypatch, tmp_path):
    monkeypatch.setattr(gallery, "studio_root", lambda: tmp_path)


def _mp4(tag = b"\x00\x00\x00\x18ftypmp42"):
    return tag


def _meta(**over):
    base = {
        "prompt": "a sloth surfing",
        "negative_prompt": None,
        "width": 1024,
        "height": 576,
        "num_frames": 49,
        "fps": 24,
        "duration_s": 2.0,
        "steps": 30,
        "guidance": 6.0,
        "seed": 7,
        "model": "unsloth/some-video-model",
        "created_at": 100.0,
    }
    base.update(over)
    return base


def test_save_writes_pair_and_round_trips():
    record = gallery.save(_mp4(), _meta())
    assert record["id"] and record["url"].endswith(f"{record['id']}/file")

    directory = gallery.gallery_dir()
    assert (directory / f"{record['id']}.mp4").is_file()
    sidecar = directory / f"{record['id']}.json"
    assert json.loads(sidecar.read_text(encoding = "utf-8"))["prompt"] == "a sloth surfing"

    listed = gallery.list_videos()
    assert len(listed) == 1
    assert listed[0]["prompt"] == "a sloth surfing" and listed[0]["seed"] == 7
    assert listed[0]["num_frames"] == 49 and listed[0]["model"] == "unsloth/some-video-model"


def test_url_shape():
    record = gallery.save(_mp4(), _meta())
    assert record["url"] == f"/api/inference/video/gallery/{record['id']}/file"


def _save_with_mtime(prompt: str, t: float) -> dict:
    record = gallery.save(_mp4(), _meta(prompt = prompt, created_at = t))
    os.utime(gallery.gallery_dir() / f"{record['id']}.mp4", (t, t))
    return record


def test_list_is_newest_first():
    old = _save_with_mtime("old", 100.0)
    new = _save_with_mtime("new", 200.0)
    assert [r["id"] for r in gallery.list_videos()] == [new["id"], old["id"]]


def test_list_paginates_with_limit_offset():
    for i in range(5):
        _save_with_mtime(f"p{i}", float(i))
    page1 = gallery.list_videos(limit = 2, offset = 0)
    page2 = gallery.list_videos(limit = 2, offset = 2)
    assert [r["prompt"] for r in page1] == ["p4", "p3"]
    assert [r["prompt"] for r in page2] == ["p2", "p1"]
    assert len(gallery.list_videos()) == 5
    assert len(gallery.list_videos(offset = 4)) == 1


def test_listing_resolves_the_folder_once(monkeypatch):
    for i in range(4):
        _save_with_mtime(f"p{i}", float(i))
    calls = []
    real = gallery.gallery_dir
    monkeypatch.setattr(gallery, "gallery_dir", lambda: calls.append(1) or real())
    listed = gallery.list_videos()
    assert len(calls) == 1
    assert [r["prompt"] for r in listed] == ["p3", "p2", "p1", "p0"]
    assert [r["order_at"] for r in listed] == [3.0, 2.0, 1.0, 0.0]


def test_video_path_rejects_unsafe_ids():
    assert gallery.video_path("../../etc/passwd") is None
    assert gallery.video_path("/etc/passwd") is None
    assert gallery.video_path("a/b") is None
    assert gallery.video_path("missing") is None


def test_video_path_returns_mp4_for_saved_id():
    record = gallery.save(_mp4(), _meta())
    path = gallery.video_path(record["id"])
    assert path is not None and path.name == f"{record['id']}.mp4"


def test_owned_video_path_serves_only_owned_clips():
    orphan = gallery.gallery_dir() / "recording.mp4"
    orphan.write_bytes(_mp4())
    assert gallery.video_path("recording") is not None
    assert gallery.owned_video_path("recording") is None

    ours = gallery.save(_mp4(), _meta(prompt = "ours"))
    assert gallery.owned_video_path(ours["id"]) is not None
    assert gallery.owned_video_path("../../etc/passwd") is None
    assert gallery.owned_video_path("missing") is None


def test_transcode_refuses_orphan_mp4():
    orphan = gallery.gallery_dir() / "recording.mp4"
    orphan.write_bytes(_real_mp4_bytes())
    assert gallery.transcode("recording", "gif") is None
    assert gallery.transcode("recording", "webm") is None


def test_delete_removes_both_files():
    record = gallery.save(_mp4(), _meta(prompt = "a"))
    gallery.save(_mp4(), _meta(prompt = "b"))
    directory = gallery.gallery_dir()
    assert gallery.delete(record["id"]) is True
    assert not (directory / f"{record['id']}.mp4").exists()
    assert not (directory / f"{record['id']}.json").exists()
    assert gallery.delete(record["id"]) is False
    assert len(gallery.list_videos()) == 1


def test_delete_keeps_sidecar_listable_when_mp4_unlink_fails(monkeypatch):
    # delete() must remove the MP4 first, else a failed unlink hides a still-present mp4.
    record = gallery.save(_mp4(), _meta(prompt = "keep"))
    directory = gallery.gallery_dir()
    mp4 = directory / f"{record['id']}.mp4"
    sidecar = directory / f"{record['id']}.json"

    real_unlink = Path.unlink

    def _fail_on_mp4(self, *a, **k):
        if self.suffix == ".mp4":
            raise PermissionError("mp4 locked")
        return real_unlink(self, *a, **k)

    # Patch Path.unlink, not os.unlink (3.10 caches _accessor); scope keeps studio_root.
    with pytest.MonkeyPatch.context() as m:
        m.setattr(Path, "unlink", _fail_on_mp4)
        assert gallery.delete(record["id"]) is False
    assert sidecar.exists() and mp4.exists()
    assert [r["prompt"] for r in gallery.list_videos()] == ["keep"]
    assert gallery.delete(record["id"]) is True


def test_clear_returns_count():
    gallery.save(_mp4(), _meta(prompt = "a"))
    gallery.save(_mp4(), _meta(prompt = "b"))
    assert gallery.clear() == 2
    assert gallery.list_videos() == []
    assert list(gallery.gallery_dir().glob("*.json")) == []


def test_clear_uses_the_locked_folder_when_the_folder_moves_mid_clear(monkeypatch, tmp_path):
    # A Settings relocation can change gallery_dir() while clear() holds the old folder's lock.
    record = gallery.save(_mp4(), _meta(prompt = "old folder"))
    old = gallery.gallery_dir()
    new = tmp_path / "relocated"
    new.mkdir()
    (new / f"{record['id']}.json").write_text(
        json.dumps(_meta(prompt = "new folder")), encoding = "utf-8"
    )
    (new / f"{record['id']}.mp4").write_bytes(_mp4())
    calls = []

    def _moving_dir():
        calls.append(1)
        return old if len(calls) == 1 else new

    monkeypatch.setattr(gallery, "gallery_dir", _moving_dir)
    assert gallery.clear(include_archived = True, return_ids = True) == [record["id"]]
    assert not (old / f"{record['id']}.mp4").exists()
    assert not (old / f"{record['id']}.json").exists()
    assert (new / f"{record['id']}.json").exists()
    assert (new / f"{record['id']}.mp4").exists()


def test_clear_preserves_orphan_mp4():
    foreign = gallery.gallery_dir() / "recording.mp4"
    foreign.write_bytes(_mp4())
    gallery.save(_mp4(), _meta(prompt = "ours"))
    assert gallery.clear() == 1
    assert foreign.exists()
    assert gallery.list_videos() == []


def test_delete_ignores_orphan_mp4():
    foreign = gallery.gallery_dir() / "recording.mp4"
    foreign.write_bytes(_mp4())
    assert gallery.delete("recording") is False
    assert foreign.exists()


def test_list_skips_orphan_mp4_without_sidecar():
    orphan = gallery.gallery_dir() / "orphan.mp4"
    orphan.write_bytes(_mp4())
    gallery.save(_mp4(), _meta(prompt = "ours"))
    listed = gallery.list_videos()
    assert [r["prompt"] for r in listed] == ["ours"]


def test_list_skips_orphan_sidecar_without_mp4():
    orphan = gallery.gallery_dir() / "lonely.json"
    orphan.write_text(json.dumps(_meta(prompt = "no video")), encoding = "utf-8")
    gallery.save(_mp4(), _meta(prompt = "ours"))
    listed = gallery.list_videos()
    assert [r["prompt"] for r in listed] == ["ours"]


def test_orphan_mp4_in_window_does_not_drop_valid_videos():
    _save_with_mtime("p2", 100.0)
    orphan = gallery.gallery_dir() / "zzz_orphan.mp4"
    orphan.write_bytes(_mp4())
    os.utime(orphan, (300.0, 300.0))
    _save_with_mtime("p1", 200.0)
    page1 = gallery.list_videos(limit = 2, offset = 0)
    assert [r["prompt"] for r in page1] == ["p1", "p2"]


def test_list_skips_corrupt_sidecar():
    directory = gallery.gallery_dir()
    (directory / "broken.mp4").write_bytes(_mp4())
    (directory / "broken.json").write_text("{not json", encoding = "utf-8")
    gallery.save(_mp4(), _meta(prompt = "ours"))
    listed = gallery.list_videos()
    assert [r["prompt"] for r in listed] == ["ours"]


def test_list_skips_invalid_utf8_sidecar():
    directory = gallery.gallery_dir()
    (directory / "badbytes.mp4").write_bytes(_mp4())
    (directory / "badbytes.json").write_bytes(b"\xff\xfe{}")
    gallery.save(_mp4(), _meta(prompt = "ours"))
    assert [r["prompt"] for r in gallery.list_videos()] == ["ours"]


def test_clear_preserves_mp4_with_present_but_invalid_sidecar():
    directory = gallery.gallery_dir()
    (directory / "foreign.mp4").write_bytes(_mp4())
    (directory / "foreign.json").write_text("{}", encoding = "utf-8")
    gallery.save(_mp4(), _meta(prompt = "ours"))
    assert gallery.clear() == 1
    assert (directory / "foreign.mp4").exists()


def test_delete_refuses_mp4_with_present_but_invalid_sidecar():
    directory = gallery.gallery_dir()
    (directory / "foreign.mp4").write_bytes(_mp4())
    (directory / "foreign.json").write_text(json.dumps({"prompt": "x"}), encoding = "utf-8")
    assert gallery.delete("foreign") is False
    assert (directory / "foreign.mp4").exists()


def test_valid_callback_paginates_over_accepted_records():
    _save_with_mtime("BAD", 300.0)
    _save_with_mtime("g1", 200.0)
    _save_with_mtime("g2", 100.0)

    def _valid(rec):
        return rec.get("prompt") != "BAD"

    page = gallery.list_videos(limit = 2, offset = 0, valid = _valid)
    assert [r["prompt"] for r in page] == ["g1", "g2"]
    assert len(gallery.list_videos(limit = 3, offset = 0, valid = _valid)) == 2


def test_valid_callback_leading_bad_records_do_not_stall_at_offset_zero():
    for i in range(3):
        _save_with_mtime(f"BAD{i}", 300.0 - i)
    _save_with_mtime("good", 10.0)

    def _valid(rec):
        return not str(rec.get("prompt", "")).startswith("BAD")

    records = gallery.list_videos(limit = 2, offset = 0, valid = _valid)
    assert [r["prompt"] for r in records] == ["good"]


def test_save_leaves_no_orphan_mp4_when_sidecar_publish_fails(monkeypatch):
    real_replace = gallery.os.replace
    calls = {"n": 0}

    def _replace(src, dst, *a, **k):
        calls["n"] += 1
        if calls["n"] == 2:
            raise OSError("simulated sidecar failure")
        return real_replace(src, dst, *a, **k)

    monkeypatch.setattr(gallery.os, "replace", _replace)
    with pytest.raises(OSError, match = "simulated sidecar failure"):
        gallery.save(_mp4(), _meta())
    assert list(gallery.gallery_dir().iterdir()) == []
    assert gallery.list_videos() == []


def _real_mp4_bytes(
    frames: int = 8,
    size: int | tuple[int, int] = 32,
    rate: int = 8,
    codec: str = "mpeg4",
) -> bytes:
    av = pytest.importorskip("av")
    np = pytest.importorskip("numpy")
    import io

    buf = io.BytesIO()
    with av.open(buf, "w", format = "mp4") as out:
        stream = out.add_stream(codec, rate = rate)
        width, height = size if isinstance(size, tuple) else (size, size)
        stream.width = width
        stream.height = height
        stream.pix_fmt = "yuv420p"
        for i in range(frames):
            frame = av.VideoFrame.from_ndarray(
                np.full((height, width, 3), (i * 30) % 256, dtype = np.uint8), format = "rgb24"
            )
            for packet in stream.encode(frame):
                out.mux(packet)
        for packet in stream.encode():
            out.mux(packet)
    return buf.getvalue()


def _real_mp4_with_audio(
    seconds: int = 1,
    size: int = 32,
    rate: int = 8,
) -> bytes:
    av = pytest.importorskip("av")
    np = pytest.importorskip("numpy")
    import io
    import math
    from fractions import Fraction

    arate = 44100
    buf = io.BytesIO()
    with av.open(buf, "w", format = "mp4") as out:
        video = out.add_stream("mpeg4", rate = rate)
        video.width = video.height = size
        video.pix_fmt = "yuv420p"
        audio = out.add_stream("aac", rate = arate)
        audio.layout = "stereo"
        for i in range(seconds * rate):
            frame = av.VideoFrame.from_ndarray(
                np.full((size, size, 3), (i * 30) % 256, dtype = np.uint8), format = "rgb24"
            )
            for packet in video.encode(frame):
                out.mux(packet)
        written = 0
        while written < seconds * arate:
            count = min(1024, seconds * arate - written)
            tone = np.array(
                [
                    int(20000 * math.sin(2 * math.pi * 440 * (written + k) / arate))
                    for k in range(count)
                ],
                dtype = np.int16,
            )
            frame = av.AudioFrame.from_ndarray(
                np.repeat(tone, 2).reshape(1, count * 2), format = "s16", layout = "stereo"
            )
            frame.sample_rate = arate
            frame.pts = written
            frame.time_base = Fraction(1, arate)
            for packet in audio.encode(frame):
                out.mux(packet)
            written += count
        for packet in video.encode():
            out.mux(packet)
        for packet in audio.encode():
            out.mux(packet)
    return buf.getvalue()


def test_webm_export_keeps_the_audio_track():
    """WebM is offered as the web-embed format, so a clip generated with synchronized audio (LTX-2)
    must not come back mute: the exporter has to mux the track as Opus, WebM's audio codec."""
    av = pytest.importorskip("av")
    import io

    source = _real_mp4_with_audio()
    with av.open(io.BytesIO(source)) as container:
        stream = container.streams.audio[0]
        source_seconds = sum(frame.samples for frame in container.decode(stream)) / stream.rate
    record = gallery.save(source, _meta())
    webm = gallery.transcode(record["id"], "webm")
    assert webm is not None and webm[:4] == b"\x1a\x45\xdf\xa3"
    with av.open(io.BytesIO(webm)) as container:
        kinds = {(s.type, s.codec_context.name) for s in container.streams}
    assert ("video", "vp9") in kinds
    assert ("audio", "opus") in kinds
    samples = 0
    with av.open(io.BytesIO(webm)) as container:
        for frame in container.decode(audio = 0):
            samples += frame.samples
    # Allow one 20 ms Opus frame; PyAV AAC padding varies, so compare the decoded source.
    assert samples >= source_seconds * 48000 - 960, (samples, source_seconds)


def test_webm_export_still_works_without_an_audio_encoder(monkeypatch):
    av = pytest.importorskip("av")
    import io

    # Wrap av.open() instead of patching add_stream: PyAV 17 types are immutable.
    real_open = av.open

    class _NoOpusContainer:
        """Delegates to the real output container, but refuses the Opus encoder."""

        def __init__(self, inner):
            self._inner = inner

        def add_stream(
            self,
            codec_name = None,
            *args,
            **kwargs,
        ):
            if codec_name == "libopus":
                raise ValueError("unknown encoder 'libopus'")
            return self._inner.add_stream(codec_name, *args, **kwargs)

        def __getattr__(self, name):
            return getattr(self._inner, name)

        def __enter__(self):
            self._inner.__enter__()
            return self

        def __exit__(self, *exc):
            return self._inner.__exit__(*exc)

    def _open(
        file,
        mode = "r",
        *args,
        **kwargs,
    ):
        inner = real_open(file, mode, *args, **kwargs)
        return _NoOpusContainer(inner) if mode == "w" else inner

    monkeypatch.setattr(av, "open", _open)
    record = gallery.save(_real_mp4_with_audio(), _meta())
    webm = gallery.transcode(record["id"], "webm")
    assert webm is not None and webm[:4] == b"\x1a\x45\xdf\xa3"
    with av.open(io.BytesIO(webm)) as container:
        assert [s.type for s in container.streams] == ["video"]


def test_transcode_gif_and_webm_produce_real_containers():
    record = gallery.save(_real_mp4_bytes(), _meta())
    gif = gallery.transcode(record["id"], "gif")
    assert gif is not None and gif.startswith(b"GIF8")
    webm = gallery.transcode(record["id"], "webm")
    assert webm is not None and webm[:4] == b"\x1a\x45\xdf\xa3"


def test_webm_export_keeps_every_frame_of_an_h264_clip():
    av = pytest.importorskip("av")
    import io

    record = gallery.save(_real_mp4_bytes(frames = 25, codec = "libx264"), _meta())
    webm = gallery.transcode(record["id"], "webm")
    with av.open(io.BytesIO(webm)) as container:
        assert sum(1 for _ in container.decode(video = 0)) == 25


def test_thumbnail_produces_a_webp_from_the_video():
    import io

    Image = pytest.importorskip("PIL.Image")
    record = gallery.save(_real_mp4_bytes(frames = 3, size = 64), _meta())
    thumbnail = gallery.thumbnail(record["id"])

    assert thumbnail is not None
    assert thumbnail[:4] == b"RIFF" and thumbnail[8:12] == b"WEBP"
    with Image.open(io.BytesIO(thumbnail)) as image:
        assert image.format == "WEBP"
        assert image.size == (64, 64)


def test_thumbnail_scales_large_frames_to_gallery_width():
    import io

    Image = pytest.importorskip("PIL.Image")
    record = gallery.save(_real_mp4_bytes(frames = 1, size = (320, 180)), _meta())

    with Image.open(io.BytesIO(gallery.thumbnail(record["id"]))) as image:
        assert image.size == (192, 108)

    portrait = gallery.save(_real_mp4_bytes(frames = 1, size = (320, 568)), _meta())
    with Image.open(io.BytesIO(gallery.thumbnail(portrait["id"]))) as image:
        assert image.size == (192, 341)


def test_thumbnail_refuses_frames_past_max_pixels_even_when_the_header_understates_them():
    import io

    av = pytest.importorskip("av")
    clip = _real_mp4_bytes(frames = 2, size = 256)
    lying = io.BytesIO()
    with av.open(io.BytesIO(clip)) as src, av.open(lying, "w", format = "mp4") as out:
        stream = out.add_stream("mpeg4", rate = 8)
        stream.width = stream.height = 16
        stream.pix_fmt = "yuv420p"
        for packet in src.demux(src.streams.video[0]):
            if packet.dts is not None:
                packet.stream = stream
                out.mux(packet)
    assert gallery.first_frame_webp(io.BytesIO(clip), container = "mp4", max_pixels = 2 * 256 * 256)
    for data in (clip, lying.getvalue()):
        with pytest.raises(RuntimeError):
            gallery.first_frame_webp(io.BytesIO(data), container = "mp4", max_pixels = 128 * 128)


def test_thumbnail_rejects_unowned_and_invalid_videos():
    assert gallery.thumbnail("does-not-exist") is None
    record = gallery.save(_mp4(), _meta())
    with pytest.raises(RuntimeError, match = "Thumbnail generation failed"):
        gallery.thumbnail(record["id"])


def test_transcode_unknown_id_and_bad_format():
    assert gallery.transcode("does-not-exist", "gif") is None
    record = gallery.save(_real_mp4_bytes(), _meta())
    with pytest.raises(ValueError):
        gallery.transcode(record["id"], "avi")


def test_transcode_to_file_writes_a_temp_file_the_caller_owns():
    record = gallery.save(_real_mp4_bytes(), _meta())
    for fmt, magic in (("webm", b"\x1a\x45\xdf\xa3"), ("gif", b"GIF8")):
        path = gallery.transcode_to_file(record["id"], fmt)
        assert path is not None and path.is_file(), fmt
        assert path.suffix == f".{fmt}"
        assert path.read_bytes()[: len(magic)] == magic
        path.unlink()
        assert gallery.video_path(record["id"]) is not None
    assert gallery.transcode_to_file("does-not-exist", "webm") is None


def test_transcode_to_file_leaves_no_temp_file_when_the_encode_fails(monkeypatch, tmp_path):
    import tempfile

    from core.inference import video_gallery as vg

    record = gallery.save(_real_mp4_bytes(), _meta())

    written: list[Path] = []

    def _boom(src, dest):
        dest.write_bytes(b"partial")
        written.append(Path(dest))
        raise RuntimeError("WebM export failed (libvpx-vp9 unavailable?)")

    monkeypatch.setattr(vg, "_transcode_webm", _boom)
    # Export into a test-owned dir; the shared temp dir sees other workers' exports.
    exports = tmp_path / "exports"
    exports.mkdir()
    monkeypatch.setattr(tempfile, "tempdir", str(exports))

    with pytest.raises(RuntimeError):
        vg.transcode_to_file(record["id"], "webm")

    # Without the temp file existing first, the absence check below is vacuous.
    assert written, "the export never created its temp file, so the check below is vacuous"
    assert not written[0].exists(), f"{written[0].name} survived the failed encode"
    assert (
        list(exports.iterdir()) == []
    ), f"the failed export left {[p.name for p in exports.iterdir()]} behind"


def test_gif_export_bounds_frames_and_edge(monkeypatch):
    """Every kept frame is held as a paletted image before encoding, so an unbounded walk is a
    memory bomb: 2048x2048 x 1024 frames at a 12 fps target is over 4 GB; cap both axes."""
    import io as _io

    from core.inference import video_gallery as vg

    Image = pytest.importorskip("PIL.Image")
    monkeypatch.setattr(vg, "_GIF_MAX_EDGE", 16)
    monkeypatch.setattr(vg, "_GIF_MAX_FRAMES", 4)

    record = gallery.save(_real_mp4_bytes(frames = 24, size = 64, rate = 12), _meta())
    gif = vg._transcode_gif(vg.gallery_dir() / f"{record['id']}.mp4")

    assert gif.startswith(b"GIF8")
    with Image.open(_io.BytesIO(gif)) as im:
        assert max(im.size) <= 16, im.size
        frames = 1
        try:
            while True:
                im.seek(im.tell() + 1)
                frames += 1
        except EOFError:
            pass
    assert frames <= 4, frames


def _gif_blocks(data: bytes) -> dict:
    """Walk a GIF's blocks: loop count, per-frame delays (cs) and whether each frame carries a local palette."""
    assert data[:6] in (b"GIF87a", b"GIF89a")
    width, height, packed = (
        int.from_bytes(data[6:8], "little"),
        int.from_bytes(data[8:10], "little"),
        data[10],
    )
    pos = 13 + (3 << ((packed & 7) + 1) if packed & 0x80 else 0)
    info = {
        "size": (width, height),
        "global_palette": bool(packed & 0x80),
        "loop": None,
        "delays": [],
        "local": [],
    }

    def _skip_sub_blocks(i: int) -> int:
        while data[i]:
            i += data[i] + 1
        return i + 1

    while data[pos] != 0x3B:
        if data[pos] == 0x21:
            label = data[pos + 1]
            if label == 0xF9:
                info["delays"].append(int.from_bytes(data[pos + 4 : pos + 6], "little"))
            elif label == 0xFF and data[pos + 3 : pos + 14] == b"NETSCAPE2.0":
                info["loop"] = int.from_bytes(data[pos + 16 : pos + 18], "little")
            pos = _skip_sub_blocks(pos + 2)
        elif data[pos] == 0x2C:
            flags = data[pos + 9]
            info["local"].append(bool(flags & 0x80))
            pos += 10 + (3 << ((flags & 7) + 1) if flags & 0x80 else 0)
            pos = _skip_sub_blocks(pos + 1)
        else:
            raise AssertionError(f"bad GIF block 0x{data[pos]:02x} at {pos}")
    return info


def _gradient_mp4_bytes(frames: int, size: tuple[int, int], rate: int) -> bytes:
    av = pytest.importorskip("av")
    np = pytest.importorskip("numpy")
    import io

    width, height = size
    yy, xx = np.mgrid[0:height, 0:width]
    buf = io.BytesIO()
    with av.open(buf, "w", format = "mp4") as out:
        stream = out.add_stream("mpeg4", rate = rate)
        stream.width, stream.height, stream.pix_fmt = width, height, "yuv420p"
        for i in range(frames):
            rgb = np.stack(
                [
                    (xx * 255 // width + i * 7) % 256,
                    (yy * 255 // height) % 256,
                    (xx + yy + i * 11) % 256,
                ],
                axis = -1,
            ).astype(np.uint8)
            for packet in stream.encode(av.VideoFrame.from_ndarray(rgb, format = "rgb24")):
                out.mux(packet)
        for packet in stream.encode():
            out.mux(packet)
    return buf.getvalue()


def _count_calls(monkeypatch, module, name: str) -> dict:
    calls = {"n": 0}
    real = getattr(module, name)

    def _spy(*args, **kwargs):
        calls["n"] += 1
        return real(*args, **kwargs)

    monkeypatch.setattr(module, name, _spy)
    return calls


@pytest.mark.parametrize("hold", [True, False], ids = ["held_frames", "two_decode_passes"])
def test_gif_export_uses_one_clip_wide_palette(monkeypatch, hold):
    from core.inference import video_gallery as vg

    pytest.importorskip("PIL.Image")
    if not vg._gif_palette_supported():
        pytest.skip("this PyAV build has no palettegen / paletteuse / gif encoder")
    if not hold:
        monkeypatch.setattr(vg, "_GIF_HOLD_BYTES", 0)
    palette_calls = _count_calls(monkeypatch, vg, "_transcode_gif_palette")
    pillow_calls = _count_calls(monkeypatch, vg, "_transcode_gif_pillow")
    decodes = _count_calls(monkeypatch, vg, "_gif_scaled_frames")

    record = gallery.save(_gradient_mp4_bytes(frames = 24, size = (96, 64), rate = 24), _meta())
    gif = vg._transcode_gif(vg.gallery_dir() / f"{record['id']}.mp4")

    assert palette_calls["n"] == 1 and pillow_calls["n"] == 0
    assert decodes["n"] == (1 if hold else 2)
    info = _gif_blocks(gif)
    assert info["size"] == (96, 64)
    assert info["global_palette"] and not any(info["local"][1:]), info["local"]
    assert len(info["local"]) == 12
    assert info["loop"] == 0  # NETSCAPE loop 0 = forever
    assert all(d in (8, 9) for d in info["delays"]), info["delays"]
    assert sum(info["delays"]) in (99, 100, 101)


_GIF_PEAK_RSS_SCRIPT = r"""
from fractions import Fraction
import av, numpy as np
import core.inference.video_gallery as vg

vg._GIF_HOLD_BYTES = 0
side, n = 720, 300
rgb = np.zeros((side, side, 3), np.uint8)
rgb[..., 0] = np.arange(side, dtype = np.uint8)[None, :]


def _frames(path, step, width, height):
    for _ in range(n):
        yield av.VideoFrame.from_ndarray(rgb, format = "rgb24")


def _peak_kib():
    # VmHWM is per address space; ru_maxrss would carry over the forking parent's peak
    with open("/proc/self/status") as f:
        return int(next(line for line in f if line.startswith("VmHWM:")).split()[1])


vg._gif_scaled_frames = _frames
before = _peak_kib()
gif = vg._transcode_gif_palette(None, Fraction(12), 1, side, side, n)
assert gif.startswith(b"GIF8")
print((_peak_kib() - before) // 1024)
"""


def test_gif_export_two_pass_does_not_queue_the_clip_in_palettegen():
    """With frames over _GIF_HOLD_BYTES the palette pass must not hold them either: 300 720p frames are 445 MiB if
    FFmpeg queues them all before palettegen sees EOF."""
    import subprocess
    import sys

    from core.inference import video_gallery as vg

    pytest.importorskip("numpy")
    if not os.path.exists("/proc/self/status"):
        pytest.skip("peak RSS is read from /proc/self/status (Linux only)")
    if not vg._gif_palette_supported():
        pytest.skip("this PyAV build has no palettegen / paletteuse / gif encoder")
    backend = Path(vg.__file__).resolve().parents[2]
    result = subprocess.run(
        [sys.executable, "-c", _GIF_PEAK_RSS_SCRIPT],
        cwd = backend,
        env = {**os.environ, "PYTHONPATH": str(backend)},
        capture_output = True,
        text = True,
        timeout = 300,
    )
    assert result.returncode == 0, result.stderr[-2000:]
    growth_mib = int(result.stdout.split()[-1])
    assert growth_mib < 160, f"peak RSS grew {growth_mib} MiB"


def test_gif_export_palette_path_caps_frames_and_edge(monkeypatch):
    from core.inference import video_gallery as vg

    if not vg._gif_palette_supported():
        pytest.skip("this PyAV build has no palettegen / paletteuse / gif encoder")
    monkeypatch.setattr(vg, "_GIF_MAX_EDGE", 48)
    monkeypatch.setattr(vg, "_GIF_MAX_FRAMES", 5)
    record = gallery.save(_gradient_mp4_bytes(frames = 30, size = (96, 64), rate = 12), _meta())
    info = _gif_blocks(vg._transcode_gif(vg.gallery_dir() / f"{record['id']}.mp4"))
    assert info["size"] == (48, 32)
    assert 1 <= len(info["local"]) <= 5
    assert info["loop"] == 0


def test_gif_export_falls_back_to_pillow_without_the_palette_filters(monkeypatch):
    import av.filter

    from core.inference import video_gallery as vg

    pytest.importorskip("PIL.Image")
    monkeypatch.setattr(
        av.filter,
        "filters_available",
        set(av.filter.filters_available) - {"palettegen", "paletteuse"},
    )
    assert vg._gif_palette_supported() is False
    palette_calls = _count_calls(monkeypatch, vg, "_transcode_gif_palette")
    pillow_calls = _count_calls(monkeypatch, vg, "_transcode_gif_pillow")

    record = gallery.save(_gradient_mp4_bytes(frames = 24, size = (96, 64), rate = 24), _meta())
    info = _gif_blocks(vg._transcode_gif(vg.gallery_dir() / f"{record['id']}.mp4"))

    assert palette_calls["n"] == 0 and pillow_calls["n"] == 1
    assert info["size"] == (96, 64) and len(info["local"]) == 12 and info["loop"] == 0
    assert all(d == 8 for d in info["delays"]), info["delays"]


def test_gif_export_falls_back_to_pillow_without_a_gif_encoder(monkeypatch):
    import av.codec

    from core.inference import video_gallery as vg

    pytest.importorskip("PIL.Image")
    real_codec = av.codec.Codec

    def _decoder_only(name, mode = "r"):
        if name == "gif" and mode == "w":
            raise av.codec.codec.UnknownCodecError(name)
        return real_codec(name, mode)

    monkeypatch.setattr(av.codec, "Codec", _decoder_only)
    assert "gif" in av.codecs_available
    assert vg._gif_palette_supported() is False
    pillow_calls = _count_calls(monkeypatch, vg, "_transcode_gif_pillow")

    record = gallery.save(_gradient_mp4_bytes(frames = 24, size = (96, 64), rate = 24), _meta())
    info = _gif_blocks(vg._transcode_gif(vg.gallery_dir() / f"{record['id']}.mp4"))

    assert pillow_calls["n"] == 1 and info["loop"] == 0


def test_gif_export_missing_deps_keeps_the_error_message(monkeypatch):
    import builtins

    from core.inference import video_gallery as vg

    real_import = builtins.__import__

    def _no_av(name, *args, **kwargs):
        if name == "av" or name.startswith("av."):
            raise ImportError("no av")
        return real_import(name, *args, **kwargs)

    monkeypatch.setattr(builtins, "__import__", _no_av)
    with pytest.raises(RuntimeError, match = "GIF export needs the 'av' and 'Pillow' packages."):
        vg._transcode_gif(vg.gallery_dir() / "missing.mp4")


# --- pin / archive flags ---------------------------------------------------------------------


def test_records_carry_default_flags():
    _save_with_mtime("a", 100.0)
    record = gallery.list_videos()[0]
    assert record["pinned"] is False and record["archived"] is False


def test_pinned_videos_sort_ahead_of_newer_ones():
    old = _save_with_mtime("old", 100.0)
    _save_with_mtime("new", 200.0)
    gallery.set_flags(old["id"], pinned = True)
    assert [r["prompt"] for r in gallery.list_videos()] == ["old", "new"]
    assert gallery.list_videos()[0]["pinned"] is True


def test_most_recently_pinned_leads_the_pinned_group():
    first = _save_with_mtime("first", 100.0)
    second = _save_with_mtime("second", 200.0)
    gallery.set_flags(second["id"], pinned = True)
    gallery.set_flags(first["id"], pinned = True)
    assert [r["prompt"] for r in gallery.list_videos()] == ["first", "second"]


def test_unpinning_returns_a_video_to_newest_first_order():
    old = _save_with_mtime("old", 100.0)
    _save_with_mtime("new", 200.0)
    gallery.set_flags(old["id"], pinned = True)
    gallery.set_flags(old["id"], pinned = False)
    assert [r["prompt"] for r in gallery.list_videos()] == ["new", "old"]


def test_archived_videos_leave_the_default_listing():
    keep = _save_with_mtime("keep", 100.0)
    shelved = _save_with_mtime("shelved", 200.0)
    gallery.set_flags(shelved["id"], archived = True)
    assert [r["id"] for r in gallery.list_videos()] == [keep["id"]]
    archived = gallery.list_videos(archived = True)
    assert [r["id"] for r in archived] == [shelved["id"]]
    assert archived[0]["archived"] is True


def test_restoring_puts_a_video_back_on_the_strip():
    record = _save_with_mtime("a", 100.0)
    gallery.set_flags(record["id"], archived = True)
    gallery.set_flags(record["id"], archived = False)
    assert [r["id"] for r in gallery.list_videos()] == [record["id"]]


def test_archived_videos_do_not_consume_a_page_slot():
    for i in range(4):
        record = _save_with_mtime(f"a{i}", 100.0 + i)
        if i % 2 == 0:
            gallery.set_flags(record["id"], archived = True)
    assert [r["prompt"] for r in gallery.list_videos(limit = 2)] == ["a3", "a1"]
    assert len(gallery.list_videos(limit = 3)) == 2
    assert [r["prompt"] for r in gallery.list_videos(archived = True)] == ["a2", "a0"]


def test_pinning_survives_pagination():
    oldest = _save_with_mtime("oldest", 100.0)
    for i in range(1, 4):
        _save_with_mtime(f"a{i}", 100.0 + i)
    gallery.set_flags(oldest["id"], pinned = True)
    assert gallery.list_videos(limit = 1, offset = 0)[0]["prompt"] == "oldest"


def test_set_flags_refuses_a_foreign_or_unknown_id():
    assert gallery.set_flags("does-not-exist", pinned = True) is None
    orphan = gallery.gallery_dir() / "orphan.mp4"
    orphan.write_bytes(_mp4())
    assert gallery.set_flags("orphan", pinned = True) is None


def test_delete_prunes_the_flag_entry():
    record = _save_with_mtime("a", 100.0)
    gallery.set_flags(record["id"], pinned = True)
    assert gallery.delete(record["id"]) is True
    assert gallery_flags.read(gallery.gallery_dir()) == {}


def test_clear_spares_archived_videos():
    active = _save_with_mtime("active", 100.0)
    shelved = _save_with_mtime("shelved", 200.0)
    gallery.set_flags(shelved["id"], archived = True)
    assert gallery.clear() == 1
    assert [r["id"] for r in gallery.list_videos(archived = True)] == [shelved["id"]]
    assert set(gallery_flags.read(gallery.gallery_dir())) == {shelved["id"]}
    assert gallery.video_path(active["id"]) is None


def test_clear_can_include_archived_videos():
    record = _save_with_mtime("shelved", 100.0)
    gallery.set_flags(record["id"], archived = True)
    assert gallery.clear(include_archived = True) == 1
    assert gallery.list_videos(archived = True) == []
    assert gallery_flags.read(gallery.gallery_dir()) == {}


def test_flags_are_not_required_sidecar_keys():
    record = _save_with_mtime("older-schema", 100.0)
    sidecar = gallery.gallery_dir() / f"{record['id']}.json"
    assert "pinned" not in json.loads(sidecar.read_text(encoding = "utf-8"))
    assert [r["id"] for r in gallery.list_videos()] == [record["id"]]


def test_clear_refuses_when_the_flag_store_cannot_be_read():
    record = _save_with_mtime("shelved", 100.0)
    gallery.set_flags(record["id"], archived = True)
    (gallery.gallery_dir() / ".flags.json").write_text("corrupt", encoding = "utf-8")
    with pytest.raises(gallery_flags.FlagsUnavailable):
        gallery.clear()
    assert gallery.video_path(record["id"]) is not None


def test_clear_all_still_works_with_an_unreadable_store():
    record = _save_with_mtime("a", 100.0)
    (gallery.gallery_dir() / ".flags.json").write_text("corrupt", encoding = "utf-8")
    assert gallery.clear(include_archived = True) == 1
    assert gallery.video_path(record["id"]) is None


def test_clear_all_replaces_an_unreadable_store_so_the_gallery_recovers():
    _save_with_mtime("a", 100.0)
    _save_with_mtime("b", 200.0)
    (gallery.gallery_dir() / ".flags.json").write_text(
        '{"version": 1, "items": {"a": {"archi', encoding = "utf-8"
    )
    assert gallery.clear(include_archived = True) == 2
    _save_with_mtime("c", 300.0)
    assert gallery.clear() == 1