Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

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

"""Models are Hub repos or local files of audiocpp GGUFs (general.architecture); variants are
quants, or component mixes for packages like YuE2. audio-cpp/audio.cpp-gguf models take three-
segment ids. Studio reads audiocpp.model_spec.family (the server cannot detect it). Only
resolve() parses ids."""

from __future__ import annotations

import hashlib
import io
import json
import os
import re
import struct
import threading
import time
from dataclasses import dataclass, field, replace
from pathlib import Path
from typing import Any, BinaryIO, Iterable, Optional, Sequence

from core.inference.audio_cpp_option_table import (
    ACE_STEP_BASE_NAME,
    ENUM_PRESETS,
    OPTION_RENAMES,
    STUDIO_OPTION_LISTS,
    OptionRule,
    rules_for,
)
from loggers import get_logger

logger = get_logger(__name__)

AUDIO_CPP_REPO = "audio-cpp/audio.cpp-gguf"
AUDIO_CPP_ARCHITECTURE = "audiocpp"
_UMBRELLA_PREFIX = AUDIO_CPP_REPO.lower() + "/"

# The audio_type Studio records for a model served by audio.cpp, per task.
AUDIO_CPP_TTS_AUDIO_TYPE = "audiocpp_tts"
AUDIO_CPP_MUSIC_AUDIO_TYPE = "audiocpp_music"
AUDIO_CPP_SEP_AUDIO_TYPE = "audiocpp_sep"
AUDIO_CPP_AUDIO_TYPES = frozenset(
    (AUDIO_CPP_TTS_AUDIO_TYPE, AUDIO_CPP_MUSIC_AUDIO_TYPE, AUDIO_CPP_SEP_AUDIO_TYPE)
)
_AUDIO_TYPE_BY_TASK = {
    "tts": AUDIO_CPP_TTS_AUDIO_TYPE,
    "music": AUDIO_CPP_MUSIC_AUDIO_TYPE,
    "sep": AUDIO_CPP_SEP_AUDIO_TYPE,
}


def audio_type_for_task(task: Optional[str]) -> Optional[str]:
    return _AUDIO_TYPE_BY_TASK.get(task or "")


# Studio task -> the Hub pipeline task its rows carry.
HUB_TASKS = {
    "tts": "text-to-speech",
    "music": "text-to-audio",
    "asr": "automatic-speech-recognition",
    # Shares its tag with kinds Studio has no page for; audio_type tells them apart.
    "sep": "audio-to-audio",
}

DEFAULT_AUDIO_CPP_STT_MODEL = f"{AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF"


@dataclass(frozen = True)
class AudioCppPackageVariant:
    """One component mix of a package family: its files and the session options that pick them."""

    key: str
    files: tuple[str, ...]
    session_options: dict = field(default_factory = dict, hash = False, compare = False)


@dataclass(frozen = True)
class WorkflowBinding:
    """How a Studio audio workflow reaches audiocpp_server: the task token, the endpoint and the
    request fields the workflow sends."""

    server_task: str
    # Routes: speech /v1/audio/speech, tasks /v1/tasks/run, transcriptions /v1/audio/transcriptions
    endpoint: str
    route: Optional[str] = None
    inputs: tuple[str, ...] = ()


@dataclass(frozen = True)
class CloneSpec:
    """Transcript of the clip: required, optional or unused"""

    reference_text: str = "optional"
    # Options the runtime spec omits but the family reads; validated like spec options.
    tool_options: tuple[dict, ...] = field(default = (), hash = False)
    # Transcript not needed under (option, values) waivers; under dropped (a subset) it is not sent
    reference_text_waived: tuple[tuple[str, tuple[str, ...]], ...] = ()
    reference_text_dropped: tuple[tuple[str, tuple[str, ...]], ...] = ()
    emotion_audio: bool = False
    language_names: bool = False
    speed: bool = False
    instructions: bool = False
    # Reads a free voice or style description beside the reference (Breeze, VoxCPM2).
    description: bool = False


@dataclass(frozen = True)
class EditSpec:
    """How a family edits a recording through ``/v1/tasks/run``."""

    server_task: str
    # markup (DotTTS <sub>/<del>/<ins>), sentence (Vevo2) or instructions (FireRedAudio, chained).
    style: str
    source_field: str = "source_audio"
    route: Optional[str] = None
    template: Optional[str] = None
    # Speed/pitch template; None = no delivery control.
    delivery_template: Optional[str] = None
    max_changes: Optional[int] = None
    # Options Studio fills itself, so Advanced never sends them.
    claims: tuple[str, ...] = ("template_name", "source_text", "target_text", "instruction")


@dataclass(frozen = True)
class ConvertSpec:
    """How a family converts a recording to another voice on /v1/tasks/run."""

    modes: tuple[tuple[str, str], ...] = (("speech", "vc"),)
    builtin_voices: tuple[tuple[str, str], ...] = ()
    pitch: tuple[tuple[str, bool], ...] = ()
    style: bool = False
    # "audio" (audio + voice_ref) or "source_target" (source_audio + target_voice).
    fields: str = "audio"
    # RVC refuses seed as an unknown option.
    seed: bool = True
    source_rate: int = 16000
    target_rate: Optional[int] = 16000
    pitch_options: str = "semitone"
    # Seed-VC speech routes, default first: a session keeps the route it first ran.
    routes: tuple[str, ...] = ()
    tool_options: tuple[dict, ...] = field(default = (), hash = False)
    hidden_options: tuple[str, ...] = ()

    @property
    def target(self) -> str:
        return "builtin" if self.builtin_voices else "audio"

    @property
    def server_tasks(self) -> dict[str, str]:
        return dict(self.modes)


@dataclass(frozen = True)
class SeparationSpec:
    """Changing overlap_option restarts the server"""

    overlap_option: Optional[str] = None


@dataclass(frozen = True)
class CompanionModel:
    """A second model a family loads beside its own (MioTTS's MioCodec), by session option."""

    id: str
    variant: str
    session_option: str


MUSIC_MAX_VARIATIONS = 4


@dataclass(frozen = True)
class MusicMode:
    id: str  # song | sfx | edit
    lyrics: str = "unused"  # required | optional | unused
    description: str = "required"  # required | optional
    instrumental: str = "always"  # toggle | always | never
    section_case: Optional[str] = None  # lower ([verse]) | title ([Verse])
    # (min, max, default) seconds, narrowed to the spec's bounds at resolve time.
    duration: tuple[float, float, float] = (5.0, 240.0, 30.0)
    approximate: bool = False
    # "batch" (one call) | "sequential" (one call each) | None (one take).
    variations: Optional[str] = None
    actions: tuple[str, ...] = ()
    max_ranges: int = 0
    max_source_s: float = 240.0


@dataclass(frozen = True)
class MusicSpec:
    modes: tuple[MusicMode, ...]
    description_option: Optional[str] = None
    instrumental_lyrics: Optional[str] = None
    edit_rate: Optional[int] = None
    rtf: float = 4.0
    # A model that ends the song itself gets no length budget; the runtime caps it at this many s.
    self_ending_s: Optional[float] = None

    def mode(self, mode_id: Optional[str]) -> Optional[MusicMode]:
        return next((m for m in self.modes if m.id == mode_id), None)


_STABLE_AUDIO_SONG = MusicMode("song", duration = (1.0, 120.0, 30.0), variations = "batch")
_STABLE_AUDIO_SFX = MusicMode("sfx", duration = (1.0, 120.0, 8.0), variations = "batch")
# Small's runtime window is 120 s (sample_size / sample_rate): a longer edit comes back cut.
_STABLE_AUDIO_EDIT = MusicMode(
    "edit", actions = ("inpaint", "restyle"), max_ranges = 8, max_source_s = 120.0
)
MUSIC_SPECS: dict[str, MusicSpec] = {
    "ace_step": MusicSpec(
        (
            MusicMode("song", lyrics = "optional", instrumental = "toggle", section_case = "lower"),
            # "continue" (the runtime's "complete") is base-only upstream; with_variant adds it.
            MusicMode("edit", actions = ("repaint", "extend", "cover"), max_ranges = 1),
        ),
        instrumental_lyrics = "[Instrumental]",
        edit_rate = 48000,
        rtf = 2.0,
    ),
    "stable_audio": MusicSpec(
        (_STABLE_AUDIO_SONG, _STABLE_AUDIO_EDIT),
        edit_rate = 44100,
        rtf = 1.0,
    ),
    "heartmula": MusicSpec(
        (MusicMode("song", lyrics = "required", instrumental = "never"),),
        description_option = "tags",
    ),
    "midashenglm_gen": MusicSpec(
        # The spec allows 163.84 s, but the runtime drops the connection past ~81 s (2048 frames).
        (
            MusicMode("song", duration = (1.0, 80.0, 30.0), variations = "sequential"),
            MusicMode("sfx", duration = (1.0, 80.0, 10.0), variations = "sequential"),
        ),
        rtf = 2.0,
    ),
    "controlfoley": MusicSpec(
        (MusicMode("sfx", duration = (1.0, 60.0, 8.0), variations = "sequential"),),
        rtf = 2.0,
    ),
    "minimax_music3": MusicSpec(
        (
            MusicMode(
                "song",
                lyrics = "required",
                instrumental = "never",
                section_case = "lower",
                approximate = True,
            ),
        ),
    ),
    "yue2": MusicSpec(
        (
            MusicMode(
                "song",
                lyrics = "optional",
                instrumental = "toggle",
                section_case = "title",
                approximate = True,
            ),
        ),
        description_option = "style",
        # Empty lyrics still sing; only this tag stays wordless.
        instrumental_lyrics = "[Instrumental]",
        rtf = 6.0,
        # Any length budget cut songs mid-verse (#13337); upstream's own cap is 9000 frames = 360 s.
        self_ending_s = 360.0,
    ),
}


def _stable_audio_music(names: Iterable[str]) -> MusicSpec:
    spec = MUSIC_SPECS["stable_audio"]
    text = " ".join(names).lower()
    if re.search(r"(^|[-_ /.])sfx([-_ /.]|$)", text):
        return replace(spec, modes = (_STABLE_AUDIO_SFX,), edit_rate = None)
    if "medium" in text:
        # Medium generates far past Small's window; keep Studio's 240 s cap.
        return replace(
            spec,
            modes = (
                replace(_STABLE_AUDIO_SONG, duration = (1.0, 240.0, 30.0)),
                replace(_STABLE_AUDIO_SFX, duration = (1.0, 240.0, 8.0)),
                replace(_STABLE_AUDIO_EDIT, max_source_s = 240.0),
            ),
        )
    return spec


def _is_number(value: Any) -> bool:
    return isinstance(value, (int, float)) and not isinstance(value, bool)


def music_with_spec_bounds(
    music: Optional[MusicSpec], raw_options: Sequence[Any]
) -> Optional[MusicSpec]:
    if music is None:
        return None
    low = high = None
    for item in raw_options:
        if isinstance(item, dict) and item.get("name") == "duration_sec":
            low, high = item.get("min"), item.get("max")
            break
    if not _is_number(low) and not _is_number(high):
        return music
    modes = []
    for mode in music.modes:
        if mode.id == "edit":
            modes.append(mode)
            continue
        lo, hi, default = mode.duration
        if _is_number(low):
            lo = max(lo, float(low))
        if _is_number(high):
            hi = min(hi, float(high))
        if hi < lo:
            hi = lo
        modes.append(replace(mode, duration = (lo, hi, min(hi, max(lo, default)))))
    return replace(music, modes = tuple(modes))


_CLONE_INPUTS = ("text", "reference", "reference_text", "language")


def option_matches(pairs: Iterable[tuple[str, Iterable[str]]], options: Optional[dict]) -> bool:
    """Whether ``options`` sets any ``(option, values)`` pair, bools read as ``true``/``false``."""
    options = options or {}
    for name, values in pairs:
        if name in options:
            value = options[name]
            text = ("true" if value else "false") if isinstance(value, bool) else str(value)
            if text.strip().lower() in values:
                return True
    return False


def _bindings_for(
    task: str,
    server_task: Optional[str],
    family: Any = None,
) -> dict[str, WorkflowBinding]:
    """The workflows a Studio task offers, keyed by workflow id; empty when Studio has none."""
    if task == "tts":
        bindings: dict[str, WorkflowBinding] = {}
        if getattr(family, "speaks", True):
            bindings["speak"] = WorkflowBinding(
                server_task or "tts", "speech", None, ("text", "instruct", "language", "voice")
            )
        clone = getattr(family, "clone", None)
        if clone is not None:
            bindings["clone"] = WorkflowBinding(server_task or "tts", "speech", None, _CLONE_INPUTS)
        edit = getattr(family, "edit", None)
        if edit is not None:
            bindings["edit"] = WorkflowBinding(
                edit.server_task, "tasks", edit.route, ("source", "text", "reference_text")
            )
        convert = getattr(family, "convert", None)
        if convert is not None:
            bindings["convert"] = WorkflowBinding(
                convert.modes[0][1], "tasks", None, ("source", "target", "source_text")
            )
        return bindings
    if task == "music":
        return {
            "music": WorkflowBinding("gen", "tasks", None, ("text", "lyrics", "duration_seconds"))
        }
    if task == "asr":
        return {"transcribe": WorkflowBinding("asr", "transcriptions", None, ("audio",))}
    if task == "sep":
        return {"separate": WorkflowBinding("sep", "tasks", None, ("audio",))}
    return {}


@dataclass(frozen = True)
class AudioCppFamily:
    family: str
    task: str
    # audiocpp_server task when it is not the Studio task's default (a voice-design package runs "vdes").
    server_task: Optional[str] = None
    # Phonemizes with eSpeak-ng, so it needs a bundle built with AUDIOCPP_STATIC_ESPEAK.
    needs_espeak: bool = False
    # Default speech fields (e.g. voice); an options dict here merges under the request's own options
    request_defaults: dict = field(default_factory = dict, hash = False, compare = False)
    # Values injected into the server config's model entry.
    model_options: dict = field(default_factory = dict, hash = False, compare = False)
    # Package families load a directory of several GGUFs; their variants are the package's mixes.
    package: tuple[AudioCppPackageVariant, ...] = ()
    # Request options Studio shows when neither the runtime nor the GGUF offers a current spec.
    options: tuple[dict, ...] = ()
    # Built-in speakers when the spec lists none (the published Qwen3-TTS GGUFs embed a legacy spec).
    voices: tuple[str, ...] = ()
    # Why Studio refuses this family, when it does.
    unsupported: Optional[str] = None
    speaks: bool = True
    clone: Optional[CloneSpec] = None
    companions: tuple[CompanionModel, ...] = ()
    edit: Optional[EditSpec] = None
    convert: Optional[ConvertSpec] = None
    separation: Optional[SeparationSpec] = None
    music: Optional[MusicSpec] = field(default = None, hash = False, compare = False)

    @property
    def default_server_task(self) -> str:
        if self.server_task:
            return self.server_task
        return "gen" if self.task == "music" else self.task

    @property
    def workflows(self) -> dict[str, WorkflowBinding]:
        return _bindings_for(self.task, self.default_server_task, self)


def _minimax_package(key: str, lm: str, rvq: str, flow: str) -> AudioCppPackageVariant:
    files = (
        "config.json",
        "config/language_model.json",
        "config/rvq_depth_decoder.json",
        "config/condition_encoder.json",
        "config/transformer.json",
        "config/vocoder.json",
        "tokenizer/tokenizer.json",
        "tokenizer/tokenizer_config.json",
        f"language_model_{lm}.gguf",
        f"rvq_depth_decoder_{rvq}.gguf",
        "condition_encoder.gguf",
        f"transformer_{flow}.gguf",
        "vocoder.gguf",
    )
    return AudioCppPackageVariant(
        key,
        files,
        {
            "minimax_music3.language_model_gguf": f"language_model_{lm}.gguf",
            "minimax_music3.rvq_depth_decoder_gguf": f"rvq_depth_decoder_{rvq}.gguf",
            "minimax_music3.flow_transformer_gguf": f"transformer_{flow}.gguf",
        },
    )


def _yue2_package(key: str, quant: str) -> AudioCppPackageVariant:
    main = f"yue2-3b-{quant}.gguf"
    return AudioCppPackageVariant(
        key,
        (
            "sidecars/yue2-model-config.json",
            "sidecars/yue2-generation-config.json",
            "sidecars/yue2-qwen.tiktoken",
            "sidecars/yue2-vae-config.json",
            main,
            "yue2-vae-f16.gguf",
        ),
        {"yue2.model_gguf": main, "yue2.vae_gguf": "yue2-vae-f16.gguf"},
    )


def _opt(name: str, type_: str, description: str, **kw) -> dict:
    return {"name": name, "type": type_, "description": description, **kw}


def _tool(name: str, type_: str, description: str, **kw) -> dict:
    """A clone tool option in ``_clean_option``'s shape."""
    return {
        "name": name,
        "type": type_,
        "description": description,
        "required": False,
        "default": kw.get("default"),
        "min": kw.get("min"),
        "max": kw.get("max"),
        "values": kw.get("values"),
    }


MIOCODEC_FOLDER = "MioCodec-25Hz-44.1kHz-v2-GGUF"

_QWEN3_BASE = AudioCppFamily(
    "qwen3_tts",
    "tts",
    speaks = False,
    clone = CloneSpec(
        "required",
        tool_options = (
            _tool(
                "x_vector_only_mode",
                "bool",
                "Clone the timbre only; the clip's transcript is not needed.",
                default = False,
            ),
        ),
        reference_text_waived = (("x_vector_only_mode", ("true",)),),
        reference_text_dropped = (("x_vector_only_mode", ("true",)),),
        language_names = True,
    ),
)
_CLONE_FAMILIES: tuple[AudioCppFamily, ...] = (
    # Clone-only (VoiceCloning, VoiceConversion); Chatterbox-Turbo is its own family and still speaks
    AudioCppFamily(
        "chatterbox",
        "tts",
        server_task = "clon",
        speaks = False,
        clone = CloneSpec(
            "unused",
            tool_options = (
                _tool(
                    "exaggeration", "float", "Emotion exaggeration.", min = 0.0, max = 2.0, default = 0.5
                ),
                _tool(
                    "guidance_scale",
                    "float",
                    "Classifier-free guidance.",
                    min = 0.0,
                    max = 5.0,
                    default = 0.5,
                ),
            ),
        ),
        # A clon session refuses a conversion ("prepare requires text input"), so Convert loads vc.
        convert = ConvertSpec(
            source_rate = 16000,
            target_rate = 24000,
            tool_options = (
                _tool(
                    "s3gen_cfg_rate",
                    "float",
                    "Classifier-free guidance of the voice decoder.",
                    min = 0.0,
                    max = 3.0,
                    default = 0.7,
                ),
                _tool("num_inference_steps", "int", "Decoder steps.", min = 1, max = 100, default = 10),
            ),
        ),
    ),
    AudioCppFamily("f5_tts", "tts", speaks = False, clone = CloneSpec("required", speed = True)),
    AudioCppFamily(
        "index_tts2",
        "tts",
        speaks = False,
        clone = CloneSpec(
            "unused",
            tool_options = (
                _tool(
                    "emotion_vector",
                    "string",
                    "Eight comma-separated weights: happy, angry, sad, afraid, disgusted, "
                    "melancholic, surprised, calm.",
                ),
                _tool("emotion_alpha", "float", "Emotion strength.", min = 0.0, max = 1.0, default = 1.0),
                _tool(
                    "use_emotion_text", "bool", "Take the emotion from emotion_text.", default = False
                ),
                _tool("emotion_text", "string", "A description of the emotion."),
            ),
            emotion_audio = True,
        ),
    ),
    AudioCppFamily(
        "cosyvoice3",
        "tts",
        speaks = False,
        clone = CloneSpec(
            "required",
            # Required for the default zero_shot template only.
            reference_text_waived = (("template_name", ("cross_lingual", "instruct")),),
            reference_text_dropped = (("template_name", ("cross_lingual",)),),
            instructions = True,
        ),
    ),
    AudioCppFamily("voxcpm2", "tts", clone = CloneSpec("optional", description = True)),
    AudioCppFamily("fish_audio", "tts", clone = CloneSpec("required")),
    AudioCppFamily("breeze_tts", "tts", clone = CloneSpec("required", description = True)),
    # Its clone instruction takes only fixed attribute words; free text fails the run.
    AudioCppFamily("omnivoice", "tts", clone = CloneSpec("required")),
    AudioCppFamily("voxcpm1", "tts", clone = CloneSpec("required")),
    AudioCppFamily("dots_tts", "tts", clone = CloneSpec("optional")),
    AudioCppFamily("higgs_audio_tts", "tts", clone = CloneSpec("optional")),
    # MOSS ignores a transcript; Irodori refuses one ("unknown Irodori-TTS request option").
    AudioCppFamily("moss_tts_local", "tts", clone = CloneSpec("unused")),
    AudioCppFamily("moss_tts_nano", "tts", clone = CloneSpec("unused")),
    # No description: the 500M v3 checkpoint refuses one (no caption conditioning weights).
    AudioCppFamily("irodori_tts", "tts", clone = CloneSpec("unused")),
    AudioCppFamily("echo_tts", "tts", server_task = "clon", speaks = False, clone = CloneSpec("unused")),
    AudioCppFamily(
        "confucius4_tts", "tts", server_task = "clon", speaks = False, clone = CloneSpec("unused")
    ),
    # Instruct under tts defaults to instruct_tts, which needs reference audio.
    AudioCppFamily("fireredtts3", "tts", speaks = False, clone = CloneSpec("optional")),
    # "FireRedAce": under tts it defaults to tts_clone, which needs reference audio.
    AudioCppFamily(
        "firered_audio",
        "tts",
        speaks = False,
        clone = CloneSpec("optional"),
        edit = EditSpec(
            "tts",
            "instructions",
            source_field = "audio",
            template = "semantic_edit",
            delivery_template = "acoustic_edit",
            max_changes = 5,
            claims = ("template_name", "instruction"),
        ),
    ),
    # Vevo2 reads a sent transcript as text to speak, so it never gets one; it edits only as an s2s session, and an edit after Clone restarts the server
    AudioCppFamily(
        "vevo2",
        "tts",
        speaks = False,
        clone = CloneSpec("unused"),
        edit = EditSpec("s2s", "sentence", route = "editing"),
        convert = ConvertSpec(
            modes = (("speech", "vc"), ("singing", "svc")),
            pitch = (("speech", True), ("singing", True)),
            style = True,
            fields = "source_target",
            pitch_options = "shift_steps",
            source_rate = 24000,
            target_rate = 24000,
            tool_options = (
                _tool(
                    "num_inference_steps",
                    "int",
                    "Flow matching steps.",
                    min = 1,
                    max = 100,
                    default = 32,
                ),
            ),
        ),
    ),
    # MioCodec's sibling-folder default never matches the umbrella layout: pass it by session option.
    AudioCppFamily(
        "miotts",
        "tts",
        speaks = False,
        clone = CloneSpec("unused"),
        companions = (
            CompanionModel(
                f"{AUDIO_CPP_REPO}/{MIOCODEC_FOLDER}", "Q8_0", "miotts.codec_model_path"
            ),
        ),
    ),
    # Both need a reference clip on every run (mira_tts/session.cpp, sopro_tts/session.cpp).
    AudioCppFamily("mira_tts", "tts", speaks = False, clone = CloneSpec("unused")),
    AudioCppFamily("sopro_tts", "tts", speaks = False, clone = CloneSpec("unused")),
)


_CONVERT_FAMILIES: tuple[AudioCppFamily, ...] = (
    AudioCppFamily(
        "rvc",
        "tts",
        server_task = "vc",
        speaks = False,
        convert = ConvertSpec(
            builtin_voices = (
                ("default", "Default"),
                ("manthos", "Manthos"),
                ("chocola", "Chocola"),
                ("fraise", "Fraise"),
            ),
            pitch = (("speech", False),),
            seed = False,
            source_rate = 16000,
            target_rate = None,
            # audio_pad_duration_sec reads as a file option to the run route.
            hidden_options = ("audio_pad_duration_sec", "speaker_id", "pitch_extractor"),
        ),
    ),
    # Speech routes ignore semitone_shift; the V1 speech F0 path fails ("RMVPE is not initialized").
    AudioCppFamily(
        "seed_vc",
        "tts",
        server_task = "vc",
        speaks = False,
        convert = ConvertSpec(
            modes = (("speech", "vc"), ("singing", "svc")),
            pitch = (("singing", True),),
            source_rate = 44100,
            target_rate = 44100,
            routes = ("v2_vc", "v1_whisper_bigvgan_vc", "v1_xlsr_hift_vc"),
            hidden_options = ("f0_condition",),
        ),
    ),
    AudioCppFamily(
        "meanvc2",
        "tts",
        server_task = "vc",
        speaks = False,
        convert = ConvertSpec(source_rate = 16000, target_rate = 16000),
    ),
    AudioCppFamily(
        "tone_color_vc",
        "tts",
        server_task = "vc",
        speaks = False,
        convert = ConvertSpec(source_rate = 22050, target_rate = 22050),
    ),
)


_SEPARATION_FAMILIES: tuple[AudioCppFamily, ...] = (
    AudioCppFamily("htdemucs", "sep", separation = SeparationSpec()),
    AudioCppFamily("htdemucs_6stems", "sep", separation = SeparationSpec()),
    AudioCppFamily("bs_roformer", "sep", separation = SeparationSpec("num_overlap")),
    AudioCppFamily("mel_band_roformer", "sep", separation = SeparationSpec("num_overlap")),
)


# Table families can be newer than some runtimes, so the runtime check still applies to them.
_RUNTIME_GATED_FAMILIES = frozenset(("mira_tts", "sopro_tts"))

_MULTI_FILE_PACKAGE = "This model ships as a multi-file package Unsloth Studio cannot load yet."

_FAMILY_LIST: tuple[AudioCppFamily, ...] = (
    # eSpeak-ng is linked statically (GPL-3.0-or-later) in the Unsloth bundles.
    AudioCppFamily("kokoro_tts", "tts", needs_espeak = True),
    AudioCppFamily("kitten_tts", "tts", needs_espeak = True),
    AudioCppFamily("piper_tts", "tts", needs_espeak = True),
    AudioCppFamily("inflect_v2", "tts", needs_espeak = True),
    AudioCppFamily(
        "pocket_tts", "tts", request_defaults = {"voice": "alba"}, clone = CloneSpec("unused")
    ),
    # Supertonic's presets (include/engine/models/supertonic/session.h:22 defaults to M1).
    AudioCppFamily(
        "supertonic",
        "tts",
        request_defaults = {"voice": "M1"},
        voices = ("M1", "M2", "M3", "M4", "M5", "F1", "F2", "F3", "F4", "F5"),
    ),
    AudioCppFamily("qwen3_tts", "tts"),
    *_CLONE_FAMILIES,
    *_CONVERT_FAMILIES,
    *(
        AudioCppFamily(name, "tts")
        for name in (
            "moss_tts_v15",
            "moss_ttsd",
            "chatterbox_turbo",
            "neutts",
            "magpie_tts",
            # Its spec lists clone, but from a short reference clip it may not keep the voice.
            "dramabox",
            "vibevoice",
            "glm_tts",
            "outetts",
            "sanotts",
            "soprano_tts",
            "zipvoice",
            "vieneu_v3_turbo",
            "audio8_tts",
        )
    ),
    # Voice design only: every voice is designed from the instruction.
    AudioCppFamily(
        "moss_voicegen",
        "tts",
        server_task = "vdes",
        request_defaults = {
            "options": {
                "instruct": "A warm, clear, natural adult voice speaking at a relaxed pace."
            }
        },
    ),
    # Music generation.
    AudioCppFamily(
        "ace_step",
        "music",
        music = MUSIC_SPECS["ace_step"],
        # The spec declares no request options; these are the ones loader.cpp reads.
        options = (
            _opt("bpm", "int", "Tempo in beats per minute.", min = 30, max = 300),
            _opt("keyscale", "string", "Key and scale, e.g. A minor."),
            _opt(
                "timesignature",
                "enum",
                "Beats per bar.",
                values = ["2", "3", "4", "6"],
            ),
            _opt("negative_prompt", "string", "What to avoid."),
            _opt("sampler_mode", "enum", "Diffusion sampler.", values = ["euler", "heun"]),
            _opt(
                "num_inference_steps",
                "int",
                "Diffusion denoising steps.",
                min = 1,
                max = 20,
                default = 8,
            ),
            _opt("guidance_scale", "float", "Diffusion guidance scale.", min = 0.0),
            _opt("shift", "float", "Timestep shift.", min = 1.0, max = 5.0),
        ),
    ),
    AudioCppFamily(
        "stable_audio",
        "music",
        music = MUSIC_SPECS["stable_audio"],
        options = (
            _opt(
                "sampler",
                "enum",
                "Diffusion sampler.",
                values = ["pingpong", "euler"],
            ),
            _opt(
                "num_inference_steps",
                "int",
                "Diffusion denoising steps.",
                min = 1,
                max = 100,
                default = 8,
            ),
            _opt(
                "guidance_scale", "float", "Classifier-free guidance scale.", min = 0.0, default = 1.0
            ),
            _opt("apg_scale", "float", "Adaptive projected guidance scale.", min = 0.0, default = 1.0),
            _opt("negative_prompt", "string", "What to avoid."),
        ),
    ),
    *(
        AudioCppFamily(name, "music", music = MUSIC_SPECS[name])
        for name in ("heartmula", "midashenglm_gen", "controlfoley")
    ),
    AudioCppFamily(
        "minimax_music3",
        "music",
        music = MUSIC_SPECS["minimax_music3"],
        package = (
            _minimax_package("Q4_0", "q4_0", "q8_0", "q4_0"),
            _minimax_package("Q8_0", "q8_0", "q8_0", "q8_0"),
            _minimax_package("BF16", "bf16", "bf16", "bf16"),
        ),
        # The runtime's current spec; the one embedded in the published GGUFs predates it.
        options = (
            _opt(
                "num_inference_steps",
                "int",
                "Flow matching Euler steps per chunk.",
                min = 1,
                default = 30,
            ),
            _opt(
                "guidance_scale",
                "float",
                "Flow transformer classifier-free guidance scale.",
                min = 0.0,
                default = 1.7,
            ),
            _opt(
                "ar_guidance_scale",
                "float",
                "Autoregressive semantic and depth CFG scale.",
                min = 0.0,
                default = 1.5,
            ),
            _opt(
                "top_k",
                "int",
                "Top-k sampling for semantic and residual code sampling.",
                min = 1,
                default = 50,
            ),
        ),
    ),
    AudioCppFamily(
        "yue2",
        "music",
        music = MUSIC_SPECS["yue2"],
        package = (
            _yue2_package("Q8_0", "q8_0"),
            _yue2_package("BF16", "bf16"),
            _yue2_package("Q4_0", "q4_0"),
        ),
        options = (
            _opt(
                "cot",
                "enum",
                "Symbolic planning route. off skips ABC generation; melody/full generate ABC before music tokens.",
                values = ["off", "melody", "full"],
                default = "full",
            ),
            _opt("num_inference_steps", "int", "NAR midpoint ODE steps.", min = 1, default = 8),
            _opt(
                "guidance_scale",
                "float",
                "Semantic classifier-free guidance scale.",
                min = 0.0,
                max = 20.0,
            ),
            _opt(
                "semantic_temperature",
                "float",
                "Semantic codec sampling temperature.",
                min = 0.0,
                max = 5.0,
            ),
            _opt(
                "semantic_top_p",
                "float",
                "Semantic codec nucleus sampling probability.",
                min = 0.0,
                max = 1.0,
            ),
            _opt("semantic_top_k", "int", "Semantic codec top-k sampling limit.", min = 1),
        ),
    ),
    # Full context fails past ~400 s encoder ceiling; windows drop about a third of words.
    AudioCppFamily(
        "parakeet_tdt",
        "asr",
        model_options = {
            "session_options": {
                "parakeet_tdt.offline_mode": "auto",
                "parakeet_tdt.audio_chunk_threshold_sec": "390",
            }
        },
    ),
    *(
        AudioCppFamily(name, "asr")
        for name in (
            "qwen3_asr",
            "canary_asr",
            "citrinet_asr",
            "cohere_asr",
            "higgs_audio_stt",
            "granite5asr",
            "kroko_asr",
            "moonshine_asr",
            "moss_transcribe_diarize",
            "nemotron_asr",
            "niagara_asr",
            "voxtral_realtime",
            "vibevoice_asr",
            "vibevoice_asr_streaming",
            "hviske_asr",
            "fun_asr_nano",
            "sense_asr",
            "confucius4_r2t2",
            "audio8_asr",
        )
    ),
    *_SEPARATION_FAMILIES,
    # Package families Studio does not lay out yet.
    *(
        AudioCppFamily(
            name,
            "",
            unsupported = _MULTI_FILE_PACKAGE,
        )
        for name in ("minimax_h3", "auk", "liveavatar", "vibeasr")
    ),
    AudioCppFamily(
        "miocodec",
        "",
        unsupported = "MioCodec is the codec MioTTS loads with; pick MioTTS to use it.",
    ),
    # Tasks Studio has no page for.
    *(
        AudioCppFamily(
            name, "", unsupported = f"{what} models are not supported in Unsloth Studio yet."
        )
        for names, what in (
            (("qwen3_forced_aligner", "mms_forced_aligner"), "Forced-alignment"),
            (("sortformer_diar", "sortformer_diar_v2", "nemotron_3_diar"), "Speaker diarization"),
            (("pulsevad", "silero_vad", "marblenet_vad"), "Voice activity detection"),
            (("muscriptor", "sheetsage2"), "Music transcription"),
            (("apollo", "audiosr", "universr", "personaplex"), "Speech-to-speech"),
        )
        for name in names
    ),
    # Its spec says ASR, but it answers with a description of the audio, not what was said.
    AudioCppFamily(
        "samsone",
        "",
        unsupported = "SAMSONE describes audio rather than transcribing speech, so Unsloth Studio "
        "does not offer it for transcription.",
    ),
)

FAMILIES: dict[str, AudioCppFamily] = {f.family: f for f in _FAMILY_LIST}

_DOTS_EDIT = EditSpec("tts", "markup", template = "edit")

# Sessions refuse any backend but CPU ("Niagara ASR CPU variants require --backend cpu").
CPU_ONLY_FAMILIES: frozenset[str] = frozenset({"niagara_asr"})

# Spec task names that are not runtime task tokens.
_SPEC_TO_SERVER_TASK = {
    "music": "gen",
    "sfx": "gen",
    "edit": "gen",
    "clone": "clon",
    "design": "vdes",
    "speaker": "spk",
}
_TASK_NAMES = {
    "align": "Forced-alignment",
    "diar": "Speaker diarization",
    "sep": "Source separation",
    "vad": "Voice activity detection",
    "midi": "Music transcription",
    "s2s": "Speech-to-speech",
    "spk": "Speaker embedding",
    "turn": "Turn detection",
    "clon": "Voice cloning",
    "vdes": "Voice design",
}


def recommended_gguf_files(spec: Optional[dict]) -> tuple[str, ...]:
    """Base names of the GGUFs in the spec's recommended package, else its default GGUF package."""
    packages = [p for p in (spec or {}).get("packages") or [] if isinstance(p, dict)]
    packages = [p for p in packages if str(p.get("format") or "").lower() == "gguf"]
    wanted = ((spec or {}).get("ui") or {}).get("recommended_package")
    package = next((p for p in packages if wanted and p.get("id") == wanted), None) or next(
        (p for p in packages if p.get("default") is True), None
    )
    files = (package or {}).get("files") or []
    return tuple(
        f.replace("\\", "/").rsplit("/", 1)[-1]
        for f in files
        if isinstance(f, str) and f.lower().endswith(".gguf")
    )


def _spec_music(tasks: Sequence[str], request: Optional[list]) -> MusicSpec:
    """Music modes for a family the table does not list, from its spec tasks and options."""
    names = {str(o.get("name")) for o in request or [] if isinstance(o, dict)}
    sings = "lyrics" in names
    modes = []
    if "music" in tasks or "sfx" not in tasks:
        modes.append(
            MusicMode(
                "song",
                lyrics = "optional" if sings else "unused",
                instrumental = "toggle" if sings else "always",
            )
        )
    if "sfx" in tasks:
        modes.append(MusicMode("sfx", duration = (1.0, 60.0, 8.0)))
    # Whether a seed is sent follows the spec's request keys (takes_seed).
    return MusicSpec(tuple(modes))


def _family_from_spec_tasks(
    family: str,
    spec: Optional[dict],
    label: Optional[str] = None,
) -> AudioCppFamily:
    """Policy for a family Unsloth Studio does not list, from the tasks its spec declares.

    The spec can be the one a GGUF embeds, newer than the installed runtime, so a family the
    runtime does not load is refused here rather than failing at load with "unsupported model
    family hint". ``label`` names the model in that refusal.
    """
    tasks = [str(t).lower() for t in (spec or {}).get("tasks") or [] if isinstance(t, str)]
    # ``edit`` is a music edit for some families and a speech edit for others, so it names no page.
    tokens = [_SPEC_TO_SERVER_TASK.get(t, t) for t in tasks if t != "edit"] or tasks
    request = ((spec or {}).get("options") or {}).get("request") or None
    request = request if isinstance(request, list) else None
    # One page set per family. Speech first (with Clone when the spec clones), then music, then
    # transcription; a clone-only family loads as a cloning session and offers Clone alone.
    for token in ("tts", "vdes", "gen", "asr", "clon", "sep"):
        if token not in tokens:
            continue
        if runtime_knows_family(family) is False:
            return AudioCppFamily(
                family,
                "",
                unsupported = f"{label or family} needs a newer audio runtime than the one installed.",
            )
        if len(recommended_gguf_files(spec)) > 1:
            return AudioCppFamily(family, "", unsupported = _MULTI_FILE_PACKAGE)
        if token in ("tts", "vdes", "clon"):
            clone = None
            if "clon" in tokens:
                # Clone always sends a reference, and a family that declares reference_text then
                # needs it (fish_drama3, kitten_tts2); an undeclared option is refused.
                names = {str(o.get("name")) for o in request or [] if isinstance(o, dict)}
                text = "optional" if request is None else "unused"
                clone = CloneSpec("required" if "reference_text" in names else text)
            if token == "clon":
                return AudioCppFamily(family, "tts", server_task = "clon", speaks = False, clone = clone)
            return AudioCppFamily(family, "tts", server_task = token, clone = clone)
        if token == "gen":
            music = _spec_music(tasks, request)
            return AudioCppFamily(family, "music", server_task = "gen", music = music)
        if token == "sep":
            return AudioCppFamily(family, "sep", separation = SeparationSpec())
        return AudioCppFamily(family, "asr", server_task = "asr")
    if tokens:
        what = _TASK_NAMES.get(tokens[0])
        if tokens[0] in ("vc", "svc"):
            message = "Unsloth Studio doesn't support voice conversion models yet."
        elif what:
            message = f"{what} models are not supported in Unsloth Studio yet."
        else:
            message = f"Unsloth Studio does not support the '{tokens[0]}' task yet."
        return AudioCppFamily(family, "", unsupported = message)
    return AudioCppFamily(
        family,
        "",
        unsupported = f"Unsloth Studio does not know what the model family '{family}' does.",
    )


def family_policy(
    family: str,
    spec: Optional[dict] = None,
    names: Iterable[str] = (),
    label: Optional[str] = None,
) -> AudioCppFamily:
    """Table entry, else the spec; names pick the Qwen3-TTS kind (CustomVoice needs a speaker,
    VoiceDesign designs one, Base only clones)."""
    if family in _RUNTIME_GATED_FAMILIES and runtime_knows_family(family) is False:
        return AudioCppFamily(
            family,
            "",
            unsupported = f"{label or family} needs a newer audio runtime than the one installed.",
        )
    policy = FAMILIES.get(family) or _family_from_spec_tasks(family, spec, label)
    if family == "qwen3_tts":
        text = " ".join(names).lower()
        if "voicedesign" in text or "voice-design" in text:
            return AudioCppFamily(
                family,
                "tts",
                server_task = "vdes",
                request_defaults = {
                    "options": {
                        "instruct": "A warm, clear, natural adult voice speaking at a relaxed pace."
                    }
                },
            )
        if "customvoice" in text or "custom-voice" in text:
            # A speaker is mandatory: the package's spk_id table.
            return AudioCppFamily(
                family,
                "tts",
                request_defaults = {"voice": "vivian"},
                voices = (
                    "vivian",
                    "serena",
                    "ryan",
                    "aiden",
                    "ono_anna",
                    "sohee",
                    "uncle_fu",
                    "eric",
                    "dylan",
                ),
            )
        if "base" in text:
            return _QWEN3_BASE
    if family == "stable_audio" and policy.music is not None:
        return replace(policy, music = _stable_audio_music(names))
    if family == "fireredtts3" and re.search(r"(^|[-_ /])base([-_ ./]|$)", " ".join(names).lower()):
        return replace(policy, server_task = "clon")
    if family == "dots_tts" and re.search(r"(^|[-_ /])edit([-_ ./]|$)", " ".join(names).lower()):
        # DotTTS-MF and SOAR support speech only.
        return replace(policy, edit = _DOTS_EDIT)
    return policy


# maps saved Settings keys and earlier subfolder ids to current rows and variants for compatibility.
_LEGACY_KEYS: dict[str, tuple[str, Optional[str]]] = {
    "audiocpp-kokoro-82m": ("Kokoro-82M-GGUF", None),
    "audiocpp-kitten-tts-mini": ("KittenTTS-GGUF", None),
    "audiocpp-piper-en-us-lessac": ("Piper-TTS-GGUF", None),
    "audiocpp-inflect-micro-v2": ("Inflect-Micro-v2-GGUF", None),
    "audiocpp-pocket-tts-en": ("PocketTTS-GGUF", "english/Q8_0"),
    "audiocpp-moss-tts-nano": ("MOSS-TTS-Nano-100M-GGUF", None),
    "audiocpp-supertonic-3": ("Supertonic-3-GGUF", None),
    "audiocpp-chatterbox-turbo": ("Chatterbox-Turbo-GGUF", None),
    "audiocpp-voxcpm2": ("VoxCPM2-GGUF", None),
    "audiocpp-qwen3-tts-1.7b-customvoice": ("Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF", None),
    "audiocpp-qwen3-tts-1.7b-voicedesign": ("Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF", None),
    "audiocpp-ace-step-1.5-turbo": ("ACE-Step1.5-GGUF", "turbo/Q8_0"),
    "audiocpp-ace-step-1.5-base": ("ACE-Step1.5-GGUF", "base/Q8_0"),
    "audiocpp-stable-audio-3-small-music": ("Stable-Audio-3-Small-Music-GGUF", None),
    "audiocpp-qwen3-asr-0.6b": ("Qwen3-ASR-0.6B-GGUF", None),
    "audiocpp-qwen3-asr-1.7b": ("Qwen3-ASR-1.7B-GGUF", None),
    "audiocpp-parakeet-tdt-0.6b-v3": ("Parakeet-TDT-0.6B-v3-GGUF", None),
    "audiocpp-canary-180m-flash": ("Canary-180M-Flash-GGUF", None),
    "audiocpp-moonshine-tiny": ("Moonshine-Streaming-GGUF", "tiny/Q8_0"),
    "audiocpp-moonshine-small": ("Moonshine-Streaming-GGUF", "small/Q8_0"),
    "audiocpp-moonshine-medium": ("Moonshine-Streaming-GGUF", "medium/Q8_0"),
    "audiocpp-nemotron-3.5-asr-0.6b": ("Nemotron-3.5-ASR-Streaming-0.6B-GGUF", None),
}
_LEGACY_SUBFOLDER_VARIANTS = {
    "moonshine-streaming-gguf/tiny": "tiny/Q8_0",
    "moonshine-streaming-gguf/small": "small/Q8_0",
}


@dataclass(frozen = True)
class AudioCppRef:
    id: str
    repo_id: Optional[str]
    folder: str = ""
    variant_hint: Optional[str] = None
    local_path: Optional[str] = None

    @property
    def display_name(self) -> str:
        if self.local_path:
            return Path(self.local_path).stem
        if self.folder:
            return self.folder
        return str(self.repo_id).split("/")[-1]


_REPO_ID_RE = re.compile(r"^[A-Za-z0-9][\w.\-]*/[\w.\-]+$")


def is_legacy_key(identifier: Optional[str]) -> bool:
    """A dictation key saved by earlier builds (``audiocpp-parakeet-tdt-0.6b-v3``). No I/O."""
    return bool(identifier) and str(identifier).strip() in _LEGACY_KEYS


def legacy_keys() -> tuple[str, ...]:
    return tuple(_LEGACY_KEYS)


def is_umbrella_id(identifier: Optional[str]) -> bool:
    """A folder row of the audio.cpp umbrella repo, or a legacy dictation key. No I/O."""
    if not identifier:
        return False
    text = str(identifier).strip()
    return text in _LEGACY_KEYS or text.lower().startswith(_UMBRELLA_PREFIX)


def parse_identifier(identifier: Optional[str]) -> Optional[AudioCppRef]:
    """The ref ``identifier`` names, without any I/O; None when it cannot name an audio.cpp model."""
    if not identifier:
        return None
    text = str(identifier).strip().rstrip("/")
    if not text:
        return None
    legacy = _LEGACY_KEYS.get(text)
    if legacy is not None:
        folder, hint = legacy
        return AudioCppRef(f"{AUDIO_CPP_REPO}/{folder}", AUDIO_CPP_REPO, folder, hint)
    if text.lower().startswith(_UMBRELLA_PREFIX):
        rest = text[len(_UMBRELLA_PREFIX) :].replace("\\", "/").strip("/")
        parts = [p for p in rest.split("/") if p]
        if not parts or any(p in (".", "..") for p in parts):
            return None
        folder = parts[0]
        sub = "/".join(parts[1:])
        hint = None
        if sub:
            hint = _LEGACY_SUBFOLDER_VARIANTS.get(f"{folder}/{sub}".lower(), sub)
        return AudioCppRef(f"{AUDIO_CPP_REPO}/{folder}", AUDIO_CPP_REPO, folder, hint)
    if text.lower().endswith(".gguf"):
        path = Path(text).expanduser()
        try:
            if path.is_file():
                return AudioCppRef(str(path), None, local_path = str(path))
        except OSError:
            return None
        return None
    if _REPO_ID_RE.match(text):
        return AudioCppRef(text, text)
    return None


def split_variant_ref(identifier: str) -> tuple[str, Optional[str]]:
    """``repo:Q8_0`` -> ``("repo", "Q8_0")``, ``row:tiny/Q8_0`` -> ``("row", "tiny/Q8_0")``; a bare id
    keeps no variant. Paths are left whole."""
    text = str(identifier or "").strip()
    if ":" in text and not re.match(r"^[A-Za-z]:[\\/]", text):
        base, _, variant = text.rpartition(":")
        if base and variant and not variant.startswith(("/", "\\")):
            return base, variant
    return text, None


_FIXED_SIZES = {0: 1, 1: 1, 2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 10: 8, 11: 8, 12: 8}
_WANTED_KEYS = (
    "general.architecture",
    "audiocpp.model_spec.family",
    "audiocpp.model_spec.json",
)


@dataclass(frozen = True)
class AudioCppHeader:
    architecture: Optional[str]
    family: Optional[str]
    spec: Optional[dict] = field(default = None, hash = False, compare = False)
    # False when the read stopped before the header's end (a remote prefix): absent keys may lie beyond it.
    complete: bool = True
    source: Optional[str] = field(default = None, compare = False)

    @property
    def is_audio_cpp(self) -> bool:
        return (self.architecture or "").strip().lower() == AUDIO_CPP_ARCHITECTURE


def parse_header(stream: BinaryIO) -> Optional[AudioCppHeader]:
    """Truncation-safe: a prefix that ends early returns what was read, with complete=False."""
    try:
        head = stream.read(24)
        if len(head) < 24:
            return None
        magic, _version, _tensors, kv_count = struct.unpack("<IIQQ", head)
        if magic != 0x46554747 or kv_count > 1 << 20:
            return None
        found: dict[str, str] = {}
        for _ in range(kv_count):
            raw = stream.read(8)
            if len(raw) < 8:
                return _header(found, complete = False)
            (klen,) = struct.unpack("<Q", raw)
            if klen > 1 << 16:
                return _header(found, complete = False)
            key_bytes = stream.read(klen)
            type_bytes = stream.read(4)
            if len(key_bytes) < klen or len(type_bytes) < 4:
                return _header(found, complete = False)
            key = key_bytes.decode("utf-8", "replace")
            (vtype,) = struct.unpack("<I", type_bytes)
            if key in _WANTED_KEYS and vtype == 8:
                raw = stream.read(8)
                if len(raw) < 8:
                    return _header(found, complete = False)
                (slen,) = struct.unpack("<Q", raw)
                if slen > 1 << 26:
                    return _header(found, complete = False)
                value = stream.read(slen)
                if len(value) < slen:
                    return _header(found, complete = False)
                found[key] = value.decode("utf-8", "replace")
                if all(k in found for k in _WANTED_KEYS):
                    break
                continue
            if not _skip_value(stream, vtype):
                return _header(found, complete = False)
        return _header(found, complete = True)
    except (OSError, struct.error, ValueError):
        return None


def _skip_value(stream: BinaryIO, vtype: int) -> bool:
    if vtype == 8:
        raw = stream.read(8)
        if len(raw) < 8:
            return False
        stream.seek(struct.unpack("<Q", raw)[0], 1)
        return True
    if vtype == 9:
        raw = stream.read(12)
        if len(raw) < 12:
            return False
        atype, alen = struct.unpack("<IQ", raw)
        if atype == 8:
            for _ in range(alen):
                raw = stream.read(8)
                if len(raw) < 8:
                    return False
                stream.seek(struct.unpack("<Q", raw)[0], 1)
            return True
        size = _FIXED_SIZES.get(atype)
        if size is None:
            return False
        stream.seek(size * alen, 1)
        return True
    size = _FIXED_SIZES.get(vtype)
    if size is None:
        return False
    stream.seek(size, 1)
    return True


def _header(found: dict[str, str], *, complete: bool) -> AudioCppHeader:
    spec = None
    raw = found.get("audiocpp.model_spec.json")
    if raw:
        try:
            parsed = json.loads(raw)
            spec = parsed if isinstance(parsed, dict) else None
        except ValueError:
            spec = None
    family = found.get("audiocpp.model_spec.family") or (spec or {}).get("family")
    return AudioCppHeader(
        architecture = found.get("general.architecture"),
        family = str(family).strip() if family else None,
        spec = spec,
        complete = complete,
    )


_header_cache: dict[tuple, Optional[AudioCppHeader]] = {}
_header_lock = threading.Lock()
_HEADER_CACHE_MAX = 512


def _cached_header(key: tuple, compute) -> Optional[AudioCppHeader]:
    with _header_lock:
        if key in _header_cache:
            return _header_cache[key]
    value = compute()
    with _header_lock:
        while len(_header_cache) >= _HEADER_CACHE_MAX:
            _header_cache.pop(next(iter(_header_cache)))
        _header_cache[key] = value
    return value


def read_local_header(path: str | Path) -> Optional[AudioCppHeader]:
    """The audio.cpp header keys of a local GGUF, memoized on its size and mtime. Never raises."""
    try:
        stat = os.stat(path)
    except OSError:
        return None
    key = ("local", os.path.realpath(path), stat.st_size, int(stat.st_mtime))

    def compute():
        try:
            with open(path, "rb") as f:
                return parse_header(f)
        except OSError:
            return None

    return _cached_header(key, compute)


def read_remote_header(
    repo_id: str,
    filename: str,
    hf_token: Optional[str] = None,
    *,
    size: Optional[int] = None,
) -> Optional[AudioCppHeader]:
    """Ranged read of the first 64 KiB of a Hub GGUF, enough to say audio.cpp; a prefix with no family is read further, past embedded sidecars"""

    def compute():
        from core.inference.diffusion_compat import _read_gguf_header

        header = None
        for max_bytes in (1 << 16, 1 << 22):
            if size is not None and 0 < size <= max_bytes // 2 and header is not None:
                break
            data = _read_gguf_header(
                repo_id, filename, hf_token, max_bytes = max_bytes, timeout_seconds = 10
            )
            if not data:
                return header
            header = parse_header(io.BytesIO(data))
            if header is None or not header.is_audio_cpp or header.family or header.complete:
                return header
        return header

    # Per credential, as resolve() is: a gated file an anonymous probe could not read is not missing.
    token_id = hashlib.sha256(hf_token.encode()).hexdigest()[:16] if hf_token else ""
    return _cached_header(("remote", repo_id.lower(), filename, size, token_id), compute)


@dataclass(frozen = True)
class RepoFile:
    path: str
    size: int = 0
    # The Hub listing's LFS sha256, when known; not part of equality.
    sha256: str = field(default = "", compare = False)


def hub_offline() -> bool:
    return os.environ.get("HF_HUB_OFFLINE", "").strip().lower() in ("1", "true", "yes", "on")


def _hub_cache() -> Path:
    from utils.hf_cache_settings import active_hf_hub_cache
    return Path(active_hf_hub_cache())


def snapshot_dirs(repo_id: str, hub_cache: Optional[Path] = None) -> list[Path]:
    """Cached snapshots of ``repo_id``: ``refs/main`` first, then newest."""
    root = hub_cache if hub_cache is not None else _hub_cache()
    repo_dir = root / ("models--" + repo_id.replace("/", "--"))
    try:
        candidates = [p for p in (repo_dir / "snapshots").iterdir() if p.is_dir()]
    except OSError:
        if hub_cache is not None:
            return []
        # A cached repo whose casing differs from the request.
        try:
            wanted = repo_dir.name.lower()
            match = next((p for p in root.iterdir() if p.name.lower() == wanted), None)
        except OSError:
            match = None
        if match is None:
            return []
        return snapshot_dirs(match.name[len("models--") :].replace("--", "/"), root)
    try:
        main_sha = (repo_dir / "refs" / "main").read_text(encoding = "utf-8").strip()
    except OSError:
        main_sha = ""

    def order(p: Path) -> tuple[int, float]:
        try:
            mtime = p.stat().st_mtime
        except OSError:
            mtime = 0.0
        return (0 if p.name == main_sha else 1, -mtime)

    return sorted(candidates, key = order)


def _cached_listing(repo_id: str, folder: str) -> list[RepoFile]:
    """Every file under ``folder`` in any cached snapshot, from disk."""
    seen: dict[str, RepoFile] = {}
    for snapshot in snapshot_dirs(repo_id):
        base = snapshot / folder if folder else snapshot
        if not base.is_dir():
            continue
        for dirpath, _dirs, files in os.walk(base):
            for name in files:
                full = Path(dirpath) / name
                rel = full.relative_to(snapshot).as_posix()
                if rel in seen:
                    continue
                try:
                    size = full.stat().st_size
                except OSError:
                    continue
                seen[rel] = RepoFile(rel, size)
    return sorted(seen.values(), key = lambda f: f.path)


def _hub_listing(repo_id: str, folder: str, hf_token: Optional[str]) -> list[RepoFile]:
    from huggingface_hub import HfApi

    api = HfApi(token = hf_token or None)
    entries = api.list_repo_tree(
        repo_id, path_in_repo = folder or None, recursive = True, repo_type = "model"
    )
    out = []
    for entry in entries:
        size = getattr(entry, "size", None)
        if size is None:  # a folder
            continue
        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)


_listing_cache: dict[tuple, tuple[float, list[RepoFile], bool]] = {}
_listing_lock = threading.Lock()
_LISTING_TTL_SECONDS = 300.0


def list_files(
    repo_id: str,
    folder: str = "",
    hf_token: Optional[str] = None,
    *,
    network: bool = True,
) -> tuple[list[RepoFile], bool]:
    """``(files, from_hub)`` under ``folder``: the Hub listing, else the cached copy."""
    from hub.utils.hf_tokens import normalize_token

    token = normalize_token(hf_token) if hf_token is not False else None
    use_hub = network and not hub_offline()
    key = (repo_id.lower(), folder.lower(), hashlib.sha1(str(token).encode()).hexdigest()[:8])
    if use_hub:
        with _listing_lock:
            hit = _listing_cache.get(key)
        if hit is not None and time.monotonic() - hit[0] < _LISTING_TTL_SECONDS:
            return list(hit[1]), hit[2]
        try:
            files = _hub_listing(repo_id, folder, token)
            with _listing_lock:
                _listing_cache[key] = (time.monotonic(), files, True)
            return list(files), True
        except Exception as exc:  # noqa: BLE001 - offline, refused or gone: the cache may still hold it
            logger.debug("audio.cpp: Hub listing of %s/%s failed: %s", repo_id, folder, exc)
    return _cached_listing(repo_id, folder), False


_QUANT_RE = re.compile(
    r"(?:^|[-_.])((?:[it]?q\d(?:_[a-z0-9]+)*)|bf16|f16|f32|fp16|fp32|orig)(?=$|[-_.])",
    re.IGNORECASE,
)
# Ternary TQ2_1 (GGUF type 44) has only a CPU kernel; CUDA aborts on it (kitten_tts2 docs).
CPU_ONLY_QUANTS = frozenset(("TQ2_1",))
# K and IQ quants come after F32 so the established order stays as it was.
_QUANT_PREFERENCE = (
    *("Q8_0", "F16", "BF16", "ORIG", "Q6_K", "Q5_K_M", "Q4_K_M", "Q4_0", "F32"),
    *("Q5_K", "Q5_K_S", "Q4_K", "Q4_K_S", "IQ4_NL", "IQ4_XS", "Q3_K_L", "Q3_K_M", "Q3_K"),
    *("Q3_K_S", "IQ3_M", "IQ3_S", "IQ3_XS", "IQ3_XXS", "Q2_K", "IQ2_M", "IQ2_XS", "IQ2_XXS"),
)
_PREFERRED_SCOPES = ("turbo", "english", "tiny")
_SKIP_FILE_RE = re.compile(
    r"(^|/)(readme[^/]*|license[^/]*|\.gitattributes|[^/]*\.(md|mp4|mp3|wav|png|jpe?g|gif))$", re.I
)
# q4-ios stores a rank-3 ConvTranspose weight as 2-D Q4_K: "quantized tensor byte size mismatch".
_UNLOADABLE_FILES = {
    "vibevoice-1.5b-q4-ios.gguf": "This VibeVoice Q4 build cannot be loaded by audio.cpp. "
    "Use the Q8_0 or BF16 variant.",
}


def _unloadable_reason(path: str) -> Optional[str]:
    return _UNLOADABLE_FILES.get(Path(path).name.lower())


def _is_quant(word: str) -> bool:
    """Whether ``word`` is a quant label (``Q8_0``, ``BF16``, ``orig``) rather than a name."""
    return bool(_QUANT_RE.fullmatch(f"-{word}"))


def quant_label(filename: str) -> str:
    """``kokoro-82m-q8_0.gguf`` -> ``Q8_0``; the stem's last word when no quant is named."""
    stem = Path(filename).name
    if stem.lower().endswith(".gguf"):
        stem = stem[: -len(".gguf")]
    matches = list(_QUANT_RE.finditer(stem))
    if matches:
        token = matches[-1].group(1)
        # "orig" (unquantized as published) is a word, not a quant token.
        return token.lower() if token.lower() == "orig" else token.upper()
    return re.split(r"[-_.]", stem)[-1].upper() or stem.upper()


@dataclass(frozen = True)
class AudioCppVariant:
    key: str
    files: tuple[RepoFile, ...]
    # Repo path the server opens; empty for a package, which loads as a directory.
    primary: str
    session_options: dict = field(default_factory = dict, hash = False, compare = False)
    label: Optional[str] = None

    @property
    def size_bytes(self) -> int:
        return sum(f.size for f in self.files)

    @property
    def main_file(self) -> str:
        """The GGUF that stands for this variant in listings."""
        if self.primary:
            return self.primary
        ggufs = [f for f in self.files if f.path.lower().endswith(".gguf")]
        return max(ggufs, key = lambda f: f.size).path if ggufs else self.files[0].path


def _single_file_variants(
    files: Sequence[RepoFile],
    folder: str,
    *,
    unloadable: bool = False,
) -> list[AudioCppVariant]:
    prefix = f"{folder}/" if folder else ""
    ggufs = [
        f
        for f in files
        if f.path.lower().endswith(".gguf")
        and "mmproj" not in f.path.lower()
        and "imatrix" not in f.path.lower()
        and (unloadable or _unloadable_reason(f.path) is None)
    ]
    rows = []
    for gguf in ggufs:
        rel = gguf.path[len(prefix) :] if gguf.path.startswith(prefix) else gguf.path
        sub = rel.rpartition("/")[0]
        rows.append((gguf, sub, quant_label(rel)))
    # Several models at one quant in one place (Moonshine tiny/small/medium): key each by its distinct words.
    seen: set[tuple[str, str]] = set()
    crowded: set[str] = set()
    for _gguf, sub, quant in rows:
        if (sub, quant.lower()) in seen:
            crowded.add(sub)
        seen.add((sub, quant.lower()))
    models = {sub: {_model_stem(g.path) for g, s, _q in rows if s == sub} for sub in crowded}
    variants = []
    for gguf, sub, quant in rows:
        key = f"{sub}/{quant}" if sub else quant
        label = None
        if sub in crowded:
            scope = _distinct_part(_model_stem(gguf.path), models[sub])
            key = f"{sub}/{scope}/{quant}" if sub else f"{scope}/{quant}"
            label = f"{quant} · {scope}"
        elif sub:
            label = f"{quant} · {sub}"
        gguf_dir = gguf.path.rpartition("/")[0]
        # Voices and other extras audio.cpp reads beside the GGUF (PocketTTS's embeddings/*.safetensors).
        extras = tuple(
            f
            for f in files
            if f.path.startswith(f"{gguf_dir}/embeddings/" if gguf_dir else "embeddings/")
        )
        variants.append(AudioCppVariant(key, (gguf, *extras), gguf.path, label = label))
    return variants


def _model_stem(path: str) -> str:
    """A GGUF's file name without its quant: ``irodori-tts-v4.1-anime-q8_0.gguf`` -> ``irodori-tts-v4.1-anime``."""
    stem = Path(path).name[: -len(".gguf")]
    matches = list(_QUANT_RE.finditer(stem))
    if not matches:
        return stem
    last = matches[-1]
    return (stem[: last.start()] + stem[last.end() :]).strip("-_.") or stem


def _distinct_part(stem: str, stems: Sequence[str]) -> str:
    """The words of ``stem`` its siblings do not share: ``moonshine-streaming-tiny`` among
    ``...-small`` gives ``tiny``. Dots stay inside a word (``v4.1``). The whole stem when nothing is left."""
    split = [re.split(r"[-_]", s) for s in stems]
    words = re.split(r"[-_]", stem)
    head = 0
    while all(len(w) > head for w in split) and len({w[head].lower() for w in split}) == 1:
        head += 1
    tail = 0
    while (
        all(len(w) > head + tail for w in split) and len({w[-1 - tail].lower() for w in split}) == 1
    ):
        tail += 1
    middle = words[head : len(words) - tail]
    return "-".join(middle) or stem


def _package_variants(
    policy: AudioCppFamily, files: Sequence[RepoFile], folder: str
) -> list[AudioCppVariant]:
    prefix = f"{folder}/" if folder else ""
    by_path = {f.path: f for f in files}
    variants = []
    for package in policy.package:
        found = [by_path.get(prefix + rel) for rel in package.files]
        if any(f is None for f in found):
            continue
        variants.append(
            AudioCppVariant(
                package.key, tuple(found), "", session_options = dict(package.session_options)
            )
        )
    return variants


def _variant_rank(variant: AudioCppVariant) -> tuple:
    sub = variant.key.rpartition("/")[0].lower()
    scope_rank = (
        0 if not sub else (1 + _PREFERRED_SCOPES.index(sub) if sub in _PREFERRED_SCOPES else 10)
    )
    # Q8_0_V2 is a Q8_0 re-export and FP32 is F32 under another name.
    quant = re.sub(r"_V\d+$", "", quant_label(variant.main_file))
    quant = {"FP32": "F32", "FP16": "F16"}.get(quant, quant)
    quant_rank = (
        _QUANT_PREFERENCE.index(quant) if quant in _QUANT_PREFERENCE else len(_QUANT_PREFERENCE)
    )
    stem = Path(variant.main_file).name.lower()
    stem_rank = min(
        (i for i, word in enumerate(_PREFERRED_SCOPES) if word in stem),
        default = len(_PREFERRED_SCOPES),
    )
    return (scope_rank, stem_rank, quant_rank, variant.key.lower())


def match_variant(
    variants: Sequence[AudioCppVariant],
    wanted: Optional[str],
    folder: str = "",
) -> Optional[AudioCppVariant]:
    """match a key, file, or quant; shared quants use default order; row folders are not scopes."""
    text = (wanted or "").strip().replace("\\", "/")
    if not text:
        return None
    low = text.lower()
    for variant in variants:
        if variant.key.lower() == low:
            return variant
    mains = [(variant, variant.main_file.replace("\\", "/").lower()) for variant in variants]
    for variant, main in mains:
        if main == low:
            return variant
    for variant, main in mains:
        if main.endswith(f"/{low}") or main.rsplit("/", 1)[-1] in (low, f"{low}.gguf"):
            return variant
    quant = low.rsplit("/", 1)[-1]
    matches = [
        v
        for v in variants
        if quant_label(v.main_file).lower() == quant
        and ("/" not in low or v.key.lower().endswith(low))
    ]
    if matches:
        return sorted(matches, key = _variant_rank)[0]
    # support legacy requests that name only a subfolder, such as PocketTTS-GGUF/english.
    scoped = [v for v in variants if v.key.lower().startswith(low + "/")]
    if scoped:
        return sorted(scoped, key = _variant_rank)[0]
    return _match_by_words(variants, low, folder)


def _match_by_words(
    variants: Sequence[AudioCppVariant],
    low: str,
    folder: str = "",
) -> Optional[AudioCppVariant]:
    """Matches the key's words against the file, so bare Q8_0 and the listing's tiny/Q8_0 both load it."""
    parts = [part for part in low.split("/") if part]
    if not parts:
        return None
    quant = parts[-1] if _is_quant(parts[-1]) else None
    scopes = parts[:-1] if quant else parts
    if not scopes:
        return None

    prefix = f"{folder}/".lower() if folder else ""

    def named(path: str, scope: str) -> bool:
        # Scope words run together below the row's folder: ``multilingual-ctc`` is not ``multilingual-large-ctc``,
        # and ``Irodori-TTS-v4-Small-GGUF`` does not make every file in it ``v4-small``.
        path = path.lower()
        path = path[len(prefix) :] if prefix and path.startswith(prefix) else path
        words = "-".join(re.split(r"[-_./]", path))
        return f"-{'-'.join(re.split(r'[-_.]', scope))}-" in f"-{words}-"

    matches = [
        v
        for v in variants
        if all(named(v.main_file, scope) for scope in scopes)
        and (quant is None or quant_label(v.main_file).lower() == quant)
    ]
    return sorted(matches, key = _variant_rank)[0] if matches else None


_STUDIO_DRIVEN_OPTIONS = frozenset(
    {
        "input",
        "text",
        "language",
        "seed",
        "instruct",
        "instruction",
        "instructions",
        "reference_text",
        "voice_ref",
        "phonemes",
        "return_timestamps",
        "stop_after",
        "export_semantic",
        "abc",
        # A JSON array of codec indices: a debugging hook, not a setting.
        "semantic_prefix",
    }
)
# The music form fills these from its lyrics, description and duration fields.
_MUSIC_DRIVEN_OPTIONS = frozenset(
    {
        "lyrics",
        "style",
        "caption",
        "prompt",
        "tags",
        "duration",
        "duration_sec",
        "duration_seconds",
        "route",
        "task_route",
        "repainting_start",
        "repainting_end",
        "repaint_mode",
        "repaint_strength",
        "audio_cover_strength",
        "cover_noise_strength",
        "init_noise_level",
        "inpaint_mask_start_seconds",
        "inpaint_mask_end_seconds",
        "inpaint_start",
        "inpaint_end",
        "audio_input_kind",
        "batch_size",
        "semantic_max_tokens",
        "semantic_min_tokens",
    }
)
CONVERT_DRIVEN_OPTIONS = frozenset(
    {
        "voice_id",
        "semitone_shift",
        "auto_f0_adjust",
        "use_pitch_shift",
        "source_shift_steps",
        "prosody_shift_steps",
        "target_text",
        "style_ref_text",
    }
)
_RENDERABLE_TYPES = frozenset({"bool", "int", "float", "string", "enum"})
_MAX_STRING_OPTION = 4000


def runtime_spec(family: str) -> Optional[dict]:
    """``model_specs/<family>.json`` of the installed runtime, the spec the binary was built with."""
    if not family or not re.fullmatch(r"[a-z0-9_]+", family):
        return None
    try:
        from core.inference.audio_cpp_server import find_audio_cpp_server_binary
        binary = find_audio_cpp_server_binary()
    except Exception:  # noqa: BLE001 - no runtime, no runtime spec
        return None
    if not binary:
        return None
    for parent in list(Path(binary).resolve().parents)[:3]:
        path = parent / "model_specs" / f"{family}.json"
        try:
            with open(path, "r", encoding = "utf-8") as f:
                data = json.load(f)
            return data if isinstance(data, dict) else None
        except (OSError, ValueError):
            continue
    return None


def runtime_knows_family(family: str) -> Optional[bool]:
    """Whether the installed runtime loads ``family``; None when Unsloth Studio cannot tell.

    The install fetches ``model_specs/`` from the release's source commit and puts it beside the
    server. With that folder, a family is known exactly when it has a spec file there. No folder
    (a custom build, or a fetch that failed) means unknown, and the spec's own tasks decide.
    """
    if not family or not re.fullmatch(r"[a-z0-9_]+", family):
        return None
    try:
        from core.inference.audio_cpp_server import find_audio_cpp_server_binary
        binary = find_audio_cpp_server_binary()
    except Exception:  # noqa: BLE001 - no runtime, no answer
        return None
    if not binary:
        return None
    if runtime_spec(family) is not None:
        return True
    try:
        parents = list(Path(binary).resolve().parents)[:3]
        if any((parent / "model_specs").is_dir() for parent in parents):
            return False
    except (OSError, ValueError):
        return None
    return None


def _clean_option(raw: Any) -> Optional[dict]:
    if not isinstance(raw, dict):
        return None
    name = str(raw.get("name") or "").strip()
    kind = str(raw.get("type") or "").strip().lower()
    if not name or "." in name or kind not in _RENDERABLE_TYPES:
        return None
    if name in _STUDIO_DRIVEN_OPTIONS or name.endswith(("_file", "_path", "_dir")):
        return None
    option: dict[str, Any] = {
        "name": name,
        "type": kind,
        "description": str(raw.get("description") or ""),
        "required": bool(raw.get("required", False)),
        "default": raw.get("default"),
        "min": raw.get("min"),
        "max": raw.get("max"),
        "values": None,
    }
    if kind == "enum":
        values = raw.get("values")
        if not isinstance(values, list) or not values:
            # A shared domain the spec names instead of listing (text_chunk_mode_full).
            values = list(ENUM_PRESETS.get(str(raw.get("preset") or ""), ()))
        # One choice is no choice.
        if len(values) < 2:
            return None
        option["values"] = [str(v) for v in values]
    for bound in ("min", "max"):
        if not isinstance(option[bound], (int, float)) or isinstance(option[bound], bool):
            option[bound] = None
    if kind in ("int", "float") and (
        isinstance(option["default"], bool) or not isinstance(option["default"], (int, float))
    ):
        option["default"] = None
    if kind == "bool" and not isinstance(option["default"], bool):
        option["default"] = None
    if kind in ("string", "enum") and option["default"] is not None:
        option["default"] = str(option["default"])
    return option


def option_schema(
    policy: AudioCppFamily, spec: Optional[dict], embedded: Optional[dict]
) -> tuple[dict, ...]:
    """MiniMax Music 3 and YuE2 show a Studio-side list: their specs carry dozens of knobs and the published GGUFs embed a stale copy"""
    if policy.task == "sep":
        return ()
    if policy.options:
        source = {"options": {"request": list(policy.options)}}
    else:
        source = spec
        if source is None or not ((source.get("options") or {}).get("request")):
            source = embedded
        if not ((source or {}).get("options") or {}).get("request"):
            # A legacy spec declares none, though the loader reads some.
            listed = STUDIO_OPTION_LISTS.get(policy.family)
            if listed:
                source = {"options": {"request": list(listed)}, "ui": (source or {}).get("ui")}
    raw = ((source or {}).get("options") or {}).get("request") or []
    driven = _MUSIC_DRIVEN_OPTIONS if policy.task == "music" else frozenset()
    if policy.convert is not None:
        driven = driven | frozenset(policy.convert.hidden_options)
    # A renamed option shows once, under the legacy name every runtime reads.
    legacy = {canonical: old for old, canonical in OPTION_RENAMES.get(policy.family, ())}
    out = []
    names = set()
    for item in raw:
        option = _clean_option(item)
        if option is not None and option["name"] in legacy:
            option["name"] = legacy[option["name"]]
        if option is None or option["name"] in driven or option["name"] in names:
            continue
        if option["name"] == "voice":
            continue
        if policy.task == "tts" and _is_alias_or_json_row(option):
            continue
        names.add(option["name"])
        out.append(option)
    if policy.task == "tts" and policy.default_server_task != "vdes":
        ui = (source or {}).get("ui") or (spec or {}).get("ui") or (embedded or {}).get("ui") or {}
        voices = (ui.get("builtin_voices") if isinstance(ui, dict) else None) or list(policy.voices)
        # One voice is no choice: the request's own default speaks it.
        if isinstance(voices, list) and len(voices) > 1 and all(isinstance(v, str) for v in voices):
            default = policy.request_defaults.get("voice") or ui.get("default_voice")
            out.insert(
                0,
                {
                    "name": "voice",
                    "type": "enum",
                    "description": "Built-in speaker.",
                    "required": False,
                    "default": str(default) if default in voices else None,
                    "min": None,
                    "max": None,
                    "values": list(voices),
                },
            )
            # The built-in voice row is the one voice control; the server reads it for these too.
            out = [o for o in out if o["name"] not in ("voice_id", "speaker")]
    return tuple(out)


def _is_alias_or_json_row(option: dict) -> bool:
    """A spec row that repeats another under a second name, or wants raw JSON typed in."""
    description = option.get("description") or ""
    return description.startswith("Alias of") or (
        option["type"] == "string" and re.search(r"\bJSON\b", description) is not None
    )


def validate_options(schema: Sequence[dict], values: Optional[dict]) -> dict:
    """``values`` checked against ``schema``: unknown names and values of the wrong kind are dropped,
    numbers are clamped to their bounds."""
    if not isinstance(values, dict):
        return {}
    by_name = {o["name"]: o for o in schema}
    out: dict[str, Any] = {}
    for name, value in values.items():
        option = by_name.get(str(name))
        if option is None or value is None:
            continue
        kind = option["type"]
        try:
            if kind == "bool":
                if isinstance(value, str):
                    if value.strip().lower() not in ("true", "false", "1", "0"):
                        continue
                    value = value.strip().lower() in ("true", "1")
                elif not isinstance(value, (bool, int)):
                    continue
                out[name] = bool(value)
            elif kind in ("int", "float"):
                if isinstance(value, bool):
                    continue
                number = float(value)
                if number != number or number in (float("inf"), float("-inf")):
                    continue
                if option.get("min") is not None:
                    number = max(float(option["min"]), number)
                if option.get("max") is not None:
                    number = min(float(option["max"]), number)
                out[name] = int(round(number)) if kind == "int" else number
            elif kind == "enum":
                if str(value) in (option.get("values") or []):
                    out[name] = str(value)
            elif kind == "string":
                text = str(value)
                if text.strip():
                    out[name] = text[:_MAX_STRING_OPTION]
        except (TypeError, ValueError):
            continue
    return out


@dataclass(frozen = True)
class AudioCppModel:
    """One loadable audio.cpp model: a repo (or folder, or local file) at one variant."""

    id: str
    repo_id: Optional[str]
    folder: str
    display_name: str
    family: str
    task: str
    server_task: str
    variant: AudioCppVariant
    variants: tuple[AudioCppVariant, ...]
    default_variant: str
    needs_espeak: bool = False
    request_defaults: dict = field(default_factory = dict, hash = False, compare = False)
    model_options: dict = field(default_factory = dict, hash = False, compare = False)
    options: tuple[dict, ...] = field(default = (), hash = False, compare = False)
    # ``options`` before the family's OPTION_RULES, so a variant change re-applies them from scratch.
    spec_options: tuple[dict, ...] = field(default = (), hash = False, compare = False)
    # Option names each workflow ("*" = all) leaves out, from the rules.
    option_hidden: dict = field(default_factory = dict, hash = False, compare = False)
    unsupported: Optional[str] = None
    local_path: Optional[str] = None
    tags: tuple[str, ...] = ()
    speaks: bool = True
    clone: Optional[CloneSpec] = None
    companions: tuple[CompanionModel, ...] = ()
    required_inputs: tuple[str, ...] = ()
    edit: Optional[EditSpec] = None
    convert: Optional[ConvertSpec] = None
    separation: Optional[SeparationSpec] = None
    music: Optional[MusicSpec] = field(default = None, hash = False, compare = False)
    # A strict spec (``schema_version``) makes the runtime refuse any undeclared option.
    request_keys: Optional[frozenset[str]] = field(default = None, hash = False, compare = False)
    from_hub: bool = field(default = False, hash = False, compare = False)
    # Listed files audio.cpp cannot load: never in ``variants``, still the cache's to delete.
    unloadable: tuple[AudioCppVariant, ...] = ()

    def __post_init__(self) -> None:
        if not self.spec_options and self.options:
            object.__setattr__(self, "spec_options", tuple(self.options))

    @property
    def cache_variants(self) -> tuple[AudioCppVariant, ...]:
        return self.variants + self.unloadable

    @property
    def is_package(self) -> bool:
        return not self.variant.primary

    @property
    def files(self) -> tuple[str, ...]:
        return tuple(f.path for f in self.variant.files)

    @property
    def gguf_file(self) -> str:
        return self.variant.main_file

    @property
    def size_bytes(self) -> int:
        return self.variant.size_bytes

    @property
    def cpu_only(self) -> bool:
        """The variant's weights have no GPU kernel in audio.cpp, so it runs on the CPU backend."""
        return quant_label(self.gguf_file) in CPU_ONLY_QUANTS

    @property
    def audio_type(self) -> Optional[str]:
        return audio_type_for_task(self.task)

    @property
    def hub_task(self) -> Optional[str]:
        return HUB_TASKS.get(self.task)

    @property
    def workflows(self) -> dict[str, WorkflowBinding]:
        return _bindings_for(self.task, self.server_task, self)

    @property
    def clone_options(self) -> tuple[dict, ...]:
        """Spec options plus the clone tool options the spec omits."""
        if self.clone is None or not self.clone.tool_options:
            return self.options
        names = {o["name"] for o in self.options}
        return (*self.options, *(o for o in self.clone.tool_options if o["name"] not in names))

    @property
    def convert_options(self) -> tuple[dict, ...]:
        if self.convert is None:
            return ()
        own = tuple(o for o in self.options if o["name"] not in CONVERT_DRIVEN_OPTIONS)
        names = {o["name"] for o in own}
        return (*own, *(o for o in self.convert.tool_options if o["name"] not in names))

    @property
    def key(self) -> str:
        """A short name, unique per model and variant, for the link farm."""
        stem = re.sub(r"[^a-z0-9]+", "-", self.display_name.lower()).strip("-")[:24] or "model"
        digest = hashlib.sha1(f"{self.id.lower()}@{self.variant.key.lower()}".encode()).hexdigest()
        return f"{stem}-{digest[:8]}"

    @property
    def canonical_id(self) -> str:
        """``id:variant``: what dictation records, so a reload picks the same files."""
        return f"{self.id}:{self.variant.key}"

    def with_variant(self, variant: AudioCppVariant) -> "AudioCppModel":
        model_options = dict(self.model_options)
        if variant.session_options:
            model_options["session_options"] = {
                **dict(model_options.get("session_options") or {}),
                **variant.session_options,
            }
        changes = _ace_step_variant(self, variant) if self.family == "ace_step" else {}
        model = replace(self, variant = variant, model_options = model_options, **changes)
        options, hidden = apply_option_rules(
            model.family, _rule_text(model), model.spec_options, Path(variant.primary).name
        )
        return replace(model, options = options, option_hidden = hidden)


def _rule_text(model: "AudioCppModel") -> str:
    """What an OptionRule ``match`` is searched in: repo id, folder, variant key and file names."""
    return " ".join((model.id, model.folder, model.variant.key, *model.files)).lower()


def apply_option_rules(
    family: str,
    text: str,
    options: Sequence[dict],
    served: str = "",
) -> tuple[tuple[dict, ...], dict[str, frozenset[str]]]:
    """``options`` with the family's matching rules applied, and the names each workflow hides."""
    rules = rules_for(family, text, served)
    out = [dict(o) for o in options]
    hidden: dict[str, frozenset[str]] = {}
    for rule in rules:
        names = {o["name"] for o in out}
        for raw in rule.extra:
            option = _clean_option(raw)
            if option is not None and option["name"] not in names:
                names.add(option["name"])
                out.append(option)
        for option in out:
            _apply_rule(rule, option)
        for workflow, names_hidden in rule.hidden.items():
            hidden[workflow] = hidden.get(workflow, frozenset()) | frozenset(names_hidden)
    for option in out:
        # A default outside the (possibly narrowed) domain is no default.
        if option.get("default") is not None and not validate_options(
            (option,), {option["name"]: option["default"]}
        ):
            option["default"] = None
    return tuple(out), hidden


def _apply_rule(rule: OptionRule, option: dict) -> None:
    name = option["name"]
    if name in rule.bounds:
        low, high = rule.bounds[name]
        if low is not None:
            option["min"] = low
        if high is not None:
            option["max"] = high
    if name in rule.values and option["type"] == "enum":
        option["values"] = [v for v in rule.values[name] if v in (option.get("values") or [])]
    if name in rule.defaults:
        option["default"] = rule.defaults[name]
    if option["type"] in ("int", "float") and option.get("default") is not None:
        number = float(option["default"])
        if option.get("min") is not None:
            number = max(float(option["min"]), number)
        if option.get("max") is not None:
            number = min(float(option["max"]), number)
        option["default"] = int(round(number)) if option["type"] == "int" else number


def filled_options(model: "AudioCppModel", workflow: str, values: Optional[dict]) -> dict:
    """``values`` over the model's recommended defaults; tool panels send their own 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),
        _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 takes_seed(model: "AudioCppModel", workflow: str) -> bool:
    """Speak, Clone and Music take a seed unless a strict spec leaves it out."""
    return workflow in ("speak", "clone", "music") and (
        model.request_keys is None or "seed" in model.request_keys
    )


def ignored_options(model: "AudioCppModel", workflow: str, values: Optional[dict]) -> list[str]:
    """User-sent option names the request will not carry: not offered for ``workflow``, or left out
    of a strict spec. ``voice`` travels top level and ``seed`` is the caller's to check. A renamed
    option is judged under its legacy name, as ``filled_options`` sends it."""
    if not isinstance(values, dict):
        return []
    offered = {o["name"] for o in workflow_options(model, workflow)}
    pairs = OPTION_RENAMES.get(model.family, ())
    legacy = {canonical: old for old, canonical in pairs}
    keys = model.request_keys
    if pairs and keys is not None:
        keys = keys | {old for old, canonical in pairs if canonical in keys}

    def dropped(name: str) -> bool:
        name = legacy.get(name, name)
        return name not in offered or (keys is not None and name not in keys)

    return sorted(
        name for name in map(str, values) if name not in ("seed", "voice") and dropped(name)
    )


_SEED_OPTION = dict(
    name = "seed",
    type = "int",
    required = False,
    default = None,
    min = 0,
    max = 2147483647,
    values = None,
    description = "The model default gives each take a new random seed. Reuse one from a clip's menu.",
)


def workflow_options(model: "AudioCppModel", workflow: str) -> tuple[dict, ...]:
    """The options ``workflow`` shows and accepts; only Speak offers a built-in voice."""
    if workflow == "convert":
        options = model.convert_options
    elif workflow == "clone":
        options = model.clone_options
    elif workflow == "edit":
        claims = set(model.edit.claims) if model.edit is not None else set()
        options = tuple(o for o in model.options if o["name"] not in claims)
    else:
        options = model.options
    hidden = set(model.option_hidden.get("*", ())) | set(model.option_hidden.get(workflow, ()))
    if workflow in ("clone", "edit", "convert"):
        hidden.add("voice")
    shown = tuple(o for o in options if o["name"] not in hidden)
    return (*shown, dict(_SEED_OPTION)) if takes_seed(model, workflow) else shown


def request_options(
    schema: Sequence[dict],
    values: Optional[dict],
    request_keys: Optional[frozenset[str]] = None,
    fill: Optional[Iterable[str]] = None,
) -> dict:
    """Defaults for fill names (never voice; request_keys only when strict), under user values."""
    fill = None if fill is None else frozenset(fill)
    defaults = {
        o["name"]: o["default"]
        for o in schema
        if o.get("default") is not None
        and o["name"] != "voice"
        and (fill is None or o["name"] in fill)
        and (request_keys is None or o["name"] in request_keys)
    }
    return {**validate_options(schema, defaults), **validate_options(schema, values)}


def _ace_step_variant(model: "AudioCppModel", variant: AudioCppVariant) -> dict[str, Any]:
    """Base takes the "complete" task and turbo does not (ACE-Step-1.5 acestep/constants.py
    TASK_TYPES_TURBO vs TASK_TYPES_BASE)."""
    base = bool(re.search(ACE_STEP_BASE_NAME, Path(variant.primary).name, re.IGNORECASE))
    music = model.music
    if music is not None:
        modes = []
        for m in music.modes:
            if m.id == "edit":
                actions = tuple(a for a in m.actions if a != "continue")
                m = replace(m, actions = (*actions, "continue") if base else actions)
            modes.append(m)
        music = replace(music, modes = tuple(modes))
    return {"music": music}


class AudioCppModelError(ValueError):
    """The id names an audio.cpp model Studio cannot run (task, package or variant)."""


def _names_for(ref: AudioCppRef, files: Sequence[RepoFile]) -> tuple[str, ...]:
    return (
        ref.id,
        ref.folder,
        *(Path(f.path).name for f in files if f.path.lower().endswith(".gguf")),
    )


_TAG_FAMILY_RE = re.compile(r"^[a-z0-9_]+$")


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. A digit right after a name that ends in a letter is
        # another family (kitten-tts2); after a digit it is a stripped version dot (IndexTTS2.5).
        pattern = re.escape(family).replace("_", "[-_]?")
        if not family[-1].isdigit():
            pattern += r"(?![0-9])"
        if re.search(pattern, text):
            return family
    hints = (
        (r"minimax[-_]?music[-_]?3", "minimax_music3"),
        (r"yue[-_]?2", "yue2"),
        (r"moonshine", "moonshine_asr"),
        (r"qwen3[-_]?asr", "qwen3_asr"),
        (r"qwen3[-_]?tts", "qwen3_tts"),
        (r"parakeet", "parakeet_tdt"),
        (r"canary", "canary_asr"),
        (r"nemotron.*asr", "nemotron_asr"),
        (r"pocket[-_]?tts", "pocket_tts"),
        (r"kokoro", "kokoro_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"),
        # 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):
            return family
    return None


def _probe_header(
    ref: AudioCppRef, candidates: Sequence[RepoFile], hf_token: Optional[str], network: bool
) -> Optional[AudioCppHeader]:
    """The first header among ``candidates`` that names a family, else the first one read."""
    first = None
    local_first: list[tuple[RepoFile, Optional[Path]]] = []
    for f in candidates:
        local = None
        if ref.local_path:
            local = Path(ref.local_path)
        elif ref.repo_id:
            for snapshot in snapshot_dirs(ref.repo_id):
                path = snapshot / f.path
                if path.is_file():
                    local = path
                    break
        local_first.append((f, local))
    local_first.sort(key = lambda item: item[1] is None)
    for f, local in local_first[:4]:
        header = None
        if local is not None:
            header = read_local_header(local)
        elif network and not hub_offline() and ref.repo_id:
            header = read_remote_header(ref.repo_id, f.path, hf_token, size = f.size or None)
        if header is None:
            continue
        header = replace(header, source = f.path)
        if not header.is_audio_cpp:
            return header
        if header.family:
            return header
        first = first or header
    return first


_resolve_cache: dict[tuple, tuple[float, Optional["AudioCppModel"]]] = {}
_resolve_lock = threading.Lock()
_RESOLVE_TTL_SECONDS = 300.0
_known_audio_cpp_ids: set[str] = set()


def looks_like_audio_cpp(identifier: Optional[str]) -> bool:
    """An umbrella row, a legacy key, or an id this process already resolved as audio.cpp. No I/O."""
    if is_umbrella_id(identifier):
        return True
    base, _variant = split_variant_ref(str(identifier or ""))
    return base.lower() in _known_audio_cpp_ids


def resolve(
    identifier: Optional[str],
    variant: Optional[str] = None,
    hf_token: Optional[str] = None,
    *,
    network: bool = True,
    tags: Sequence[str] = (),
    gguf_hint: Optional[str] = None,
) -> Optional[AudioCppModel]:
    """None for a non-audio.cpp identifier; unrunnable models still resolve, marked unsupported; network=False reads only the HF cache"""
    if identifier is None:
        return None
    base, ref_variant = split_variant_ref(str(identifier))
    ref = parse_identifier(base)
    if ref is None:
        return None
    wanted = variant or ref_variant or ref.variant_hint
    # Per credential: a gated repo one caller cannot list must not read as missing for another.
    token_id = hashlib.sha256(hf_token.encode()).hexdigest()[:16] if hf_token else ""
    key = (
        ref.id.lower(),
        (wanted or "").lower(),
        bool(network),
        token_id,
        tuple(tags),
        gguf_hint or "",
    )
    with _resolve_lock:
        hit = _resolve_cache.get(key)
        generation = _forget_generation
    if hit is not None and time.monotonic() - hit[0] < (_RESOLVE_TTL_SECONDS if network else 20.0):
        return hit[1]
    if gguf_hint and ref.repo_id and not is_umbrella_id(ref.id):
        header = _probe_header(ref, [RepoFile(gguf_hint)], hf_token, network)
        if header is not None and not header.is_audio_cpp:
            with _resolve_lock:
                _resolve_cache[key] = (time.monotonic(), None)
            return None
    model = _resolve_uncached(ref, wanted, hf_token, network, tuple(tags))
    with _resolve_lock:
        if len(_resolve_cache) > 256:
            _resolve_cache.clear()
        if generation == _forget_generation:
            _resolve_cache[key] = (time.monotonic(), model)
        if model is not None:
            _known_audio_cpp_ids.add(model.id.lower())
    return model


def forget(identifier: Optional[str] = None) -> None:
    """Drop memoized resolutions (after a download or delete changed the cache)."""
    global _forget_generation
    with _resolve_lock:
        # A lookup already reading the old cache must not store its answer after this.
        _forget_generation += 1
        # What is downloaded changed too, so the next status poll must not reuse the old listing.
        _downloaded_cache.clear()
        if identifier is None:
            _resolve_cache.clear()
            return
        low = split_variant_ref(str(identifier))[0].lower()
        for key in [k for k in _resolve_cache if k[0] == low]:
            _resolve_cache.pop(key, None)


def _resolve_uncached(
    ref: AudioCppRef,
    wanted: Optional[str],
    hf_token: Optional[str],
    network: bool,
    tags: tuple[str, ...],
) -> Optional[AudioCppModel]:
    from_hub = False
    if ref.local_path:
        files = [RepoFile(Path(ref.local_path).name, _size(ref.local_path))]
    else:
        files, from_hub = list_files(ref.repo_id, ref.folder, hf_token, network = network)
    files = [f for f in files if not _SKIP_FILE_RE.search(f.path)]
    ggufs = [f for f in files if f.path.lower().endswith(".gguf")]
    if not ggufs:
        return None
    header = _probe_header(ref, ggufs, hf_token, network)
    names = _names_for(ref, files)
    umbrella = ref.repo_id is not None and ref.repo_id.lower() == AUDIO_CPP_REPO.lower()
    if header is not None and not header.is_audio_cpp:
        return None
    family = header.family if header is not None else None
    if header is None:
        # Unread (offline, not cached): only a repo that says it is audio.cpp counts.
        owner = str(ref.repo_id or "").split("/")[0].lower()
        text = " ".join(names).lower()
        tagged = any(t.lower() in ("audio.cpp", "audiocpp") for t in tags)
        if not (
            umbrella or owner == "audio-cpp" or tagged or "audiocpp" in text or "audio.cpp" in text
        ):
            return None
    if not family:
        family = next(
            (t for t in tags if _TAG_FAMILY_RE.match(t) and t in FAMILIES), None
        ) or family_from_names(names)
    if not family:
        reason = "Unsloth Studio could not tell which model family this audio GGUF is."
        variant = AudioCppVariant(quant_label(ggufs[0].path), (ggufs[0],), ggufs[0].path)
        return AudioCppModel(
            id = ref.id,
            repo_id = ref.repo_id,
            folder = ref.folder,
            display_name = ref.display_name,
            family = "",
            task = "",
            server_task = "",
            variant = variant,
            variants = (variant,),
            default_variant = variant.key,
            unsupported = reason,
            local_path = ref.local_path,
            from_hub = from_hub,
        )
    spec = runtime_spec(family)
    embedded = header.spec if header is not None else None
    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)
    unloadable: list[AudioCppVariant] = []
    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)
    else:
        variants = _single_file_variants(files, ref.folder, unloadable = True)
        if ref.local_path:
            variants = [
                AudioCppVariant(v.key, v.files, ref.local_path, label = v.label) for v in variants
            ]
        variants.sort(key = _variant_rank)
        # The spec's recommended package leads, so two files at one quant pick the right one.
        recommended = {f.lower() for f in recommended_gguf_files(spec or embedded)}
        if len(recommended) == 1:
            variants.sort(key = lambda v: Path(v.main_file).name.lower() not in recommended)
        unloadable = [v for v in variants if _unloadable_reason(v.primary)]
        variants = [v for v in variants if not _unloadable_reason(v.primary)]
    unsupported = policy.unsupported
    if not variants and unloadable:
        unsupported = unsupported or _unloadable_reason(unloadable[0].primary)
        default = unloadable[0]
    else:
        if not variants:
            unsupported = (
                unsupported
                or "This repository does not publish every file this model package needs."
            )
            variants = [AudioCppVariant(quant_label(ggufs[0].path), (ggufs[0],), ggufs[0].path)]
        default = variants[0]
    chosen = match_variant(variants, wanted, ref.folder) if wanted else default
    if (
        chosen is not None
        and wanted
        and (not from_hub or "/" not in chosen.key)
        and chosen.key.lower() != wanted.lower()
    ):
        # A cache-only listing keys the row more loosely (``Q8_0``, ``ctc/F16``): keep the full listing's key.
        text = wanted.strip().strip("/")
        head, _, tail = text.rpartition("/")
        quant = chosen.key.rpartition("/")[2]
        scope = head if tail.lower() == quant.lower() else ""
        if (
            not scope
            and "/" not in chosen.key
            and re.fullmatch(r"[A-Za-z0-9]+", text)
            and not _is_quant(text)
        ):
            scope = text  # a bare sub-variant name ("tiny"), not a quant or a file stem
        if scope:
            chosen = AudioCppVariant(
                f"{scope}/{quant}",
                chosen.files,
                chosen.primary,
                dict(chosen.session_options),
                f"{quant} · {scope.rsplit('/', 1)[-1]}",
            )
    if chosen is None:
        unsupported = unsupported or (
            f"Variant '{wanted}' not found. Available variants: "
            + ", ".join(v.key for v in variants)
        )
        chosen = default
    if header is not None and header.source and chosen.primary and chosen.primary != header.source:
        # Quantizations of one model can embed different specs (MagpieTTS's orig names an option
        # ``speaker`` that its Q8_0 calls ``voice_id``): options must come from the file served.
        own = _probe_header(ref, [RepoFile(chosen.primary)], hf_token, network)
        if own is not None and own.is_audio_cpp and own.family == family and own.spec:
            embedded = own.spec
    model = AudioCppModel(
        id = ref.id,
        repo_id = ref.repo_id,
        folder = ref.folder,
        display_name = ref.display_name,
        family = family,
        task = policy.task,
        server_task = policy.default_server_task,
        variant = default,
        variants = tuple(variants),
        default_variant = default.key,
        needs_espeak = policy.needs_espeak,
        request_defaults = dict(policy.request_defaults),
        model_options = dict(policy.model_options),
        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(contract, embedded, policy),
        edit = policy.edit,
        convert = policy.convert,
        separation = policy.separation,
        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,
        unloadable = tuple(unloadable),
    )
    return model.with_variant(chosen)


def _request_source(spec: Optional[dict], embedded: Optional[dict]) -> dict:
    if spec is None or not ((spec.get("options") or {}).get("request")):
        spec = embedded
    return spec if isinstance(spec, dict) else {}


def _raw_request_options(spec: Optional[dict], embedded: Optional[dict]) -> list:
    raw = (_request_source(spec, embedded).get("options") or {}).get("request") or []
    return raw if isinstance(raw, list) else []


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/ first.
    if (
        not runtime_first
        and isinstance(embedded, dict)
        and embedded.get("schema_version") is not None
    ):
        if (embedded.get("options") or {}).get("request"):
            spec = None
    if _request_source(spec, embedded).get("schema_version") is None:
        return None
    names = frozenset(
        str(item.get("name")).strip()
        for item in _raw_request_options(spec, embedded)
        if isinstance(item, dict) and str(item.get("name") or "").strip()
    )
    return names or None


# Spec options Studio fills from request fields, so a required one is a field the user must give.
_REQUIRED_INPUT_NAMES = ("instruct", "reference_text")


def _required_inputs(
    spec: Optional[dict],
    embedded: Optional[dict],
    policy: Optional[AudioCppFamily] = None,
) -> tuple[str, ...]:
    """Names in ``_REQUIRED_INPUT_NAMES`` the raw spec marks ``required`` (``_clean_option`` hides
    them), minus those the family's defaults fill."""
    defaulted = set(((policy.request_defaults if policy else {}) or {}).get("options") or {})
    source = spec
    if source is None or not ((source.get("options") or {}).get("request")):
        source = embedded
    raw = ((source or {}).get("options") or {}).get("request") or []
    found = []
    for item in raw:
        if not isinstance(item, dict) or not item.get("required"):
            continue
        name = str(item.get("name") or "").strip()
        if name in _REQUIRED_INPUT_NAMES and name not in found and name not in defaulted:
            found.append(name)
    return tuple(found)


def _size(path: str) -> int:
    try:
        return os.stat(path).st_size
    except OSError:
        return 0


def package_variant_files(names: Iterable[str]) -> Optional[dict[str, tuple[str, ...]]]:
    """``{variant key: repo paths}`` when ``names`` (a repo's root listing) is an audio.cpp package
    layout Studio knows, else None. A pure function of the names, for the GGUF download planner."""
    present = set(names)
    for policy in _FAMILY_LIST:
        if not policy.package:
            continue
        found = {
            variant.key: variant.files
            for variant in policy.package
            if all(path in present for path in variant.files)
        }
        if found:
            return found
    return None


def companion_files(path: str, names: Iterable[str]) -> tuple[str, ...]:
    """The umbrella files the model GGUF at ``path`` loads beside it (MioTTS's MioCodec), from the
    umbrella's listing ``names``. A pure function of the names, for the GGUF download planner."""
    folder, sep, _ = path.partition("/")
    policy = FAMILIES.get(family_from_names((folder,)) or "") if sep else None
    if policy is None or not policy.companions:
        return ()
    names = list(names)
    found = []
    for companion in policy.companions:
        sub = companion.id[len(_UMBRELLA_PREFIX) :]
        files = [RepoFile(name, 0) for name in names if name.startswith(f"{sub}/")]
        variant = match_variant(_single_file_variants(files, sub), companion.variant, sub)
        if variant is not None:
            found.append(variant.primary)
    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]]:
    """Maps an umbrella folder id to the real repo and path-qualified variant key the downloader uses."""
    if not is_umbrella_id(identifier):
        return None
    model = resolve(identifier, variant, hf_token, network = not hub_offline())
    if model is None or not model.repo_id or not model.variant.primary:
        return None
    if persist:
        _refuse_stale_download(model, hf_token, hub_cache = hub_cache)
    from hub.utils.gguf import gguf_variant_key

    key = gguf_variant_key(model.variant.primary)
    # A cache-only listing can name a crowded folder's file by its bare quant: record Hub listings only.
    if model.from_hub:
        row = (model.id, model.variant.key)
        with _job_rows_lock:
            _job_rows[(model.repo_id.lower(), key.lower())] = row
        # Saved only at a job's start: a status poll after completion would recreate the dropped file.
        if persist and _saved_job_row(key) != row:
            _save_job_row(key, row)
    return model.repo_id, key


# (umbrella repo, planner key) -> (row id, quant) at job start: a file in flight has no cache entry yet.
_job_rows: dict[tuple[str, str], tuple[str, str]] = {}
_job_rows_lock = threading.Lock()
# Persisted for restarted / sibling backends; one file per key so concurrent writers never merge a map.
_JOB_ROWS_DIR = "audio_cpp_job_rows"


def _job_row_path(key: str, create: bool = False) -> Optional[Path]:
    from hub.utils.state_dir import state_root

    root = state_root(create = create)
    if root is None:
        return None
    folder = root / _JOB_ROWS_DIR
    if create:
        try:
            folder.mkdir(exist_ok = True)
        except OSError:
            return None
    return folder / f"{hashlib.sha256(key.lower().encode()).hexdigest()[:32]}.json"


def _saved_job_row(key: str) -> Optional[tuple[str, str]]:
    """The persisted row of ``key``; anything unreadable or malformed reads as absent."""
    try:
        path = _job_row_path(key)
        data = json.loads(path.read_text(encoding = "utf-8")) if path is not None else None
    except Exception:  # noqa: BLE001 - unreadable, malformed or absurdly nested: no saved row
        return None
    if not (isinstance(data, list) and len(data) == 3 and all(isinstance(v, str) for v in data)):
        return None
    saved_key, row_id, quant = data
    # A damaged file must not rename another model.
    folder = key.split("/", 1)[0]
    if saved_key.lower() != key.lower() or not quant:
        return None
    if row_id.lower() != f"{AUDIO_CPP_REPO}/{folder}".lower():
        return None
    return row_id, quant


def _save_job_row(key: str, row: Optional[tuple[str, str]]) -> None:
    """Record (or with None drop) ``key``'s row on disk. Best effort: a failed write keeps the old file."""
    path = _job_row_path(key, create = row is not None)
    if path is None:
        return
    if row is None:
        try:
            path.unlink(missing_ok = True)
        except OSError as exc:
            logger.debug("audio.cpp: could not drop the row of %s: %s", key, exc)
        return
    tmp = path.with_name(f".{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
    try:
        tmp.write_text(json.dumps([key, *row]), encoding = "utf-8")
        os.replace(tmp, path)
    except OSError as exc:
        logger.debug("audio.cpp: could not save the row of %s: %s", key, exc)
        try:
            tmp.unlink(missing_ok = True)
        except OSError:
            pass


def forget_job_row(repo_id: Optional[str], variant: Optional[str]) -> None:
    """Drop an umbrella job's saved row once the job has ended; this process keeps its own copy."""
    if str(repo_id or "").lower() != AUDIO_CPP_REPO.lower() or not variant:
        return
    _save_job_row(variant.replace("\\", "/"), None)


def folder_row_for_download(repo_id: str, variant: Optional[str]) -> Optional[tuple[str, str]]:
    """``(folder row id, variant key)`` for an umbrella download job, the inverse of
    ``download_target``: jobs run on the umbrella repo, but Unsloth Studio names them by row. None
    for any other job. Answered from what ``download_target`` recorded when the job started, then
    from the cache, falling back to reading the planner key's path."""
    if str(repo_id or "").lower() != AUDIO_CPP_REPO.lower() or not variant or "/" not in variant:
        return None
    with _job_rows_lock:
        started = _job_rows.get((repo_id.lower(), variant.replace("\\", "/").lower()))
    if started is None:
        started = _saved_job_row(variant.replace("\\", "/"))
    if started is not None:
        return started
    parts = variant.replace("\\", "/").split("/")
    row_id = f"{AUDIO_CPP_REPO}/{parts[0]}"
    try:
        model = resolve(row_id, network = False)
    except Exception:  # noqa: BLE001 - the path-derived key below still names it
        model = None
    if model is not None:
        from hub.utils.gguf import gguf_variant_key
        for candidate in model.cache_variants:
            if candidate.primary and gguf_variant_key(candidate.primary).lower() == variant.lower():
                return row_id, candidate.key
    return row_id, "/".join([*parts[1:-1], quant_label(f"{parts[-1]}.gguf")])


def cached_folder_target(
    identifier: Optional[str], variant: Optional[str] = None
) -> Optional[tuple[str, list[str]]]:
    """``(umbrella repo, path-qualified variant keys)`` a cache action on an umbrella folder row
    works on, from the cache only; None for any other id.

    With a variant, only that folder's own variant (a bare ``Q8_0`` would name another folder's file
    at repo scope); without one, every variant of the folder with its GGUF on disk. Never the whole
    repo: an empty list means nothing of this folder is cached.
    """
    if not is_umbrella_id(identifier):
        return None
    base, inline = split_variant_ref(str(identifier))
    ref = parse_identifier(base)
    if ref is None or not ref.folder:
        return None
    # No Hub folder name holds a colon; on Windows ``snapshot / "C:"`` would name the snapshot root.
    if ":" in ref.folder:
        return AUDIO_CPP_REPO, []
    wanted = (variant or "").strip() or inline or ref.variant_hint
    model = resolve(ref.id, wanted, network = False)
    chosen: list[AudioCppVariant] = []
    if model is not None and model.repo_id:
        if wanted:
            chosen = _cached_variants_named(model.cache_variants, wanted, ref.folder)
        else:
            snapshots = snapshot_dirs(model.repo_id)
            chosen = [
                v
                for v in model.cache_variants
                if v.primary
                and any((s / v.primary).exists() or (s / v.primary).is_symlink() for s in snapshots)
            ]
    from hub.utils.gguf import gguf_variant_key

    keys = [gguf_variant_key(v.primary) for v in chosen if v.primary]
    if wanted and keys:
        return AUDIO_CPP_REPO, keys
    if (
        wanted
        and model is not None
        and _on_disk_quant_named(model.cache_variants, wanted, ref.folder)
    ):
        return AUDIO_CPP_REPO, []
    # A quant cancelled before any file finished has only download state; the variant delete clears it.
    partial = _folder_state_keys(ref.folder)
    if wanted:
        partial = [k for k in partial if _state_key_named(k, wanted, ref.folder)]
        return AUDIO_CPP_REPO, partial if len(partial) == 1 else []
    seen = {k.lower() for k in keys}
    return AUDIO_CPP_REPO, keys + [k for k in partial if k.lower() not in seen]


def _on_disk_quant_named(variants: Sequence[AudioCppVariant], wanted: str, folder: str) -> bool:
    """Whether ``wanted`` is ambiguous on disk: its quant and scope words fit several variants."""
    found, quant_given = _variants_matching(variants, wanted, folder)
    return quant_given and len(found) > 1


def _folder_state_keys(folder: str) -> list[str]:
    """Planner keys under ``<folder>/`` with a download manifest or cancel marker in the active cache."""
    try:
        from hub.utils import download_manifest
        found = {
            key
            for listing in (
                download_manifest.iter_variant_manifests(
                    "model", AUDIO_CPP_REPO, hub_cache = _hub_cache()
                ),
                download_manifest.iter_variant_markers(
                    "model", AUDIO_CPP_REPO, hub_cache = _hub_cache()
                ),
            )
            for key, _path in listing
        }
    except Exception:  # noqa: BLE001 - unreadable state names nothing more
        return []
    prefix = f"{folder.lower()}/"
    return sorted(k for k in found if k.lower().startswith(prefix) and len(k) > len(prefix))


def _state_key_named(key: str, wanted: str, folder: str) -> bool:
    """Whether a folder's planner key (``<Folder>/<dirs>/<file stem>``) is the variant ``wanted``
    names, by the same rules as a cached variant: the key itself, its file, or its quant plus scope
    words."""
    low = wanted.strip().replace("\\", "/").strip("/").lower()
    path = key.lower()
    stem = path.rsplit("/", 1)[-1]
    if not low or low in (path, stem, f"{stem}.gguf") or f"{folder.lower()}/{low}" == path:
        return bool(low)
    parts = [p for p in low.split("/") if p]
    if quant_label(f"{stem}.gguf").lower() != parts[-1]:
        return False
    dirs = set(path.split("/")[1:-1])
    folder_words = set(re.split(r"[-_.]+", folder.lower()))
    words = dirs | (set(re.split(r"[-_.]+", stem)) - folder_words)
    return all(_scope_word_matches(w, words, stem) for w in parts[:-1])


def _scope_word_matches(word: str, scope: set[str], stem: str) -> bool:
    """A scope word is one of ``scope``, or a compound (``v4-small``) whose parts run, in order, through
    the file stem: its parts can all be folder words, which ``scope`` leaves out."""
    if word in scope:
        return True
    parts = [p for p in re.split(r"[-_.]+", word) if p]
    if len(parts) < 2:
        return False
    # In order and adjacent: `multilingual-ctc` must not name `multilingual-large-ctc`.
    words = [w for w in re.split(r"[-_.]+", stem) if w]
    return any(words[i : i + len(parts)] == parts for i in range(len(words) - len(parts) + 1))


def _cached_variants_named(
    variants: Sequence[AudioCppVariant], wanted: str, folder: str
) -> list[AudioCppVariant]:
    """The cached variants ``wanted`` names. The picker keys a multi-size folder's quants from the Hub
    listing (``tiny/Q8_0``) while a cache holding one size keys it ``Q8_0``, so scope words also
    match the file path; a quant must still pick exactly one, never a fallback default (``match_variant``
    would rank a bare ``Q8_0`` onto one of ``tiny/Q8_0`` and ``small/Q8_0``)."""
    found, quant_given = _variants_matching(variants, wanted, folder)
    return found if not quant_given or len(found) == 1 else []


def _variants_matching(
    variants: Sequence[AudioCppVariant], wanted: str, folder: str
) -> tuple[list[AudioCppVariant], bool]:
    """Every variant ``wanted`` could name, and whether it named a quant (which must be unique)."""
    low = wanted.strip().replace("\\", "/").strip("/").lower()
    for exact in (
        [v for v in variants if v.key.lower() == low],
        [v for v in variants if v.main_file.lower() in (low, f"{folder}/{low}".lower())],
        [v for v in variants if v.main_file.rsplit("/", 1)[-1].lower() in (low, f"{low}.gguf")],
    ):
        if len(exact) == 1:
            return exact, False
        if exact:
            return [], False
    parts = [p for p in low.split("/") if p]
    if not parts:
        return [], False
    quants = {quant_label(v.main_file).lower() for v in variants}
    quant = parts[-1] if parts[-1] in quants else None
    words = parts[:-1] if quant else parts
    folder_words = set(re.split(r"[-_.]+", folder.lower()))

    def stem_of(v: AudioCppVariant) -> str:
        return v.main_file.rsplit("/", 1)[-1].lower().removesuffix(".gguf")

    def scope(v: AudioCppVariant) -> set[str]:
        # A size or edition: a directory of the key, or a word of the file name the folder's own
        # name does not supply (``tiny`` in ``moonshine-streaming-tiny-q8_0``).
        return set(v.key.lower().split("/")[:-1]) | (
            set(re.split(r"[-_.]+", stem_of(v))) - folder_words
        )

    found = [
        v
        for v in variants
        if (quant is None or quant_label(v.main_file).lower() == quant)
        and all(_scope_word_matches(w, scope(v), stem_of(v)) for w in words)
    ]
    return found, quant is not None


def folder_snapshot_dir(identifier: Optional[str]) -> Optional[Path]:
    """``<snapshot>/<Folder>`` of the first cached snapshot holding an umbrella folder row."""
    ref = parse_identifier(split_variant_ref(str(identifier or ""))[0])
    if ref is None or not ref.folder or not ref.repo_id or ":" in ref.folder:
        return None
    snapshots = [s for s in snapshot_dirs(ref.repo_id) if (s / ref.folder).is_dir()]
    # The snapshot holding a variant's weights, not a newer metadata-only or partial one.
    from core.inference.audio_cpp_files import _file_complete

    model = resolve(ref.id, network = False)
    variants = [v for v in (model.cache_variants if model is not None else ()) if v.files]
    for snapshot in snapshots:
        if any(all(_file_complete(snapshot / f.path, f.size) for f in v.files) for v in variants):
            return snapshot / ref.folder
    for snapshot in snapshots:
        if any(p.suffix.lower() == ".gguf" for p in (snapshot / ref.folder).rglob("*")):
            return snapshot / ref.folder
    return snapshots[0] / ref.folder if snapshots else None


def require_runnable(model: AudioCppModel, task: Optional[str] = None) -> None:
    """Raise ``AudioCppModelError`` when Studio cannot run ``model`` (for ``task`` when given)."""
    if model.unsupported:
        raise AudioCppModelError(model.unsupported)
    if task == "asr" and model.task != "asr":
        raise AudioCppModelError(f"{model.display_name} is not a speech-to-text model.")
    # The main audio slot, which speech, music and separation models share.
    if task in ("tts", "music") and model.task not in ("tts", "music", "sep"):
        if model.task == "asr":
            raise AudioCppModelError(
                f"{model.display_name} is a speech-to-text model; choose it for dictation in "
                "Settings, then Voice."
            )
        raise AudioCppModelError(f"{model.display_name} is not a speech or music model.")


def repo_of(identifier: Optional[str]) -> Optional[str]:
    """The Hub repo that holds ``identifier``'s files. No I/O."""
    base, _variant = split_variant_ref(str(identifier or ""))
    ref = parse_identifier(base) if not base.lower().endswith(".gguf") else None
    return ref.repo_id if ref is not None else None


# Recommended ASR rows for dictation, in the order the Voice settings list them.
RECOMMENDED_STT_MODELS: tuple[str, ...] = tuple(
    f"{AUDIO_CPP_REPO}/{folder}"
    for folder in (
        "Qwen3-ASR-0.6B-GGUF",
        "Qwen3-ASR-1.7B-GGUF",
        "Parakeet-TDT-0.6B-v3-GGUF",
        "Canary-180M-Flash-GGUF",
        "Moonshine-Streaming-GGUF",
        "Nemotron-3.5-ASR-Streaming-0.6B-GGUF",
    )
)


_downloaded_cache: dict[Optional[str], tuple[float, list[AudioCppModel]]] = {}
_forget_generation = 0
_DOWNLOADED_TTL_SECONDS = 10.0


def downloaded_models(task: Optional[str] = None) -> list[AudioCppModel]:
    """Found by reading only GGUF headers; status polls hit this, so results are cached a few seconds."""
    with _resolve_lock:
        hit = _downloaded_cache.get(task)
        generation = _forget_generation
    if hit is not None and time.monotonic() - hit[0] < _DOWNLOADED_TTL_SECONDS:
        return list(hit[1])
    out = _scan_downloaded(task)
    with _resolve_lock:
        if generation == _forget_generation:
            _downloaded_cache[task] = (time.monotonic(), out)
    return list(out)


def _scan_downloaded(task: Optional[str]) -> list[AudioCppModel]:
    from core.inference import audio_cpp_files

    out: list[AudioCppModel] = []
    root = _hub_cache()
    try:
        repo_dirs = [p for p in root.iterdir() if p.name.startswith("models--") and p.is_dir()]
    except OSError:
        return out
    for repo_dir in repo_dirs:
        repo_id = repo_dir.name[len("models--") :].replace("--", "/")
        snapshots = snapshot_dirs(repo_id, root)
        if not snapshots:
            continue
        ids: list[str] = []
        if repo_id.lower() == AUDIO_CPP_REPO.lower():
            folders = set()
            for snapshot in snapshots:
                try:
                    folders.update(p.name for p in snapshot.iterdir() if p.is_dir())
                except OSError:
                    continue
            ids = [f"{AUDIO_CPP_REPO}/{name}" for name in sorted(folders)]
        else:
            first_gguf = None
            for snapshot in snapshots:
                # Root or one folder down holds GGUFs; a full cache walk per status poll costs more than it finds
                first_gguf = next(
                    iter(sorted([*snapshot.glob("*.gguf"), *snapshot.glob("*/*.gguf")])), None
                )
                if first_gguf is not None:
                    break
            if first_gguf is None:
                continue
            header = read_local_header(first_gguf)
            if header is None or not header.is_audio_cpp:
                continue
            ids = [repo_id]
        for model_id in ids:
            try:
                model = resolve(model_id, network = False)
            except Exception:  # noqa: BLE001 - one unreadable repo never hides the rest
                model = None
            if model is None or (model.unsupported and not model.family):
                continue
            if task is not None and model.task != task:
                continue
            cached = next(
                (
                    v
                    for v in model.cache_variants
                    if audio_cpp_files.cached_files(model.with_variant(v))
                ),
                None,
            )
            if cached is None:
                continue
            row = model.with_variant(cached)
            if cached in model.unloadable:
                reason = model.unsupported or _unloadable_reason(cached.primary)
                row = replace(row, unsupported = reason)
            out.append(row)
    return out