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.

18.9 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

"""The audio.cpp catalog builder: online, offline from the saved listing, cache-only, cached."""

import json
import re
import threading
import time

import pytest

from core.inference import audio_cpp_catalog as catalog
from core.inference import audio_cpp_files, audio_cpp_server
from core.inference import audio_cpp_models as acm
from core.inference.audio_cpp_models import AUDIO_CPP_REPO, AudioCppHeader, RepoFile
from hub.utils import state_dir

DRAMA_SPEC = {
    "family": "fish_drama3",
    "display_name": "Fish Audio Drama 3",
    "description": "Drama 3 speech generation and voice cloning.",
    "status": "experimental",
    "tasks": ["tts", "clone"],
    "languages": ["auto"],
    "ui": {"recommended_package": "q4"},
    "package_defaults": {"download": {"repo": "Jmica/Drama-3-GGUF"}},
    "packages": [
        {"id": "q4", "default": True, "format": "gguf", "files": ["drama-3-Q4_K_S.gguf"]},
        {"id": "src", "format": "safetensors", "files": ["model.safetensors"]},
    ],
}
KOKORO_SPEC = {
    "family": "kokoro_tts",
    "display_name": "Kokoro 82M",
    "status": "community",
    "tasks": ["tts"],
    "languages": ["en-us", "zh"],
    "package_defaults": {"download": {"repo": AUDIO_CPP_REPO}},
    "packages": [
        {
            "id": "kokoro_q8",
            "default": True,
            "format": "gguf",
            "target_directory": "Kokoro-82M-GGUF",
            "files": ["Kokoro-82M-GGUF/kokoro-82m-q8_0.gguf"],
        }
    ],
}
NEW_TTS = AudioCppHeader("audiocpp", "new_tts", {"family": "new_tts", "tasks": ["tts", "clone"]})
UMBRELLA = [
    RepoFile("Kokoro-82M-GGUF/kokoro-82m-q8_0.gguf", 100),
    RepoFile("Kokoro-82M-GGUF/kokoro-82m-bf16.gguf", 200),
    RepoFile("Kokoro-82M-GGUF/README.md", 5),
    RepoFile("New-TTS-GGUF/new-tts-q8_0.gguf", 300),
    RepoFile("HTDemucs-GGUF/htdemucs-f16.gguf", 400),
    RepoFile("README.md", 1),
]
DRAMA = [RepoFile("drama-3-Q4_K_S.gguf", 7000), RepoFile("drama-3-Q2_K.gguf", 5000)]


@pytest.fixture
def env(tmp_path, monkeypatch):
    hub_root = tmp_path / "hub"
    hub_root.mkdir()
    monkeypatch.setattr(acm, "_hub_cache", lambda: hub_root)
    monkeypatch.setattr(audio_cpp_files, "_hub_cache", lambda: hub_root)
    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "studio-cache")
    monkeypatch.setattr(acm, "runtime_knows_family", lambda family: None)
    monkeypatch.setattr(acm, "_listing_cache", {})
    monkeypatch.setenv("HF_HUB_OFFLINE", "0")
    calls = {"hub": 0, "header": 0}
    umbrella = list(UMBRELLA)

    def listing(repo_id, folder, token):
        calls["hub"] += 1
        assert token is None and folder == ""
        return list(umbrella if repo_id == AUDIO_CPP_REPO else DRAMA)

    def header(
        repo_id,
        filename,
        hf_token = None,
        *,
        size = None,
    ):
        calls["header"] += 1
        assert hf_token is False
        return NEW_TTS if filename.startswith("New-TTS-GGUF/") else None

    monkeypatch.setattr(acm, "_hub_listing", listing)
    monkeypatch.setattr(acm, "read_remote_header", header)
    runtime = tmp_path / "runtime"
    (runtime / "bin").mkdir(parents = True)
    specs = runtime / "model_specs"
    specs.mkdir()
    (specs / "fish_drama3.json").write_text(json.dumps(DRAMA_SPEC))
    (specs / "kokoro_tts.json").write_text(json.dumps(KOKORO_SPEC))
    (specs / "Bad Name.json").write_text("{not json")
    binary = str(runtime / "bin" / "audiocpp_server")
    monkeypatch.setattr(audio_cpp_server, "find_audio_cpp_server_binary", lambda: binary)
    catalog.forget_audio_catalog()
    acm.forget()
    yield {"tmp": tmp_path, "hub": hub_root, "specs": specs, "calls": calls, "umbrella": umbrella}
    catalog.forget_audio_catalog()
    acm.forget()


def _rows(payload):
    return {m.id: m for m in payload.models}


def _saved_file(env):
    return env["tmp"] / "studio-cache" / state_dir._HUB_STATE_DIRNAME / "audio_cpp_catalog.json"


def _assert_safe(env, payload):
    text = json.dumps(payload.model_dump())
    assert str(env["tmp"]) not in text
    assert not re.search(r'"(/|[A-Za-z]:\\\\)[^"]*"', text)
    for m in payload.models:
        assert not re.search(r"(?<!Unsloth )Studio", m.unsupported_reason or "")
        assert (m.unsupported_reason is None) == bool(m.workflows)


def test_online_lists_umbrella_folders_spec_families_and_community_repos(env):
    payload = catalog.audio_catalog_payload()
    assert payload.source == "hub" and payload.runtime_specs
    rows = _rows(payload)
    kokoro = rows[f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"]
    assert kokoro.workflows == ["speak"] and kokoro.display_name == "Kokoro 82M"
    assert kokoro.languages == ["en-us", "zh"] and kokoro.status == "community"
    assert kokoro.size_bytes == 100 and kokoro.source == "umbrella"
    assert rows[f"{AUDIO_CPP_REPO}/New-TTS-GGUF"].workflows == ["speak", "clone"]
    assert rows[f"{AUDIO_CPP_REPO}/HTDemucs-GGUF"].workflows == ["separate"]
    drama = rows["Jmica/Drama-3-GGUF"]
    assert drama.source == "community" and drama.folder == "" and drama.family == "fish_drama3"
    assert drama.languages is None and drama.status == "experimental"
    assert drama.size_bytes == 7000
    assert [m.source for m in payload.models].count("community") == 1
    saved = json.loads(_saved_file(env).read_text())
    assert saved["schema"] == 1
    assert saved["folders"]["New-TTS-GGUF"]["family"] == "new_tts"
    assert "README.md" not in json.dumps(saved)
    _assert_safe(env, payload)


def test_offline_reads_the_saved_listing_without_the_hub(env, monkeypatch):
    online = _rows(catalog.audio_catalog_payload())
    catalog.forget_audio_catalog()
    monkeypatch.setenv("HF_HUB_OFFLINE", "1")
    env["calls"].update(hub = 0, header = 0)
    payload = catalog.audio_catalog_payload()
    assert payload.source == "saved"
    assert set(_rows(payload)) == set(online)
    assert _rows(payload)[f"{AUDIO_CPP_REPO}/New-TTS-GGUF"].workflows == ["speak", "clone"]
    assert env["calls"] == {"hub": 0, "header": 0}
    _assert_safe(env, payload)


def _kokoro_on_disk(env):
    repo = env["hub"] / ("models--" + AUDIO_CPP_REPO.replace("/", "--"))
    gguf = repo / "snapshots" / ("a" * 40) / "Kokoro-82M-GGUF" / "kokoro-82m-q8_0.gguf"
    gguf.parent.mkdir(parents = True)
    gguf.write_bytes(b"x")
    (repo / "refs").mkdir()
    (repo / "refs" / "main").write_text("a" * 40)


def test_offline_without_a_saved_listing_lists_the_cached_folders(env, monkeypatch):
    monkeypatch.setenv("HF_HUB_OFFLINE", "1")
    _kokoro_on_disk(env)
    payload = catalog.audio_catalog_payload()
    assert payload.source == "cache"
    umbrella = [m for m in payload.models if m.source == "umbrella"]
    assert [m.folder for m in umbrella] == ["Kokoro-82M-GGUF"]
    assert umbrella[0].downloaded and umbrella[0].workflows == ["speak"]
    assert env["calls"] == {"hub": 0, "header": 0}
    _assert_safe(env, payload)


def test_a_saved_listing_deleted_mid_run_degrades_to_the_cache(env, monkeypatch):
    catalog.audio_catalog_payload()
    catalog.forget_audio_catalog()
    monkeypatch.setenv("HF_HUB_OFFLINE", "1")
    _kokoro_on_disk(env)
    _saved_file(env).unlink()
    assert catalog.audio_catalog_payload().source == "cache"
    catalog.forget_audio_catalog()
    _saved_file(env).write_text('{"schema": 1, "folders": {"X": {"files": "bad"}}}')
    assert catalog.audio_catalog_payload().source == "cache"


def test_the_catalog_is_cached_and_a_degraded_answer_is_retried_sooner(env, monkeypatch):
    clock = [1000.0]
    monkeypatch.setattr(catalog.time, "monotonic", lambda: clock[0])
    catalog.audio_catalog_payload()
    hub_calls = env["calls"]["hub"]
    catalog.audio_catalog_payload()
    clock[0] += 299
    catalog.audio_catalog_payload()
    assert env["calls"]["hub"] == hub_calls
    catalog.forget_audio_catalog()
    acm._listing_cache.clear()
    catalog.audio_catalog_payload()
    assert env["calls"]["hub"] > hub_calls

    def down(repo_id, *_a):
        env["calls"]["hub"] += repo_id == AUDIO_CPP_REPO
        raise OSError("Hub down")

    monkeypatch.setattr(acm, "_hub_listing", down)
    catalog.forget_audio_catalog()
    acm._listing_cache.clear()
    env["calls"]["hub"] = 0
    assert catalog.audio_catalog_payload().source == "saved"
    clock[0] += 29
    catalog.audio_catalog_payload()
    assert env["calls"]["hub"] == 1
    clock[0] += 2
    catalog.audio_catalog_payload()
    assert env["calls"]["hub"] == 2


def test_without_runtime_specs_folders_resolve_by_bounded_header_probes(env, monkeypatch):
    for f in env["specs"].iterdir():
        f.unlink()
    env["specs"].rmdir()
    monkeypatch.setattr(acm, "runtime_spec", lambda family: None)
    many = [RepoFile(f"Mystery-{i:02d}-GGUF/mystery-{i:02d}-q8_0.gguf", 10) for i in range(40)]
    env["umbrella"].extend(many)
    payload = catalog.audio_catalog_payload()
    assert payload.runtime_specs is False
    assert all(m.source == "umbrella" for m in payload.models)
    assert env["calls"]["header"] <= catalog._MAX_PROBES
    rows = _rows(payload)
    assert rows[f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"].workflows == ["speak"]
    assert rows[f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"].display_name == "Kokoro-82M-GGUF"
    mystery = [m for m in payload.models if m.folder.startswith("Mystery-")]
    assert len(mystery) == 40 and not mystery[0].workflows
    assert mystery[0].unsupported_reason == catalog._NO_FAMILY
    _assert_safe(env, payload)


def test_a_name_hint_whose_spec_places_other_folders_falls_back_to_the_header(env, monkeypatch):
    # "Kokoro" hints kokoro_tts, whose runtime spec places Kokoro-82M-GGUF only.
    env["umbrella"].append(RepoFile("Kokoro-Next-GGUF/kokoro-next-q8_0.gguf", 50))
    probe = acm.read_remote_header
    other = AudioCppHeader("audiocpp", "other_tts", {"family": "other_tts", "tasks": ["tts"]})
    monkeypatch.setattr(
        acm,
        "read_remote_header",
        lambda repo_id, filename, hf_token = None, *, size = None: (
            other
            if filename.startswith("Kokoro-Next-GGUF/")
            else probe(repo_id, filename, hf_token, size = size)
        ),
    )
    monkeypatch.setattr(acm, "runtime_knows_family", lambda family: family != "other_tts")
    rows = _rows(catalog.audio_catalog_payload())
    assert acm.family_from_names(("Kokoro-Next-GGUF",)) == "kokoro_tts"
    row = rows[f"{AUDIO_CPP_REPO}/Kokoro-Next-GGUF"]
    assert row.family == "other_tts" and not row.workflows
    assert "needs a newer audio runtime" in row.unsupported_reason
    assert rows[f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"].workflows == ["speak"]


def test_a_header_family_a_spec_places_elsewhere_survives_offline(env, monkeypatch):
    # Phonon-2-GGUF's header says parakeet_tdt, whose runtime spec places another folder only.
    env["umbrella"].append(RepoFile("Phonon-GGUF/phonon-q8.gguf", 50))
    probe = acm.read_remote_header
    kokoro = AudioCppHeader("audiocpp", "kokoro_tts", {"family": "kokoro_tts", "tasks": ["tts"]})
    monkeypatch.setattr(
        acm,
        "read_remote_header",
        lambda repo_id, filename, hf_token = None, *, size = None: (
            kokoro
            if filename.startswith("Phonon-GGUF/")
            else probe(repo_id, filename, hf_token, size = size)
        ),
    )
    online = _rows(catalog.audio_catalog_payload())[f"{AUDIO_CPP_REPO}/Phonon-GGUF"]
    assert online.family == "kokoro_tts" and online.workflows == ["speak"]
    catalog.forget_audio_catalog()
    monkeypatch.setenv("HF_HUB_OFFLINE", "1")
    env["calls"].update(hub = 0, header = 0)
    payload = catalog.audio_catalog_payload()
    assert payload.source == "saved" and env["calls"]["header"] == 0
    offline = _rows(payload)[f"{AUDIO_CPP_REPO}/Phonon-GGUF"]
    assert offline.family == "kokoro_tts" and offline.workflows == ["speak"]


def test_a_community_repo_several_specs_download_from_is_not_listed(env):
    # mirek190/audio.cpp holds GLM-TTS, Hviske and OuteTTS: its bare id resolves to one of them.
    for family, files in (("glm_tts", ["GLM-TTS_Q8.gguf"]), ("hviske_asr", ["hviske_Q8.gguf"])):
        spec = {
            "family": family,
            "tasks": ["tts" if family == "glm_tts" else "asr"],
            "packages": [
                {"format": "gguf", "files": files, "download": {"repo": "Mixed/audio.cpp"}}
            ],
        }
        (env["specs"] / f"{family}.json").write_text(json.dumps(spec))
    rows = _rows(catalog.audio_catalog_payload())
    assert "Mixed/audio.cpp" not in rows
    assert rows["Jmica/Drama-3-GGUF"].family == "fish_drama3"
    targets = catalog._spec_targets(
        {
            "a": {"packages": [{"format": "gguf", "download": {"repo": "Same/Repo"}}]},
            "b": {"packages": [{"format": "gguf", "download": {"repo": "same/repo"}}]},
            "c": {"packages": [{"format": "gguf", "download": {"repo": "One/Repo"}}]},
        },
        [],
    )
    assert targets == ({}, {"One/Repo": "c"})


def test_a_community_repo_whose_package_needs_sidecars_is_withheld(env):
    # trklou/audio.cpp (F5/Habibi) reads vocab.txt beside its GGUF; ampixa/sanoTTS a config.json.
    for family, repo, files in (
        (
            "f5_tts",
            "trklou/audio.cpp",
            ["habibi-unified/habibi-unified-orig.gguf", "habibi-unified/vocab.txt"],
        ),
        ("sanotts", "ampixa/sanoTTS", ["gguf/heart-nano-f32.gguf", "gguf/config.json"]),
        ("voices_tts", "Voices/TTS", ["v-q8_0.gguf", "embeddings/alba.safetensors"]),
        # Licenses and checksums ride along but are never loaded (Kitten TTS 2 is self-contained).
        (
            "kitten_tts2",
            "dignome/kitten_tts2",
            ["kitten.gguf", "LICENSE", "NOTICE", "native/LICENSE", "SHA256SUMS", "README.md"],
        ),
    ):
        spec = {
            "family": family,
            "tasks": ["tts", "clone"],
            "package_defaults": {"download": {"repo": repo}},
            "packages": [{"id": "p", "default": True, "format": "gguf", "files": files}],
        }
        (env["specs"] / f"{family}.json").write_text(json.dumps(spec))
    rows = _rows(catalog.audio_catalog_payload())
    for repo in ("trklou/audio.cpp", "ampixa/sanoTTS"):
        assert rows[repo].workflows == [] and rows[repo].unsupported_reason == catalog._SIDECARS
    assert rows["Voices/TTS"].unsupported_reason is None and rows["Voices/TTS"].workflows
    assert rows["dignome/kitten_tts2"].unsupported_reason is None
    assert rows["Jmica/Drama-3-GGUF"].workflows == ["speak", "clone"]


def test_a_community_repo_whose_gguf_is_not_audio_cpp_is_withheld(env, monkeypatch):
    # SenseVoice and Echo-TTS publish GGUFs whose architecture is not "audiocpp": resolve() is None.
    spec = {
        "family": "sense_asr",
        "tasks": ["asr"],
        "package_defaults": {"download": {"repo": "FunAudioLLM/SenseVoiceSmall-GGUF-audiocpp"}},
        "packages": [{"id": "q8", "default": True, "format": "gguf", "files": ["sv.gguf"]}],
    }
    (env["specs"] / "sense_asr.json").write_text(json.dumps(spec))
    probe = acm.read_remote_header
    seen = []

    def header(
        repo_id,
        filename,
        hf_token = None,
        *,
        size = None,
    ):
        seen.append((repo_id, filename))
        if repo_id.startswith("FunAudioLLM/"):
            return AudioCppHeader("sensevoice-small", "sense_asr")
        if repo_id == "Jmica/Drama-3-GGUF":
            return AudioCppHeader("audiocpp", "fish_drama3")
        return probe(repo_id, filename, hf_token, size = size)

    monkeypatch.setattr(acm, "read_remote_header", header)
    rows = _rows(catalog.audio_catalog_payload())
    sense = rows["FunAudioLLM/SenseVoiceSmall-GGUF-audiocpp"]
    assert sense.workflows == [] and sense.unsupported_reason == catalog._NOT_AUDIO_CPP
    assert rows["Jmica/Drama-3-GGUF"].workflows == ["speak", "clone"]
    # The spec's recommended file is the one probed.
    assert ("Jmica/Drama-3-GGUF", "drama-3-Q4_K_S.gguf") in seen


def test_a_spec_dir_read_is_capped_and_ignores_bad_files(env, monkeypatch):
    (env["specs"] / "huge.json").write_bytes(b" " * (catalog._MAX_SPEC_BYTES + 1))
    (env["specs"] / "list.json").write_text("[]")
    (env["specs"] / "evil.json").write_text(json.dumps({"family": "../x", "packages": []}))
    index = catalog._spec_index(env["specs"])
    assert set(index) == {"fish_drama3", "kokoro_tts"}


def test_a_spec_with_an_empty_gguf_package_does_not_break_the_catalog(env):
    bad = {"family": "empty_pkg", "tasks": ["tts"], "packages": [{"format": "gguf", "files": []}]}
    (env["specs"] / "empty_pkg.json").write_text(json.dumps(bad))
    payload = catalog.audio_catalog_payload()
    assert payload.source == "hub"
    assert _rows(payload)[f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"].workflows == ["speak"]


def test_concurrent_cold_callers_share_one_build(env, monkeypatch):
    build, builds = catalog._build, []

    def slow(*args):
        builds.append(1)
        time.sleep(0.2)
        return build(*args)

    monkeypatch.setattr(catalog, "_build", slow)
    threads = [threading.Thread(target = catalog.audio_catalog_payload) for _ in range(4)]
    for t in threads:
        t.start()
    for t in threads:
        t.join()
    assert len(builds) == 1


def test_a_build_with_a_late_family_probe_is_retried_sooner(env, monkeypatch):
    clock = [1000.0]
    monkeypatch.setattr(catalog.time, "monotonic", lambda: clock[0])
    # Every probe misses the deadline, so New-TTS-GGUF stays unplaced in a Hub answer.
    monkeypatch.setattr(catalog, "_bounded", lambda jobs: {})
    for f in env["specs"].iterdir():
        f.unlink()
    payload = catalog.audio_catalog_payload()
    assert payload.source == "hub"
    assert not _rows(payload)[f"{AUDIO_CPP_REPO}/New-TTS-GGUF"].workflows
    hub_calls = env["calls"]["hub"]
    acm._listing_cache.clear()
    clock[0] += catalog._DEGRADED_TTL_SECONDS + 1
    catalog.audio_catalog_payload()
    assert env["calls"]["hub"] == hub_calls + 1


def test_a_package_row_is_sized_by_every_file_it_loads():
    sizes = {
        "sidecars/yue2-model-config.json": 1_000,
        "sidecars/yue2-generation-config.json": 1_000,
        "sidecars/yue2-qwen.tiktoken": 2_000_000,
        "sidecars/yue2-vae-config.json": 1_000,
        "yue2-3b-q8_0.gguf": 4_264_195_616,
        "yue2-3b-q4_0.gguf": 2_666_000_000,
        "yue2-vae-f16.gguf": 265_000_000,
    }
    files = [RepoFile(path, size) for path, size in sizes.items()]
    q8 = {"id": "q8", "format": "gguf", "default": True, "files": ["yue2-3b-q8_0.gguf"]}
    q4 = {"id": "q4", "format": "gguf", "files": ["yue2-3b-q4_0.gguf"]}
    repo = "audio-cpp/Yue2-3B-GGUF"
    row = catalog._row(repo, repo, "", "yue2", {"packages": [q8, q4]}, files)
    assert row.size_bytes == sum(size for path, size in sizes.items() if "q4_0" not in path)
    assert row.smallest_size_bytes == sum(
        size for path, size in sizes.items() if "q8_0" not in path
    )


def test_the_smallest_variant_skips_quants_a_gpu_cannot_run():
    files = [RepoFile("kitten-tq2_1.gguf", 10_000_000), RepoFile("kitten-q8_0.gguf", 40_000_000)]
    repo = "someone/Kitten-GGUF"
    row = catalog._row(repo, repo, "", "kokoro_tts", {}, files)
    assert row.smallest_size_bytes == 40_000_000