Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: 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.pyindex 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+@staticmethoddef _download_missing(model: AudioCppModel,@@ -424,6 +489,14 @@ class AudioCppBackend:from utils.hf_cache_settings import active_hf_hub_cachecache_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.pyindex 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, Sequencefrom 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: strsize: 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[Repsize = getattr(entry, "size", None)if size is None: # a foldercontinue- 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 Nonetry:- 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_binarybinary = find_audio_cpp_server_binary()except Exception: # noqa: BLE001 - no runtime, no answerreturn 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 Nonedef _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:continueif 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 familyhints = (@@ -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]) -> listreturn 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 = Noneif _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_keykey = 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.pyindex 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.pyindex 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 problemfrom core.inference.audio_cpp_files import served_path_problemtry:diff --git a/studio/backend/core/inference/audio_cpp_spec_families.py b/studio/backend/core/inference/audio_cpp_spec_families.pydeleted file mode 100644index 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.pyindex 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 = Nonetry: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_idif 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 detectedresult = {"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.pyindex 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 excreturn text, variant+try:from core.inference.audio_cpp_models import download_targettarget = 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 excexcept Exception as exc: # noqa: BLE001 - an unresolvable row downloads nothinglogger.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.pyindex 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.jsonindex 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.jsonindex 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.pynew file mode 100644index 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 ABSENTdiff --git a/studio/backend/tests/test_audio_cpp_clone_requests.py b/studio/backend/tests/test_audio_cpp_clone_requests.pyindex 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, kassert 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.pynew file mode 100644index 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.pyindex 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_specdef _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_servermonkeypatch.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, tdef 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.pynew file mode 100644index 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.5diff --git a/studio/backend/tests/test_audio_cpp_option_table.py b/studio/backend/tests/test_audio_cpp_option_table.pyindex 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 pytestfrom core.inference import audio_cpp_backend, audio_cpp_filesfrom core.inference import audio_cpp_models as acmfrom 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, familydiff --git a/studio/backend/tests/test_audio_cpp_runtime_specs.py b/studio/backend/tests/test_audio_cpp_runtime_specs.pynew file mode 100644index 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.pyindex 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 Pathimport pytestfrom 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.pyindex 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.pyindex 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.pyindex 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" includedif (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.pyindex 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 annotationsimport osimport platform+import re+import shutilimport sys+import threadingfrom pathlib import Pathfrom 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 excreturn _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.tsindex 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.tsindex 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.tsindex 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.pyindex 46a2c83957f..d599cb33de5 100644--- a/studio/install_audio_cpp_prebuilt.py+++ b/studio/install_audio_cpp_prebuilt.py@@ -42,6 +42,7 @@ import argparseimport datetimeimport fnmatchimport glob+import hashlibimport jsonimport osimport platform@@ -54,6 +55,7 @@ import tempfileimport urllib.errorimport urllib.requestimport zipfile+from concurrent.futures import ThreadPoolExecutorfrom pathlib import Pathfrom 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] = releasereturn 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.pyindex 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 == []