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.

Studio: audio.cpp v0.9.2 support (#14073)

Etherl475a02ac188c
diff --git a/studio/backend/core/inference/audio_cpp_backend.py b/studio/backend/core/inference/audio_cpp_backend.py
index fd7824313ac..11a4ac51d69 100644
--- a/studio/backend/core/inference/audio_cpp_backend.py
+++ b/studio/backend/core/inference/audio_cpp_backend.py
@@ -403,13 +403,78 @@ class AudioCppBackend:
def _ensure_downloaded(self, model: AudioCppModel, hf_token: Optional[str]) -> bool:
"""Fetch what the model and its companions still lack; True when the model's own files were."""
+ from core.inference.audio_cpp_server import stale_runtime_download_problem
+
+ companions = [
+ (companion, _resolve_companion(model, companion, hf_token, network = True))
+ for companion in model.companions
+ ]
+ # The model itself passed model_runtime_problem; its companions download separately.
+ for _companion, companion_model in companions:
+ problem = stale_runtime_download_problem(companion_model)
+ if problem:
+ raise RuntimeError(problem)
fetched = self._download_missing(model, hf_token)
- for companion in model.companions:
- companion_model = _resolve_companion(model, companion, hf_token, network = True)
+ for companion, companion_model in companions:
if self._download_missing(companion_model, hf_token):
forget(companion.id)
return fetched
+ @staticmethod
+ def _rebuild_header_only(
+ model: AudioCppModel,
+ path: str,
+ hf_token: Optional[str],
+ cache_dir: str,
+ cancel_event = None,
+ ) -> bool:
+ """Place a republished GGUF whose tensors are unchanged from the cached older copy, fetching
+ only its new header. False means download it as usual; never raises."""
+ try:
+ from hub.utils import gguf_header_delta as delta
+ from core.inference.audio_cpp_models import hub_offline, snapshot_dirs
+
+ if (
+ hub_offline()
+ or not path.lower().endswith(".gguf")
+ or not delta.delta_enabled()
+ or (cancel_event is not None and cancel_event.is_set())
+ ):
+ return False
+ if not any((s / path).is_file() for s in snapshot_dirs(model.repo_id, Path(cache_dir))):
+ return False
+ from huggingface_hub import get_hf_file_metadata, hf_hub_url
+ from huggingface_hub.file_download import (
+ _cache_commit_hash_for_specific_revision,
+ repo_folder_name,
+ )
+
+ token = hf_token or None
+ meta = get_hf_file_metadata(hf_hub_url(model.repo_id, path), token = token, timeout = 10)
+ etag = (getattr(meta, "etag", None) or "").strip('"').lower()
+ listed = next((f.sha256 for f in model.variant.files if f.path == path), "")
+ commit = getattr(meta, "commit_hash", None) or ""
+ if (listed and listed != etag) or not commit:
+ return False
+ # Pinned to the new commit: refs/main still names the old snapshot, which holds this path.
+ result = delta.prepare_media_gguf(
+ model.repo_id,
+ path,
+ token,
+ revision = commit,
+ cache_dir = cache_dir,
+ cancel_event = cancel_event,
+ metadata_fn = lambda: meta,
+ )
+ if not result.placed:
+ return False
+ repo_dir = Path(cache_dir) / repo_folder_name(repo_id = model.repo_id, repo_type = "model")
+ _cache_commit_hash_for_specific_revision(str(repo_dir), "main", commit)
+ return True
+ except Exception as exc: # noqa: BLE001 - an optimisation only: the normal download follows
+ logger.info("audio.cpp: header-only rebuild of %s skipped: %s", path, exc)
+ return False
+
@staticmethod
def _download_missing(
model: AudioCppModel,
@@ -424,6 +489,14 @@ class AudioCppBackend:
from utils.hf_cache_settings import active_hf_hub_cache
cache_dir = str(active_hf_hub_cache())
+ rebuilt = [
+ path
+ for path, _size in missing
+ if AudioCppBackend._rebuild_header_only(model, path, hf_token, cache_dir, cancel_event)
+ ]
+ if rebuilt:
+ # refs/main now names the rebuilt commit; unchanged files link in from blobs on disk.
+ missing = audio_cpp_files.missing_files(model)
for path, _size in missing:
if cancel_event is not None and cancel_event.is_set():
raise AudioCppRequestCancelledError("Request cancelled.")
diff --git a/studio/backend/core/inference/audio_cpp_models.py b/studio/backend/core/inference/audio_cpp_models.py
index 12ca49c25be..b3b017c97a9 100644
--- a/studio/backend/core/inference/audio_cpp_models.py
+++ b/studio/backend/core/inference/audio_cpp_models.py
@@ -37,6 +37,7 @@ from typing import Any, BinaryIO, Iterable, Optional, Sequence
from core.inference.audio_cpp_option_table import (
ACE_STEP_BASE_NAME,
ENUM_PRESETS,
+ OPTION_RENAMES,
STUDIO_OPTION_LISTS,
OptionRule,
rules_for,
@@ -1428,6 +1429,8 @@ def read_remote_header(
class RepoFile:
path: str
size: int = 0
+ # The Hub listing's LFS sha256, when known; not part of equality.
+ sha256: str = field(default = "", compare = False)
def hub_offline() -> bool:
@@ -1505,7 +1508,8 @@ def _hub_listing(repo_id: str, folder: str, hf_token: Optional[str]) -> list[Rep
size = getattr(entry, "size", None)
if size is None: # a folder
continue
- out.append(RepoFile(str(entry.path), int(size or 0)))
+ sha256 = getattr(getattr(entry, "lfs", None), "sha256", "") or ""
+ out.append(RepoFile(str(entry.path), int(size or 0), str(sha256).lower()))
return sorted(out, key = lambda f: f.path)
@@ -1864,18 +1868,14 @@ def runtime_spec(family: str) -> Optional[dict]:
def runtime_knows_family(family: str) -> Optional[bool]:
"""Whether the installed runtime loads ``family``; None when Unsloth Studio cannot tell.
- A runtime that ships ``model_specs/`` answers from it. The prebuilt bundles do not ship that
- folder, so for the prebuilt releases in ``AUDIO_CPP_SPEC_FAMILIES_TAGS`` the families their
- source tree specs are listed in ``audio_cpp_spec_families``. Any other runtime (no install, a
- custom build, an unlisted tag) is unknown, and the spec's own tasks decide as before.
+ The install fetches ``model_specs/`` from the release's source commit and puts it beside the
+ server. With that folder, a family is known exactly when it has a spec file there. No folder
+ (a custom build, or a fetch that failed) means unknown, and the spec's own tasks decide.
"""
if not family or not re.fullmatch(r"[a-z0-9_]+", family):
return None
try:
- from core.inference.audio_cpp_server import (
- find_audio_cpp_server_binary,
- read_install_record,
- )
+ from core.inference.audio_cpp_server import find_audio_cpp_server_binary
binary = find_audio_cpp_server_binary()
except Exception: # noqa: BLE001 - no runtime, no answer
return None
@@ -1887,17 +1887,9 @@ def runtime_knows_family(family: str) -> Optional[bool]:
parents = list(Path(binary).resolve().parents)[:3]
if any((parent / "model_specs").is_dir() for parent in parents):
return False
- tag = read_install_record(binary).get("release_tag")
except (OSError, ValueError):
return None
- from core.inference.audio_cpp_spec_families import (
- AUDIO_CPP_SPEC_FAMILIES,
- AUDIO_CPP_SPEC_FAMILIES_TAGS,
- )
-
- if tag not in AUDIO_CPP_SPEC_FAMILIES_TAGS:
- return None
- return family in AUDIO_CPP_SPEC_FAMILIES
+ return None
def _clean_option(raw: Any) -> Optional[dict]:
@@ -1968,10 +1960,14 @@ def option_schema(
driven = _MUSIC_DRIVEN_OPTIONS if policy.task == "music" else frozenset()
if policy.convert is not None:
driven = driven | frozenset(policy.convert.hidden_options)
+ # A renamed option shows once, under the legacy name every runtime reads.
+ legacy = {canonical: old for old, canonical in OPTION_RENAMES.get(policy.family, ())}
out = []
names = set()
for item in raw:
option = _clean_option(item)
+ if option is not None and option["name"] in legacy:
+ option["name"] = legacy[option["name"]]
if option is None or option["name"] in driven or option["name"] in names:
continue
if option["name"] == "voice":
@@ -2220,12 +2216,43 @@ def _apply_rule(rule: OptionRule, option: dict) -> None:
def filled_options(model: "AudioCppModel", workflow: str, values: Optional[dict]) -> dict:
"""``values`` over the model's recommended defaults; tool panels send their own options."""
- return request_options(
+ pairs = OPTION_RENAMES.get(model.family, ())
+ keys = model.request_keys
+ if pairs and keys is not None:
+ # The schema names a renamed option by its legacy name, so strict keys must too.
+ keys = keys | {old for old, canonical in pairs if canonical in keys}
+ out = request_options(
workflow_options(model, workflow),
- values,
- model.request_keys,
+ _legacy_option_names(values, pairs),
+ keys,
fill = (o["name"] for o in model.options),
)
+ return _wire_option_names(out, pairs, model.request_keys)
+
+
+def _legacy_option_names(
+ values: Optional[dict], pairs: tuple[tuple[str, str], ...]
+) -> Optional[dict]:
+ """``values`` with renamed options under their legacy name; a legacy value given too wins."""
+ if not pairs or not isinstance(values, dict):
+ return values
+ out = dict(values)
+ for old, canonical in pairs:
+ if canonical in out:
+ value = out.pop(canonical)
+ if out.get(old) is None:
+ out[old] = value
+ return out
+
+
+def _wire_option_names(
+ options: dict, pairs: tuple[tuple[str, str], ...], keys: Optional[frozenset[str]]
+) -> dict:
+ """One name per renamed option: the canonical one only when the strict contract lists it."""
+ renamed = {old: canonical for old, canonical in pairs if keys is not None and canonical in keys}
+ if not renamed:
+ return options
+ return {renamed.get(name, name): value for name, value in options.items()}
def workflow_options(model: "AudioCppModel", workflow: str) -> tuple[dict, ...]:
@@ -2300,8 +2327,11 @@ def family_from_names(names: Iterable[str]) -> Optional[str]:
text = " ".join(names).lower().replace(".", "")
for family in sorted(FAMILIES, key = len, reverse = True):
# re.escape leaves "_" alone, so the separator is matched loosely here: "Chatterbox-Turbo"
- # is chatterbox_turbo, not chatterbox.
+ # is chatterbox_turbo, not chatterbox. A digit right after a name that ends in a letter is
+ # another family (kitten-tts2); after a digit it is a stripped version dot (IndexTTS2.5).
pattern = re.escape(family).replace("_", "[-_]?")
+ if not family[-1].isdigit():
+ pattern += r"(?![0-9])"
if re.search(pattern, text):
return family
hints = (
@@ -2315,12 +2345,13 @@ def family_from_names(names: Iterable[str]) -> Optional[str]:
(r"nemotron.*asr", "nemotron_asr"),
(r"pocket[-_]?tts", "pocket_tts"),
(r"kokoro", "kokoro_tts"),
- (r"kitten", "kitten_tts"),
+ (r"kitten(?![-_]?tts[-_]?2)", "kitten_tts"),
(r"piper", "piper_tts"),
(r"inflect", "inflect_v2"),
(r"ace[-_]?step", "ace_step"),
(r"stable[-_]?audio", "stable_audio"),
- (r"voxtral", "voxtral_realtime"),
+ # Voxtral TTS speaks; only the realtime ASR model is voxtral_realtime.
+ (r"voxtral(?![^ ]*tts)", "voxtral_realtime"),
)
for pattern, family in hints:
if re.search(pattern, text):
@@ -2504,7 +2535,14 @@ def _resolve_uncached(
)
spec = runtime_spec(family)
embedded = header.spec if header is not None else None
- policy = family_policy(family, spec or embedded, names, ref.display_name)
+ from core.inference.audio_cpp_server import SPEC_FIRST_RUNTIME, runtime_release_key
+
+ # Follow the spec the runtime checks: v0.9.2 puts model_specs/ first, an older prebuilt
+ # only the GGUF's own (a backfilled folder must not change its options or tasks).
+ release = runtime_release_key()
+ runtime_first = release is not None and release >= SPEC_FIRST_RUNTIME
+ contract = None if release is not None and not runtime_first else spec
+ policy = family_policy(family, contract or embedded, names, ref.display_name)
if policy.package:
# In the package's own order: its first mix is the one the runtime defaults to.
variants = _package_variants(policy, files, ref.folder)
@@ -2575,19 +2613,19 @@ def _resolve_uncached(
needs_espeak = policy.needs_espeak,
request_defaults = dict(policy.request_defaults),
model_options = dict(policy.model_options),
- spec_options = option_schema(policy, spec, embedded),
+ spec_options = option_schema(policy, contract, embedded),
unsupported = unsupported,
local_path = ref.local_path,
tags = tuple(tags),
speaks = policy.speaks,
clone = policy.clone,
companions = policy.companions,
- required_inputs = _required_inputs(spec, embedded, policy),
+ required_inputs = _required_inputs(contract, embedded, policy),
edit = policy.edit,
convert = policy.convert,
separation = policy.separation,
- music = music_with_spec_bounds(policy.music, _raw_request_options(spec, embedded)),
- request_keys = _request_keys(spec, embedded),
+ music = music_with_spec_bounds(policy.music, _raw_request_options(contract, embedded)),
+ request_keys = _request_keys(contract, embedded, runtime_first = runtime_first),
from_hub = from_hub,
)
return model.with_variant(chosen)
@@ -2604,9 +2642,18 @@ def _raw_request_options(spec: Optional[dict], embedded: Optional[dict]) -> list
return raw if isinstance(raw, list) else []
-def _request_keys(spec: Optional[dict], embedded: Optional[dict]) -> Optional[frozenset[str]]:
- # The server prefers an embedded v1 contract over model_specs/ (model_spec/package.cpp).
- if isinstance(embedded, dict) and embedded.get("schema_version") is not None:
+def _request_keys(
+ spec: Optional[dict],
+ embedded: Optional[dict],
+ runtime_first: bool = False,
+) -> Optional[frozenset[str]]:
+ # v0.9.1 checks the GGUF's embedded v1 contract first; v0.9.2 checks model_specs/ and its
+ # built-in specs first (model_spec/package.cpp).
+ if (
+ not runtime_first
+ and isinstance(embedded, dict)
+ and embedded.get("schema_version") is not None
+ ):
if (embedded.get("options") or {}).get("request"):
spec = None
if _request_source(spec, embedded).get("schema_version") is None:
@@ -2687,11 +2734,132 @@ def companion_files(path: str, names: Iterable[str]) -> tuple[str, ...]:
return tuple(found)
+def _fetches_gguf(
+ repo_id: str,
+ path: str,
+ hf_token: Optional[str],
+ hub_cache: Optional[Path] = None,
+) -> bool:
+ """Whether a download job into ``hub_cache`` fetches GGUF ``path``: true unless the Hub's current
+ file is already there (its etag blob, or the commit's snapshot without symlinks). Offline: any copy."""
+ if not path.lower().endswith(".gguf"):
+ return False
+ try:
+ snapshots = snapshot_dirs(repo_id, hub_cache)
+ except Exception: # noqa: BLE001 - an unreadable cache is one to fetch into
+ snapshots = []
+ on_disk = any((snapshot / path).is_file() for snapshot in snapshots)
+ if hub_offline():
+ return not on_disk
+ try:
+ from huggingface_hub import get_hf_file_metadata, hf_hub_url
+ meta = get_hf_file_metadata(hf_hub_url(repo_id, path), token = hf_token or None, timeout = 10)
+ except Exception: # noqa: BLE001 - unreachable Hub: judge by the cache alone
+ return not on_disk
+ etag, commit = getattr(meta, "etag", None), getattr(meta, "commit_hash", None)
+ if not etag or not snapshots:
+ return not on_disk
+ repo_dir = snapshots[0].parent.parent
+ if (repo_dir / "blobs" / etag).is_file():
+ return False
+ return not (commit and (repo_dir / "snapshots" / commit / path).is_file())
+
+
+def _refuse_stale_download(
+ model: AudioCppModel,
+ hf_token: Optional[str],
+ fetched: Sequence[str] = (),
+ hub_cache: Optional[Path] = None,
+) -> None:
+ """Raise ``AudioCppRuntimeTooOldError`` when a download job for ``model`` would fetch GGUFs
+ the installed runtime is too old to load; ``fetched`` are files already known to be fetched."""
+ from core.inference.audio_cpp_server import (
+ SPEC_FIRST_RUNTIME,
+ AudioCppRuntimeTooOldError,
+ runtime_release_key,
+ stale_runtime_download_problem,
+ )
+
+ release = runtime_release_key()
+ if release is None or release >= SPEC_FIRST_RUNTIME:
+ return
+ # The planner adds the companions' files (MioTTS's MioCodec) to the same job.
+ checked = [model]
+ for companion in model.companions:
+ try:
+ found = resolve(companion.id, companion.variant, hf_token, network = not hub_offline())
+ except Exception: # noqa: BLE001 - the planner reports a companion it cannot find
+ found = None
+ if found is not None:
+ checked.append(found)
+ for item in checked:
+ if item.local_path or not item.repo_id:
+ continue
+ if any(
+ f.path in fetched or _fetches_gguf(item.repo_id, f.path, hf_token, hub_cache)
+ for f in item.variant.files
+ ):
+ raise AudioCppRuntimeTooOldError(
+ stale_runtime_download_problem(item, assume_fetched = True)
+ )
+
+
+def refuse_stale_download(
+ identifier: Optional[str],
+ variant: Optional[str],
+ hf_token: Optional[str] = None,
+ *,
+ files: Sequence[str] = (),
+ hub_cache: Optional[Path] = None,
+) -> None:
+ """The old-runtime gate for a download job of a repo outside the umbrella, such as
+ ``audio-cpp/MiniMax-Music3-GGUF``, or of a scoped job's ``files`` in any repo;
+ ``download_target`` gates the umbrella's folder rows."""
+ from core.inference.audio_cpp_server import SPEC_FIRST_RUNTIME, runtime_release_key
+
+ release = runtime_release_key()
+ if release is None or release >= SPEC_FIRST_RUNTIME or not identifier:
+ return
+ # Row -> the files the job fetches there; None means the row's own variant.
+ rows: dict[str, Optional[list[str]]] = {identifier: None}
+ if files:
+ # A scoped job fetches exactly these files: only the GGUFs it would download count.
+ wanted = [f for f in files if _fetches_gguf(identifier, f, hf_token, hub_cache)]
+ umbrella = identifier.lower() + "/" == _UMBRELLA_PREFIX
+ rows = {}
+ for name in wanted:
+ if umbrella and "/" not in name:
+ continue
+ row = f"{AUDIO_CPP_REPO}/{name.split('/')[0]}" if umbrella else identifier
+ rows.setdefault(row, []).append(name)
+ elif is_umbrella_id(identifier):
+ return
+ network = not hub_offline()
+ for row, names in sorted(rows.items()):
+ try:
+ model = resolve(row, None if names else variant, hf_token, network = network)
+ checked = [model] if model is not None else []
+ if model is not None and names:
+ keys = {v.key for v in model.variants if any(f.path in names for f in v.files)}
+ checked = [
+ model
+ if key == model.variant.key
+ else resolve(row, key, hf_token, network = network)
+ for key in sorted(keys)
+ ] or checked
+ except Exception: # noqa: BLE001 - a repo that cannot be resolved is the downloader's to report
+ continue
+ for found in checked:
+ if found is not None:
+ _refuse_stale_download(found, hf_token, names or (), hub_cache)
+
+
def download_target(
identifier: Optional[str],
variant: Optional[str],
hf_token: Optional[str] = None,
persist: bool = True,
+ hub_cache: Optional[Path] = None,
) -> Optional[tuple[str, str]]:
"""``(repo, variant key)`` the Hub GGUF downloader fetches for an umbrella folder row, else None.
@@ -2704,6 +2872,8 @@ def download_target(
model = resolve(identifier, variant, hf_token, network = not hub_offline())
if model is None or not model.repo_id or not model.variant.primary:
return None
+ if persist:
+ _refuse_stale_download(model, hf_token, hub_cache = hub_cache)
from hub.utils.gguf import gguf_variant_key
key = gguf_variant_key(model.variant.primary)
diff --git a/studio/backend/core/inference/audio_cpp_option_table.py b/studio/backend/core/inference/audio_cpp_option_table.py
index ff1a6a1c4f8..7a46025486c 100644
--- a/studio/backend/core/inference/audio_cpp_option_table.py
+++ b/studio/backend/core/inference/audio_cpp_option_table.py
@@ -40,6 +40,16 @@ ENUM_PRESETS: Mapping[str, tuple[str, ...]] = MappingProxyType(
_EMPTY: Mapping[str, Any] = MappingProxyType({})
+# (legacy, canonical) option names renamed in audio.cpp v0.9.2 (0xShug0/audio.cpp#926), which still
+# reads the legacy name. A fixed table, not one per release.
+OPTION_RENAMES: Mapping[str, tuple[tuple[str, str], ...]] = MappingProxyType(
+ {
+ "chatterbox": (("s3gen_cfg_rate", "flow_guidance_scale"),),
+ "seed_vc": (("length_adjust", "duration_scale"),),
+ "ace_step": (("lm_cfg_scale", "lm_guidance_scale"),),
+ }
+)
+
@dataclass(frozen = True)
class OptionRule:
diff --git a/studio/backend/core/inference/audio_cpp_server.py b/studio/backend/core/inference/audio_cpp_server.py
index 001e4e06981..99d60337f46 100644
--- a/studio/backend/core/inference/audio_cpp_server.py
+++ b/studio/backend/core/inference/audio_cpp_server.py
@@ -64,6 +64,10 @@ class AudioCppUnavailableError(RuntimeError):
"""audiocpp_server is missing, failed to start, or stopped answering."""
+class AudioCppRuntimeTooOldError(AudioCppUnavailableError):
+ """The installed runtime is older than the GGUFs a download would fetch."""
+
+
class AudioCppStartCancelledError(RuntimeError):
"""A start was cancelled (training pre-empted it, or Unsloth is shutting down)."""
@@ -161,6 +165,25 @@ def read_install_record(binary: str) -> dict:
return {}
+# First release that checks model_specs/ before a GGUF's embedded spec and reads the renamed options.
+SPEC_FIRST_RUNTIME = (0, 9, 2)
+
+
+def runtime_release_key(binary: Optional[str] = None) -> Optional[tuple[int, int, int]]:
+ """``(major, minor, patch)`` of the installed prebuilt runtime, or None for a custom build or
+ an unreadable tag. Reads only the install record, so it is safe on hot paths."""
+ try:
+ binary = binary if binary is not None else find_audio_cpp_server_binary()
+ if not binary:
+ return None
+ from utils.audio_cpp_freshness import parse_release_version
+
+ key = parse_release_version(read_install_record(binary).get("release_tag"))
+ except Exception: # noqa: BLE001 - an unknown runtime is not an old one
+ return None
+ return tuple(key[:3]) if key else None
+
+
def is_available() -> bool:
return find_audio_cpp_server_binary() is not None
@@ -194,6 +217,37 @@ def binary_has_espeak(binary: Optional[str]) -> bool:
UPDATE_IN_PROGRESS = threading.Event()
+def stale_runtime_download_problem(
+ model: AudioCppModel,
+ binary: Optional[str] = None,
+ *,
+ hub_cache: Optional[Path] = None,
+ assume_fetched: bool = False,
+) -> Optional[str]:
+ """Why ``model``'s files must not be downloaded for a runtime older than v0.9.2, or None.
+ ``assume_fetched``: the caller already knows a GGUF would be fetched, so the cache is not read.
+
+ The audio GGUFs on the Hub track the newest runtime, so an older one could load a fresh
+ download wrongly. A complete cache, a local file or an unknown runtime is never refused.
+ """
+ release = runtime_release_key(binary)
+ if release is None or release >= SPEC_FIRST_RUNTIME or model.local_path:
+ return None
+ from core.inference.audio_cpp_files import missing_files
+
+ try:
+ # Only a GGUF carries the spec an old runtime may misread; other files are fetched as before.
+ missing = [] if assume_fetched else missing_files(model, hub_cache = hub_cache)
+ if not assume_fetched and not any(path.lower().endswith(".gguf") for path, _ in missing):
+ return None
+ except Exception: # noqa: BLE001 - an unreadable cache is the download's to report
+ return None
+ return (
+ f"{model.display_name} needs a newer audio runtime before its files can be downloaded. "
+ "Update the audio runtime from the update banner, or run `unsloth studio update`."
+ )
+
+
def model_runtime_problem(model: AudioCppModel, binary: Optional[str] = None) -> Optional[str]:
"""Why ``model`` cannot run on the installed runtime, or None when it can."""
if UPDATE_IN_PROGRESS.is_set():
@@ -208,6 +262,9 @@ def model_runtime_problem(model: AudioCppModel, binary: Optional[str] = None) ->
f"{model.display_name} needs an audio runtime built with eSpeak-ng, and the installed one "
"has none. Run `unsloth studio update` to install the Unsloth audio runtime."
)
+ problem = stale_runtime_download_problem(model, binary)
+ if problem:
+ return problem
from core.inference.audio_cpp_files import served_path_problem
try:
diff --git a/studio/backend/core/inference/audio_cpp_spec_families.py b/studio/backend/core/inference/audio_cpp_spec_families.py
deleted file mode 100644
index 5e6d108b01b..00000000000
--- a/studio/backend/core/inference/audio_cpp_spec_families.py
+++ /dev/null
@@ -1,121 +0,0 @@
-# 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 model families the prebuilt audio.cpp runtime loads, for bundles that ship no ``model_specs/``.
-
-A family Unsloth Studio does not list is offered from the tasks its GGUF's spec declares, and that
-spec can be newer than the runtime. This set lets Unsloth Studio refuse such a family up front instead
-of failing at load with "unsupported model family hint". It holds only for the tags it was checked against.
-"""
-
-from __future__ import annotations
-
-# The unslothai/audio.cpp releases whose model_specs/*.json stems equal the set below. Add a release
-# here once its stems are checked equal; on any change, regenerate the set and keep only matching tags.
-AUDIO_CPP_SPEC_FAMILIES_TAGS = frozenset({"v0.9.0-unsloth.1", "v0.9.1-unsloth.1"})
-
-AUDIO_CPP_SPEC_FAMILIES = frozenset(
- (
- "ace_step",
- "apollo",
- "audio8_asr",
- "audio8_tts",
- "audiosr",
- "auk",
- "breeze_tts",
- "bs_roformer",
- "builtin_audio_utils",
- "canary_asr",
- "chatterbox",
- "chatterbox_turbo",
- "citrinet_asr",
- "cohere_asr",
- "confucius4_r2t2",
- "confucius4_tts",
- "controlfoley",
- "cosyvoice3",
- "dots_tts",
- "dramabox",
- "echo_tts",
- "f5_tts",
- "firered_audio",
- "fireredtts3",
- "fish_audio",
- "fun_asr_nano",
- "gigaam_asr",
- "glm_tts",
- "granite5asr",
- "heartmula",
- "higgs_audio_stt",
- "higgs_audio_tts",
- "htdemucs",
- "htdemucs_6stems",
- "hviske_asr",
- "index_tts2",
- "inflect_v2",
- "irodori_tts",
- "kitten_tts",
- "kokoro_tts",
- "kroko_asr",
- "liveavatar",
- "magpie_tts",
- "maya1",
- "meanvc2",
- "mel_band_roformer",
- "midashenglm_gen",
- "minimax_h3",
- "minimax_music3",
- "miocodec",
- "miotts",
- "mira_tts",
- "mms_forced_aligner",
- "moonshine_asr",
- "moss_transcribe_diarize",
- "moss_tts_local",
- "moss_tts_nano",
- "moss_tts_v15",
- "moss_ttsd",
- "moss_voicegen",
- "muscriptor",
- "nemotron_3_diar",
- "nemotron_asr",
- "neutts",
- "niagara_asr",
- "omnivoice",
- "outetts",
- "parakeet_tdt",
- "personaplex",
- "piper_tts",
- "pocket_tts",
- "pulsevad",
- "qwen3_asr",
- "qwen3_forced_aligner",
- "qwen3_tts",
- "rvc",
- "sam_audio",
- "samsone",
- "sanotts",
- "seed_vc",
- "sense_asr",
- "sheetsage2",
- "soprano_tts",
- "sopro_tts",
- "sortformer_diar",
- "sortformer_diar_v2",
- "stable_audio",
- "supertonic",
- "tone_color_vc",
- "universr",
- "vevo2",
- "vibeasr",
- "vibevoice",
- "vibevoice_asr",
- "vibevoice_asr_streaming",
- "vieneu_v3_turbo",
- "voxcpm1",
- "voxcpm2",
- "voxtral_realtime",
- "yue2",
- "zipvoice",
- )
-)
diff --git a/studio/backend/core/inference/stt_audiocpp_sidecar.py b/studio/backend/core/inference/stt_audiocpp_sidecar.py
index fcd224e6ce3..be1fc870168 100644
--- a/studio/backend/core/inference/stt_audiocpp_sidecar.py
+++ b/studio/backend/core/inference/stt_audiocpp_sidecar.py
@@ -125,6 +125,9 @@ def _nemotron_language(language: str, code: str) -> Optional[str]:
def _runtime_language(family: str, language: Optional[str]) -> Optional[str]:
"""``language`` in the form ``family`` reads it, or None to let the model detect it."""
+ if family in ("owsm", "owsm_ctc"):
+ # OWSM takes ISO 639-3 codes ("<en>" fails) and defaults to English; detect instead.
+ return "auto"
code = normalize_whisper_language(language)
if not code:
return None
@@ -485,6 +488,11 @@ class _AudioCppDownloadState:
repo = None
try:
model = resolve_audio_cpp_stt_model(model_id, network = True, hf_token = hf_token)
+ problem = audio_cpp_server.stale_runtime_download_problem(
+ model, None, hub_cache = hub_cache
+ )
+ if problem:
+ raise SttModelIdError(problem)
repo = model.repo_id
if not repo:
raise RuntimeError("a local model file has nothing to download")
@@ -846,6 +854,9 @@ class AudioCppSttSidecar:
_notify(on_phase, "downloading_aligner")
try:
aligner = audio_cpp_backend._resolve_companion(entry, QWEN3_ALIGNER, network = True)
+ problem = audio_cpp_server.stale_runtime_download_problem(aligner)
+ if problem:
+ raise audio_cpp_server.AudioCppRuntimeTooOldError(problem)
audio_cpp_backend.AudioCppBackend._download_missing(aligner, None, cancel_event)
except AudioCppRequestCancelledError:
raise SttTranscriptionCancelledError("Transcription cancelled.") from None
@@ -1036,9 +1047,16 @@ class AudioCppSttSidecar:
on_phase = on_phase,
)
_notify(on_phase, "transcribing")
+ # A strict spec without a language option (Hviske-v6) has no use for one.
+ keys = entry.request_keys
+ sent = (
+ _runtime_language(entry.family, language)
+ if keys is None or "language" in keys
+ else None
+ )
payload = self._post_details(
path,
- _runtime_language(entry.family, language),
+ sent,
cancel_event,
dict(_TIMESTAMP_OPTIONS) if aligned else {},
)
@@ -1051,9 +1069,13 @@ class AudioCppSttSidecar:
finally:
self._schedule_idle_unload_locked()
details = stt_details.normalize(payload, entry.family, rate)
+ detected = details["language"]
+ if sent == "auto":
+ # OWSM reports what it heard, not the ignored choice; OWSM-CTC only echoes "auto" back.
+ detected = None if str(detected or "").lower() == "auto" else detected
result = {
"text": details["text"],
- "language": lang or details["language"],
+ "language": (detected or lang) if sent == "auto" else (lang or detected),
"duration": duration,
"model": _reported_name(model, entry),
}
diff --git a/studio/backend/hub/services/models/downloads.py b/studio/backend/hub/services/models/downloads.py
index f6bfcc7c276..b6bffc1eed7 100644
--- a/studio/backend/hub/services/models/downloads.py
+++ b/studio/backend/hub/services/models/downloads.py
@@ -215,11 +215,25 @@ def _download_cache_paths(download_dir: Optional[str]):
return paths
+def _gate_hub_cache(download_dir: Optional[str]) -> Optional[Path]:
+ """The Hub cache a job with ``download_dir`` writes into, without registering the folder; None
+ (the Models folder) for no folder or one the job itself will refuse."""
+ if not (download_dir or "").strip():
+ return None
+ try:
+ from utils.hf_cache_settings import download_cache_paths
+ return Path(download_cache_paths(download_dir).hub_cache)
+ except Exception: # noqa: BLE001 - an invalid folder is the job's to report
+ return None
+
+
async def _audio_cpp_target(
repo_id: str,
variant: Optional[str],
hf_token: Optional[str] = None,
persist: bool = False,
+ stale_gate: bool = True,
+ hub_cache: Optional[Path] = None,
) -> tuple[str, Optional[str]]:
"""``(repo, variant)`` a download of an audio.cpp umbrella folder row really works on.
@@ -228,13 +242,27 @@ async def _audio_cpp_target(
the variant planner gives that file. Anything else passes through unchanged.
"""
text = (repo_id or "").strip()
+ from core.inference.audio_cpp_server import AudioCppRuntimeTooOldError
+
if not text.lower().startswith("audio-cpp/audio.cpp-gguf/"):
+ # A variant-less job is a full snapshot, which never fetches a GGUF (SNAPSHOT_IGNORE_PATTERNS).
+ if persist and stale_gate and variant:
+ from core.inference.audio_cpp_models import refuse_stale_download
+ try:
+ await asyncio.to_thread(
+ refuse_stale_download, text, variant, hf_token, hub_cache = hub_cache
+ )
+ except AudioCppRuntimeTooOldError as exc:
+ raise HTTPException(status_code = 409, detail = str(exc)) from exc
return text, variant
+
try:
from core.inference.audio_cpp_models import download_target
target = await asyncio.to_thread(
- download_target, text, (variant or "").strip() or None, hf_token, persist
+ download_target, text, (variant or "").strip() or None, hf_token, persist, hub_cache
)
+ except AudioCppRuntimeTooOldError as exc:
+ raise HTTPException(status_code = 409, detail = str(exc)) from exc
except Exception as exc: # noqa: BLE001 - an unresolvable row downloads nothing
logger.warning("Could not resolve the audio model %s for download: %s", text, exc)
target = None
@@ -243,6 +271,24 @@ async def _audio_cpp_target(
return target
+async def _refuse_stale_scoped_download(
+ repo_id: str,
+ files: list[str],
+ hf_token: Optional[str],
+ hub_cache: Optional[Path] = None,
+) -> None:
+ """A scoped job skips ``_audio_cpp_target``; its audio GGUFs get the same old-runtime gate."""
+ from core.inference.audio_cpp_models import refuse_stale_download
+ from core.inference.audio_cpp_server import AudioCppRuntimeTooOldError
+
+ try:
+ await asyncio.to_thread(
+ refuse_stale_download, repo_id, None, hf_token, files = files, hub_cache = hub_cache
+ )
+ except AudioCppRuntimeTooOldError as exc:
+ raise HTTPException(status_code = 409, detail = str(exc)) from exc
+
+
async def download_model_response(
body: DownloadModelRequest,
hf_token: Optional[str] = None,
@@ -260,9 +306,18 @@ async def download_model_response(
raise HTTPException(status_code = 403, detail = "Account is retired")
hf_token = account_access.account_hf_token(hf_token)
allow_ambient_token = allow_ambient_token and not account_access.managed_account()
+ # The old-runtime preflight resolves with ambient credentials (resolve() has no anonymous mode),
+ # so a caller that must stay anonymous skips it for repos other than the public umbrella.
+ stale_gate = bool(hf_token) or allow_ambient_token
+ gate_cache = _gate_hub_cache(getattr(body, "download_dir", None))
if body.gguf_variant or not body.scope_id:
target_repo, target_variant = await _audio_cpp_target(
- body.repo_id, body.gguf_variant, hf_token, persist = True
+ body.repo_id,
+ body.gguf_variant,
+ hf_token,
+ persist = True,
+ stale_gate = stale_gate,
+ hub_cache = gate_cache,
)
if target_repo != body.repo_id.strip():
body = body.model_copy(update = {"repo_id": target_repo, "gguf_variant": target_variant})
@@ -300,6 +355,8 @@ async def download_model_response(
if not _is_valid_gguf_variant(scope_variant):
raise HTTPException(status_code = 400, detail = f"Invalid scope_id: {body.scope_id!r}")
variant = scope_variant
+ if stale_gate:
+ await _refuse_stale_scoped_download(repo_id, scoped_files, hf_token, gate_cache)
key = _download_job_key(repo_id, variant)
_reject_if_load_owned(key)
# Size and Auto resolution may perform network probes, so keep both off the event loop.
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 9acf9b7452b..c805f28bb57 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -559,6 +559,9 @@ def _start_llama_cpp_probes_if_enabled(app: FastAPI) -> None:
if os.environ.get("UNSLOTH_DISABLE_UPDATE_CHECK") == "1":
return
+ from utils.audio_cpp_update import start_model_specs_backfill
+
+ start_model_specs_backfill()
threading.Thread(
target = _run_llama_cpp_startup_probes,
args = (app,),
diff --git a/studio/backend/tests/fixtures/audio_cpp_catalog_specs.json b/studio/backend/tests/fixtures/audio_cpp_catalog_specs.json
index 29d8ead6f59..0817ba60a15 100644
--- a/studio/backend/tests/fixtures/audio_cpp_catalog_specs.json
+++ b/studio/backend/tests/fixtures/audio_cpp_catalog_specs.json
@@ -31,6 +31,7 @@
"audio-cpp/audio.cpp-gguf/Irodori-TTS-v4-Small-GGUF": {"family":"irodori_tts","files":["irodori-tts-v4-small-f16.gguf","irodori-tts-v4-small-q8_0.gguf","irodori-tts-v4.1-anime-q8_0.gguf"],"spec":{"options":{"request":[{"default":"ja","name":"language","required":false,"type":"string"},{"name":"instruction","required":false,"type":"string"},{"default":true,"name":"no_ref","required":false,"type":"bool"},{"default":40,"min":1,"name":"num_inference_steps","required":false,"type":"int"},{"min":0,"name":"duration_sec","required":false,"type":"float"},{"default":1,"min":0,"name":"duration_scale","required":false,"type":"float"},{"default":"endline","name":"text_chunk_mode","required":false,"type":"enum","values":["japanese","endline"]},{"min":1,"name":"text_chunk_size","required":false,"type":"int"},{"default":0.5,"min":0,"name":"min_duration_sec","required":false,"type":"float"},{"default":30,"min":0,"name":"max_duration_sec","required":false,"type":"float"},{"default":3,"min":0,"name":"text_guidance_scale","required":false,"type":"float"},{"default":5,"min":0,"name":"speaker_guidance_scale","required":false,"type":"float"},{"default":3,"min":0,"name":"caption_guidance_scale","required":false,"type":"float"},{"min":0,"name":"guidance_scale","required":false,"type":"float"},{"default":"independent","name":"guidance_mode","required":false,"type":"enum","values":["independent","joint","alternating"]},{"default":0.5,"min":0,"name":"guidance_min_t","required":false,"type":"float"},{"default":1,"min":0,"name":"guidance_max_t","required":false,"type":"float"},{"min":0,"name":"seed","required":false,"type":"int"},{"default":true,"name":"trim_tail","required":false,"type":"bool"}]},"schema_version":1,"tasks":["tts","clone","design"]},"task":"tts"},
"audio-cpp/audio.cpp-gguf/KittenTTS-GGUF": {"family":"kitten_tts","files":["LICENSE","README.md","kitten-tts-mini-0.8-orig.gguf"],"spec":{"options":{"request":[{"default":1,"min":0.01,"name":"speed","required":false,"type":"float"},{"min":0,"name":"seed","required":false,"type":"int"},{"default":"default","name":"text_chunk_mode","required":false,"type":"enum","values":["default","tag_aware","japanese","endline"]},{"default":400,"min":32,"name":"text_chunk_size","required":false,"type":"int"}]},"schema_version":1,"tasks":["tts"],"ui":{"builtin_voices":["Bella","Jasper","Luna","Bruno","Rosie","Hugo","Kiki","Leo"],"default_voice":"Leo"}},"task":"tts"},
"audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF": {"family":"kokoro_tts","files":["kokoro-82m-bf16.gguf","kokoro-82m-q8_0.gguf"],"spec":{"options":{"request":[{"name":"language","required":false,"type":"string"},{"min":0,"name":"seed","required":false,"type":"int"},{"default":1,"min":0.01,"name":"speed","required":false,"type":"float"},{"name":"phonemes","required":false,"type":"string_list"},{"default":240,"min":32,"name":"text_chunk_size","required":false,"type":"int"},{"default":false,"name":"return_timestamps","required":false,"type":"bool"}]},"schema_version":1,"tasks":["tts"],"ui":{"builtin_voices":["af_alloy","af_aoede","af_bella","af_heart","af_jessica","af_kore","af_nicole","af_nova","af_river","af_sarah","af_sky","am_adam","am_echo","am_eric","am_fenrir","am_liam","am_michael","am_onyx","am_puck","am_santa","bf_alice","bf_emma","bf_isabella","bf_lily","bm_daniel","bm_fable","bm_george","bm_lewis","ef_dora","em_alex","em_santa","ff_siwis","hf_alpha","hf_beta","hm_omega","hm_psi","if_sara","im_nicola","jf_alpha","jf_gongitsune","jf_nezumi","jf_tebukuro","jm_kumo","pf_dora","pm_alex","pm_santa","zf_xiaobei","zf_xiaoni","zf_xiaoxiao","zf_xiaoyi","zm_yunjian","zm_yunxi","zm_yunxia","zm_yunyang"],"default_voice":"af_heart"}},"task":"tts"},
+ "audio-cpp/audio.cpp-gguf/KugelAudio-0-Open-GGUF": {"family":"kugelaudio","files":["LICENSE","README.md","kugelaudio-0-open-bf16.gguf","kugelaudio-0-open-q4_k.gguf","kugelaudio-0-open-q8_0.gguf"],"spec":{"options":{"request":[{"default":"default","name":"voice_id","required":false,"type":"enum","values":["default","clear","english_female","english_male"]},{"default":20,"max":1000,"min":1,"name":"num_inference_steps","required":false,"type":"int"},{"default":3,"min":0,"name":"guidance_scale","required":false,"type":"float"},{"default":2048,"min":1,"name":"max_tokens","required":false,"type":"int"},{"default":false,"name":"do_sample","required":false,"type":"bool"},{"default":1,"min":0,"name":"temperature","required":false,"type":"float"},{"default":1234,"min":-1,"name":"seed","required":false,"type":"int"},{"default":300,"min":1,"name":"text_chunk_size","required":false,"type":"int"},{"default":"default","name":"text_chunk_mode","required":false,"type":"enum","values":["default","tag_aware","japanese","endline"]}]},"schema_version":1,"tasks":["tts"],"ui":{"builtin_voices":["default","clear","english_female","english_male"],"default_voice":"default"}},"task":"tts"},
"audio-cpp/audio.cpp-gguf/MOSS-TTS-Local-v1.5-GGUF": {"family":"moss_tts_local","files":["moss-tts-local-v1.5-bf16.gguf","moss-tts-local-v1.5-q8_0.gguf"],"spec":{},"task":"tts"},
"audio-cpp/audio.cpp-gguf/MOSS-TTS-Nano-100M-GGUF": {"family":"moss_tts_nano","files":["moss-tts-nano-100m-bf16.gguf","moss-tts-nano-100m-q8_0.gguf"],"spec":{},"task":"tts"},
"audio-cpp/audio.cpp-gguf/MOSS-VoiceGenerator-GGUF": {"family":"moss_voicegen","files":["moss_voicegen_bf16_codec_f16_decode.gguf"],"spec":{"tasks":["vdes"]},"task":"tts"},
@@ -58,6 +59,7 @@
"audio-cpp/audio.cpp-gguf/Vevo2-GGUF": {"family":"vevo2","files":["vevo2-f16.gguf","vevo2-orig.gguf","vevo2-q8_0.gguf"],"spec":{},"task":"tts"},
"audio-cpp/audio.cpp-gguf/VibeVoice-1.5B-GGUF": {"family":"vibevoice","files":["vibevoice-1.5b-bf16.gguf","vibevoice-1.5b-q4-ios.gguf","vibevoice-1.5b-q8_0.gguf"],"spec":{},"task":"tts"},
"audio-cpp/audio.cpp-gguf/VoxCPM1-GGUF": {"family":"voxcpm1","files":["voxcpm-0.5b-q8_0-audiovae-f16.gguf"],"spec":{"options":{"request":[{"default":"tag_aware","name":"text_chunk_mode","preset":"text_chunk_mode_full","required":false,"type":"enum"},{"name":"seed","required":false,"type":"int"},{"default":1024,"name":"max_tokens","required":false,"type":"int"},{"default":0,"name":"min_tokens","required":false,"type":"int"},{"default":50,"name":"num_inference_steps","required":false,"type":"int"},{"default":2,"name":"guidance_scale","required":false,"type":"float"},{"default":true,"name":"retry_badcase","required":false,"type":"bool"},{"default":2,"name":"retry_badcase_max_times","required":false,"type":"int"},{"name":"retry_badcase_ratio_threshold","required":false,"type":"float"},{"name":"prompt_text","required":false,"type":"string"},{"name":"reference_text","required":false,"type":"string"}]},"schema_version":1,"tasks":["tts","clone"]},"task":"tts"},
- "audio-cpp/audio.cpp-gguf/VoxCPM2-GGUF": {"family":"voxcpm2","files":["voxcpm2-bf16.gguf","voxcpm2-orig.gguf","voxcpm2-q8_0.gguf"],"spec":{},"task":"tts"}
+ "audio-cpp/audio.cpp-gguf/VoxCPM2-GGUF": {"family":"voxcpm2","files":["voxcpm2-bf16.gguf","voxcpm2-orig.gguf","voxcpm2-q8_0.gguf"],"spec":{},"task":"tts"},
+ "audio-cpp/audio.cpp-gguf/Voxtral-4B-TTS-2603-GGUF": {"family":"voxtral_tts","files":["LICENSE","README.md","voxtral-4b-tts-2603-bf16.gguf","voxtral-4b-tts-2603-q8_0.gguf"],"spec":{"options":{"request":[{"default":"casual_male","name":"voice_id","required":false,"type":"enum","values":["casual_female","casual_male","cheerful_female","neutral_female","neutral_male","pt_male","pt_female","nl_male","nl_female","it_male","it_female","fr_male","fr_female","es_male","es_female","de_male","de_female","ar_male","hi_male","hi_female"]},{"default":2048,"min":1,"name":"max_tokens","required":false,"type":"int"},{"default":7,"min":1,"name":"num_inference_steps","required":false,"type":"int"},{"default":1.2,"min":0,"name":"guidance_scale","required":false,"type":"float"},{"min":0,"name":"seed","required":false,"type":"int"},{"default":300,"min":1,"name":"text_chunk_size","required":false,"type":"int"},{"default":"default","name":"text_chunk_mode","required":false,"type":"enum","values":["default","tag_aware","japanese","endline"]}]},"schema_version":1,"tasks":["tts"]},"task":"tts"}
}
}
diff --git a/studio/backend/tests/fixtures/audio_cpp_option_golden.json b/studio/backend/tests/fixtures/audio_cpp_option_golden.json
index 377d442bae3..16322ca5dda 100644
--- a/studio/backend/tests/fixtures/audio_cpp_option_golden.json
+++ b/studio/backend/tests/fixtures/audio_cpp_option_golden.json
@@ -96,6 +96,9 @@
"audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF": [
{"exclude":["language","return_timestamps","seed"],"include":{"speed":{"default":1.0},"text_chunk_size":{"default":240},"voice":{"default":"af_heart"}},"optional":{},"workflow":"speak"}
],
+ "audio-cpp/audio.cpp-gguf/KugelAudio-0-Open-GGUF": [
+ {"exclude":[],"include":{"do_sample":{"default":false},"guidance_scale":{"default":3.0},"max_tokens":{"default":2048},"num_inference_steps":{"default":20},"temperature":{"default":1.0},"text_chunk_mode":{"default":"default"},"text_chunk_size":{"default":300},"voice":{"default":"default"}},"optional":{"voice_id":{"default":"default"}},"workflow":"speak"}
+ ],
"audio-cpp/audio.cpp-gguf/MOSS-TTS-Local-v1.5-GGUF": [
{"exclude":[],"include":{"do_sample":{"default":true},"max_tokens":{"default":4096},"repetition_penalty":{"default":1.0},"temperature":{"default":1.7},"text_temperature":{"default":1.0},"top_k":{"default":25},"top_p":{"default":0.8}},"optional":{},"workflow":"speak"},
{"exclude":["voice"],"include":{"do_sample":{"default":true},"max_tokens":{"default":4096},"repetition_penalty":{"default":1.0},"temperature":{"default":1.7},"text_temperature":{"default":1.0},"top_k":{"default":25},"top_p":{"default":0.8}},"optional":{},"workflow":"clone"}
@@ -184,6 +187,9 @@
"audio-cpp/audio.cpp-gguf/VoxCPM2-GGUF": [
{"exclude":["prompt_text"],"include":{"guidance_scale":{"default":2.0},"min_tokens":{"default":2},"num_inference_steps":{"default":10},"retry_badcase":{"default":true},"retry_badcase_max_times":{"default":3},"retry_badcase_ratio_threshold":{"default":6.0},"text_chunk_mode":{"default":"tag_aware"}},"optional":{"max_tokens":{"default":null}},"workflow":"speak"},
{"exclude":["prompt_text","voice"],"include":{"guidance_scale":{"default":2.0},"min_tokens":{"default":2},"num_inference_steps":{"default":10},"retry_badcase":{"default":true},"retry_badcase_max_times":{"default":3},"retry_badcase_ratio_threshold":{"default":6.0},"text_chunk_mode":{"default":"tag_aware"}},"optional":{"max_tokens":{"default":null}},"workflow":"clone"}
+ ],
+ "audio-cpp/audio.cpp-gguf/Voxtral-4B-TTS-2603-GGUF": [
+ {"exclude":["voice"],"include":{"guidance_scale":{"default":1.2},"max_tokens":{"default":2048},"num_inference_steps":{"default":7},"text_chunk_mode":{"default":"default"},"text_chunk_size":{"default":300},"voice_id":{"default":"casual_male","values":["casual_female","casual_male","cheerful_female","neutral_female","neutral_male","pt_male","pt_female","nl_male","nl_female","it_male","it_female","fr_male","fr_female","es_male","es_female","de_male","de_female","ar_male","hi_male","hi_female"]}},"optional":{},"workflow":"speak"}
]
}
}
diff --git a/studio/backend/tests/test_audio_cpp_catalog_v092.py b/studio/backend/tests/test_audio_cpp_catalog_v092.py
new file mode 100644
index 00000000000..a52f443ef59
--- /dev/null
+++ b/studio/backend/tests/test_audio_cpp_catalog_v092.py
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Folders audio.cpp v0.9.2 runs that Unsloth Studio now offers: their name hints and the language
+each transcription request carries."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from core.inference import audio_cpp_models as acm
+from core.inference import stt_audiocpp_sidecar as stt
+from core.inference.audio_cpp_models import AUDIO_CPP_REPO
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from test_audio_cpp_models import _gguf_bytes, _put, _snapshot, hub # noqa: E402, F401
+from test_stt_audiocpp_details import ABSENT, fake, side, source # noqa: E402, F401
+
+
+def _names(folder, gguf = None):
+ return (f"{AUDIO_CPP_REPO}/{folder}", folder, *([gguf] if gguf else []))
+
+
+ ("names", "family"),
+ [
+ # Hub names on audio-cpp/audio.cpp-gguf; Voxtral TTS speaks, it is not the realtime ASR.
+ (_names("Voxtral-4B-TTS-2603-GGUF"), None),
+ (_names("Voxtral-4B-TTS-2603-GGUF", "voxtral-4b-tts-2603-q8_0.gguf"), None),
+ (_names("Voxtral-4B-TTS-2603-GGUF", "voxtral-4b-tts-2603-bf16.gguf"), None),
+ (_names("Voxtral-Mini-4B-Realtime-2602-GGUF"), "voxtral_realtime"),
+ (
+ _names("Voxtral-Mini-4B-Realtime-2602-GGUF", "voxtral-mini-4b-realtime-2602-q4_k.gguf"),
+ "voxtral_realtime",
+ ),
+ (_names("KittenTTS-GGUF"), "kitten_tts"),
+ (("dignome/kitten_tts2", "kitten-tts2", "kitten-tts2-native-q8-multilingual.gguf"), None),
+ # A version dot is dropped before matching: IndexTTS2.5 is still index_tts2.
+ (_names("IndexTTS2.5-GGUF"), "index_tts2"),
+ (_names("IndexTTS2.5-GGUF", "index-tts2_5-q8_0.gguf"), "index_tts2"),
+ ],
+)
+def test_name_hints(names, family):
+ assert acm.family_from_names(names) == family
+
+
+OWSM = f"{AUDIO_CPP_REPO}/OWSM-GGUF"
+HVISKE_V6 = f"{AUDIO_CPP_REPO}/Hviske-v6-GGUF"
+
+
+def _asr_spec(*options):
+ return {
+ "schema_version": 1,
+ "tasks": ["asr"],
+ "options": {"request": [{"name": n, "type": "string"} for n in options]},
+ }
+
+
+def v092_asr(fake, hub, monkeypatch):
+ monkeypatch.setattr(acm, "runtime_knows_family", lambda family: True)
+ snap = _snapshot(hub)
+ _put(
+ snap,
+ "OWSM-GGUF/owsm-v4-base-102m-q8_0.gguf",
+ _gguf_bytes(family = "owsm", spec = _asr_spec("language", "max_tokens")),
+ )
+ _put(
+ snap,
+ "OWSM-CTC-GGUF/owsm-ctc-v4-1b-q8_0.gguf",
+ _gguf_bytes(family = "owsm_ctc", spec = _asr_spec("language", "max_tokens")),
+ )
+ _put(
+ snap,
+ "Hviske-v6-GGUF/hviske-v6-q8_0.gguf",
+ _gguf_bytes(family = "hviske_asr_v6", spec = _asr_spec("max_tokens", "num_beams")),
+ )
+ acm.forget()
+ with acm._resolve_lock:
+ acm._downloaded_cache.clear()
+ return fake
+
+
[email protected]("language", ["fr", "da-DK", None])
+def test_owsm_detects_the_language_rather_than_a_two_letter_code(v092_asr, side, source, language):
+ result = side.transcribe_path(source, OWSM, language)
+ (body,) = v092_asr.bodies
+ assert body["language"] == "auto"
+ # The language the model reports hearing (the fake server answers English), not the ignored choice.
+ assert result["language"] == "English"
+
+
[email protected]("language, reported", [("fr", "fr"), (None, None)])
+def test_owsm_ctc_reports_the_choice_rather_than_an_echoed_auto(
+ v092_asr, side, source, language, reported
+):
+ result = side.transcribe_path(source, f"{AUDIO_CPP_REPO}/OWSM-CTC-GGUF", language)
+ (body,) = v092_asr.bodies
+ assert body["language"] == "auto"
+ # OWSM-CTC detects nothing and echoes "auto"; that is never reported as a language.
+ assert result["language"] == reported
+
+
[email protected]("family", ["owsm", "owsm_ctc"])
+def test_owsm_families_always_read_auto(family):
+ assert stt._runtime_language(family, "fr") == "auto"
+ assert stt._runtime_language(family, None) == "auto"
+
+
+def test_a_spec_without_a_language_option_gets_none(v092_asr, side, source):
+ assert acm.resolve(HVISKE_V6, network = False).request_keys == {"max_tokens", "num_beams"}
+ side.transcribe_path(source, HVISKE_V6, "da")
+ (body,) = v092_asr.bodies
+ assert body.get("language", ABSENT) is ABSENT
diff --git a/studio/backend/tests/test_audio_cpp_clone_requests.py b/studio/backend/tests/test_audio_cpp_clone_requests.py
index fc3a26e89f7..8728c36f044 100644
--- a/studio/backend/tests/test_audio_cpp_clone_requests.py
+++ b/studio/backend/tests/test_audio_cpp_clone_requests.py
@@ -236,6 +236,23 @@ def test_request_keys_follow_the_contract_the_server_checks(runtime, embedded, k
assert acm._request_keys(runtime, embedded) == (frozenset(keys) if keys else None)
+# fmt: off
[email protected]("runtime, embedded, keys", [
+ # v0.9.2 checks model_specs/ before the GGUF's v1 contract.
+ (_spec("instruct", "instruction", "language"), _spec("language", "seed"), {"instruct", "instruction", "language"}),
+ # A legacy model_specs/ entry is not strict, even over a v1 GGUF.
+ (_spec("instruct", "language", strict = False), _spec("language", "seed"), None),
+ # No runtime spec, or one without request options: the GGUF's own contract.
+ (None, _spec("language"), {"language"}),
+ ({**_spec(), "options": {}}, _spec("language"), {"language"}),
+ (None, _spec("language", strict = False), None),
+])
+# fmt: on
+def test_request_keys_on_a_spec_first_runtime(runtime, embedded, keys):
+ got = acm._request_keys(runtime, embedded, runtime_first = True)
+ assert got == (frozenset(keys) if keys else None)
+
+
def test_speak_on_a_runtime_with_model_specs_sends_only_what_the_gguf_declares():
runtime = _spec("instruct", "instruction", "language")
embedded = _spec("language", "template_name", "seed")
diff --git a/studio/backend/tests/test_audio_cpp_header_rebuild.py b/studio/backend/tests/test_audio_cpp_header_rebuild.py
new file mode 100644
index 00000000000..cd6426a903f
--- /dev/null
+++ b/studio/backend/tests/test_audio_cpp_header_rebuild.py
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""audio.cpp loads rebuild a republished GGUF from the cached older copy when only its header changed."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from core.inference import audio_cpp_files
+from core.inference.audio_cpp_backend import AudioCppBackend
+from core.inference.audio_cpp_models import RepoFile, _hub_listing
+from hub.utils import gguf_header_delta as delta
+
+_TESTS_DIR = str(Path(__file__).resolve().parent)
+if _TESTS_DIR not in sys.path:
+ sys.path.insert(0, _TESTS_DIR)
+
+from test_gguf_header_delta import ( # noqa: E402, F401
+ COMMIT_NEW,
+ COMMIT_OLD,
+ NAME,
+ NEW,
+ TENSORS,
+ Fetcher,
+ _small_ranges,
+ cache_with_old,
+ make_gguf,
+ sha,
+)
+
+REPO = "unsloth/Model-GGUF"
+EXTRA = "codec.bin"
+
+
+def hub(tmp_path, monkeypatch):
+ """A fake Hub: HEAD answers for COMMIT_NEW, Range reads serve ``hub.data``, downloads are recorded."""
+ monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)
+ monkeypatch.setattr("utils.hf_cache_settings.active_hf_hub_cache", lambda: tmp_path)
+ state = SimpleNamespace(data = NEW, heads = [], downloads = [], extra_blob = None)
+
+ def head(
+ url,
+ token = None,
+ timeout = None,
+ ):
+ state.heads.append(url)
+ return SimpleNamespace(
+ commit_hash = COMMIT_NEW, etag = f'"{sha(state.data)}"', size = len(state.data)
+ )
+
+ def download(
+ repo_id,
+ filename,
+ token = None,
+ cache_dir = None,
+ ):
+ state.downloads.append(filename)
+ repo_dir = Path(cache_dir) / ("models--" + repo_id.replace("/", "--"))
+ snap = repo_dir / "snapshots" / (repo_dir / "refs" / "main").read_text()
+ if filename == EXTRA and state.extra_blob: # an unchanged blob: link only
+ os.symlink(os.path.join("..", "..", "blobs", state.extra_blob), snap / filename)
+
+ monkeypatch.setattr("huggingface_hub.get_hf_file_metadata", head)
+ monkeypatch.setattr("huggingface_hub.hf_hub_download", download)
+ monkeypatch.setattr(delta, "hub_range_fetcher", lambda *a, **k: Fetcher(state.data))
+ return state
+
+
+def _model(*files):
+ return SimpleNamespace(
+ repo_id = REPO, local_path = None, variant = SimpleNamespace(files = tuple(files))
+ )
+
+
+def _new_file(listed_sha = None, data = NEW):
+ return RepoFile(NAME, len(data), sha(data) if listed_sha is None else listed_sha)
+
+
+def test_header_only_change_is_rebuilt_without_a_download(tmp_path, hub):
+ repo_dir = cache_with_old(tmp_path, symlinks = True)
+ model = _model(_new_file())
+ assert AudioCppBackend._download_missing(model, None) is True
+ assert hub.downloads == [] and len(hub.heads) == 1
+ assert (repo_dir / "refs" / "main").read_text() == COMMIT_NEW
+ assert sha((repo_dir / "snapshots" / COMMIT_NEW / NAME).read_bytes()) == sha(NEW)
+ assert audio_cpp_files.missing_files(model) == []
+
+
+def test_changed_tensors_fall_back_to_the_download(tmp_path, hub):
+ repo_dir = cache_with_old(tmp_path, symlinks = True)
+ hub.data = make_gguf({"general.architecture": "llama"}, TENSORS[:1])
+ AudioCppBackend._download_missing(_model(_new_file(data = hub.data)), None)
+ assert hub.downloads == [NAME]
+ assert (repo_dir / "refs" / "main").read_text() == COMMIT_OLD
+
+
+def test_listing_sha_disagreeing_with_the_hub_falls_back(tmp_path, hub):
+ cache_with_old(tmp_path, symlinks = True)
+ AudioCppBackend._download_missing(_model(_new_file(listed_sha = "c" * 64)), None)
+ assert hub.downloads == [NAME]
+
+
[email protected]("case", ["offline", "kill switch", "no older copy", "not a gguf"])
+def test_no_head_request_when_nothing_can_be_rebuilt(tmp_path, hub, monkeypatch, case):
+ name = NAME
+ if case == "offline":
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ elif case == "kill switch":
+ monkeypatch.setenv(delta.DELTA_ENV, "0")
+ elif case == "not a gguf":
+ name = EXTRA
+ if case != "no older copy":
+ cache_with_old(tmp_path, symlinks = True)
+ model = _model(RepoFile(name, len(NEW), sha(NEW)))
+ assert AudioCppBackend._rebuild_header_only(model, name, None, str(tmp_path)) is False
+ assert hub.heads == []
+
+
+def test_unchanged_files_of_a_mixed_variant_are_linked_after_the_rebuild(tmp_path, hub):
+ repo_dir = cache_with_old(tmp_path, symlinks = True)
+ extra = b"unchanged codec"
+ blob = hub.extra_blob = hashlib.sha256(extra).hexdigest()
+ (repo_dir / "blobs" / blob).write_bytes(extra)
+ os.symlink(os.path.join("..", "..", "blobs", blob), repo_dir / "snapshots" / COMMIT_OLD / EXTRA)
+ model = _model(_new_file(), RepoFile(EXTRA, len(extra)))
+ assert audio_cpp_files.missing_files(model) == [(NAME, len(NEW))]
+ assert AudioCppBackend._download_missing(model, None) is True
+ assert hub.downloads == [EXTRA]
+ assert audio_cpp_files.missing_files(model) == []
+
+
+def test_hub_listing_keeps_the_lfs_sha256(monkeypatch):
+ entries = [
+ SimpleNamespace(path = "m.gguf", size = 4, lfs = SimpleNamespace(sha256 = "AB" * 32)),
+ SimpleNamespace(path = "README.md", size = 2, lfs = None),
+ SimpleNamespace(path = "sub", size = None),
+ ]
+
+ class Api:
+ def __init__(self, token = None):
+ pass
+
+ def list_repo_tree(self, *args, **kwargs):
+ return entries
+
+ monkeypatch.setattr("huggingface_hub.HfApi", Api)
+ files = _hub_listing(REPO, "", None)
+ assert [(f.path, f.sha256) for f in files] == [("README.md", ""), ("m.gguf", "ab" * 32)]
+ # The sha256 never changes equality, so a cached listing still matches a fresh one.
+ assert files[1] == RepoFile("m.gguf", 4) and hash(files[1]) == hash(RepoFile("m.gguf", 4))
diff --git a/studio/backend/tests/test_audio_cpp_models.py b/studio/backend/tests/test_audio_cpp_models.py
index d1cca1ebe52..276c771619e 100644
--- a/studio/backend/tests/test_audio_cpp_models.py
+++ b/studio/backend/tests/test_audio_cpp_models.py
@@ -349,6 +349,7 @@ def test_unsupported_task_tokens_are_refused_by_a_readable_name(hub):
_REAL_RUNTIME_KNOWS_FAMILY = acm.runtime_knows_family
+_REAL_RUNTIME_SPEC = acm.runtime_spec
def _fake_runtime(
@@ -376,34 +377,15 @@ def _fake_runtime(
return binary
-def test_the_spec_family_list_covers_the_published_runtimes():
- from core.inference.audio_cpp_spec_families import (
- AUDIO_CPP_SPEC_FAMILIES,
- AUDIO_CPP_SPEC_FAMILIES_TAGS,
- )
-
- # Both releases ship the same model_specs/ stems, so a v0.9.0 install keeps the up-front refusal.
- assert {"v0.9.0-unsloth.1", "v0.9.1-unsloth.1"} <= AUDIO_CPP_SPEC_FAMILIES_TAGS
- for family in ("crisperwhisper", "index_echo", "audio_flamingo", "kugelaudio", "smart_turn"):
- assert family not in AUDIO_CPP_SPEC_FAMILIES
- for family in ("samsone", "gigaam_asr", "maya1"):
- assert family in AUDIO_CPP_SPEC_FAMILIES
- assert set(acm.FAMILIES) - AUDIO_CPP_SPEC_FAMILIES == {"marblenet_vad", "silero_vad"}
-
-
-def test_runtime_knows_a_family_from_its_specs_or_the_listed_tags(monkeypatch, tmp_path):
+def test_runtime_knows_a_family_from_its_specs_folder(monkeypatch, tmp_path):
from core.inference import audio_cpp_server
monkeypatch.setattr(audio_cpp_server, "find_audio_cpp_server_binary", lambda: None)
assert acm.runtime_knows_family("samsone") is None
- for tag in ("v0.9.0-unsloth.1", "v0.9.1-unsloth.1"):
- _fake_runtime(monkeypatch, tmp_path / tag, tag = tag)
- assert acm.runtime_knows_family("samsone") is True
- assert acm.runtime_knows_family("crisperwhisper") is False
- _fake_runtime(monkeypatch, tmp_path / "newer", tag = "v9.9.9-unsloth.1")
- assert acm.runtime_knows_family("crisperwhisper") is None
- _fake_runtime(monkeypatch, tmp_path / "custom")
- assert acm.runtime_knows_family("crisperwhisper") is None
+ # No folder (a custom build, or a fetch that failed) is unknown whatever the tag says.
+ for tag in ("v0.9.1-unsloth.1", "v0.9.2-unsloth.1", None):
+ _fake_runtime(monkeypatch, tmp_path / str(tag), tag = tag)
+ assert acm.runtime_knows_family("crisperwhisper") is None
_fake_runtime(
monkeypatch, tmp_path / "specs", tag = "v0.9.1-unsloth.1", specs = ("crisperwhisper",)
)
@@ -414,7 +396,13 @@ def test_runtime_knows_a_family_from_its_specs_or_the_listed_tags(monkeypatch, t
def test_a_spec_fallback_family_the_runtime_lacks_is_refused(hub, monkeypatch, tmp_path):
# The hub fixture leaves the runtime out of reach; this test installs one.
monkeypatch.setattr(acm, "runtime_knows_family", _REAL_RUNTIME_KNOWS_FAMILY)
- _fake_runtime(monkeypatch, tmp_path, tag = "v0.9.1-unsloth.1")
+ monkeypatch.setattr(acm, "runtime_spec", _REAL_RUNTIME_SPEC)
+ binary = _fake_runtime(
+ monkeypatch, tmp_path, tag = "v0.9.1-unsloth.1", specs = ("gigaam_asr", "kokoro_tts")
+ )
+ (binary.parent / "model_specs" / "gigaam_asr.json").write_text(
+ json.dumps({"family": "gigaam_asr", "tasks": ["asr"]})
+ )
for family, folder, tasks in (
("gigaam_asr", "GigaAM-v3-GGUF", ["asr"]),
("crisperwhisper", "CrisperWhisper2.0-GGUF", ["asr"]),
diff --git a/studio/backend/tests/test_audio_cpp_option_renames.py b/studio/backend/tests/test_audio_cpp_option_renames.py
new file mode 100644
index 00000000000..72481c75aef
--- /dev/null
+++ b/studio/backend/tests/test_audio_cpp_option_renames.py
@@ -0,0 +1,234 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Options audio.cpp v0.9.2 renamed: one control under the legacy name, one name on the wire, and
+the spec each runtime checks deciding which."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from core.inference import audio_cpp_models as acm
+from core.inference import audio_cpp_server as srv
+from core.inference.audio_cpp_models import AUDIO_CPP_REPO
+from core.inference.audio_cpp_option_table import OPTION_RENAMES
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from test_audio_cpp_models import _fake_runtime, _gguf_bytes, _put, _snapshot, hub # noqa: E402, F401
+
+
+def _float(
+ name,
+ default,
+ description = "",
+ **kw,
+):
+ return {
+ "name": name,
+ "type": "float",
+ "description": description,
+ "required": False,
+ "default": default,
+ **kw,
+ }
+
+
+def _spec(
+ family,
+ *options,
+ strict = False,
+):
+ spec = {"family": family, "options": {"request": list(options)}}
+ return {**spec, "schema_version": 1} if strict else spec
+
+
+# Request options trimmed from model_specs/ at v0.9.1 and v0.9.2.
+_STEPS = {
+ "name": "num_inference_steps",
+ "type": "int",
+ "description": "",
+ "required": False,
+ "min": 1,
+}
+CHATTERBOX_OLD = _spec("chatterbox", _float("s3gen_cfg_rate", 0.7), {**_STEPS, "default": 10})
+CHATTERBOX_NEW = _spec("chatterbox", _float("flow_guidance_scale", 0.7), {**_STEPS, "default": 10})
+SEED_VC_OLD = _spec(
+ "seed_vc",
+ _float("length_adjust", 1.0, "Output duration multiplier.", min = 0.0),
+ {**_STEPS, "default": 30},
+ strict = True,
+)
+SEED_VC_NEW = _spec(
+ "seed_vc",
+ _float("duration_scale", 1.0, "V1 output duration multiplier.", min = 0.0),
+ {**_STEPS, "default": 30},
+ strict = True,
+)
+
+FOLDERS = {
+ "chatterbox": ("Chatterbox-GGUF", ("chatterbox-q8_0.gguf",)),
+ "seed_vc": ("SeedVC-MLX-GGUF", ("seed-vc-mlx-q8_0.gguf",)),
+ "ace_step": (
+ "ACE-Step1.5-GGUF",
+ ("base/ace-step-1.5-base-q8_0.gguf", "turbo/ace-step-1.5-turbo-q8_0.gguf"),
+ ),
+}
+
+
+def _resolve(
+ hub,
+ monkeypatch,
+ tmp_path,
+ family,
+ embedded,
+ runtime = None,
+ tag = None,
+):
+ """``family``'s umbrella folder with ``embedded`` in its GGUF, ``runtime`` as its model_specs/
+ entry, and an install record for ``tag`` (None: a custom build)."""
+ folder, files = FOLDERS[family]
+ snap = _snapshot(hub)
+ for rel in files:
+ _put(snap, f"{folder}/{rel}", _gguf_bytes(family = family, spec = embedded))
+ _fake_runtime(monkeypatch, tmp_path / "runtime", tag = tag)
+ monkeypatch.setattr(acm, "runtime_spec", lambda name: runtime if name == family else None)
+ acm.forget()
+ model = acm.resolve(f"{AUDIO_CPP_REPO}/{folder}", network = False)
+ assert model is not None and model.unsupported is None
+ return model
+
+
+def _names(model):
+ return [o["name"] for o in model.options]
+
+
+def test_the_table_lists_three_pairs():
+ assert dict(OPTION_RENAMES) == {
+ "chatterbox": (("s3gen_cfg_rate", "flow_guidance_scale"),),
+ "seed_vc": (("length_adjust", "duration_scale"),),
+ "ace_step": (("lm_cfg_scale", "lm_guidance_scale"),),
+ }
+
+
+def test_refreshed_chatterbox_shows_one_control_under_the_legacy_name(hub, monkeypatch, tmp_path):
+ model = _resolve(hub, monkeypatch, tmp_path, "chatterbox", CHATTERBOX_NEW)
+ assert model.request_keys is None
+ assert _names(model).count("s3gen_cfg_rate") == 1 and "flow_guidance_scale" not in _names(model)
+ (option,) = (o for o in model.options if o["name"] == "s3gen_cfg_rate")
+ assert option["default"] == 0.7
+ convert = acm.filled_options(model, "convert", {"s3gen_cfg_rate": 1.0})
+ assert convert["s3gen_cfg_rate"] == 1.0 and "flow_guidance_scale" not in convert
+ clone = acm.filled_options(model, "clone", {})
+ assert clone["s3gen_cfg_rate"] == 0.7 and "flow_guidance_scale" not in clone
+
+
+def test_the_schema_drops_a_canonical_entry_beside_its_legacy_one(hub, monkeypatch, tmp_path):
+ both = _spec("chatterbox", _float("s3gen_cfg_rate", 0.7), _float("flow_guidance_scale", 0.9))
+ model = _resolve(hub, monkeypatch, tmp_path, "chatterbox", both)
+ assert [o["default"] for o in model.options if o["name"] == "s3gen_cfg_rate"] == [0.7]
+ assert "flow_guidance_scale" not in _names(model)
+
+
+def test_an_api_caller_may_use_the_canonical_name(hub, monkeypatch, tmp_path):
+ model = _resolve(hub, monkeypatch, tmp_path, "chatterbox", CHATTERBOX_NEW)
+ out = acm.filled_options(model, "convert", {"flow_guidance_scale": 1.0})
+ assert out["s3gen_cfg_rate"] == 1.0 and "flow_guidance_scale" not in out
+ # Both given: the legacy value wins, whatever the order.
+ for values in (
+ {"flow_guidance_scale": 2.0, "s3gen_cfg_rate": 1.0},
+ {"s3gen_cfg_rate": 1.0, "flow_guidance_scale": 2.0},
+ ):
+ out = acm.filled_options(model, "convert", values)
+ assert out["s3gen_cfg_rate"] == 1.0 and "flow_guidance_scale" not in out
+
+
+def test_strict_refreshed_seed_vc_sends_the_canonical_name(hub, monkeypatch, tmp_path):
+ model = _resolve(hub, monkeypatch, tmp_path, "seed_vc", SEED_VC_NEW)
+ assert "duration_scale" in model.request_keys and "length_adjust" in _names(model)
+ out = acm.filled_options(model, "convert", {"length_adjust": 1.5})
+ assert out["duration_scale"] == 1.5 and "length_adjust" not in out
+ # Left unset, the default is still filled, under the name the contract declares.
+ out = acm.filled_options(model, "convert", {})
+ assert out["duration_scale"] == 1.0 and "length_adjust" not in out
+
+
+def test_old_seed_vc_sends_the_legacy_name(hub, monkeypatch, tmp_path):
+ model = _resolve(hub, monkeypatch, tmp_path, "seed_vc", SEED_VC_OLD)
+ for values in ({"length_adjust": 1.5}, {"duration_scale": 1.5}):
+ out = acm.filled_options(model, "convert", values)
+ assert out["length_adjust"] == 1.5 and "duration_scale" not in out
+
+
+def test_ace_step_takes_the_canonical_planner_guidance_as_input(hub, monkeypatch, tmp_path):
+ model = _resolve(hub, monkeypatch, tmp_path, "ace_step", {})
+ out = acm.filled_options(model, "music", {"lm_guidance_scale": 3.0})
+ assert out["lm_cfg_scale"] == 3.0 and "lm_guidance_scale" not in out
+
+
+def test_a_spec_first_runtime_takes_its_own_spec_over_an_old_strict_gguf(
+ hub, monkeypatch, tmp_path
+):
+ model = _resolve(
+ hub,
+ monkeypatch,
+ tmp_path,
+ "seed_vc",
+ SEED_VC_OLD,
+ runtime = SEED_VC_NEW,
+ tag = "v0.9.2-unsloth.1",
+ )
+ assert "length_adjust" in _names(model) and "duration_scale" not in _names(model)
+ assert "duration_scale" in model.request_keys and "length_adjust" not in model.request_keys
+ out = acm.filled_options(model, "convert", {"length_adjust": 1.5})
+ assert out["duration_scale"] == 1.5 and "length_adjust" not in out
+
+
+def test_an_older_runtime_ignores_a_backfilled_model_specs(hub, monkeypatch, tmp_path):
+ model = _resolve(
+ hub,
+ monkeypatch,
+ tmp_path,
+ "seed_vc",
+ SEED_VC_OLD,
+ runtime = SEED_VC_NEW,
+ tag = "v0.9.1-unsloth.1",
+ )
+ assert model.request_keys == frozenset({"length_adjust", "num_inference_steps"})
+ assert [o["description"] for o in model.options if o["name"] == "length_adjust"] == [
+ "Output duration multiplier."
+ ]
+ out = acm.filled_options(model, "convert", {"length_adjust": 1.5})
+ assert out["length_adjust"] == 1.5 and "duration_scale" not in out
+
+
+def test_a_custom_build_keeps_the_embedded_contract_first(hub, monkeypatch, tmp_path):
+ model = _resolve(hub, monkeypatch, tmp_path, "seed_vc", SEED_VC_OLD, runtime = SEED_VC_NEW)
+ assert srv.runtime_release_key() is None
+ assert model.request_keys == frozenset({"length_adjust", "num_inference_steps"})
+ out = acm.filled_options(model, "convert", {"length_adjust": 1.5})
+ assert out["length_adjust"] == 1.5 and "duration_scale" not in out
+
+
+def _loose(spec):
+ return {k: v for k, v in spec.items() if k != "schema_version"}
+
+
+# fmt: off
[email protected]("family, workflow, embedded, runtime", [
+ ("chatterbox", "convert", CHATTERBOX_OLD, CHATTERBOX_NEW),
+ ("chatterbox", "convert", CHATTERBOX_NEW, CHATTERBOX_NEW),
+ ("seed_vc", "convert", _loose(SEED_VC_OLD), SEED_VC_NEW),
+ ("seed_vc", "convert", _loose(SEED_VC_NEW), SEED_VC_NEW),
+ ("ace_step", "music", {}, None),
+])
+# fmt: on
+def test_a_v091_runtime_gets_only_legacy_names(hub, monkeypatch, tmp_path, family, workflow, embedded, runtime):
+ model = _resolve(hub, monkeypatch, tmp_path, family, embedded, runtime = runtime, tag = "v0.9.1-unsloth.1")
+ assert model.request_keys is None
+ ((old, canonical),) = OPTION_RENAMES[family]
+ for values in ({}, {old: 1.5}, {canonical: 1.5}):
+ out = acm.filled_options(model, workflow, values)
+ assert canonical not in out, (values, out)
+ if values:
+ assert out[old] == 1.5
diff --git a/studio/backend/tests/test_audio_cpp_option_table.py b/studio/backend/tests/test_audio_cpp_option_table.py
index cc29270ca64..c6728555de8 100644
--- a/studio/backend/tests/test_audio_cpp_option_table.py
+++ b/studio/backend/tests/test_audio_cpp_option_table.py
@@ -19,11 +19,10 @@ import pytest
from core.inference import audio_cpp_backend, audio_cpp_files
from core.inference import audio_cpp_models as acm
from core.inference.audio_cpp_option_table import (
- AUDIO_CPP_OPTION_TABLE_TAGS,
+ OPTION_RENAMES,
OPTION_RULES,
STUDIO_OPTION_LISTS,
)
-from core.inference.audio_cpp_spec_families import AUDIO_CPP_SPEC_FAMILIES_TAGS
_TESTS_DIR = str(Path(__file__).resolve().parent)
if _TESTS_DIR not in sys.path:
@@ -83,10 +82,6 @@ def _wanted(model, workflow):
return workflow in model.workflows
-def test_the_table_is_written_for_the_pinned_runtime():
- assert AUDIO_CPP_OPTION_TABLE_TAGS == AUDIO_CPP_SPEC_FAMILIES_TAGS
-
-
def test_the_fixture_covers_the_catalog():
source = CATALOG.read_text(encoding = "utf-8")
seeded = {
@@ -99,7 +94,7 @@ def test_the_fixture_covers_the_catalog():
def test_tables_name_known_families():
- for family in (*STUDIO_OPTION_LISTS, *OPTION_RULES):
+ for family in (*STUDIO_OPTION_LISTS, *OPTION_RULES, *OPTION_RENAMES):
assert family in acm.FAMILIES, family
diff --git a/studio/backend/tests/test_audio_cpp_runtime_specs.py b/studio/backend/tests/test_audio_cpp_runtime_specs.py
new file mode 100644
index 00000000000..b39b1f34103
--- /dev/null
+++ b/studio/backend/tests/test_audio_cpp_runtime_specs.py
@@ -0,0 +1,640 @@
+# 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 old-runtime download gate, the runtime's model_specs/ folder, and its backfill."""
+
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import replace
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from core.inference import audio_cpp_backend, audio_cpp_files, audio_cpp_server
+from core.inference import audio_cpp_models as acm
+from core.inference.audio_cpp_models import AudioCppModel, AudioCppVariant, RepoFile
+from utils import audio_cpp_update
+
+COMMIT = "0097d365" + "a" * 32
+REPO = "unslothai/audio.cpp"
+
+
+def _model(
+ folder = "Canary-180M-Flash-GGUF",
+ family = "canary_asr",
+ task = "asr",
+) -> AudioCppModel:
+ main = RepoFile(f"{folder}/{folder.lower()}-q8_0.gguf", 4)
+ variant = AudioCppVariant("Q8_0", (main,), main.path)
+ return AudioCppModel(
+ id = f"audio-cpp/audio.cpp-gguf/{folder}",
+ repo_id = "audio-cpp/audio.cpp-gguf",
+ folder = folder,
+ display_name = folder,
+ family = family,
+ task = task,
+ server_task = task,
+ variant = variant,
+ variants = (variant,),
+ default_variant = "Q8_0",
+ )
+
+
+def _runtime(
+ monkeypatch,
+ root: Path,
+ *,
+ record = None,
+ specs = None,
+ bin_dir = "",
+) -> Path:
+ """An audiocpp_server under ``root`` with an install record (when given) and a model_specs/ folder beside it."""
+ server_dir = root / bin_dir if bin_dir else root
+ server_dir.mkdir(parents = True, exist_ok = True)
+ binary = server_dir / audio_cpp_server.BINARY_NAME
+ binary.write_bytes(b"\x7fELF")
+ if record is not None:
+ (root / audio_cpp_server.INSTALL_RECORD).write_text(json.dumps(record))
+ if specs is not None:
+ (server_dir / "model_specs").mkdir()
+ for name in specs:
+ (server_dir / "model_specs" / f"{name}.json").write_text(json.dumps({"family": name}))
+ monkeypatch.setattr(audio_cpp_server, "find_audio_cpp_server_binary", lambda: str(binary))
+ return binary
+
+
+def _missing(monkeypatch, result):
+ def fake(model, *, hub_cache = None):
+ if isinstance(result, Exception):
+ raise result
+ return result
+
+ monkeypatch.setattr(audio_cpp_files, "missing_files", fake)
+
+
+def _hub(monkeypatch, tmp_path, remote: dict) -> Path:
+ """An empty active Hub cache; the Hub answers ``remote[file name]``, else ``remote["etag"]``."""
+ import huggingface_hub
+
+ from utils import hf_cache_settings
+
+ root = tmp_path / "hub"
+ root.mkdir()
+ monkeypatch.setattr(hf_cache_settings, "active_hf_hub_cache", lambda: str(root))
+ monkeypatch.setattr(acm, "hub_offline", lambda: False)
+ monkeypatch.setattr(
+ huggingface_hub,
+ "get_hf_file_metadata",
+ lambda url, **kw: type(
+ "M",
+ (),
+ {
+ "etag": remote.get(url.rsplit("/", 1)[-1], remote.get("etag")),
+ "commit_hash": remote.get("commit"),
+ },
+ )(),
+ )
+ return root
+
+
+def _cache(root: Path, repo_id: str, path: str, blob: str) -> None:
+ """Cache ``path`` the way huggingface_hub does: a snapshot symlink to ``blobs/<etag>``."""
+ repo = root / ("models--" + repo_id.replace("/", "--"))
+ (repo / "blobs").mkdir(parents = True, exist_ok = True)
+ (repo / "blobs" / blob).write_bytes(b"GGUF")
+ link = repo / "snapshots" / "c0ffee" / path
+ link.parent.mkdir(parents = True, exist_ok = True)
+ link.symlink_to(repo / "blobs" / blob)
+
+
+MESSAGE = (
+ "Canary-180M-Flash-GGUF needs a newer audio runtime before its files can be downloaded. "
+ "Update the audio runtime from the update banner, or run `unsloth studio update`."
+)
+
+
+ "tag, missing, expected",
+ [
+ ("v0.9.1-unsloth.1", [("x.gguf", 4)], MESSAGE),
+ ("v0.9.0-unsloth.1", [("x.gguf", 4)], MESSAGE),
+ # A complete cache still loads on an old runtime.
+ ("v0.9.1-unsloth.1", [], None),
+ # A cached GGUF whose companion asset is missing is repaired as before.
+ ("v0.9.1-unsloth.1", [("embeddings.safetensors", 4), ("config.json", 1)], None),
+ ("v0.9.1-unsloth.1", [("embeddings.safetensors", 4), ("X.GGUF", 4)], MESSAGE),
+ ("v0.9.2-unsloth.1", [("x.gguf", 4)], None),
+ ("v0.10.0-unsloth.1", [("x.gguf", 4)], None),
+ ("garbage", [("x.gguf", 4)], None),
+ ("v0.9.1-unsloth.1", OSError("unreadable cache"), None),
+ ],
+)
+def test_the_download_gate(monkeypatch, tmp_path, tag, missing, expected):
+ binary = _runtime(monkeypatch, tmp_path, record = {"release_tag": tag})
+ _missing(monkeypatch, missing)
+ assert audio_cpp_server.stale_runtime_download_problem(_model(), str(binary)) == expected
+ assert audio_cpp_server.stale_runtime_download_problem(_model()) == expected
+
+
+def test_a_custom_build_or_a_local_file_is_never_gated(monkeypatch, tmp_path):
+ _missing(monkeypatch, [("x.gguf", 4)])
+ _runtime(monkeypatch, tmp_path / "custom")
+ assert audio_cpp_server.stale_runtime_download_problem(_model()) is None
+ _runtime(monkeypatch, tmp_path / "old", record = {"release_tag": "v0.9.1-unsloth.1"})
+ local = replace(_model(), local_path = str(tmp_path / "m.gguf"))
+ assert audio_cpp_server.stale_runtime_download_problem(local) is None
+
+
+def test_the_tag_is_checked_before_the_cache(monkeypatch, tmp_path):
+ _runtime(monkeypatch, tmp_path, record = {"release_tag": "v0.9.2-unsloth.1"})
+ _missing(monkeypatch, AssertionError("the cache was read on a current runtime"))
+ assert audio_cpp_server.stale_runtime_download_problem(_model()) is None
+
+
+def test_model_runtime_problem_refuses_a_download_on_an_old_runtime(monkeypatch, tmp_path):
+ _runtime(monkeypatch, tmp_path, record = {"release_tag": "v0.9.1-unsloth.1"})
+ _missing(monkeypatch, [("x.gguf", 4)])
+ assert audio_cpp_server.model_runtime_problem(_model()) == MESSAGE
+
+
+def test_load_is_refused_before_any_download(monkeypatch, tmp_path):
+ _runtime(monkeypatch, tmp_path, record = {"release_tag": "v0.9.1-unsloth.1"})
+ _missing(monkeypatch, [("x.gguf", 4)])
+ downloads = []
+ monkeypatch.setattr(
+ audio_cpp_backend.AudioCppBackend,
+ "_download_missing",
+ lambda self, *a, **kw: downloads.append(a) or True,
+ )
+ model = _model("Chatterbox-GGUF", "chatterbox", "tts")
+ config = SimpleNamespace(identifier = model.id, audio_cpp = model)
+ with pytest.raises(RuntimeError, match = "needs a newer audio runtime"):
+ audio_cpp_backend.AudioCppBackend().load_model(config)
+ assert downloads == []
+
+
+def test_the_dictation_download_is_refused_before_it_starts(monkeypatch, tmp_path):
+ from core.inference import stt_audiocpp_sidecar, stt_download_worker
+
+ _runtime(monkeypatch, tmp_path / "rt", record = {"release_tag": "v0.9.1-unsloth.1"})
+ _missing(monkeypatch, [("x.gguf", 4)])
+ model = _model()
+ monkeypatch.setattr(stt_audiocpp_sidecar, "resolve_audio_cpp_stt_model", lambda *a, **kw: model)
+ spawned = []
+ monkeypatch.setattr(stt_download_worker, "spawn_download", lambda *a, **kw: spawned.append(a))
+ import huggingface_hub
+
+ def no_network(*a, **kw):
+ raise AssertionError("the Hub was asked before the gate")
+
+ monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", no_network)
+ state = stt_audiocpp_sidecar._AudioCppDownloadState()
+ state._run(model.id, None, tmp_path / "hub")
+ assert state._error == MESSAGE
+ assert spawned == []
+
+
+def test_a_missing_companion_is_refused_before_any_download(monkeypatch, tmp_path):
+ _runtime(monkeypatch, tmp_path / "rt", record = {"release_tag": "v0.9.1-unsloth.1"})
+ tts = replace(
+ _model("MioTTS-GGUF", "miotts", "tts"),
+ companions = (
+ acm.CompanionModel("audio-cpp/audio.cpp-gguf/MioCodec-GGUF", "Q8_0", "codec_model"),
+ ),
+ )
+ codec = _model("MioCodec-GGUF", "miocodec", "codec")
+ # The TTS files are cached; only the codec still has files to fetch.
+ monkeypatch.setattr(
+ audio_cpp_files,
+ "missing_files",
+ lambda model, *, hub_cache = None: [] if model is tts else [("codec.gguf", 4)],
+ )
+ monkeypatch.setattr(audio_cpp_backend, "_resolve_companion", lambda *a, **kw: codec)
+ downloads = []
+ monkeypatch.setattr(
+ audio_cpp_backend.AudioCppBackend,
+ "_download_missing",
+ staticmethod(lambda model, *a, **kw: downloads.append(model.id)),
+ )
+ assert audio_cpp_server.model_runtime_problem(tts) is None
+ with pytest.raises(RuntimeError, match = "MioCodec-GGUF needs a newer audio runtime"):
+ audio_cpp_backend.AudioCppBackend()._ensure_downloaded(tts, None)
+ assert downloads == []
+
+
+def test_a_hub_download_job_is_refused_on_an_old_runtime(monkeypatch, tmp_path):
+ import asyncio
+
+ from fastapi import HTTPException
+
+ from hub.services.models import downloads
+
+ _runtime(monkeypatch, tmp_path / "rt", record = {"release_tag": "v0.9.1-unsloth.1"})
+ _missing(monkeypatch, [("x.gguf", 4)])
+ model = replace(_model(), from_hub = True)
+ monkeypatch.setattr(acm, "resolve", lambda *a, **kw: model)
+ with pytest.raises(HTTPException) as refused:
+ asyncio.run(downloads._audio_cpp_target(model.id, "Q8_0", persist = True))
+ assert refused.value.status_code == 409 and refused.value.detail == MESSAGE
+ # A cached model whose companion is missing is refused too: the job would fetch the companion.
+ codec = replace(_model("MioCodec-GGUF", "miocodec", "codec"), from_hub = True)
+ tts = replace(
+ _model("MioTTS-GGUF", "miotts", "tts"),
+ from_hub = True,
+ companions = (acm.CompanionModel(codec.id, "Q8_0", "codec_model"),),
+ )
+ monkeypatch.setattr(acm, "resolve", lambda ident, *a, **kw: codec if ident == codec.id else tts)
+ monkeypatch.setattr(
+ audio_cpp_files,
+ "missing_files",
+ lambda m, *, hub_cache = None: [] if m is tts else [("codec.gguf", 4)],
+ )
+ with pytest.raises(HTTPException, match = "409"):
+ asyncio.run(downloads._audio_cpp_target(tts.id, "Q8_0", persist = True))
+ monkeypatch.setattr(acm, "resolve", lambda *a, **kw: model)
+ _missing(monkeypatch, [("x.gguf", 4)])
+ # Status and progress polls resolve the same row without the gate.
+ assert asyncio.run(downloads._audio_cpp_target(model.id, "Q8_0"))[0] == model.repo_id
+
+
+def test_a_download_job_outside_the_umbrella_is_gated_too(monkeypatch, tmp_path):
+ import asyncio
+
+ from fastapi import HTTPException
+
+ from hub.services.models import downloads
+
+ music = replace(
+ _model(), id = "audio-cpp/MiniMax-Music3-GGUF", repo_id = "audio-cpp/MiniMax-Music3-GGUF"
+ )
+ looked_up = []
+ monkeypatch.setattr(
+ acm,
+ "resolve",
+ lambda ident, *a, **kw: looked_up.append(ident) or (music if ident == music.id else None),
+ )
+ _missing(monkeypatch, [("x.gguf", 4)])
+ # A current runtime never looks the repo up, so ordinary GGUF downloads pay nothing.
+ _runtime(monkeypatch, tmp_path / "new", record = {"release_tag": "v0.9.2-unsloth.1"})
+ assert asyncio.run(downloads._audio_cpp_target(music.id, "Q8_0", persist = True)) == (
+ music.id,
+ "Q8_0",
+ )
+ assert looked_up == []
+ _runtime(monkeypatch, tmp_path / "old", record = {"release_tag": "v0.9.1-unsloth.1"})
+ with pytest.raises(HTTPException) as refused:
+ asyncio.run(downloads._audio_cpp_target(music.id, "Q8_0", persist = True))
+ assert (
+ refused.value.status_code == 409 and "needs a newer audio runtime" in refused.value.detail
+ )
+ # A repo that is not an audio model, and status polls, pass through unchanged.
+ assert asyncio.run(downloads._audio_cpp_target("org/llm-GGUF", "Q4_K_M", persist = True)) == (
+ "org/llm-GGUF",
+ "Q4_K_M",
+ )
+ assert asyncio.run(downloads._audio_cpp_target(music.id, "Q8_0")) == (music.id, "Q8_0")
+ # A caller that must stay anonymous never has a repo resolved with the ambient token.
+ looked_up.clear()
+ assert asyncio.run(
+ downloads._audio_cpp_target(music.id, "Q8_0", persist = True, stale_gate = False)
+ ) == (music.id, "Q8_0")
+ assert looked_up == []
+
+
+def test_a_scoped_download_job_is_gated_on_the_files_it_fetches(monkeypatch, tmp_path):
+ import asyncio
+
+ from fastapi import HTTPException
+
+ from hub.services.models import downloads
+
+ aligner = _model("Qwen3-ForcedAligner-0.6B-GGUF", "qwen3_forced_aligner", "aligner")
+ looked_up = []
+ monkeypatch.setattr(acm, "resolve", lambda ident, *a, **kw: looked_up.append(ident) or aligner)
+ remote = {"etag": "blob"}
+ root = _hub(monkeypatch, tmp_path, remote)
+ _missing(monkeypatch, [("x.gguf", 4)])
+ files = ["Qwen3-ForcedAligner-0.6B-GGUF/aligner-q8_0.gguf", "README.md"]
+ scoped = lambda repo, names: asyncio.run( # noqa: E731
+ downloads._refuse_stale_scoped_download(repo, names, None)
+ )
+ _runtime(monkeypatch, tmp_path / "new", record = {"release_tag": "v0.9.2-unsloth.1"})
+ scoped(acm.AUDIO_CPP_REPO, files)
+ assert looked_up == []
+ _runtime(monkeypatch, tmp_path / "old", record = {"release_tag": "v0.9.1-unsloth.1"})
+ with pytest.raises(HTTPException) as refused:
+ scoped(acm.AUDIO_CPP_REPO, files)
+ assert (
+ refused.value.status_code == 409 and "needs a newer audio runtime" in refused.value.detail
+ )
+ # The umbrella's files resolve as their folder rows.
+ assert looked_up == [aligner.id]
+ # Files already cached, or no GGUF at all, fetch nothing the runtime loads.
+ _cache(root, acm.AUDIO_CPP_REPO, files[0], "blob")
+ scoped(acm.AUDIO_CPP_REPO, files)
+ scoped("org/some-model", ["README.md", "config.json"])
+ assert looked_up == [aligner.id]
+ # An older cached copy does not count when the Hub serves a refreshed file.
+ remote["etag"] = "refreshed"
+ with pytest.raises(HTTPException):
+ scoped(acm.AUDIO_CPP_REPO, files)
+
+
+def test_a_download_job_reads_the_cache_it_writes_into(monkeypatch, tmp_path):
+ from hub.services.models import downloads
+
+ model = _model()
+ path = model.variant.files[0].path
+ monkeypatch.setattr(acm, "resolve", lambda *a, **kw: model)
+ _hub(monkeypatch, tmp_path, {"etag": "cursha", "commit": "c0ffee"})
+ _runtime(monkeypatch, tmp_path / "old", record = {"release_tag": "v0.9.1-unsloth.1"})
+ chosen = tmp_path / "chosen"
+ _cache(chosen, model.repo_id, path, "cursha")
+ # Complete in the chosen folder, empty in the Models folder: the job fetches nothing.
+ acm._refuse_stale_download(model, None, hub_cache = chosen)
+ with pytest.raises(audio_cpp_server.AudioCppRuntimeTooOldError):
+ acm._refuse_stale_download(model, None)
+ assert downloads._gate_hub_cache(None) is None
+ assert downloads._gate_hub_cache(" ") is None
+
+
+def test_a_cache_without_symlinks_counts_as_complete(monkeypatch, tmp_path):
+ # Without symlink support huggingface_hub moves the blob into the commit's snapshot.
+ model = _model()
+ path = model.variant.files[0].path
+ monkeypatch.setattr(acm, "resolve", lambda *a, **kw: model)
+ root = _hub(monkeypatch, tmp_path, {"etag": "cursha", "commit": "c0ffee"})
+ target = root / ("models--" + model.repo_id.replace("/", "--")) / "snapshots" / "c0ffee" / path
+ target.parent.mkdir(parents = True)
+ target.write_bytes(b"GGUF")
+ _runtime(monkeypatch, tmp_path / "old", record = {"release_tag": "v0.9.1-unsloth.1"})
+ acm._refuse_stale_download(model, None)
+
+
+def test_a_full_snapshot_job_is_never_gated(monkeypatch, tmp_path):
+ import asyncio
+
+ from hub.services.models import downloads
+
+ looked_up = []
+ monkeypatch.setattr(acm, "resolve", lambda ident, *a, **kw: looked_up.append(ident))
+ _runtime(monkeypatch, tmp_path / "old", record = {"release_tag": "v0.9.1-unsloth.1"})
+ # No variant means a full snapshot, which skips every *.gguf.
+ repo = "audio-cpp/MiniMax-Music3-GGUF"
+ assert asyncio.run(downloads._audio_cpp_target(repo, None, persist = True)) == (repo, None)
+ assert looked_up == []
+
+
+def test_a_scoped_job_is_checked_at_the_quant_of_its_file(monkeypatch, tmp_path):
+ folder = "Canary-180M-Flash-GGUF"
+ q8, q4 = (RepoFile(f"{folder}/canary-{q}.gguf", 4) for q in ("q8_0", "q4_k_m"))
+ variants = (AudioCppVariant("Q8_0", (q8,), q8.path), AudioCppVariant("Q4_K_M", (q4,), q4.path))
+ base = replace(_model(), variants = variants)
+ pick = lambda key: next(v for v in variants if v.key == (key or "Q8_0")) # noqa: E731
+ monkeypatch.setattr(
+ acm, "resolve", lambda ident, variant = None, *a, **kw: replace(base, variant = pick(variant))
+ )
+ # The default Q8_0 is cached; only the Q4_K_M the job asks for is missing.
+ monkeypatch.setattr(
+ audio_cpp_files,
+ "missing_files",
+ lambda m, *, hub_cache = None: [(q4.path, 4)] if m.variant.key == "Q4_K_M" else [],
+ )
+ root = _hub(monkeypatch, tmp_path, {"canary-q8_0.gguf": "q8sha", "canary-q4_k_m.gguf": "q4sha"})
+ _cache(root, acm.AUDIO_CPP_REPO, q8.path, "q8sha")
+ _runtime(monkeypatch, tmp_path / "old", record = {"release_tag": "v0.9.1-unsloth.1"})
+ with pytest.raises(audio_cpp_server.AudioCppRuntimeTooOldError):
+ acm.refuse_stale_download(acm.AUDIO_CPP_REPO, None, files = [q4.path])
+ acm.refuse_stale_download(acm.AUDIO_CPP_REPO, None, files = [q8.path])
+
+
+def test_a_download_job_compares_blob_identity_not_size(monkeypatch, tmp_path):
+ # OWSM's refreshed q8_0 has the same byte size as the original, so only the etag tells them apart;
+ # Studio's pinned downloads leave no refs/main, so the cache is read by snapshot, not by ref.
+ model = _model()
+ path = model.variant.files[0].path
+ monkeypatch.setattr(acm, "resolve", lambda *a, **kw: model)
+ remote = {"etag": "oldsha"}
+ root = _hub(monkeypatch, tmp_path, remote)
+ _cache(root, model.repo_id, path, "oldsha")
+ _missing(monkeypatch, AssertionError("a download job never trusts a same-sized cached copy"))
+ _runtime(monkeypatch, tmp_path / "old", record = {"release_tag": "v0.9.1-unsloth.1"})
+ acm.refuse_stale_download(model.repo_id, None, files = [path])
+ acm._refuse_stale_download(model, None)
+ remote["etag"] = "newsha"
+ for call in (
+ lambda: acm.refuse_stale_download(model.repo_id, None, files = [path]),
+ lambda: acm._refuse_stale_download(model, None),
+ ):
+ with pytest.raises(audio_cpp_server.AudioCppRuntimeTooOldError):
+ call()
+
+
+def test_the_timestamp_aligner_is_not_fetched_for_an_old_runtime(monkeypatch, tmp_path):
+ from core.inference import stt_audiocpp_sidecar
+
+ _runtime(monkeypatch, tmp_path / "rt", record = {"release_tag": "v0.9.1-unsloth.1"})
+ _missing(monkeypatch, [("x.gguf", 4)])
+ aligner = _model("Qwen3-ForcedAligner-0.6B-GGUF", "qwen3_forced_aligner", "aligner")
+ monkeypatch.setattr(audio_cpp_backend, "_resolve_companion", lambda *a, **kw: aligner)
+ downloads = []
+ monkeypatch.setattr(
+ audio_cpp_backend.AudioCppBackend,
+ "_download_missing",
+ staticmethod(lambda model, *a, **kw: downloads.append(model.id)),
+ )
+ side = stt_audiocpp_sidecar.AudioCppSttSidecar()
+ with pytest.raises(
+ stt_audiocpp_sidecar.SttModelNotDownloadedError, match = "needs a newer audio runtime"
+ ):
+ side._ensure_aligner_downloaded(_model("Qwen3-ASR-0.6B-GGUF", "qwen3_asr", "asr"))
+ assert downloads == []
+
+
+def test_runtime_knows_family_reads_the_folder_beside_the_server(monkeypatch, tmp_path):
+ # Windows bundles keep the server and its fetched folder under bin/.
+ _runtime(
+ monkeypatch,
+ tmp_path,
+ record = {"release_tag": "v0.9.2-unsloth.1"},
+ specs = ("owsm",),
+ bin_dir = "bin",
+ )
+ assert acm.runtime_knows_family("owsm") is True
+ assert acm.runtime_knows_family("crisperwhisper") is False
+ assert acm.runtime_knows_family("../owsm") is None
+
+
+def test_an_old_runtime_folder_hides_only_the_families_it_lacks(monkeypatch, tmp_path):
+ rows = {
+ "voxtral_tts": "tts",
+ "kugelaudio": "tts",
+ "owsm": "asr",
+ "owsm_ctc": "asr",
+ "crisperwhisper": "asr",
+ "hviske_asr_v6": "asr",
+ }
+ old = [family for family in rows if family not in ("voxtral_tts", "hviske_asr_v6")]
+ _runtime(monkeypatch, tmp_path, record = {"release_tag": "v0.9.1-unsloth.1"}, specs = old)
+ refused = {
+ family
+ for family, task in rows.items()
+ if acm.family_policy(family, {"tasks": [task]}).unsupported
+ }
+ assert refused == {"voxtral_tts", "hviske_asr_v6"}
+ assert acm.family_policy("owsm", {"tasks": ["asr"]}).task == "asr"
+
+
+def test_vad_families_never_reach_the_folder_check(monkeypatch, tmp_path):
+ _runtime(monkeypatch, tmp_path, record = {"release_tag": "v0.9.2-unsloth.1"}, specs = ("owsm",))
+ for family in ("silero_vad", "marblenet_vad"):
+ assert family in acm.FAMILIES
+ assert acm.family_policy(family).unsupported.startswith("Voice activity detection")
+
+
+def managed(monkeypatch, tmp_path):
+ """An Unsloth Studio-owned v0.9.2 install without model_specs/, and a stub installer."""
+ root = tmp_path / "audio.cpp"
+ root.mkdir()
+ (root / ".unsloth-studio-owned").write_text("")
+ for name in (
+ "AUDIOCPP_SERVER_PATH",
+ "UNSLOTH_AUDIO_CPP_PATH",
+ "UNSLOTH_SKIP_AUDIO_CPP_INSTALL",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ monkeypatch.setattr(audio_cpp_server, "managed_audio_cpp_dir", lambda: root)
+ record = {"release_tag": "v0.9.2-unsloth.1", "published_repo": REPO, "source_commit": COMMIT}
+ binary = _runtime(monkeypatch, root, record = record)
+ real_core = audio_cpp_update._installer().core
+ fetches, forgets = [], []
+
+ def fetch(repo, commit, dest_dir):
+ fetches.append((repo, commit, dest_dir))
+ (dest_dir / "model_specs").mkdir()
+ return True
+
+ installer = SimpleNamespace(
+ core = real_core, _release_index = lambda repo, tag: {}, _fetch_model_specs = fetch
+ )
+ monkeypatch.setattr(audio_cpp_update, "_installer", lambda: installer)
+ monkeypatch.setattr(acm, "forget", lambda *a: forgets.append(a))
+ return SimpleNamespace(
+ root = root,
+ binary = binary,
+ record = record,
+ installer = installer,
+ fetches = fetches,
+ forgets = forgets,
+ )
+
+
+def _write_record(env, **changes):
+ record = {k: v for k, v in {**env.record, **changes}.items() if v is not None}
+ (env.root / audio_cpp_server.INSTALL_RECORD).write_text(json.dumps(record))
+
+
+def test_backfill_fetches_the_recorded_commit_then_forgets(managed):
+ (managed.root / ".model_specs-killed").mkdir()
+ assert audio_cpp_update._backfill_model_specs() is True
+ assert managed.fetches == [(REPO, COMMIT, managed.binary.parent)]
+ assert managed.forgets == [()]
+ assert not (managed.root / ".model_specs-killed").exists()
+ # Once the folder is there, a second run does nothing.
+ assert audio_cpp_update._backfill_model_specs() is False
+ assert len(managed.fetches) == 1
+
+
+def test_backfill_commit_falls_back_to_the_manifest_then_the_version(managed):
+ manifest = "b" * 40
+ _write_record(
+ managed,
+ source_commit = None,
+ server_version = "audio.cpp v0.9.1-unsloth.1\ngit: 1234567 2026-10-07\nbuild: 20261007",
+ )
+ managed.installer._release_index = lambda repo, tag: {"source_commit": manifest}
+ assert audio_cpp_update._backfill_model_specs() is True
+ assert managed.fetches[-1][1] == manifest
+ (managed.binary.parent / "model_specs").rmdir()
+
+ def offline(repo, tag):
+ raise OSError("offline")
+
+ managed.installer._release_index = offline
+ assert audio_cpp_update._backfill_model_specs() is True
+ assert managed.fetches[-1][1] == "1234567"
+
+
+def test_backfill_never_fetches_by_tag(managed):
+ _write_record(managed, source_commit = None, server_version = "v0.9.2")
+ assert audio_cpp_update._backfill_model_specs() is False
+ assert managed.fetches == []
+
+
[email protected]("case", ["unmanaged", "folder", "updating", "no_tag", "no_repo"])
+def test_backfill_skips(managed, monkeypatch, case):
+ if case == "unmanaged":
+ (managed.root / ".unsloth-studio-owned").unlink()
+ elif case == "folder":
+ (managed.binary.parent / "model_specs").mkdir()
+ elif case == "updating":
+ monkeypatch.setattr(audio_cpp_server, "UPDATE_IN_PROGRESS", threading.Event())
+ audio_cpp_server.UPDATE_IN_PROGRESS.set()
+ elif case == "no_tag":
+ _write_record(managed, release_tag = None)
+ else:
+ _write_record(managed, published_repo = None)
+ assert audio_cpp_update._backfill_model_specs() is False
+ assert managed.fetches == [] and managed.forgets == []
+
+
+def test_backfill_skips_when_the_install_lock_is_busy(managed, monkeypatch):
+ core = managed.installer.core
+
+ def busy(path, *, timeout = None):
+ assert timeout == 2
+ raise core.BusyInstallConflict("busy")
+
+ managed.installer.core = SimpleNamespace(
+ install_lock = busy, install_lock_path = core.install_lock_path
+ )
+ assert audio_cpp_update._backfill_model_specs() is False
+ assert managed.fetches == []
+
+
+def test_a_failed_fetch_leaves_no_folder_and_raises_nothing(managed):
+ managed.installer._fetch_model_specs = lambda repo, commit, dest: False
+ assert audio_cpp_update._backfill_model_specs() is False
+ assert not (managed.binary.parent / "model_specs").exists()
+ assert list(managed.binary.parent.glob(".model_specs-*")) == []
+ assert managed.forgets == []
+
+ def broken(repo, commit, dest):
+ raise RuntimeError("boom")
+
+ managed.installer._fetch_model_specs = broken
+ assert audio_cpp_update._backfill_model_specs() is False
+
+
+def test_the_backfill_starts_once_and_not_when_update_checks_are_off(monkeypatch):
+ calls = []
+ ran = threading.Event()
+ monkeypatch.setattr(audio_cpp_update, "_backfill_started", False)
+ monkeypatch.setattr(
+ audio_cpp_update, "_backfill_model_specs", lambda: calls.append(1) or ran.set()
+ )
+ monkeypatch.setenv("UNSLOTH_DISABLE_UPDATE_CHECK", "1")
+ audio_cpp_update.start_model_specs_backfill()
+ assert audio_cpp_update._backfill_started is False
+ monkeypatch.delenv("UNSLOTH_DISABLE_UPDATE_CHECK")
+ audio_cpp_update.start_model_specs_backfill()
+ audio_cpp_update.start_model_specs_backfill()
+ assert ran.wait(5)
+ for thread in threading.enumerate():
+ if thread.name == "audio-cpp-spec-backfill":
+ thread.join(5)
+ assert calls == [1]
diff --git a/studio/backend/tests/test_audio_cpp_umbrella_catalog.py b/studio/backend/tests/test_audio_cpp_umbrella_catalog.py
index 49c7e918486..dec9ba32783 100644
--- a/studio/backend/tests/test_audio_cpp_umbrella_catalog.py
+++ b/studio/backend/tests/test_audio_cpp_umbrella_catalog.py
@@ -12,9 +12,9 @@ from pathlib import Path
import pytest
from core.inference import audio_cpp_models as acm
-from core.inference.audio_cpp_spec_families import AUDIO_CPP_SPEC_FAMILIES
-# Folder -> (family its GGUF header names, Audio pages), audio-cpp/audio.cpp-gguf at f861648c.
+# Folder -> (family its GGUF header names, Audio pages), audio-cpp/audio.cpp-gguf at f861648c;
+# VibeVoice-ASR-Streaming from the spec-refresh-v0.9.2 branch at 95ab5a44.
UMBRELLA = {
"ACE-Step1.5-GGUF": ("ace_step", ["music"]),
"Apollo-GGUF": ("apollo", []),
@@ -31,7 +31,7 @@ UMBRELLA = {
"Confucius4-TTS-GGUF": ("confucius4_tts", ["clone"]),
"ControlFoley-GGUF": ("controlfoley", ["music"]),
"CosyVoice3-GGUF": ("cosyvoice3", ["clone"]),
- "CrisperWhisper2.0-GGUF": ("crisperwhisper", []),
+ "CrisperWhisper2.0-GGUF": ("crisperwhisper", ["transcribe"]),
"DotTTS-Edit-GGUF": ("dots_tts", ["speak", "clone", "edit"]),
"DotTTS-MF-GGUF": ("dots_tts", ["speak", "clone"]),
"DotTTS-SOAR-GGUF": ("dots_tts", ["speak", "clone"]),
@@ -50,7 +50,7 @@ UMBRELLA = {
"Higgs-Audio-v3-STT-GGUF": ("higgs_audio_stt", ["transcribe"]),
"Higgs-Audio-v3-TTS-4B-GGUF": ("higgs_audio_tts", ["speak", "clone"]),
"Hviske-v5.3-GGUF": ("hviske_asr", ["transcribe"]),
- "Hviske-v6-GGUF": ("hviske_asr_v6", []),
+ "Hviske-v6-GGUF": ("hviske_asr_v6", ["transcribe"]),
"IndexTTS2-GGUF": ("index_tts2", ["clone"]),
"IndexTTS2.5-GGUF": ("index_tts2", ["clone"]),
"Inflect-Micro-v2-GGUF": ("inflect_v2", ["speak"]),
@@ -60,7 +60,7 @@ UMBRELLA = {
"KittenTTS-GGUF": ("kitten_tts", ["speak"]),
"Kokoro-82M-GGUF": ("kokoro_tts", ["speak"]),
"Kroko-ASR-GGUF": ("kroko_asr", ["transcribe"]),
- "KugelAudio-0-Open-GGUF": ("kugelaudio", []),
+ "KugelAudio-0-Open-GGUF": ("kugelaudio", ["speak"]),
"MMS-Forced-Aligner-GGUF": ("mms_forced_aligner", []),
"MOSS-TTS-Local-v1.5-GGUF": ("moss_tts_local", ["speak", "clone"]),
"MOSS-TTS-Nano-100M-GGUF": ("moss_tts_nano", ["speak", "clone"]),
@@ -81,8 +81,8 @@ UMBRELLA = {
"Nemotron-3.5-ASR-Streaming-0.6B-GGUF": ("nemotron_asr", ["transcribe"]),
"NeuTTS-2E-GGUF": ("neutts", ["speak"]),
"Niagara-ASR-GGUF": ("niagara_asr", ["transcribe"]),
- "OWSM-CTC-GGUF": ("owsm_ctc", []),
- "OWSM-GGUF": ("owsm", []),
+ "OWSM-CTC-GGUF": ("owsm_ctc", ["transcribe"]),
+ "OWSM-GGUF": ("owsm", ["transcribe"]),
"OmniVoice-GGUF": ("omnivoice", ["speak", "clone"]),
"Parakeet-TDT-0.6B-v3-GGUF": ("parakeet_tdt", ["transcribe"]),
"PersonaPlex-GGUF": ("personaplex", []),
@@ -114,15 +114,17 @@ UMBRELLA = {
"Vevo2-GGUF": ("vevo2", ["clone", "edit", "convert"]),
"VibeVoice-1.5B-GGUF": ("vibevoice", ["speak"]),
"VibeVoice-ASR-GGUF": ("vibevoice_asr", ["transcribe"]),
+ "VibeVoice-ASR-Streaming-7B-GGUF": ("vibevoice_asr_streaming", ["transcribe"]),
"VoxCPM1-GGUF": ("voxcpm1", ["speak", "clone"]),
"VoxCPM2-GGUF": ("voxcpm2", ["speak", "clone"]),
- "Voxtral-4B-TTS-2603-GGUF": ("voxtral_tts", []),
+ "Voxtral-4B-TTS-2603-GGUF": ("voxtral_tts", ["speak"]),
"Voxtral-Mini-4B-Realtime-2602-GGUF": ("voxtral_realtime", ["transcribe"]),
}
# Families outside acm.FAMILIES are classified by the tasks their spec lists.
SPEC_TASKS = {
"gigaam_asr": ["asr"],
+ "hviske_asr_v6": ["asr"],
"maya1": ["tts"],
"crisperwhisper": ["asr", "align"],
"kugelaudio": ["tts"],
@@ -130,6 +132,7 @@ SPEC_TASKS = {
"owsm_ctc": ["asr"],
"sidon": ["s2s"],
"smart_turn": ["turn"],
+ "voxtral_tts": ["tts"],
}
TASK_PAGE = {"tts": "speak", "music": "music", "asr": "transcribe", "sep": "separate"}
@@ -139,9 +142,8 @@ CATALOG = Path(__file__).resolve().parents[2] / "frontend/src/features/audio/aud
@pytest.fixture(autouse = True)
def pinned_runtime(monkeypatch):
- monkeypatch.setattr(
- acm, "runtime_knows_family", lambda family: family in AUDIO_CPP_SPEC_FAMILIES
- )
+ # A v0.9.2 runtime loads every family these GGUFs name.
+ monkeypatch.setattr(acm, "runtime_knows_family", lambda family: True)
# Variants of a family the pinned runtime knows that only a newer runtime loads: the pickers leave
@@ -170,10 +172,21 @@ def _catalog() -> tuple[dict[str, list[str]], set[str]]:
return seeded, set(re.findall(r'^\s*"([^"]+)":', block, re.M))
+# Runnable, but the pickers hold them back until the Hub's main branch carries their files.
+NOT_ON_HUB_MAIN = {"VibeVoice-ASR-Streaming-7B-GGUF"}
+
+
def test_the_pickers_offer_every_runnable_folder_on_its_pages():
seeded, unoffered = _catalog()
- assert seeded == {folder: pages for folder, (_, pages) in UMBRELLA.items() if pages}
- assert unoffered == {folder for folder, (_, pages) in UMBRELLA.items() if not pages}
+ assert seeded == {
+ folder: pages
+ for folder, (_, pages) in UMBRELLA.items()
+ if pages and folder not in NOT_ON_HUB_MAIN
+ }
+ assert (
+ unoffered
+ == {folder for folder, (_, pages) in UMBRELLA.items() if not pages} | NOT_ON_HUB_MAIN
+ )
@pytest.mark.parametrize(
diff --git a/studio/backend/tests/test_audio_cpp_update.py b/studio/backend/tests/test_audio_cpp_update.py
index 4378feae916..1330386a736 100644
--- a/studio/backend/tests/test_audio_cpp_update.py
+++ b/studio/backend/tests/test_audio_cpp_update.py
@@ -431,6 +431,24 @@ def test_the_runtime_is_swapped_while_no_audio_cpp_server_can_start(run_env):
}
+def test_a_runtime_swap_drops_resolutions_made_against_the_old_tree(run_env, monkeypatch):
+ from core.inference import audio_cpp_models
+
+ forgets = []
+ monkeypatch.setattr(
+ audio_cpp_models,
+ "forget",
+ lambda *a: forgets.append((a, audio_cpp_server.UPDATE_IN_PROGRESS.is_set())),
+ )
+ aupd.run_chained_phase(run_env.phase, lambda fraction: None)
+ # Before loads are allowed again, so none reuses an old-runtime resolution.
+ assert forgets == [((), True)]
+ run_env.installer(error = RuntimeError("installer timed out after 1800s"))
+ with pytest.raises(RuntimeError, match = "timed out"):
+ aupd.run_chained_phase(run_env.phase, lambda fraction: None)
+ assert len(forgets) == 2 and not audio_cpp_server.UPDATE_IN_PROGRESS.is_set()
+
+
def test_the_installer_gets_the_managed_dir_and_recorded_accelerator(run_env, managed):
aupd.run_chained_phase(run_env.phase, lambda fraction: None)
cmd = run_env.calls["cmd"]
diff --git a/studio/backend/tests/test_scoped_download_job.py b/studio/backend/tests/test_scoped_download_job.py
index 4b3ba2d3359..dc88dabdf23 100644
--- a/studio/backend/tests/test_scoped_download_job.py
+++ b/studio/backend/tests/test_scoped_download_job.py
@@ -103,6 +103,28 @@ def test_scope_requires_files_and_rejects_a_variant(monkeypatch):
assert "mutually exclusive" in str(both.value)
+def test_a_scoped_start_runs_the_old_audio_runtime_gate_first(monkeypatch):
+ _shared_setup_1(monkeypatch)
+ seen = []
+
+ async def refuse(
+ repo_id,
+ files,
+ hf_token,
+ hub_cache = None,
+ ):
+ seen.append((repo_id, files))
+ raise HTTPException(status_code = 409, detail = "needs a newer audio runtime")
+
+ monkeypatch.setattr(dl, "_refuse_stale_scoped_download", refuse)
+ monkeypatch.setattr(
+ download_lifecycle, "launch_worker", lambda *a, **k: pytest.fail("job started")
+ )
+ with pytest.raises(HTTPException) as refused:
+ asyncio.run(dl.download_model_response(_request()))
+ assert refused.value.status_code == 409 and seen == [(REPO, FILES)]
+
+
def test_scoped_start_spawns_a_file_scoped_worker(monkeypatch, tmp_path):
spawned: dict = {}
diff --git a/studio/backend/tests/test_stt_audiocpp_details.py b/studio/backend/tests/test_stt_audiocpp_details.py
index 1b1f0681ebc..4694480dc1d 100644
--- a/studio/backend/tests/test_stt_audiocpp_details.py
+++ b/studio/backend/tests/test_stt_audiocpp_details.py
@@ -74,6 +74,8 @@ FAKE_SERVER = textwrap.dedent(
if entry["family"] == "moss_transcribe_diarize":
return self.reply(200, MOSS)
payload = {"text": "Concord returned.", "language": "English"}
+ if entry["family"] == "owsm_ctc":
+ payload["language"] = language # it echoes the language it was sent, "auto" included
if (req.get("options") or {}).get("return_timestamps") == "true":
payload["words"] = [
{"word": "Concord", "start_sample": 9088, "end_sample": 19328},
diff --git a/studio/backend/utils/audio_cpp_update.py b/studio/backend/utils/audio_cpp_update.py
index 2e4a565f934..8527702d739 100644
--- a/studio/backend/utils/audio_cpp_update.py
+++ b/studio/backend/utils/audio_cpp_update.py
@@ -7,7 +7,10 @@ from __future__ import annotations
import os
import platform
+import re
+import shutil
import sys
+import threading
from pathlib import Path
from typing import Optional
@@ -23,6 +26,10 @@ _INSTALL_TIMEOUT_SECONDS = 1800
# setup.sh / setup.ps1 leave the managed tree alone when any of these is set, so an update would not take effect.
_SETUP_SKIP_VARS = ("AUDIOCPP_SERVER_PATH", "UNSLOTH_AUDIO_CPP_PATH")
_EXIT_BUSY = 3
+_COMMIT = re.compile(r"[0-9a-f]{7,40}")
+_VERSION_COMMIT = re.compile(r"^git: ([0-9a-f]{7,40})\b", re.MULTILINE)
+_backfill_started = False
+_backfill_lock = threading.Lock()
class _AudioPhaseError(RuntimeError):
@@ -404,4 +411,83 @@ def run_chained_phase(phase: dict, set_progress) -> dict:
) from exc
return _install(phase, set_progress, unloaded)
finally:
- audio_cpp_server.UPDATE_IN_PROGRESS.clear()
+ try:
+ # Resolutions follow the runtime's model_specs/, so none made against the old tree may outlive it.
+ from core.inference import audio_cpp_models
+ audio_cpp_models.forget()
+ finally:
+ audio_cpp_server.UPDATE_IN_PROGRESS.clear()
+
+
+def _spec_commit(installer, record: dict, repo: str, tag: str) -> Optional[str]:
+ """The source commit the install was built from: the record, the release manifest, else the server version string."""
+ commit = record.get("source_commit")
+ if isinstance(commit, str) and _COMMIT.fullmatch(commit):
+ return commit
+ try:
+ commit = (installer._release_index(repo, tag) or {}).get("source_commit")
+ except Exception as exc: # noqa: BLE001 - offline or rate-limited; try the version string
+ logger.debug("audio.cpp spec backfill: release lookup failed", error = str(exc))
+ commit = None
+ if isinstance(commit, str) and _COMMIT.fullmatch(commit):
+ return commit
+ version = record.get("server_version")
+ match = _VERSION_COMMIT.search(version) if isinstance(version, str) else None
+ return match.group(1) if match else None
+
+
+def _backfill_model_specs() -> bool:
+ """Fetch ``model_specs/`` for a managed install made before the installer fetched it. Returns
+ whether the folder was added; never raises."""
+ from core.inference import audio_cpp_server
+ try:
+ binary = audio_cpp_server.find_audio_cpp_server_binary()
+ if not binary or not _is_managed(binary) or audio_cpp_server.UPDATE_IN_PROGRESS.is_set():
+ return False
+ bin_dir = Path(binary).parent
+ record = audio_cpp_server.read_install_record(binary)
+ tag = _tag(record)
+ repo = record.get("published_repo")
+ if tag is None or not isinstance(repo, str) or (bin_dir / "model_specs").exists():
+ return False
+ installer = _installer()
+ commit = _spec_commit(installer, record, repo, tag)
+ if commit is None:
+ logger.info("audio.cpp spec backfill: no source commit", tag = tag)
+ return False
+ core = installer.core
+ managed_dir = audio_cpp_server.managed_audio_cpp_dir().resolve()
+ with core.install_lock(core.install_lock_path(managed_dir), timeout = 2):
+ # An update may have replaced the tree while the lock was taken.
+ if audio_cpp_server.UPDATE_IN_PROGRESS.is_set() or (bin_dir / "model_specs").exists():
+ return False
+ if audio_cpp_server.read_install_record(binary).get("release_tag") != tag:
+ return False
+ for leftover in bin_dir.glob(".model_specs-*"):
+ # Left by a killed fetch; only the exact name model_specs is ever read.
+ shutil.rmtree(leftover, ignore_errors = True)
+ if not installer._fetch_model_specs(repo, commit, bin_dir):
+ logger.info("audio.cpp spec backfill: fetch failed", tag = tag)
+ return False
+ from core.inference import audio_cpp_models
+
+ audio_cpp_models.forget()
+ logger.info("audio.cpp spec backfill: added model_specs", tag = tag, commit = commit)
+ return True
+ except Exception as exc: # noqa: BLE001 - families stay unknown, as before
+ logger.debug("audio.cpp spec backfill failed", error = str(exc))
+ return False
+
+
+def start_model_specs_backfill() -> None:
+ """Run the spec backfill once per process on a daemon thread, unless update checks are disabled."""
+ global _backfill_started
+ if update_checks_disabled():
+ return
+ with _backfill_lock:
+ if _backfill_started:
+ return
+ _backfill_started = True
+ threading.Thread(
+ target = _backfill_model_specs, daemon = True, name = "audio-cpp-spec-backfill"
+ ).start()
diff --git a/studio/frontend/scripts/check-bundle-budget.ts b/studio/frontend/scripts/check-bundle-budget.ts
index 90ff4a053b4..bc249e84c5a 100644
--- a/studio/frontend/scripts/check-bundle-budget.ts
+++ b/studio/frontend/scripts/check-bundle-budget.ts
@@ -208,7 +208,9 @@ export const BUDGET = {
// 2,047,580 B transfer against f172c8d7c4, one machine and build, Node 24, chunk count unchanged at 95): its
// logo mapping, capability row and vision gate entries live in tables the startup chunks already load. Raised
// by that growth.
- transferBytes: 2_047_549,
+ // The audio.cpp v0.9.2 picker rows (#14073) add 253 B raw / 59 B transfer to the eager audio catalog
+ // table (one machine and build, chunk count unchanged at 95). Raised by that.
+ transferBytes: 2_047_608,
rawBytes: 6_806_087,
};
diff --git a/studio/frontend/src/features/audio/audio-cpp-catalog.ts b/studio/frontend/src/features/audio/audio-cpp-catalog.ts
index c51d740f40c..1b6eae3e242 100644
--- a/studio/frontend/src/features/audio/audio-cpp-catalog.ts
+++ b/studio/frontend/src/features/audio/audio-cpp-catalog.ts
@@ -162,6 +162,7 @@ export const AUDIO_CPP_MODELS: readonly AudioCppModel[] = [
{ id: folder("Irodori-TTS-500M-v3-GGUF"), task: "tts", workflows: ["speak", "clone"] },
{ id: folder("Irodori-TTS-600M-v3-VoiceDesign-GGUF"), task: "tts", workflows: ["speak", "clone"] },
{ id: folder("Irodori-TTS-v4-Small-GGUF"), task: "tts", workflows: ["speak", "clone"] },
+ { id: folder("KugelAudio-0-Open-GGUF"), task: "tts" },
{ id: folder("MOSS-TTS-Local-v1.5-GGUF"), task: "tts", workflows: ["speak", "clone"] },
{ id: folder("MOSS-VoiceGenerator-GGUF"), task: "tts" },
{ id: folder("MagpieTTS-Multilingual-357M-GGUF"), task: "tts" },
@@ -170,6 +171,7 @@ export const AUDIO_CPP_MODELS: readonly AudioCppModel[] = [
{ id: folder("OmniVoice-GGUF"), task: "tts", workflows: ["speak", "clone"] },
{ id: folder("VibeVoice-1.5B-GGUF"), task: "tts" },
{ id: folder("VoxCPM1-GGUF"), task: "tts", workflows: ["speak", "clone"] },
+ { id: folder("Voxtral-4B-TTS-2603-GGUF"), task: "tts" },
{ id: folder("Fish-Audio-S2-Pro-GGUF"), task: "tts", workflows: ["speak", "clone"] },
{ id: folder("Confucius4-TTS-GGUF"), task: "tts", workflows: ["clone"] },
{ id: folder("FireRedTTS3-Base-GGUF"), task: "tts", workflows: ["clone"] },
@@ -228,6 +230,7 @@ export const AUDIO_CPP_MODELS: readonly AudioCppModel[] = [
task: "asr",
languages: COHERE_TRANSCRIBE_LANGUAGES,
},
+ { id: folder("CrisperWhisper2.0-GGUF"), task: "asr" },
{
id: folder("Fun-ASR-Nano-2512-GGUF"),
task: "asr",
@@ -237,8 +240,11 @@ export const AUDIO_CPP_MODELS: readonly AudioCppModel[] = [
{ id: folder("Granite-Speech-5.0-470M-TurboCTC-GGUF"), task: "asr", languages: ENGLISH },
{ id: folder("Higgs-Audio-v3-STT-GGUF"), task: "asr", languages: ENGLISH },
{ id: folder("Hviske-v5.3-GGUF"), task: "asr", languages: ["da"] },
+ { id: folder("Hviske-v6-GGUF"), task: "asr", languages: ["da"] },
{ id: folder("Kroko-ASR-GGUF"), task: "asr", languages: ENGLISH },
{ id: folder("Niagara-ASR-GGUF"), task: "asr", languages: ENGLISH },
+ { id: folder("OWSM-GGUF"), task: "asr" },
+ { id: folder("OWSM-CTC-GGUF"), task: "asr" },
{ id: folder("VibeVoice-ASR-GGUF"), task: "asr" },
{
id: folder("Voxtral-Mini-4B-Realtime-2602-GGUF"),
@@ -249,22 +255,18 @@ export const AUDIO_CPP_MODELS: readonly AudioCppModel[] = [
/** Shared-repo folders the pickers leave out, and why; the nightly catalog check fails on an unclassified folder. */
export const AUDIO_CPP_UNOFFERED_FOLDERS: Readonly<Record<string, string>> = {
- "CrisperWhisper2.0-GGUF": "needs a newer audio runtime",
- "KugelAudio-0-Open-GGUF": "needs a newer audio runtime",
- "OWSM-CTC-GGUF": "needs a newer audio runtime",
- "OWSM-GGUF": "needs a newer audio runtime",
"Sidon-GGUF": "needs a newer audio runtime",
+ // Offer it on Transcribe once the Hub's main branch carries it (only on spec-refresh-v0.9.2 for now).
+ "VibeVoice-ASR-Streaming-7B-GGUF": "not on the Hub's main branch yet",
"Smart-Turn-v3-GGUF": "needs a newer audio runtime",
"AST-AudioSet-GGUF": "needs a newer audio runtime",
"CED-GGUF": "needs a newer audio runtime",
"FireRedVAD-GGUF": "needs a newer audio runtime",
- "Hviske-v6-GGUF": "needs a newer audio runtime",
"MicroWakeWord-GGUF": "needs a newer audio runtime",
"MossFormer2-GGUF": "needs a newer audio runtime",
"Phonon-2-GGUF": "needs a newer audio runtime",
"Sherpa-KWS-GGUF": "needs a newer audio runtime",
"TF-GridNet-GGUF": "needs a newer audio runtime",
- "Voxtral-4B-TTS-2603-GGUF": "needs a newer audio runtime",
"MioCodec-25Hz-44.1kHz-v2-GGUF": "the codec MioTTS downloads and loads with",
"Qwen3-ForcedAligner-0.6B-GGUF": "the aligner Transcribe uses for Qwen3-ASR timestamps",
"MiniMax-H3-Q4-GGUF": "an audio and video package Studio cannot load yet",
diff --git a/studio/frontend/tests/audio-cpp-catalog.test.ts b/studio/frontend/tests/audio-cpp-catalog.test.ts
index 3ad308a2e21..0bf2bcb4870 100644
--- a/studio/frontend/tests/audio-cpp-catalog.test.ts
+++ b/studio/frontend/tests/audio-cpp-catalog.test.ts
@@ -159,7 +159,7 @@ test("recommended ids are unique and name their Hub repo or package folder", ()
});
test("folders of the shared repo the pickers leave out are never seeded and say why", () => {
- assert.equal(Object.keys(AUDIO_CPP_UNOFFERED_FOLDERS).length, 28);
+ assert.equal(Object.keys(AUDIO_CPP_UNOFFERED_FOLDERS).length, 23);
for (const [folder, reason] of Object.entries(AUDIO_CPP_UNOFFERED_FOLDERS)) {
assert.equal(audioCppModelFor(`${AUDIO_CPP_REPO}/${folder}`), null, folder);
assert.match(folder, /-GGUF$/);
@@ -178,6 +178,7 @@ test("folders of the shared repo the pickers leave out are never seeded and say
["Kroko-ASR-GGUF", ["en"]],
["Niagara-ASR-GGUF", ["en"]],
["Hviske-v5.3-GGUF", ["da"]],
+ ["Hviske-v6-GGUF", ["da"]],
["GigaAM-ASR-GGUF", ["ru", "en", "kk", "ky", "uz"]],
[
"Voxtral-Mini-4B-Realtime-2602-GGUF",
@@ -501,7 +502,7 @@ test("Settings > Voice lists every ASR model the Transcribe page offers", () =>
});
test("Transcribe's other ASR folders are listed by id, after the keyed models", () => {
- assert.equal(AUDIO_CPP_STT_FOLDER_IDS.length, 12);
+ assert.equal(AUDIO_CPP_STT_FOLDER_IDS.length, 16);
const keyedFolders = new Set(
AUDIO_CPP_DICTATION_MODELS.map((model) => model.id),
);
diff --git a/studio/install_audio_cpp_prebuilt.py b/studio/install_audio_cpp_prebuilt.py
index 46a2c83957f..d599cb33de5 100644
--- a/studio/install_audio_cpp_prebuilt.py
+++ b/studio/install_audio_cpp_prebuilt.py
@@ -42,6 +42,7 @@ import argparse
import datetime
import fnmatch
import glob
+import hashlib
import json
import os
import platform
@@ -54,6 +55,7 @@ import tempfile
import urllib.error
import urllib.request
import zipfile
+from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from typing import Optional, Sequence
@@ -528,6 +530,7 @@ def _release_index(
if isinstance(a, dict) and isinstance(a.get("name"), str)
],
"checksums": None,
+ "source_commit": None,
}
else:
release = {
@@ -542,6 +545,7 @@ def _release_index(
for a in bundle.manifest.get("artifacts") or []
],
"checksums": checksums,
+ "source_commit": bundle.manifest.get("source_commit"),
}
_RELEASE_INDEX_MEMO[key] = release
return release
@@ -677,6 +681,91 @@ def _extract(archive: Path, target: Path) -> None:
tf.extractall(target)
+MODEL_SPECS_DIR = "model_specs"
+_COMMIT = re.compile(r"[0-9a-f]{7,40}")
+_REPO_NAME = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+")
+_SPEC_NAME = re.compile(r"[a-z0-9_]+\.json")
+# The specs are optional, so a network that blocks GitHub costs one short try, not retries.
+_SPEC_TIMEOUT = 10
+
+
+def _spec_tree(repo: str, commit: str) -> object:
+ url = f"https://api.github.com/repos/{repo}/git/trees/{commit}:{MODEL_SPECS_DIR}"
+ data = core.download_bytes(
+ _OPS, url, timeout = _SPEC_TIMEOUT, attempts = 1, headers = _OPS.github_api_headers(url)
+ )
+ return json.loads(data.decode("utf-8"))
+
+
+def _spec_blob(repo: str, commit: str, name: str) -> bytes:
+ url = f"https://raw.githubusercontent.com/{repo}/{commit}/{MODEL_SPECS_DIR}/{name}"
+ return core.download_bytes(_OPS, url, timeout = _SPEC_TIMEOUT, attempts = 1)
+
+
+def _spec_bytes(repo: str, commit: str, name: str, blob_sha: str) -> bytes:
+ data = _spec_blob(repo, commit, name)
+ got = hashlib.sha1(b"blob %d\0" % len(data) + data).hexdigest()
+ if got != blob_sha:
+ raise RuntimeError(f"{name}: git blob sha {got} != {blob_sha}")
+ if not isinstance(json.loads(data.decode("utf-8")), dict):
+ raise RuntimeError(f"{name} is not a JSON object")
+ return data
+
+
+def _fetch_model_specs(repo: str, commit: Optional[str], dest_dir: Path) -> bool:
+ """Put audio.cpp's ``model_specs/*.json`` at ``commit`` into ``dest_dir/model_specs``, the folder
+ Unsloth Studio reads to tell which model families this runtime loads. All or nothing: every file is
+ checked against its git blob sha and must parse, else no folder is left. Never raises; True when
+ the folder is there afterwards (one already present is kept as is, with no network call).
+
+ Always by commit (the manifest's ``source_commit``), never the release tag: the fork's release
+ tags all point at its packaging commit, whose ``model_specs`` is an older tree."""
+ dest_dir = Path(dest_dir)
+ dest = dest_dir / MODEL_SPECS_DIR
+ if dest.is_dir():
+ return True
+ if not isinstance(commit, str) or not _COMMIT.fullmatch(commit):
+ log("no source commit for this release; model specs not fetched")
+ return False
+ if not isinstance(repo, str) or not _REPO_NAME.fullmatch(repo):
+ log(f"unexpected repo {repo!r}; model specs not fetched")
+ return False
+ tmp = None
+ try:
+ tree = _spec_tree(repo, commit)
+ if not isinstance(tree, dict) or tree.get("truncated") or not tree.get("tree"):
+ raise RuntimeError("empty or truncated model_specs listing")
+ entries = {
+ e["path"]: e["sha"]
+ for e in tree["tree"]
+ if isinstance(e, dict)
+ and e.get("type") == "blob"
+ and isinstance(e.get("path"), str)
+ and _SPEC_NAME.fullmatch(e["path"])
+ and isinstance(e.get("sha"), str)
+ }
+ if not entries:
+ raise RuntimeError("no spec files in the model_specs listing")
+ with ThreadPoolExecutor(max_workers = 8) as pool:
+ blobs = dict(
+ zip(
+ entries,
+ pool.map(lambda item: _spec_bytes(repo, commit, *item), entries.items()),
+ )
+ )
+ tmp = Path(tempfile.mkdtemp(prefix = ".model_specs-", dir = str(dest_dir)))
+ for name, data in blobs.items():
+ (tmp / name).write_bytes(data)
+ os.replace(tmp, dest)
+ tmp = None
+ except Exception as exc: # noqa: BLE001 - offline, 404, rate limit, bad blob: install goes on
+ log(f"model specs at {commit[:12]} not fetched ({exc})")
+ finally:
+ if tmp is not None:
+ shutil.rmtree(tmp, ignore_errors = True)
+ return dest.is_dir()
+
+
def _locate_server(root: Path) -> Optional[Path]:
for p in sorted(root.rglob(SERVER_NAME), key = lambda p: len(p.parts)):
if p.is_file():
@@ -1166,12 +1255,18 @@ def _install_locked(
extra_dirs = _cuda_runtime_dirs(backend),
require_vulkan_device = requested == "auto" and backend == "vulkan",
)
+ # Beside the server (bin/ on Windows), where Studio reads it; a failed fetch never fails the install.
+ source_commit = release.get("source_commit")
+ if _fetch_model_specs(repo, source_commit, server.parent):
+ specs = len(list((server.parent / MODEL_SPECS_DIR).glob("*.json")))
+ print(f"audio.cpp: {specs} model specs beside the server", flush = True)
(tree / OWNERSHIP_MARKER).touch()
record = {
"schema_version": 1,
"component": "audio.cpp",
"published_repo": repo,
"release_tag": tag,
+ "source_commit": source_commit,
"asset": chosen,
"asset_sha256": digest,
"cudart_asset": cudart_used,
diff --git a/tests/studio/install/test_install_audio_cpp_prebuilt_logic.py b/tests/studio/install/test_install_audio_cpp_prebuilt_logic.py
index 307684a8b1b..ebd2b3536cb 100644
--- a/tests/studio/install/test_install_audio_cpp_prebuilt_logic.py
+++ b/tests/studio/install/test_install_audio_cpp_prebuilt_logic.py
@@ -253,6 +253,8 @@ def _stub_install_io(monkeypatch, version = "audio.cpp test\nbackends: cpu"):
monkeypatch.setattr(M, "smoke_test_staged_server", lambda server, **kw: version)
monkeypatch.setattr(M, "detect_accelerator", lambda: "cpu")
monkeypatch.setattr(M, "_linux_cuda_runtime_available", lambda major: True)
+ # The spec fetch is offline here; the model_specs tests below put the real one back.
+ monkeypatch.setattr(M, "_fetch_model_specs", lambda *a: False)
def _install(
@@ -2029,3 +2031,198 @@ def test_explicit_vulkan_is_not_checked_for_a_device(monkeypatch, tmp_path):
)
assert checked == [("vulkan", False)]
assert _record(tmp_path)[:3] == (VK_ZIP, "vulkan", "vulkan")
+
+
+# model_specs: fetched at the manifest's source_commit, verified per git blob sha, all or nothing.
+
+_REAL_FETCH_MODEL_SPECS = M._fetch_model_specs
+_SPEC_COMMIT = "0097d365a00b52a6991ad7618f0a04e8d2935e47"
+
+
+def _git_sha(data):
+ import hashlib
+ return hashlib.sha1(b"blob %d\0" % len(data) + data).hexdigest()
+
+
+def _spec_repo(
+ monkeypatch,
+ files = None,
+ *,
+ tree = None,
+ fail = None,
+ bad_sha = None,
+):
+ """Serve ``files`` ({name: bytes}) through the tree/blob seams; returns the calls made."""
+ if files is None:
+ files = {
+ "chatterbox.json": b'{"family": "chatterbox"}',
+ "seed_vc.json": b'{"family": "seed_vc"}',
+ }
+ if tree is None:
+ tree = {
+ "truncated": False,
+ "tree": [
+ {"path": n, "type": "blob", "sha": _git_sha(d), "size": len(d)}
+ for n, d in files.items()
+ ],
+ }
+ calls = []
+
+ def spec_tree(repo, commit):
+ calls.append(("tree", repo, commit))
+ return tree
+
+ def spec_blob(repo, commit, name):
+ calls.append(("blob", repo, commit, name))
+ if name == fail:
+ raise OSError(f"HTTP Error 404: {name}")
+ return b'{"tampered": true}' if name == bad_sha else files[name]
+
+ monkeypatch.setattr(M, "_fetch_model_specs", _REAL_FETCH_MODEL_SPECS)
+ monkeypatch.setattr(M, "_spec_tree", spec_tree)
+ monkeypatch.setattr(M, "_spec_blob", spec_blob)
+ return calls
+
+
+def _specs_release(
+ monkeypatch,
+ tmp_path,
+ server_path = "bin/audiocpp_server.exe",
+):
+ release = dict(_release(tmp_path, CPU_ZIP, server_path = server_path), source_commit = _SPEC_COMMIT)
+ monkeypatch.setattr(M, "resolve", lambda accel, token, tag = None: (FORK, release, CPU_ZIP))
+ _stub_install_io(monkeypatch)
+
+
+def _install_with_specs(
+ monkeypatch,
+ tmp_path,
+ server_path = "bin/audiocpp_server.exe",
+ **specs,
+):
+ _specs_release(monkeypatch, tmp_path, server_path)
+ calls = _spec_repo(monkeypatch, **specs)
+ server = M.install(install_dir = tmp_path / "audio.cpp", accelerator = "cpu")
+ return server, calls
+
+
+def test_release_index_carries_the_manifest_source_commit(monkeypatch):
+ _download_host(monkeypatch)
+ assert M._release_index(FORK, _V091)["source_commit"] == _V091_COMMIT
+
+
+def test_install_fetches_model_specs_at_the_source_commit(monkeypatch, tmp_path, capsys):
+ server, calls = _install_with_specs(monkeypatch, tmp_path)
+ root = tmp_path / "audio.cpp"
+ specs = server.parent / "model_specs"
+ # Windows bundles keep the server under bin/; the folder sits beside it.
+ assert server.parent == root / "bin"
+ assert sorted(p.name for p in specs.iterdir()) == ["chatterbox.json", "seed_vc.json"]
+ assert json.loads((specs / "seed_vc.json").read_text()) == {"family": "seed_vc"}
+ assert json.loads((root / M.INSTALL_RECORD).read_text())["source_commit"] == _SPEC_COMMIT
+ # By commit, never the release tag (the fork tags point at a packaging commit).
+ assert calls[0] == ("tree", FORK, _SPEC_COMMIT)
+ assert {c[2] for c in calls} == {_SPEC_COMMIT}
+ assert "audio.cpp: 2 model specs beside the server" in capsys.readouterr().out
+ assert not list(tmp_path.rglob(".model_specs-*"))
+
+
+def test_a_flat_bundle_gets_model_specs_beside_its_server(monkeypatch, tmp_path):
+ server, _ = _install_with_specs(monkeypatch, tmp_path, server_path = "audiocpp_server.exe")
+ assert server.parent == tmp_path / "audio.cpp"
+ assert (server.parent / "model_specs" / "chatterbox.json").is_file()
+
+
+_UNSAFE_TREE = {
+ "truncated": False,
+ "tree": [
+ {"path": "../x.json", "type": "blob", "sha": "0" * 40},
+ {"path": "README.md", "type": "blob", "sha": "0" * 40},
+ {"path": "nested.json", "type": "tree", "sha": "0" * 40},
+ ],
+}
+
+
+ "specs",
+ [
+ {"bad_sha": "seed_vc.json"},
+ {"fail": "seed_vc.json"},
+ {
+ "tree": {
+ "truncated": True,
+ "tree": [{"path": "a.json", "type": "blob", "sha": "0" * 40}],
+ }
+ },
+ {"tree": {"truncated": False, "tree": []}},
+ {"tree": _UNSAFE_TREE},
+ {"files": {"list.json": b"[1, 2]"}},
+ ],
+ ids = ["sha-mismatch", "blob-404", "truncated", "empty", "unsafe-names", "not-an-object"],
+)
+def test_a_failed_spec_fetch_leaves_no_folder_and_installs_anyway(
+ monkeypatch, tmp_path, capsys, specs
+):
+ server, calls = _install_with_specs(monkeypatch, tmp_path, **specs)
+ assert server.is_file()
+ assert not list(tmp_path.rglob("model_specs")) and not list(tmp_path.rglob(".model_specs-*"))
+ assert "model specs at 0097d365a00b not fetched" in capsys.readouterr().err
+ assert "source_commit" in json.loads((tmp_path / "audio.cpp" / M.INSTALL_RECORD).read_text())
+ # Unsafe or non-blob entries are never requested.
+ assert not any(
+ c[0] == "blob" and c[3] in ("../x.json", "README.md", "nested.json") for c in calls
+ )
+
+
+def test_unsafe_names_are_skipped_beside_good_ones(monkeypatch, tmp_path):
+ good = b'{"family": "ace_step"}'
+ tree = {
+ "truncated": False,
+ "tree": [
+ *_UNSAFE_TREE["tree"],
+ {"path": "ace_step.json", "type": "blob", "sha": _git_sha(good)},
+ ],
+ }
+ dest = tmp_path / "bin"
+ dest.mkdir()
+ calls = _spec_repo(monkeypatch, {"ace_step.json": good}, tree = tree)
+ assert M._fetch_model_specs(FORK, _SPEC_COMMIT, dest) is True
+ assert [p.name for p in (dest / "model_specs").iterdir()] == ["ace_step.json"]
+ assert [c[3] for c in calls if c[0] == "blob"] == ["ace_step.json"]
+ assert sorted(p.name for p in tmp_path.rglob("*")) == ["ace_step.json", "bin", "model_specs"]
+
+
+def test_an_offline_spec_fetch_still_installs(monkeypatch, tmp_path):
+ asked = []
+
+ class _Offline:
+ def open(
+ self,
+ request,
+ timeout = None,
+ ):
+ asked.append(request.full_url)
+ raise M.urllib.error.URLError("offline")
+
+ _specs_release(monkeypatch, tmp_path)
+ monkeypatch.setattr(M, "_fetch_model_specs", _REAL_FETCH_MODEL_SPECS)
+ monkeypatch.setattr(M.core, "_URL_OPENER", _Offline())
+ server = M.install(install_dir = tmp_path / "audio.cpp", accelerator = "cpu")
+ assert server.is_file() and not (server.parent / "model_specs").exists()
+ # The real seams ask one trees URL, once, by commit; no retry and no blob.
+ assert asked == [f"https://api.github.com/repos/{FORK}/git/trees/{_SPEC_COMMIT}:model_specs"]
+ assert not list(tmp_path.rglob(".model_specs-*"))
+
+
[email protected]("commit", [None, "", FORK_TAG, "0097D365", "abc", "0097d365/../x"])
+def test_no_valid_commit_means_no_network(monkeypatch, tmp_path, commit):
+ calls = _spec_repo(monkeypatch)
+ assert M._fetch_model_specs(FORK, commit, tmp_path) is False
+ assert calls == [] and not (tmp_path / "model_specs").exists()
+
+
+def test_an_existing_specs_folder_is_kept_without_a_fetch(monkeypatch, tmp_path):
+ (tmp_path / "model_specs").mkdir()
+ calls = _spec_repo(monkeypatch)
+ assert M._fetch_model_specs(FORK, _SPEC_COMMIT, tmp_path) is True
+ assert calls == []