Skip to content

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

Studio: clearer audio.cpp errors, cleaner Speak/Clone, reproducible takes (#14075)

Etherld18ecfc850f0
diff --git a/studio/backend/core/inference/audio_cpp_backend.py b/studio/backend/core/inference/audio_cpp_backend.py
index 11a4ac51d69..9858a9229a4 100644
--- a/studio/backend/core/inference/audio_cpp_backend.py
+++ b/studio/backend/core/inference/audio_cpp_backend.py
@@ -36,10 +36,12 @@ from core.inference.audio_cpp_models import (
AudioCppModelError,
CloneSpec,
forget,
+ ignored_options,
option_matches,
filled_options,
require_runnable,
resolve,
+ takes_seed,
workflow_options,
)
from core.inference.audio_cpp_server import (
@@ -47,7 +49,9 @@ from core.inference.audio_cpp_server import (
AudioCppRequestError,
AudioCppServer,
AudioCppStartCancelledError,
+ AudioCppUnavailableError,
)
+from core.inference.audio_cpp_failures import attach_failure, classify_audio_cpp_failure, failure_of
from core.inference.audio_cpp_music import music_rules
from core.inference.audio_task_outputs import task_outputs, wav_header
from loggers import get_logger
@@ -144,6 +148,17 @@ _SPEAKER_LINE_RE = re.compile(r"^\s*Speaker\s*\d+\s*:", re.IGNORECASE | re.MULTI
_MIN_SPEED, _MAX_SPEED = 0.5, 2.0
+def _seed_option(value: Any) -> Optional[int]:
+ """A typed seed option as an int in the seed field's range, else None."""
+ if isinstance(value, bool) or (isinstance(value, float) and not value.is_integer()):
+ return None
+ try:
+ seed = int(value.strip()) if isinstance(value, str) else int(value)
+ except (TypeError, ValueError, OverflowError):
+ return None
+ return seed if 0 <= seed <= 2147483647 else None
+
+
def _primary_workflow(model: AudioCppModel) -> str:
workflows = list(model.workflows)
return "speak" if "speak" in workflows or not workflows else workflows[0]
@@ -171,6 +186,11 @@ def _reread_after_download(model: AudioCppModel, hf_token: Optional[str]) -> Aud
return fresh
+# Strict specs that list no language option yet read the request's top-level language
+# (audio.cpp extract_request_language: VoxCPM1 keeps Cantonese text Traditional with zh-HK).
+_READS_TOP_LEVEL_LANGUAGE = frozenset({"voxcpm1", "audio8_tts"})
+
+
def model_info_fields(model: AudioCppModel) -> dict[str, Any]:
"""What status reports for a loaded audio.cpp model, beyond the common audio fields."""
primary = _primary_workflow(model)
@@ -185,6 +205,15 @@ def model_info_fields(model: AudioCppModel) -> dict[str, Any]:
"audio_edit": edit_rules(model),
"audio_music": music_rules(model),
"audio_options_by_workflow": options_by_workflow(model, primary),
+ # Null when the spec takes any option; else the request fields it declares.
+ "audio_request_inputs": None
+ if model.request_keys is None
+ else sorted(
+ n
+ for n in ("instruct", "instruction", "language")
+ if n in model.request_keys
+ or (n == "language" and model.family in _READS_TOP_LEVEL_LANGUAGE)
+ ),
"audio_workflow_tasks": audio_cpp_convert.workflow_tasks(model),
"audio_convert": audio_cpp_convert.convert_caps(model),
"audio_convert_rules": model.convert
@@ -332,11 +361,23 @@ class AudioCppBackend:
# Request-raised session options (Stable Audio max_batch); cleared when another model loads.
self._session_overrides: dict[str, str] = {}
self._status_patch: Optional[dict[str, Any]] = None
+ # "cpu" once a GPU start failed and the model was restarted on the CPU.
+ self._device_fallback: Optional[str] = None
# Loading
@_invalidates_gpu_memory("audio load")
- def load_model(
+ def load_model(self, config, *args, **kwargs) -> bool:
+ try:
+ return self._load_model(config, *args, **kwargs)
+ except Exception as exc:
+ # Unsloth Studio's own refusals (runtime missing, eSpeak, newer runtime) are named here.
+ if failure_of(exc) is None:
+ model = getattr(config, "audio_cpp", None)
+ attach_failure(exc, classify_audio_cpp_failure(str(exc), model = model))
+ raise
+
+ def _load_model(
self,
config,
max_seq_length: int = 2048,
@@ -382,6 +423,10 @@ class AudioCppBackend:
model = _reread_after_download(model, hf_token)
self._session_overrides = {}
self._status_patch = None
+ from core.inference.audio_device import audio_device_forces_cpu
+
+ self._device_fallback = None
+ self._force_cpu = audio_device_forces_cpu(self.device_preference)
self._start_server(model)
self._model = model
self.models = {
@@ -394,6 +439,7 @@ class AudioCppBackend:
"context_length": 0,
**model_info_fields(model),
"audio_cpp_backend": self._server.backend if self._server else None,
+ "audio_device_fallback": self._device_fallback,
}
}
self.active_model_name = model_name
@@ -526,16 +572,61 @@ class AudioCppBackend:
self._stop_server_locked()
model_path = audio_cpp_files.materialize(model)
served = _with_session_overrides(_with_companions(model), self._session_overrides)
- try:
- self._server = AudioCppServer.start(
- served, model_path, force_cpu = self._force_cpu, cancel_event = cancel_event
- )
- except AudioCppStartCancelledError as exc:
- _raise_if_cancelled(cancel_event)
- raise RuntimeError(str(exc)) from exc
+ force_cpu = self._force_cpu
+ while True:
+ try:
+ self._server = AudioCppServer.start(
+ served, model_path, force_cpu = force_cpu, cancel_event = cancel_event
+ )
+ break
+ except AudioCppStartCancelledError as exc:
+ _raise_if_cancelled(cancel_event)
+ raise RuntimeError(str(exc)) from exc
+ except AudioCppUnavailableError as exc:
+ if force_cpu or not self._may_retry_on_cpu(exc, cancel_event):
+ raise
+ logger.warning(
+ "audio.cpp: %s could not start on the GPU; retrying once on the CPU",
+ model.id,
+ )
+ force_cpu = True
+ if force_cpu and not self._force_cpu:
+ # Sticks for this model, so a mid-generation restart goes straight to the CPU.
+ self._force_cpu = True
+ self._device_fallback = "cpu"
self._served_session = dict((served.model_options or {}).get("session_options") or {})
self.device = "cpu" if self._server.backend == "cpu" else self._server.backend
+ def _runtime_error(self, what: str, exc: AudioCppRequestError) -> Exception:
+ """The runtime's refusal as an ``AudioRuntimeError``, with any known failure attached."""
+ from core.inference.audio_errors import AudioRuntimeError
+
+ backend = getattr(self._server, "backend", None)
+ failure = classify_audio_cpp_failure(
+ exc.detail, backend = backend, model = self._model, runtime_status = exc.status
+ )
+ return attach_failure(
+ AudioRuntimeError(
+ f"The audio runtime could not {what}: {exc.detail}", status = exc.status
+ ),
+ failure,
+ )
+
+ def _may_retry_on_cpu(self, exc: BaseException, cancel_event) -> bool:
+ """One CPU retry for a GPU that could not start, unless the user pinned the GPU."""
+ from core.inference.audio_device import audio_device_default, normalize_audio_device
+ from utils.process_lifetime import is_process_shutting_down
+
+ failure = failure_of(exc)
+ pref = self.device_preference
+ return (
+ failure is not None
+ and failure.code == "gpu_unavailable"
+ and (normalize_audio_device(pref) if pref else audio_device_default()) != "gpu"
+ and not (cancel_event is not None and cancel_event.is_set())
+ and not is_process_shutting_down()
+ )
+
def _stop_server_locked(self) -> None:
server = self._server
self._server = None
@@ -585,6 +676,7 @@ class AudioCppBackend:
output_dir: Optional[str] = None,
) -> Tuple[bytes, int]:
del top_k, min_p, repetition_penalty, use_adapter
+ self.last_generation_stats = None
if not self.active_model_name or self.active_model_name not in self.models:
raise RuntimeError("No active audio model")
model = self._model
@@ -593,7 +685,25 @@ class AudioCppBackend:
_raise_if_cancelled(cancel_event)
if model.task == "sep":
raise RuntimeError(f"{model.display_name} separates audio; open Separate.")
- if workflow == "music" and music is not None:
+ audio_options = dict(audio_options or {})
+ typed = _seed_option(audio_options.pop("seed", None))
+ if (workflow == "music" and music is not None) or workflow in ("convert", "edit"):
+ wf = workflow
+ else:
+ wf = "clone" if workflow == "clone" or bool(audio_inputs) else "speak"
+ ignored = ignored_options(model, wf, audio_options)
+ audio_options = {k: v for k, v in audio_options.items() if k not in ignored}
+ seeded = takes_seed(model, wf)
+ if typed is not None and not seeded:
+ # A strict spec refuses an undeclared seed.
+ ignored = sorted({*ignored, "seed"})
+ typed = None
+ seed = seed if seed is not None else typed
+ # Music keeps its own rule (_run_music); a music model's legacy speak path sends none.
+ if seed is None and seeded and wf in ("speak", "clone") and model.task != "music":
+ seed = cm.random_seed()
+ self.last_generation_stats = {"seed": seed, "ignored_options": ignored}
+ if wf == "music":
options = filled_options(model, "music", audio_options)
return self._run_music(
model,
@@ -702,10 +812,7 @@ class AudioCppBackend:
_raise_if_cancelled(cancel_event)
raise
except AudioCppRequestError as exc:
- from core.inference.audio_errors import AudioRuntimeError
- raise AudioRuntimeError(
- f"The audio runtime could not generate audio: {exc.detail}", status = exc.status
- ) from exc
+ raise self._runtime_error("generate audio", exc) from exc
_raise_if_cancelled(cancel_event)
return wav, _wav_sample_rate(wav)
@@ -716,7 +823,15 @@ class AudioCppBackend:
with self._server_lock:
server = self._server
running = server.model if server is not None and server.alive() else None
- return server_runtime_fields(model, running)
+ fields = server_runtime_fields(model, running)
+ if self._device_fallback:
+ # A restart fell back to the CPU: the parent stops counting VRAM, the page can say so.
+ fields.update(
+ audio_device_fallback = self._device_fallback,
+ audio_cpp_backend = "cpu",
+ audio_cpu = True,
+ )
+ return fields
def _record_runtime(self) -> None:
entry = self.models.get(self.active_model_name or "")
@@ -773,10 +888,7 @@ class AudioCppBackend:
_raise_if_cancelled(cancel_event)
raise
except AudioCppRequestError as exc:
- from core.inference.audio_errors import AudioRuntimeError
- raise AudioRuntimeError(
- f"The audio runtime could not separate the track: {exc.detail}", status = exc.status
- ) from exc
+ raise self._runtime_error("separate the track", exc) from exc
except SeparationOutputError as exc:
logger.warning("audio.cpp: %s answered without decodable stems: %s", model.id, exc)
return []
@@ -1071,8 +1183,12 @@ class AudioCppBackend:
f"{model.display_name} makes at most "
f"{MUSIC_MAX_VARIATIONS if mode.variations else 1} variation(s) at a time."
)
- if seed is None and model.music.fixed_seed:
+ if seed is None:
seed = cm.random_seed()
+ if music.get("take"):
+ # One take of a run the page sends take by take.
+ seed = cm.take_seed(seed, int(music["take"]))
+ self.last_generation_stats = {**(self.last_generation_stats or {}), "seed": seed}
batch = variations if mode.variations == "batch" else 1
if mode_id == "edit":
if not source:
@@ -1137,10 +1253,7 @@ class AudioCppBackend:
_raise_if_cancelled(cancel_event)
raise
except AudioCppRequestError as exc:
- from core.inference.audio_errors import AudioRuntimeError
- raise AudioRuntimeError(
- f"The audio runtime could not generate audio: {exc.detail}", status = exc.status
- ) from exc
+ raise self._runtime_error("generate audio", exc) from exc
_raise_if_cancelled(cancel_event)
if output_dir:
_write_outputs(output_dir, outputs)
diff --git a/studio/backend/core/inference/audio_cpp_failures.py b/studio/backend/core/inference/audio_cpp_failures.py
new file mode 100644
index 00000000000..89e7531672b
--- /dev/null
+++ b/studio/backend/core/inference/audio_cpp_failures.py
@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Known audio.cpp failures, named so a client can offer the fix. Raw runtime text is only
+classified, never returned: any runtime detail in a message goes through ``sanitize_runtime_tail``."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Optional
+
+from core.inference.audio_errors import sanitize_runtime_tail
+
+# Ordered: the first code with a matching pattern wins. Lowercased text is matched.
+_PATTERNS = tuple(
+ (code, re.compile(pattern))
+ for code, pattern in (
+ # Missing library or data only: a request the runtime refuses can mention eSpeak too.
+ (
+ "espeak_missing",
+ r"could not load espeak|espeak-ng failed to initialize|espeak data package missing"
+ r"|cannot (?:read|open) espeak data|needs an audio runtime built with espeak",
+ ),
+ ("runtime_missing", r"the audio runtime is not installed"),
+ (
+ "family_unknown_to_runtime",
+ r"unsupported model family hint:|no registered model loader can load"
+ r"|needs a newer audio runtime|update the audio runtime",
+ ),
+ (
+ "gpu_unavailable",
+ r"backend requested but|failed to initialize \w+ backend on device"
+ r"|failed to initialize (?:cuda|rocm|musa)\b|ggml_vulkan: no devices found|has no device",
+ ),
+ (
+ "out_of_memory",
+ r"backend weight buffer|failed to allocate \S+ buffer of size|cudamalloc failed"
+ r"|cuda error: out of memory|memory allocation of size \d+ failed"
+ r"|does not fit in device memory|insufficient_memory|headroom exceeds available"
+ r"|no single gpu has enough free memory",
+ ),
+ (
+ "file_incomplete",
+ r"failed to read (?:magic|header|tensor info|tensor data)|invalid magic characters"
+ r"|failed to read gguf (?:metadata|tensor source)|tensor data range is out of bounds"
+ r"|model path does not exist",
+ ),
+ )
+)
+_CODES = frozenset(code for code, _ in _PATTERNS)
+_STATUS = {"file_incomplete": 422} # else 503
+
+# Messages that already come from Unsloth Studio, so no runtime line is appended.
+_STUDIO_CODES = frozenset({"runtime_missing", "family_unknown_to_runtime", "espeak_missing"})
+
+_UPDATE = "Update it from the update banner in Unsloth Studio, or run `unsloth studio update`."
+_MESSAGES = {
+ "runtime_missing": "The audio runtime isn't installed. Install it from the update banner in "
+ "Unsloth Studio, or run `unsloth studio update`.",
+ "family_unknown_to_runtime": "{name} needs a newer audio runtime than the one installed. "
+ + _UPDATE,
+ "espeak_missing": "{name} needs an audio runtime built with eSpeak-ng. " + _UPDATE,
+ "gpu_unavailable": "The audio runtime could not use the GPU. Set the audio device to CPU in "
+ "Unsloth Studio, or set UNSLOTH_AUDIO_CPP_BACKEND=cpu.",
+ "out_of_memory": "{name} ran out of memory. Free GPU memory, choose a smaller variant, or set "
+ "the audio device to CPU.",
+ "out_of_memory_cpu": "{name} ran out of memory. Close other apps to free RAM, or choose a "
+ "smaller variant.",
+ "file_incomplete": "The model file is incomplete or damaged. Delete it and download it again, "
+ "or choose another variant.",
+ # Runtime 4xx: the input is too big for the device (upstream CapacityError).
+ "capacity": "This input does not fit in device memory. Try a shorter input, or set the audio "
+ "device to CPU.",
+ "capacity_cpu": "This input does not fit in memory. Try a shorter input.",
+ # Unsloth Studio's own refusal before launch.
+ "placement": "No single GPU has enough free memory for {name}. Free GPU memory, choose a "
+ "smaller variant, or set the audio device to CPU.",
+}
+
+
+@dataclass(frozen = True)
+class AudioCppFailure:
+ code: str
+ message: str
+ status: int
+ # smaller_variants / offload_options / device only: never a path or raw runtime text.
+ extras: dict = field(default_factory = dict)
+
+ def detail(self) -> dict:
+ return {"code": self.code, "message": self.message, **self.extras}
+
+ def payload(self) -> dict:
+ return asdict(self)
+
+ @classmethod
+ def from_payload(cls, data: Any) -> Optional["AudioCppFailure"]:
+ if not isinstance(data, dict) or data.get("code") not in _CODES:
+ return None
+ code = str(data["code"])
+ extras = data.get("extras") or {}
+ extras = {
+ k: v
+ for k, v in extras.items()
+ if k in ("smaller_variants", "offload_options", "device")
+ }
+ return cls(
+ code,
+ str(data.get("message") or ""),
+ int(data.get("status") or _STATUS.get(code, 503)),
+ extras,
+ )
+
+
+class AudioCppFailureError(RuntimeError):
+ """A worker's classified failure, rebuilt in the parent process."""
+
+ def __init__(self, message: str, failure: AudioCppFailure) -> None:
+ super().__init__(message)
+ self.audio_cpp_failure = failure
+
+
+def failure_of(exc: Any) -> Optional[AudioCppFailure]:
+ failure = getattr(exc, "audio_cpp_failure", None)
+ return failure if isinstance(failure, AudioCppFailure) else None
+
+
+def attach_failure(exc: BaseException, failure: Optional[AudioCppFailure]) -> BaseException:
+ if failure is not None and failure_of(exc) is None:
+ try:
+ exc.audio_cpp_failure = failure
+ except AttributeError:
+ pass
+ return exc
+
+
+def estimate_resident_gb(size_bytes: int) -> float:
+ """Resident GPU memory for an audio.cpp package: weights plus graph and cache buffers.
+ Measured TTS peaks run about 3x the q8 weights (Qwen3-TTS 0.6B: 1.9 GB file, 5.9 GB peak)."""
+ return round(size_bytes / (1024**3) * 2.5 + 1.5, 2)
+
+
+def smaller_variants(
+ model,
+ *,
+ free_gb: Optional[float] = None,
+ limit: int = 3,
+) -> list[dict]:
+ """Variants smaller than the loaded one, largest first; only those that fit ``free_gb``."""
+ if model is None:
+ return []
+ from core.inference.audio_cpp_models import quant_label, resolve
+
+ extra = 0
+ for companion in getattr(model, "companions", ()) or ():
+ try:
+ found = resolve(companion.id, companion.variant, network = False)
+ except Exception: # noqa: BLE001 - an unknown companion counts as nothing
+ found = None
+ extra += found.size_bytes if found is not None else 0
+ rows = []
+ for variant in sorted(model.variants, key = lambda v: v.size_bytes, reverse = True):
+ estimate = estimate_resident_gb(variant.size_bytes + extra)
+ if not 0 < variant.size_bytes < model.size_bytes or (
+ free_gb is not None and estimate > free_gb
+ ):
+ continue
+ label = variant.label or quant_label(variant.main_file)
+ rows.append(
+ {
+ # The quant /api/models/gguf-variants lists for this row.
+ "variant": variant.key,
+ "label": label,
+ "size_bytes": variant.size_bytes,
+ "estimate_gb": estimate,
+ }
+ )
+ return rows[:limit]
+
+
+def offload_options(model) -> list[str]:
+ """Session options of the installed runtime's spec that move experts off the GPU."""
+ if model is None:
+ return []
+ from core.inference.audio_cpp_models import runtime_spec
+
+ spec = runtime_spec(model.family) or {}
+ session = (spec.get("options") or {}).get("session") if isinstance(spec, dict) else None
+ return [
+ str(option["name"])
+ for option in session or ()
+ if isinstance(option, dict) and "expert" in str(option.get("name") or "")
+ ]
+
+
+def classify_audio_cpp_failure(
+ text: str,
+ *,
+ backend: Optional[str] = None,
+ model = None,
+ runtime_status: Optional[int] = None,
+ free_gb: Optional[float] = None,
+) -> Optional[AudioCppFailure]:
+ """The known failure in ``text`` (a runtime log tail or error), or None."""
+ raw = str(text or "")
+ lowered = raw.lower()
+ for code, pattern in _PATTERNS:
+ # A CUDA build prints its CUDA init failure on CPU launches too.
+ if code == "gpu_unavailable" and backend in (None, "cpu"):
+ continue
+ match = pattern.search(lowered)
+ if match is None:
+ continue
+ capacity = (
+ code == "out_of_memory" and runtime_status is not None and 400 <= runtime_status < 500
+ )
+ placement = "no single gpu" in lowered
+ on_cpu = code == "out_of_memory" and backend == "cpu"
+ key = "placement" if placement else "capacity" if capacity else code
+ key = f"{key}_cpu" if on_cpu and key in ("out_of_memory", "capacity") else key
+ message = _MESSAGES[key].format(name = getattr(model, "display_name", None) or "This model")
+ # "device": the run was already on the CPU, so "set the audio device to CPU" can't help.
+ extras: dict = {"device": "cpu"} if on_cpu else {}
+ if code == "out_of_memory" and not capacity:
+ if variants := smaller_variants(model, free_gb = free_gb):
+ extras["smaller_variants"] = variants
+ listed = ", ".join(
+ f"{row['label']} (~{row['estimate_gb']:.1f} GB)" for row in variants
+ )
+ message += f" Smaller variants: {listed}."
+ if offload := offload_options(model):
+ extras["offload_options"] = offload
+ message += f" This model can offload experts: set {' or '.join(offload[:2])}."
+ if code not in _STUDIO_CODES and not placement:
+ start = raw.rfind("\n", 0, match.start()) + 1
+ end = raw.find("\n", match.end())
+ line = sanitize_runtime_tail(raw[start : end if end >= 0 else len(raw)], 200)
+ if line:
+ message += f" Details: {line}"
+ return AudioCppFailure(code, message, 400 if capacity else _STATUS.get(code, 503), extras)
+ return None
+
+
+def problem_http_exception(problem: str, model = None):
+ """A preflight refusal as an HTTPException: the classified shape, else today's 501 string."""
+ from fastapi import HTTPException
+
+ failure = classify_audio_cpp_failure(problem, model = model)
+ if failure is None:
+ return HTTPException(status_code = 501, detail = problem)
+ return HTTPException(status_code = failure.status, detail = failure.detail())
diff --git a/studio/backend/core/inference/audio_cpp_models.py b/studio/backend/core/inference/audio_cpp_models.py
index f04745702c5..b9addf803d9 100644
--- a/studio/backend/core/inference/audio_cpp_models.py
+++ b/studio/backend/core/inference/audio_cpp_models.py
@@ -199,8 +199,6 @@ class MusicSpec:
description_option: Optional[str] = None
instrumental_lyrics: Optional[str] = None
edit_rate: Optional[int] = None
- # The runtime's default seed is fixed, so repeat runs would be identical.
- fixed_seed: bool = True
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
@@ -229,7 +227,6 @@ MUSIC_SPECS: dict[str, MusicSpec] = {
"stable_audio": MusicSpec(
(_STABLE_AUDIO_SONG, _STABLE_AUDIO_EDIT),
edit_rate = 44100,
- fixed_seed = False,
rtf = 1.0,
),
"heartmula": MusicSpec(
@@ -1053,8 +1050,8 @@ def _spec_music(tasks: Sequence[str], request: Optional[list]) -> MusicSpec:
)
if "sfx" in tasks:
modes.append(MusicMode("sfx", duration = (1.0, 60.0, 8.0)))
- # A declared request without ``seed`` refuses one, so it is never sent.
- return MusicSpec(tuple(modes), fixed_seed = request is None or "seed" in names)
+ # Whether a seed is sent follows the spec's request keys (takes_seed).
+ return MusicSpec(tuple(modes))
def _family_from_spec_tasks(
@@ -2035,6 +2032,8 @@ def option_schema(
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":
@@ -2056,9 +2055,19 @@ def option_schema(
"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."""
@@ -2318,6 +2327,40 @@ def _wire_option_names(
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."""
+ if not isinstance(values, dict):
+ return []
+ offered = {o["name"] for o in workflow_options(model, workflow)}
+ keys = model.request_keys
+ return sorted(
+ name
+ for name in map(str, values)
+ if name not in ("seed", "voice")
+ and (name not in offered or (keys is not None and name not in keys))
+ )
+
+
+_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":
@@ -2332,7 +2375,8 @@ def workflow_options(model: "AudioCppModel", workflow: str) -> tuple[dict, ...]:
hidden = set(model.option_hidden.get("*", ())) | set(model.option_hidden.get(workflow, ()))
if workflow in ("clone", "edit", "convert"):
hidden.add("voice")
- return tuple(o for o in options if o["name"] not in hidden)
+ 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(
diff --git a/studio/backend/core/inference/audio_cpp_server.py b/studio/backend/core/inference/audio_cpp_server.py
index 99d60337f46..5b5afd276d3 100644
--- a/studio/backend/core/inference/audio_cpp_server.py
+++ b/studio/backend/core/inference/audio_cpp_server.py
@@ -31,6 +31,7 @@ from pathlib import Path
from typing import Any, BinaryIO, Optional
from core.inference.audio_cpp_models import AudioCppModel
+from core.inference.audio_cpp_failures import classify_audio_cpp_failure
from core.inference.audio_errors import sanitize_runtime_tail
from loggers import get_logger
from utils.prebuilt.child_env import isolate_home, scrub_env
@@ -56,13 +57,20 @@ _ERROR_BODY_BYTES = 64 * 1024
# CUDA graph replay wedges these transducers mid-request (server spins, never answers); graphs off fixes it.
_NO_CUDA_GRAPH_FAMILIES = frozenset({"nemotron_asr", "parakeet_tdt"})
_GPU_HOST_THREADS = 8
-# Startup output of a GPU backend that found no device, as opposed to a model that failed to load.
-_GPU_INIT_FAILURES = ("has no device", "failed to initialize cuda", "backend requested but")
class AudioCppUnavailableError(RuntimeError):
"""audiocpp_server is missing, failed to start, or stopped answering."""
+ def __init__(
+ self,
+ message: str,
+ failure = None,
+ ) -> None:
+ super().__init__(message)
+ if failure is not None:
+ self.audio_cpp_failure = failure
+
class AudioCppRuntimeTooOldError(AudioCppUnavailableError):
"""The installed runtime is older than the GGUFs a download would fetch."""
@@ -592,17 +600,19 @@ class AudioCppServer:
tail = self.log_tail()
logger.warning("audiocpp_server exited during startup: %s", tail)
last = f" Last output: {sanitize_runtime_tail(tail)}" if tail else ""
- # A CUDA build prints its CUDA init failure on CPU launches too.
- lowered = tail.lower()
- if self.backend != "cpu" and any(s in lowered for s in _GPU_INIT_FAILURES):
+ # The raw tail is classified; only the sanitized one is shown.
+ failure = classify_audio_cpp_failure(tail, backend = self.backend, model = self.model)
+ if failure is not None and failure.code == "gpu_unavailable":
raise AudioCppUnavailableError(
f"The audio runtime could not start on the {self.backend.upper()} backend "
"because no usable GPU is visible. Choose CPU for the audio device in "
- "Unsloth Studio, or set UNSLOTH_AUDIO_CPP_BACKEND=cpu." + last
+ "Unsloth Studio, or set UNSLOTH_AUDIO_CPP_BACKEND=cpu." + last,
+ failure,
)
raise AudioCppUnavailableError(
"The audio runtime exited before becoming ready; the model file may be "
- "incomplete or unsupported by this build." + last
+ "incomplete or unsupported by this build." + last,
+ failure,
)
if self._probe():
return
@@ -702,13 +712,11 @@ class AudioCppServer:
if cancel_event is not None and cancel_event.is_set():
raise AudioCppRequestCancelledError("Request cancelled.") from exc
if not self.alive():
+ tail = self.log_tail()
raise AudioCppUnavailableError(
"The audio runtime stopped while serving the request."
- + (
- f" Last output: {sanitize_runtime_tail(self.log_tail())}"
- if self.log_tail()
- else ""
- )
+ + (f" Last output: {sanitize_runtime_tail(tail)}" if tail else ""),
+ classify_audio_cpp_failure(tail, backend = self.backend, model = self.model),
) from exc
raise AudioCppUnavailableError(f"The audio runtime did not answer: {exc}") from exc
finally:
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 84be36e7f7d..799eca015a8 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -25,6 +25,7 @@ from io import BytesIO
from pathlib import Path
from typing import Any, Callable, Generator, Mapping, Optional, Sequence, Tuple, Union
from core.inference.audio_device import audio_device_forces_cpu, audio_load_runs_on_cpu
+from core.inference.audio_cpp_failures import AudioCppFailure, AudioCppFailureError, attach_failure
from core.inference.context_refusal import ContextBudgetExceeded
from core.inference.native_audio import NATIVE_AUDIO_TYPES, is_native_audio_model
from core.inference.audio_errors import (
@@ -433,6 +434,8 @@ def _mirrored_model_entry(model_info: dict, model_name: str) -> dict:
"audio_edit": model_info.get("audio_edit"),
"audio_music": model_info.get("audio_music"),
"audio_cpp_backend": model_info.get("audio_cpp_backend"),
+ "audio_device_fallback": model_info.get("audio_device_fallback"),
+ "audio_request_inputs": model_info.get("audio_request_inputs"),
"max_image_side": model_info.get("max_image_side"),
}
@@ -2376,10 +2379,11 @@ class InferenceOrchestrator:
# model it would otherwise report as satisfied. Native audio only:
# marking anything else tells training a GPU model holds no VRAM.
_audio_type = model_info.get("audio_type")
+ # An audio.cpp model that fell back to the CPU holds no VRAM either.
self.models[self.active_model_name]["audio_cpu"] = (
_audio_type in NATIVE_AUDIO_TYPES
and audio_load_runs_on_cpu(_audio_type, audio_device)
- )
+ ) or model_info.get("audio_cpp_backend") == "cpu"
self.models[self.active_model_name].update(
_mlx_runtime_mirror_fields(model_info)
)
@@ -2395,6 +2399,9 @@ class InferenceOrchestrator:
error = resp.get("message") or resp.get("error") or "Failed to load model"
self.active_model_name = None
self.models.clear()
+ failure = AudioCppFailure.from_payload(resp.get("failure"))
+ if failure is not None:
+ raise AudioCppFailureError(error, failure)
raise Exception(error)
except Exception as exc:
@@ -4026,12 +4033,18 @@ class InferenceOrchestrator:
resp.get("error", "This backend cannot generate audio."),
hint = resp.get("hint"),
)
+ failure = AudioCppFailure.from_payload(resp.get("failure"))
if resp.get("code") == AUDIO_RUNTIME_ERROR_CODE:
- raise AudioRuntimeError(
- resp.get("error", "Audio generation failed"),
- status = resp.get("status"),
+ raise attach_failure(
+ AudioRuntimeError(
+ resp.get("error", "Audio generation failed"),
+ status = resp.get("status"),
+ ),
+ failure,
)
- raise RuntimeError(resp.get("error", "Audio generation failed"))
+ raise attach_failure(
+ RuntimeError(resp.get("error", "Audio generation failed")), failure
+ )
if rtype == "error":
if cancel_event is not None and cancel_event.is_set():
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index b6bbcac913d..06e165a8cd1 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -855,6 +855,8 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
"audio_edit",
"audio_music",
"audio_cpp_backend",
+ "audio_device_fallback",
+ "audio_request_inputs",
)
if k in _entry
}
@@ -930,6 +932,8 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
)
except Exception as exc:
+ from core.inference.audio_cpp_failures import failure_of
+ failure = failure_of(exc)
_send_response(
resp_queue,
{
@@ -937,6 +941,7 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
"success": False,
"error": str(exc),
"stack": traceback.format_exc(limit = 20),
+ **({"failure": failure.payload()} if failure is not None else {}),
},
)
@@ -1806,6 +1811,7 @@ def _handle_generate_audio(backend, cmd: dict, resp_queue: Any, cancel_event) ->
"request_id": request_id,
"outputs": outputs,
"sample_rate": 44100,
+ **_audio_runtime(backend),
},
)
logger.info("Finished audio separation for request_id=%s", request_id)
@@ -1875,6 +1881,10 @@ def _handle_generate_audio(backend, cmd: dict, resp_queue: Any, cancel_event) ->
elif isinstance(exc, AudioBackendUnsupportedError):
response["code"] = AUDIO_UNSUPPORTED_CODE
response["hint"] = exc.hint
+ from core.inference.audio_cpp_failures import failure_of
+
+ if failure_of(exc) is not None:
+ response["failure"] = failure_of(exc).payload()
_send_response(resp_queue, response)
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 4272137079a..4d7756ee739 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -1526,6 +1526,14 @@ class _InferenceRuntimeFields(BaseModel):
"description sent as instructions)."
),
)
+ audio_request_inputs: Optional[List[str]] = Field(
+ None,
+ description = "instruct/instruction/language fields a strict audio.cpp model reads, else None.",
+ )
+ audio_device_fallback: Optional[Literal["cpu"]] = Field(
+ None,
+ description = "'cpu' when the audio.cpp model could not start on the GPU and runs on the CPU.",
+ )
audio_music: Optional[Dict[str, Any]] = Field(
None,
description = (
@@ -5912,6 +5920,17 @@ class AudioRunRequest(BaseModel):
seed: Optional[int] = Field(None, ge = -(2**63), le = 2**64 - 1)
max_tokens: Optional[int] = Field(None, ge = 1)
convert: Optional[AudioConvertParams] = None
+ # One take of a music run the page sends take by take; its clips share group_id.
+ take: Optional[int] = Field(None, ge = 1, le = 4)
+ group_id: Optional[str] = Field(None, pattern = r"^[0-9a-f]{32}$")
+
+ @model_validator(mode = "after")
+ def _take_fields(self):
+ if (self.take, self.group_id) != (None, None) and (
+ self.workflow != "music" or self.variations != 1 or None in (self.take, self.group_id)
+ ):
+ raise ValueError("take and group_id go together, for music with variations 1.")
+ return self
@model_validator(mode = "after")
def _fields_of_the_workflow(self):
@@ -5976,12 +5995,14 @@ class AudioRunClip(BaseModel):
sample_rate: int
duration_s: float
workflow: str
+ seed: Optional[int] = None
class AudioRunAudio(BaseModel):
data: str
format: str = "wav"
sample_rate: int
+ seed: Optional[int] = None
class AudioRunResponse(BaseModel):
@@ -5992,6 +6013,9 @@ class AudioRunResponse(BaseModel):
audio: Optional[AudioRunAudio] = Field(
None, description = "The audio inline, only when saving it to history failed"
)
+ ignored_options: List[str] = Field(
+ default_factory = list, description = "Sent options the model does not take; not sent"
+ )
class AudioInputRecord(BaseModel):
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 46c42ba405b..9cb54abcfc1 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -8310,7 +8310,7 @@ async def _monitored_media_request(
# .get("message") on a non-dict "error" used to raise out of this handler,
# skipping finish() and stranding the row at "running".
error = detail.get("error")
- message = error.get("message") if isinstance(error, dict) else None
+ message = error.get("message") if isinstance(error, dict) else detail.get("message")
detail = message or str(detail)
api_monitor.fail(monitor_id, str(detail))
raise
@@ -8701,6 +8701,8 @@ def _llama_runtime_fields(llama_backend: LlamaCppBackend) -> dict:
audio_workflows = None,
audio_reference_text = None,
audio_required_inputs = None,
+ audio_request_inputs = None,
+ audio_device_fallback = None,
audio_options_by_workflow = None,
audio_workflow_tasks = None,
audio_server_task = None,
@@ -11324,7 +11326,8 @@ def _audio_cpp_switch_target(requested_model: Optional[str]) -> Optional[tuple]:
# serve this one must be refused here rather than after the eviction.
problem = model_runtime_problem(model)
if problem:
- raise HTTPException(status_code = 501, detail = problem)
+ from core.inference.audio_cpp_failures import problem_http_exception
+ raise problem_http_exception(problem, model)
return (model.id, model.variant.key, model.id, False)
@@ -16614,11 +16617,7 @@ def _audio_intent_gguf_refusal(config, request) -> Optional[str]:
)
-def audio_cpp_resident_gb(package_bytes: int) -> float:
- """Resident GPU memory for an audio.cpp package: weights plus the runtime's graph and cache
- buffers. Measured TTS peaks run about 3x the q8 weights (Qwen3-TTS 0.6B: 1.9 GB file, 5.9 GB
- peak), so this errs on the side of placing the model on a card that holds it."""
- return round(package_bytes / (1024**3) * 2.5 + 1.5, 2)
+from core.inference.audio_cpp_failures import estimate_resident_gb as audio_cpp_resident_gb
def _native_audio_cpu_load(config, request) -> bool:
@@ -16653,9 +16652,14 @@ def _resident_audio_placement_matches(backend, request) -> bool:
audio_type = resident.get("audio_type")
if audio_type not in NATIVE_AUDIO_TYPES:
return True
- return bool(resident.get("audio_cpu", False)) == audio_load_runs_on_cpu(
- audio_type, getattr(request, "audio_device", None)
- )
+ device = getattr(request, "audio_device", None)
+ if resident.get("audio_device_fallback") == "cpu":
+ # Its GPU start failed: Auto would land on the CPU again, so only a pinned GPU reloads.
+ from core.inference.audio_device import audio_device_default, normalize_audio_device
+ return (
+ normalize_audio_device(device) != "gpu" if device else audio_device_default() != "gpu"
+ )
+ return bool(resident.get("audio_cpu", False)) == audio_load_runs_on_cpu(audio_type, device)
def _resident_audio_holds_no_gpu(backend) -> bool:
@@ -16694,7 +16698,8 @@ async def _preflight_native_audio_placement(
)
if problem:
# Refused here, before the orchestrator evicts the resident model for a load that cannot start.
- raise HTTPException(status_code = 501, detail = problem)
+ from core.inference.audio_cpp_failures import problem_http_exception
+ raise problem_http_exception(problem, audio_cpp_model)
if getattr(config, "is_lora", False):
raise HTTPException(
status_code = 400,
@@ -16817,10 +16822,23 @@ async def _preflight_native_audio_placement(
key = lambda item: (-item[1], item[0]),
)
if not fitting:
- raise ValueError(
+ refusal = ValueError(
"No single GPU has enough free memory for this native audio model. "
"Select a GPU with enough free memory and try again."
)
+ if audio_type in AUDIO_CPP_AUDIO_TYPES and audio_cpp_model is not None:
+ from core.inference.audio_cpp_failures import (
+ attach_failure,
+ classify_audio_cpp_failure,
+ )
+
+ free_by_gpu = availability.effective_free_gb if availability is not None else {}
+ free = [gb for index, gb in free_by_gpu.items() if index in candidates]
+ failure = classify_audio_cpp_failure(
+ str(refusal), model = audio_cpp_model, free_gb = max(free, default = None)
+ )
+ attach_failure(refusal, failure)
+ raise refusal
resolved = [fitting[0][0]]
if automatic and availability is not None and resolved and len(resolved) == 1:
selected_gpu = resolved[0]
@@ -16837,7 +16855,11 @@ async def _preflight_native_audio_placement(
try:
resolved, required_gb, post_handoff_free_gb = await asyncio.to_thread(_resolve)
except ValueError as exc:
- raise HTTPException(status_code = 400, detail = str(exc)) from exc
+ from core.inference.audio_cpp_failures import failure_of
+
+ failure = failure_of(exc)
+ detail = failure.detail() if failure is not None else str(exc)
+ raise HTTPException(status_code = 400, detail = detail) from exc
return placement._replace(
resolved_gpu_ids = resolved,
native_required_gb = required_gb,
@@ -18591,6 +18613,9 @@ async def load_model_gated(
def _ran_out_of_memory(exc: HTTPException) -> bool:
+ if isinstance(exc.detail, dict): # a classified audio.cpp failure
+ # Out of CPU RAM: evicting GPU models frees none of it.
+ return exc.detail.get("code") == "out_of_memory" and exc.detail.get("device") != "cpu"
return exc.status_code == 500 and "out of memory" in str(exc.detail).lower()
@@ -20234,6 +20259,8 @@ async def _load_model_impl(
audio_convert = _model_info.get("audio_convert"),
audio_convert_route = _model_info.get("audio_convert_route"),
audio_required_inputs = _model_info.get("audio_required_inputs"),
+ audio_request_inputs = _model_info.get("audio_request_inputs"),
+ audio_device_fallback = _model_info.get("audio_device_fallback"),
audio_music = _model_info.get("audio_music"),
is_mlx = bool(_model_info.get("is_mlx", False)),
mlx_kv_quant = _model_info.get("mlx_kv_quant"),
@@ -20301,9 +20328,18 @@ async def _load_model_impl(
logger.warning("GGUF runtime missing while loading '%s': %s", model_log_label, e)
raise HTTPException(status_code = 400, detail = str(e))
except Exception as e:
+ from core.inference.audio_cpp_failures import failure_of
from core.inference.gpu_arbiter import DECISIONS, GpuOwnerBusyError
from utils.transformers_version import SidecarSwapInProgress
+ if (failure := failure_of(e)) is not None:
+ logger.warning(
+ "Load of '%s' failed (%s): %s",
+ model_log_label,
+ failure.code,
+ redact_native_paths(str(e)),
+ )
+ raise HTTPException(status_code = failure.status, detail = failure.detail()) from e
if isinstance(e, account_access.GpuBusyForAnotherAccountError):
raise account_access.gpu_busy_error() from e
if isinstance(e, GpuOwnerBusyError) and e.owner == DECISIONS:
@@ -23054,6 +23090,8 @@ async def _slot_status(current_subject: str):
audio_convert_route = model_info.get("audio_convert_route"),
audio_reference_text = model_info.get("audio_reference_text"),
audio_required_inputs = model_info.get("audio_required_inputs"),
+ audio_request_inputs = model_info.get("audio_request_inputs"),
+ audio_device_fallback = model_info.get("audio_device_fallback"),
audio_music = model_info.get("audio_music"),
gguf_variant = model_info.get("gguf_variant"),
is_mlx = bool(model_info.get("is_mlx", False)),
@@ -23535,6 +23573,11 @@ async def _generate_tts_wav(
# An idle auto-unload cancels through the backend without setting this route's event.
if _audio_cancel.is_set() or isinstance(e, AudioGenerationCancelledError):
raise HTTPException(status_code = 499, detail = "Audio generation cancelled")
+ from core.inference.audio_cpp_failures import failure_of
+
+ if (failure := failure_of(e)) is not None:
+ logger.warning("Audio generation failed (%s): %s", failure.code, e)
+ raise HTTPException(status_code = failure.status, detail = failure.detail())
# Missing capability, not a failure: no retry helps, and the message
# carries no path or user input, so send it as written.
if isinstance(e, AudioBackendUnsupportedError):
@@ -23712,8 +23755,10 @@ async def generate_audio(
)
record = None
if persist:
+ seed = _audio_stats(tts_stats).get("seed")
+ meta = {"settings": {"seed": seed}} if seed is not None else None
record = await asyncio.to_thread(
- _persist_tts_clip, wav_bytes, sample_rate, text, model_name, audio_type
+ _persist_tts_clip, wav_bytes, sample_rate, text, model_name, audio_type, meta
)
return record, wav_bytes, sample_rate, model_name
@@ -23730,6 +23775,7 @@ async def generate_audio(
persisted_clip, wav_bytes, sample_rate, model_name = await generate()
api_monitor.relabel(monitor_id, model_name)
truncated = bool((tts_stats.get("stats") or {}).get("truncated"))
+ stats = _audio_stats(tts_stats)
audio_b64 = base64.b64encode(wav_bytes).decode("ascii")
return JSONResponse(
@@ -23738,6 +23784,8 @@ async def generate_audio(
"object": "chat.completion.audio",
"model": model_name,
"clip_id": persisted_clip.get("id") if persisted_clip else None,
+ "seed": stats.get("seed"),
+ "ignored_options": list(stats.get("ignored_options") or []),
"audio": {"data": audio_b64, "format": "wav", "sample_rate": sample_rate},
"choices": [
{
@@ -23778,8 +23826,17 @@ def _convert_role_error(exc, role: str):
return exc
-def _audio_run_settings(body: AudioRunRequest, reference_text_used: bool) -> dict[str, Any]:
- """The run's recipe for history: scalar options only."""
+def _audio_stats(holder: dict) -> dict[str, Any]:
+ stats = holder.get("stats")
+ return stats if isinstance(stats, dict) else {}
+
+
+def _audio_run_settings(
+ body: AudioRunRequest,
+ reference_text_used: bool,
+ seed: Optional[int] = None,
+) -> dict[str, Any]:
+ """The run's recipe for history: scalar options only, and the seed the run used."""
options = {
str(name): value
for name, value in (body.options or {}).items()
@@ -23791,6 +23848,7 @@ def _audio_run_settings(body: AudioRunRequest, reference_text_used: bool) -> dic
"options": options,
"reference_text_used": reference_text_used,
"speed": body.speed,
+ "seed": seed,
}
@@ -23816,6 +23874,7 @@ def _audio_run_clip(record: dict[str, Any], role: str = "output") -> dict[str, A
return {
"role": role,
**{k: record[k] for k in ("id", "url", "sample_rate", "duration_s", "workflow")},
+ "seed": (record.get("settings") or {}).get("seed"),
}
@@ -23825,14 +23884,21 @@ def _audio_run_response(
sample_rate: int,
model_name: str,
sources: list[dict[str, Any]] = (),
+ stats: Optional[dict] = None,
) -> AudioRunResponse:
"""The clips a run made; the WAV inline when history could not keep it."""
import base64
+ ignored = list((stats or {}).get("ignored_options") or [])
if record is None:
audio = {"data": base64.b64encode(wav_bytes).decode("ascii"), "sample_rate": sample_rate}
- return AudioRunResponse(clips = list(sources), model = model_name, audio = audio)
- return AudioRunResponse(clips = [_audio_run_clip(record), *sources], model = model_name)
+ audio["seed"] = (stats or {}).get("seed")
+ return AudioRunResponse(
+ clips = list(sources), model = model_name, audio = audio, ignored_options = ignored
+ )
+ return AudioRunResponse(
+ clips = [_audio_run_clip(record), *sources], model = model_name, ignored_options = ignored
+ )
async def _run_audio_edit(
@@ -23881,6 +23947,7 @@ async def _run_audio_edit(
audio_options = body.options,
seed = body.seed,
)
+ stats: dict = {}
wav_bytes, sample_rate, model_name, audio_type = await _generate_tts_wav(
body.text,
payload,
@@ -23895,6 +23962,7 @@ async def _run_audio_edit(
"text": body.text,
},
requested_model = body.model or _RELOAD_ONLY_MODEL,
+ stats_holder = stats,
)
source_record = None
try:
@@ -23924,7 +23992,9 @@ async def _run_audio_edit(
"edit",
)
sources = [_audio_run_clip(source_record, "source")] if source_record is not None else []
- return _audio_run_response(record, wav_bytes, sample_rate, model_name, sources)
+ return _audio_run_response(
+ record, wav_bytes, sample_rate, model_name, sources, _audio_stats(stats)
+ )
_REPAINT_BEYOND_END_S = 30.0
@@ -24169,6 +24239,8 @@ async def _run_music_workflow(
"instrumental": body.instrumental,
"duration_s": seconds,
"variations": variations,
+ # 0-based: the backend seeds take n with seed + n.
+ "take": body.take - 1 if body.take else None,
"edit": body.edit.model_dump() if body.edit is not None else None,
"timeout_s": timeout_seconds(
family, work_s, variations, model_info.get("audio_cpp_backend")
@@ -24182,6 +24254,7 @@ async def _run_music_workflow(
audio_options = body.options,
seed = body.seed,
)
+ stats: dict = {}
wav_bytes, sample_rate, model_name, audio_type = await _generate_tts_wav(
body.text,
payload,
@@ -24193,14 +24266,17 @@ async def _run_music_workflow(
"music": music,
"output_dir": str(run_dir),
},
+ stats_holder = stats,
)
outputs = await asyncio.to_thread(_read_music_outputs, run_dir)
finally:
await asyncio.to_thread(shutil.rmtree, run_dir, ignore_errors = True)
if not outputs:
- outputs = [(wav_bytes, sample_rate, body.seed)]
- group_id = uuid.uuid4().hex if len(outputs) > 1 else None
- role = "edit" if body.mode == "edit" else ("variation" if len(outputs) > 1 else "output")
+ outputs = [(wav_bytes, sample_rate, _audio_stats(stats).get("seed", body.seed))]
+ ignored = list(_audio_stats(stats).get("ignored_options") or [])
+ many = len(outputs) > 1 or body.take is not None
+ group_id = body.group_id or (uuid.uuid4().hex if len(outputs) > 1 else None)
+ role = "edit" if body.mode == "edit" else ("variation" if many else "output")
prompt = body.text.strip() or " ".join((body.lyrics or "").split())[:200]
clips = []
for index, (wav, rate, seed) in enumerate(outputs):
@@ -24208,7 +24284,7 @@ async def _run_music_workflow(
"role": role,
"group_id": group_id,
"settings": _audio_music_settings(
- body, seconds, seed, index + 1 if len(outputs) > 1 else None, song
+ body, seconds, seed, (body.take or index + 1) if many else None, song
),
}
if source is not None:
@@ -24227,7 +24303,9 @@ async def _run_music_workflow(
"data": base64.b64encode(wav).decode("ascii"),
"format": "wav",
"sample_rate": rate,
+ "seed": seed,
},
+ ignored_options = ignored,
)
continue
clips.append(
@@ -24238,9 +24316,12 @@ async def _run_music_workflow(
"sample_rate": record["sample_rate"],
"duration_s": record["duration_s"],
"workflow": record["workflow"],
+ "seed": seed,
}
)
- return AudioRunResponse(clips = clips, group_id = group_id, model = model_name)
+ return AudioRunResponse(
+ clips = clips, group_id = group_id, model = model_name, ignored_options = ignored
+ )
async def _run_audio_convert(
@@ -24303,6 +24384,7 @@ async def _run_audio_convert(
audio_options = body.options,
seed = body.seed,
)
+ stats: dict = {}
wav_bytes, sample_rate, model_name, audio_type = await _generate_tts_wav(
source.name,
payload,
@@ -24316,6 +24398,7 @@ async def _run_audio_convert(
"prepare_audio_inputs": _prepare,
},
requested_model = body.model or _RELOAD_ONLY_MODEL,
+ stats_holder = stats,
)
builtin = None
if target is not None:
@@ -24355,7 +24438,9 @@ async def _run_audio_convert(
# An upload expires within a day; a history clip does not.
(seen.get("paths") or {}).get("source") if source.kind == "input" else None,
)
- return _audio_run_response(record, wav_bytes, sample_rate, model_name)
+ return _audio_run_response(
+ record, wav_bytes, sample_rate, model_name, stats = _audio_stats(stats)
+ )
@router.post("/audio/run", response_model = AudioRunResponse)
@@ -24404,10 +24489,15 @@ async def _dispatch_audio_run(
status_code = 400,
detail = "A music mode, lyrics, variations, a source clip and edits apply to Music only.",
)
+ stats: dict = {}
record, wav_bytes, sample_rate, model_name = await _speak(
- body, request, current_subject, requested_model = body.model or _RELOAD_ONLY_MODEL
+ body,
+ request,
+ current_subject,
+ requested_model = body.model or _RELOAD_ONLY_MODEL,
+ stats_holder = stats,
)
- return _audio_run_response(record, wav_bytes, sample_rate, model_name)
+ return _audio_run_response(record, wav_bytes, sample_rate, model_name, [], _audio_stats(stats))
async def _speak(
@@ -24456,6 +24546,7 @@ async def _speak(
audio_options = body.options,
seed = body.seed,
)
+ stats = tts_kwargs.setdefault("stats_holder", {})
wav_bytes, sample_rate, model_name, audio_type = await _generate_tts_wav(
body.text,
payload,
@@ -24473,7 +24564,9 @@ async def _speak(
return None, wav_bytes, sample_rate, model_name
extra_meta: dict[str, Any] = {
"role": "output",
- "settings": _audio_run_settings(body, reference_text is not None),
+ "settings": _audio_run_settings(
+ body, reference_text is not None, _audio_stats(stats).get("seed")
+ ),
}
if reference_source is not None:
extra_meta["reference_name"] = reference_source.name
@@ -24695,6 +24788,11 @@ async def _run_separation(
raise HTTPException(status_code = 499, detail = "Audio generation cancelled")
if isinstance(e, AudioBackendUnsupportedError):
raise HTTPException(status_code = 501, detail = e.message)
+ from core.inference.audio_cpp_failures import failure_of
+
+ if (failure := failure_of(e)) is not None:
+ logger.warning("Audio separation failed: %s", failure.code)
+ raise HTTPException(status_code = failure.status, detail = failure.detail())
if isinstance(e, AudioRuntimeError):
status_code, detail = audio_runtime_http_error(e)
logger.warning("Audio separation refused by the runtime: %s", e)
diff --git a/studio/backend/tests/fixtures/audio_cpp_option_golden.json b/studio/backend/tests/fixtures/audio_cpp_option_golden.json
index 16322ca5dda..fa73e61199a 100644
--- a/studio/backend/tests/fixtures/audio_cpp_option_golden.json
+++ b/studio/backend/tests/fixtures/audio_cpp_option_golden.json
@@ -94,7 +94,7 @@
{"exclude":[],"include":{"speed":{"default":1.0},"text_chunk_mode":{"default":"default"},"text_chunk_size":{"default":400},"voice":{"default":"Leo"}},"optional":{},"workflow":"speak"}
],
"audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF": [
- {"exclude":["language","return_timestamps","seed"],"include":{"speed":{"default":1.0},"text_chunk_size":{"default":240},"voice":{"default":"af_heart"}},"optional":{},"workflow":"speak"}
+ {"exclude":["language","return_timestamps"],"include":{"speed":{"default":1.0},"text_chunk_size":{"default":240},"voice":{"default":"af_heart"}},"optional":{},"workflow":"speak"}
],
"audio-cpp/audio.cpp-gguf/KugelAudio-0-Open-GGUF": [
{"exclude":[],"include":{"do_sample":{"default":false},"guidance_scale":{"default":3.0},"max_tokens":{"default":2048},"num_inference_steps":{"default":20},"temperature":{"default":1.0},"text_chunk_mode":{"default":"default"},"text_chunk_size":{"default":300},"voice":{"default":"default"}},"optional":{"voice_id":{"default":"default"}},"workflow":"speak"}
@@ -133,7 +133,7 @@
{"exclude":["voice"],"include":{"audio_chunk_duration":{"default":15.0},"audio_chunk_threshold":{"default":30.0},"class_temperature":{"default":0.0},"denoise":{"default":true},"guidance_scale":{"default":2.0},"layer_penalty_factor":{"default":5.0},"num_inference_steps":{"default":32},"position_temperature":{"default":5.0},"postprocess_output":{"default":true},"preprocess_prompt":{"default":true},"speed":{"default":1.0},"t_shift":{"default":0.1}},"optional":{"duration":{"default":null}},"workflow":"clone"}
],
"audio-cpp/audio.cpp-gguf/Piper-TTS-GGUF": [
- {"exclude":["seed"],"include":{"duration_variation":{"default":0.8},"speed":{"default":1.0},"text_chunk_mode":{"default":"default"},"text_chunk_size":{"default":280},"variation":{"default":0.667}},"optional":{},"workflow":"speak"}
+ {"exclude":[],"include":{"duration_variation":{"default":0.8},"speed":{"default":1.0},"text_chunk_mode":{"default":"default"},"text_chunk_size":{"default":280},"variation":{"default":0.667}},"optional":{},"workflow":"speak"}
],
"audio-cpp/audio.cpp-gguf/PocketTTS-GGUF": [
{"exclude":[],"include":{"eos_threshold":{"default":-4.0},"frames_after_eos":{"default":-1}},"optional":{"noise_clamp":{"default":null},"temperature":{"default":null},"voice":{"default":"alba"}},"workflow":"speak"},
diff --git a/studio/backend/tests/test_audio_cpp_clone_requests.py b/studio/backend/tests/test_audio_cpp_clone_requests.py
index 8728c36f044..2983beca4c3 100644
--- a/studio/backend/tests/test_audio_cpp_clone_requests.py
+++ b/studio/backend/tests/test_audio_cpp_clone_requests.py
@@ -386,3 +386,10 @@ def test_miotts_downloads_mio_codec_and_starts_with_its_path(monkeypatch, tmp_pa
assert entry["task"] == "tts"
kokoro = MODELS["kokoro"]()
assert acb._with_companions(kokoro) is kokoro
+
+
+def test_a_blank_clone_seed_is_picked_by_the_server(monkeypatch):
+ monkeypatch.setattr(acb.cm, "random_seed", lambda: 99)
+ backend, server = _backend(MODELS["chatterbox"]())
+ backend.generate_audio_response(TEXT, workflow = "clone", audio_inputs = {"reference": REF})
+ assert server.calls[-1][1]["seed"] == "99" and backend.last_generation_stats["seed"] == 99
diff --git a/studio/backend/tests/test_audio_cpp_failure_routes.py b/studio/backend/tests/test_audio_cpp_failure_routes.py
new file mode 100644
index 00000000000..817b9a0761d
--- /dev/null
+++ b/studio/backend/tests/test_audio_cpp_failure_routes.py
@@ -0,0 +1,192 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A classified failure reaches the client as {"detail": {"code", "message", ...}}; anything
+unclassified keeps today's status and text."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from fastapi import FastAPI, HTTPException
+from fastapi.testclient import TestClient
+
+import routes.inference as ri
+from core.inference import audio_cpp_failures as af
+from core.inference import audio_cpp_server as srv
+from models.inference import ChatCompletionRequest, LoadRequest
+from .test_audio_cpp_failures import _model
+
+_MISSING = "The audio runtime is not installed. Run `unsloth studio update` to install it."
+
+
+def _oom() -> af.AudioCppFailure:
+ return af.classify_audio_cpp_failure("cudaMalloc failed: out of memory", backend = "cuda")
+
+
+def _load(side_effect) -> HTTPException:
+ request = LoadRequest(model_path = "audio-cpp/audio.cpp-gguf/M-GGUF")
+ with (
+ patch.object(
+ ri,
+ "_resolve_model_identifier_for_request",
+ return_value = (request.model_path,) * 2 + (False,),
+ ),
+ patch.object(ri, "resolve_effective_chat_template_override", return_value = None),
+ patch.object(ri, "get_inference_backend", return_value = MagicMock(active_model_name = None)),
+ patch.object(ri, "get_llama_cpp_backend", return_value = MagicMock()),
+ patch.object(ri.ModelConfig, "from_identifier", side_effect = side_effect),
+ ):
+ with pytest.raises(HTTPException) as raised:
+ asyncio.run(ri.load_model(request, MagicMock(), current_subject = "test-user"))
+ return raised.value
+
+
+def test_load_detail_is_structured_when_classified_else_500_prefix():
+ error = _load(af.AudioCppFailureError("Failed to load model", _oom()))
+ assert error.status_code == 503 and error.detail["code"] == "out_of_memory"
+ assert "ran out of memory" in error.detail["message"]
+ error = _load(RuntimeError("totally different failure"))
+ assert error.status_code == 500 and error.detail.startswith("Failed to load model: ")
+
+
+def test_deferred_load_error_keeps_dict_detail(monkeypatch):
+ monkeypatch.setattr(ri, "_TUNNEL_KEEPALIVE_AFTER_S", 0.05)
+ monkeypatch.setattr(ri, "_TUNNEL_KEEPALIVE_EVERY_S", 0.02)
+ detail = _oom().detail()
+
+ async def slow_boom():
+ await asyncio.sleep(0.2)
+ raise HTTPException(status_code = 503, detail = detail)
+
+ async def run():
+ response = await ri._tunnel_safe_json(slow_boom(), label = "t")
+ return b"".join([chunk async for chunk in response.body_iterator])
+
+ body = json.loads(asyncio.run(run()))
+ assert body["_deferred_error"] == {"status_code": 503, "detail": detail}
+
+
+def test_v1_path_maps_detail_code_to_openai_error_code():
+ from utils.api_errors import install_api_error_handlers
+
+ app = FastAPI()
+ install_api_error_handlers(app)
+
+ @app.post("/v1/audio/speech")
+ async def speech():
+ raise af.problem_http_exception(_MISSING)
+
+ response = TestClient(app).post("/v1/audio/speech")
+ assert response.status_code == 503
+ error = response.json()["error"]
+ assert error["code"] == "runtime_missing" and "isn't installed" in error["message"]
+
+
+def _preflight(
+ problem,
+ *,
+ availability = None,
+ prepared = None,
+):
+ import utils.hardware as hardware
+
+ model = _model()
+ config = SimpleNamespace(identifier = model.id, audio_type = "audiocpp_tts", audio_cpp = model)
+ request = SimpleNamespace(gpu_ids = None, hf_token = None, max_seq_length = 2048, audio_device = None)
+ placement = ri._LoadPlacement(None, None, False, False)
+ with (
+ patch.object(srv, "model_runtime_problem", lambda _model: problem),
+ patch.object(ri, "_native_audio_cpu_load", lambda *_a: False),
+ patch.object(ri, "_native_audio_post_handoff_free_gb", lambda: availability),
+ patch("utils.hardware.get_device", return_value = hardware.DeviceType.CUDA),
+ patch.object(hardware, "IS_ROCM", False),
+ patch("core.inference.native_audio.native_audio_security_targets", return_value = [model.id]),
+ patch("utils.hardware.prepare_gpu_selection", return_value = prepared or ([0], {})),
+ ):
+ return asyncio.run(ri._preflight_native_audio_placement(config, request, placement))
+
+
+ "problem, status, detail",
+ [
+ (_MISSING, 503, "runtime_missing"),
+ ("The audio runtime is being updated. Try again in a moment.", 501, None),
+ ],
+)
+def test_preflight_problem_is_503_with_code_else_501_string(problem, status, detail):
+ with pytest.raises(HTTPException) as raised:
+ _preflight(problem)
+ assert raised.value.status_code == status
+ assert (
+ raised.value.detail == problem if detail is None else raised.value.detail["code"] == detail
+ )
+
+
+def test_placement_refusal_lists_variants_that_fit(monkeypatch):
+ monkeypatch.setattr(af, "offload_options", lambda model: [])
+ availability = ri._NativeAudioAvailability({0: 7.0, 1: 5.0}, {0: 0.0, 1: 0.0})
+ with pytest.raises(HTTPException) as raised:
+ _preflight(
+ None, availability = availability, prepared = ([0, 1], {"selection_mode": "fallback_all"})
+ )
+ detail = raised.value.detail
+ assert ri.audio_cpp_resident_gb is af.estimate_resident_gb
+ assert raised.value.status_code == 400 and detail["code"] == "out_of_memory"
+ assert [row["label"] for row in detail["smaller_variants"]] == ["Q2", "Q1"]
+ assert detail["message"].startswith("No single GPU has enough free memory for Model M.")
+
+
+def test_generation_crash_oom_maps_to_out_of_memory(monkeypatch):
+ tail = "ggml_gallocr_reserve_n: failed to allocate CUDA0 buffer of size 9663676416"
+ crash = af.attach_failure(
+ srv.AudioCppUnavailableError("The audio runtime stopped while serving the request."),
+ af.classify_audio_cpp_failure(tail, backend = "cuda"),
+ )
+
+ model = "audio-cpp/audio.cpp-gguf/M-GGUF"
+ backend = SimpleNamespace(
+ active_model_name = model,
+ models = {model: {"is_audio": True, "audio_type": "audiocpp_tts"}},
+ generate_audio_response = MagicMock(side_effect = crash),
+ )
+ monkeypatch.setattr(
+ ri, "get_llama_cpp_backend", lambda: SimpleNamespace(is_loaded = False, _is_audio = False)
+ )
+ monkeypatch.setattr(ri, "get_inference_backend", lambda: backend)
+ monkeypatch.setattr(ri, "_maybe_auto_switch_model", AsyncMock(return_value = None))
+ payload = ChatCompletionRequest(model = model, messages = [{"role": "user", "content": "hello"}])
+ with pytest.raises(HTTPException) as raised:
+ asyncio.run(ri._generate_tts_wav("hello", payload, request = None, current_subject = "t"))
+ assert raised.value.status_code == 503 and raised.value.detail["code"] == "out_of_memory"
+
+
+def test_oom_retry_and_monitor_read_the_structured_detail(monkeypatch):
+ oom = HTTPException(status_code = 503, detail = _oom().detail())
+ assert ri._ran_out_of_memory(oom)
+ other = af.classify_audio_cpp_failure("model path does not exist: /m", backend = "cuda")
+ assert not ri._ran_out_of_memory(HTTPException(status_code = 422, detail = other.detail()))
+ # Out of CPU RAM: unloading kept GPU models cannot make room, so no eviction retry.
+ cpu = af.classify_audio_cpp_failure(
+ "failed to allocate CPU buffer of size 9663676416", backend = "cpu"
+ )
+ assert cpu.extras == {"device": "cpu"}
+ assert not ri._ran_out_of_memory(HTTPException(status_code = 503, detail = cpu.detail()))
+ monitor = MagicMock()
+ monkeypatch.setattr(ri, "api_monitor", monitor)
+ monkeypatch.setattr(ri, "_request_used_api_key", lambda request: False)
+ request = SimpleNamespace(
+ state = SimpleNamespace(), url = SimpleNamespace(path = "/x"), method = "POST"
+ )
+
+ async def run():
+ async with ri._monitored_media_request(request, model = "m", prompt = "", subject = None):
+ raise oom
+
+ with pytest.raises(HTTPException):
+ asyncio.run(run())
+ assert monitor.fail.call_args.args[1] == oom.detail["message"]
diff --git a/studio/backend/tests/test_audio_cpp_failures.py b/studio/backend/tests/test_audio_cpp_failures.py
new file mode 100644
index 00000000000..c37efd9d71e
--- /dev/null
+++ b/studio/backend/tests/test_audio_cpp_failures.py
@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Each runtime string below is copied from audio.cpp v0.9.2 (`git grep` at that tag finds it), so
+a reworded upstream message shows up here rather than as a silently generic error."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+
+from core.inference import audio_cpp_failures as af
+from core.inference.audio_cpp_models import AudioCppModel, AudioCppVariant, RepoFile
+
+
+def _model(sizes = (8, 4, 3, 2, 1), current = 0) -> AudioCppModel:
+ variants = tuple(
+ AudioCppVariant(f"Q{gb}", (RepoFile(f"m-q{gb}.gguf", gb * 1024**3),), f"m-q{gb}.gguf")
+ for gb in sizes
+ )
+ return AudioCppModel(
+ id = "audio-cpp/audio.cpp-gguf/M-GGUF",
+ repo_id = "audio-cpp/audio.cpp-gguf",
+ folder = "M-GGUF",
+ display_name = "Model M",
+ family = "qwen3_tts",
+ task = "tts",
+ server_task = "tts",
+ variant = variants[current],
+ variants = variants,
+ default_variant = variants[current].key,
+ )
+
+
+ "text, backend, code",
+ [
+ ("Could not load eSpeak-ng; install the shared library", None, "espeak_missing"),
+ ("eSpeak-ng failed to initialize; check its data directory", None, "espeak_missing"),
+ ("eSpeak data package missing phontab", None, "espeak_missing"),
+ ("unsupported model family hint: fish_drama3", None, "family_unknown_to_runtime"),
+ ("no registered model loader can load: /m/x.gguf", None, "family_unknown_to_runtime"),
+ ("CUDA backend requested but registry 'CUDA' has no device 0", "cuda", "gpu_unavailable"),
+ ("Failed to initialize Vulkan backend on device 0", "vulkan", "gpu_unavailable"),
+ (
+ "ggml_cuda_init: failed to initialize CUDA: no CUDA-capable device",
+ "cuda",
+ "gpu_unavailable",
+ ),
+ ("ggml_vulkan: No devices found.", "vulkan", "gpu_unavailable"),
+ ("failed to allocate CUDA0 backend weight buffer", "cuda", "out_of_memory"),
+ (
+ "ggml_gallocr_reserve_n: failed to allocate CUDA0 buffer of size 9663676416",
+ "cuda",
+ "out_of_memory",
+ ),
+ (
+ "alloc: allocating 9216.00 MiB on device 0: cudaMalloc failed: out of memory",
+ "cuda",
+ "out_of_memory",
+ ),
+ ("CUDA error: out of memory\n current device: 0", "cuda", "out_of_memory"),
+ ("ggml_vulkan: Device memory allocation of size 123 failed.", "vulkan", "out_of_memory"),
+ (
+ "LFM2-Audio prefill graph does not fit in device memory at 9 prompt steps",
+ "cuda",
+ "out_of_memory",
+ ),
+ (
+ "cannot load model 'm': estimated 9 GiB + 512 MiB headroom exceeds available CUDA memory",
+ None,
+ "out_of_memory",
+ ),
+ ("gguf_init_from_file_impl: failed to read magic", None, "file_incomplete"),
+ (
+ "gguf_init_from_file_impl: invalid magic characters: 'xxxx', expected 'GGUF'",
+ None,
+ "file_incomplete",
+ ),
+ ("gguf_init_from_file_impl: failed to read tensor data", None, "file_incomplete"),
+ ("failed to read GGUF metadata: /m/x.gguf", None, "file_incomplete"),
+ ("tensor data range is out of bounds: blk.0.attn_q.weight", None, "file_incomplete"),
+ ("model path does not exist: /m/x.gguf", None, "file_incomplete"),
+ # A CUDA build logs its init failure on CPU launches too.
+ ("ggml_cuda_init: failed to initialize CUDA: no CUDA-capable device", "cpu", None),
+ ("failed to allocate GGUF context", "cuda", None),
+ ("Failed to initialize GGML context for Granite 5 ASR encoder", "cuda", None),
+ ("CosyVoice3 requires reference audio", "cuda", None),
+ # A refused request that only mentions eSpeak keeps the runtime's own reason.
+ ("zipvoice: tokenizer must be espeak, emilia, or simple", "cuda", None),
+ ("Inflect v2 eSpeak-ng produced no phonemes", "cuda", None),
+ ("The audio runtime is being updated. Try again in a moment.", "cuda", None),
+ ("", "cuda", None),
+ ],
+)
+def test_classifies_upstream_runtime_strings(text, backend, code):
+ failure = af.classify_audio_cpp_failure(text, backend = backend, model = _model())
+ if code is None:
+ assert failure is None
+ return
+ assert failure.code == code and "/m/" not in failure.message
+ detail = failure.detail()
+ assert {"code", "message"} <= detail.keys() and not {"error", "type"} & detail.keys()
+ assert af.AudioCppFailure.from_payload(failure.payload()) == failure
+
+
+def test_studio_runtime_messages_classify(tmp_path, monkeypatch):
+ from core.inference import audio_cpp_models as models
+ from core.inference import audio_cpp_server as srv
+
+ monkeypatch.setattr(srv, "find_audio_cpp_server_binary", lambda: None)
+ missing = srv.model_runtime_problem(_model())
+ assert af.classify_audio_cpp_failure(missing).code == "runtime_missing"
+ binary = tmp_path / srv.BINARY_NAME
+ binary.write_bytes(b"x")
+ kokoro = replace(_model(), needs_espeak = True)
+ espeak = af.classify_audio_cpp_failure(srv.model_runtime_problem(kokoro, str(binary)))
+ assert espeak.code == "espeak_missing" and espeak.status == 503
+ monkeypatch.setattr(models, "runtime_knows_family", lambda family: False)
+ policy = models._family_from_spec_tasks("new_tts", {"tasks": ["tts"]}, "New TTS")
+ newer = af.classify_audio_cpp_failure(policy.unsupported, model = _model())
+ assert newer.code == "family_unknown_to_runtime" and "Model M" in newer.message
+
+
+def test_oom_lists_smaller_variants_and_offload_options(monkeypatch):
+ from core.inference import audio_cpp_models as models
+
+ monkeypatch.setattr(models, "runtime_spec", lambda family: None)
+ model = _model(sizes = (4, 8, 3, 2, 1), current = 0)
+ failure = af.classify_audio_cpp_failure(
+ "cudaMalloc failed: out of memory", backend = "cuda", model = model
+ )
+ rows = failure.extras["smaller_variants"]
+ assert [row["label"] for row in rows] == [
+ "Q3",
+ "Q2",
+ "Q1",
+ ] and "offload_options" not in failure.extras
+ assert rows[0] == {
+ "variant": model.variants[2].key,
+ "label": "Q3",
+ "size_bytes": 3 * 1024**3,
+ "estimate_gb": af.estimate_resident_gb(3 * 1024**3),
+ }
+ assert "Smaller variants: Q3 (~9.0 GB)" in failure.message and failure.status == 503
+ fits = af.smaller_variants(model, free_gb = af.estimate_resident_gb(2 * 1024**3))
+ assert [row["label"] for row in fits] == ["Q2", "Q1"]
+ assert af.smaller_variants(_model(current = 4)) == []
+ on_cpu = af.classify_audio_cpp_failure(
+ "failed to allocate CPU buffer of size 9", backend = "cpu", model = model
+ )
+ assert on_cpu.extras["device"] == "cpu" and "GPU" not in on_cpu.message.split(" Smaller")[0]
+ assert af.AudioCppFailure.from_payload(on_cpu.payload()) == on_cpu
+ text = "LFM2-Audio prefill graph does not fit in device memory at 9 prompt steps"
+ capacity = af.classify_audio_cpp_failure(text, backend = "cuda", runtime_status = 400)
+ assert (capacity.code, capacity.status, capacity.extras) == ("out_of_memory", 400, {})
+ assert af.AudioCppFailure.from_payload(capacity.payload()) == capacity
+ cpu = af.classify_audio_cpp_failure(text, backend = "cpu", runtime_status = 400)
+ assert cpu.extras == {"device": "cpu"} and "CPU" not in cpu.message
+ session = [{"name": "context_length", "type": "int"}]
+ monkeypatch.setattr(models, "runtime_spec", lambda family: {"options": {"session": session}})
+ assert af.offload_options(_model()) == []
+ session += [
+ {"name": "cpu_expert_layers", "type": "int"},
+ {"name": "disk_experts", "type": "bool"},
+ ]
+ failure = af.classify_audio_cpp_failure(
+ "cuda error: out of memory", backend = "cuda", model = _model()
+ )
+ assert failure.extras["offload_options"] == ["cpu_expert_layers", "disk_experts"]
+ assert "set cpu_expert_layers or disk_experts" in failure.message
+ assert (
+ af.failure_of(af.AudioCppFailureError("boom", failure)) is failure
+ and af.failure_of(KeyError()) is None
+ )
+ assert (
+ af.AudioCppFailure.from_payload({"code": "nope"})
+ is af.AudioCppFailure.from_payload(None)
+ is None
+ )
diff --git a/studio/backend/tests/test_audio_cpp_models.py b/studio/backend/tests/test_audio_cpp_models.py
index 1de9bf1e4c9..b288778cf31 100644
--- a/studio/backend/tests/test_audio_cpp_models.py
+++ b/studio/backend/tests/test_audio_cpp_models.py
@@ -1652,6 +1652,7 @@ def test_status_fields_of_a_loaded_model():
"speed",
"text_chunk_size",
"mode",
+ "seed",
]
@@ -3136,3 +3137,88 @@ def test_exact_audio_filename_path_wins_over_an_earlier_suffix_match():
exact = AudioCppVariant("chosen/Q8_0", (RepoFile(filename),), f"chosen/{filename}")
assert acm.match_variant((archived, exact), f"chosen/{filename}") is exact
+
+
+def _spec_rows(*rows):
+ return {"options": {"request": [{"type": "string", **row} for row in rows]}}
+
+
+def _names(family, spec):
+ return [o["name"] for o in acm.option_schema(acm.FAMILIES[family], spec, None)]
+
+
+def test_voice_fold_and_alias_json_rows_hidden_for_tts_only():
+ voices = {"type": "enum", "values": ["a", "b"]}
+ rows = ({"name": "voice_id", **voices}, {"name": "speaker", **voices}, {"name": "speaker_id"})
+ spec = {**_spec_rows(*rows), "ui": {"builtin_voices": ["af_heart", "am_adam"]}}
+ assert _names("kokoro_tts", spec) == ["voice", "speaker_id"]
+ # Magpie reads options.voice_id on v0.9.1, so its row stays the voice control.
+ for family in ("magpie_tts", "neutts"):
+ assert _names(family, _spec_rows(*rows)) == ["voice_id", "speaker", "speaker_id"]
+ spec = _spec_rows(
+ {"name": "lang", "description": "Alias of language."},
+ {"name": "conds", "description": "A JSON array of conditioning clips."},
+ {"name": "steps", "type": "int", "description": "JSON-free steps; Alias of nothing"},
+ {"name": "note", "description": "Plain text."},
+ )
+ assert _names("magpie_tts", spec) == ["steps", "note"]
+ music = _spec_rows({"name": "complete_track_classes", "description": "A JSON list of classes."})
+ assert _names("controlfoley", music) == ["complete_track_classes"]
+
+
+def test_audio_request_inputs_and_seed_row_follow_the_declared_keys():
+ def inputs(keys):
+ model = _speech_model("kokoro_tts", request_keys = keys and frozenset(keys))
+ return audio_cpp_backend.model_info_fields(model)["audio_request_inputs"]
+
+ assert inputs(None) is None and inputs({"speed", "seed"}) == []
+ assert inputs({"language", "instruction", "instruct", "seed"}) == [
+ "instruct",
+ "instruction",
+ "language",
+ ]
+ # VoxCPM1 lists no language option but reads the top-level one, so Clone keeps the selector.
+ voxcpm1 = _speech_model("voxcpm1", request_keys = frozenset({"seed", "max_tokens"}))
+ assert audio_cpp_backend.model_info_fields(voxcpm1)["audio_request_inputs"] == ["language"]
+ loose = _speech_model("kokoro_tts")
+ strict = _speech_model("kokoro_tts", request_keys = frozenset({"speed"}))
+ seeded = _speech_model("kokoro_tts", request_keys = frozenset({"speed", "seed"}))
+ for workflow in ("speak", "clone", "music", "edit", "convert"):
+ want = workflow in ("speak", "clone", "music")
+ assert acm.takes_seed(loose, workflow) is acm.takes_seed(seeded, workflow) is want
+ assert acm.takes_seed(strict, workflow) is False
+ (row,) = acm.workflow_options(loose, "speak")
+ assert [row[k] for k in ("name", "type", "min", "max", "default")] == [
+ "seed",
+ "int",
+ 0,
+ 2147483647,
+ None,
+ ]
+ assert acm.workflow_options(strict, "speak") == () and acm.workflow_options(loose, "edit") == ()
+
+
+ "keys, options, sent, ignored",
+ [
+ (None, {"seed": ""}, "1234", []),
+ ({"speed", "seed"}, {"seed": 42, "speed": 1.5}, "42", []),
+ ({"speed", "seed"}, {"seed": "42", "speed": 1.5}, "42", []),
+ ({"speed", "seed"}, {"seed": 42.0, "speed": 1.5}, "42", []),
+ ({"speed"}, {"seed": 5}, None, ["seed"]),
+ ({"speed", "seed"}, {"mode": "b", "bogus": 1, "speed": 1.5}, "1234", ["bogus", "mode"]),
+ (None, {"voice": "am_adam", "speed": 1.5, "mode": "b", "seed": 3}, "3", []),
+ ],
+)
+def test_seed_option_and_ignored_options(monkeypatch, keys, options, sent, ignored):
+ monkeypatch.setattr(audio_cpp_music, "random_seed", lambda: 1234)
+ schema = acm.option_schema(acm.FAMILIES["kokoro_tts"], KOKORO_SPEC, None)
+ model = _speech_model("kokoro_tts", options = schema, request_keys = keys and frozenset(keys))
+ b, srv = _backend_with(model, SPEECH_WAV)
+ typed = dict(options)
+ b.generate_audio_response("hi", audio_options = typed)
+ body = srv.calls[0][1]
+ assert typed == options and body.get("seed") == sent and "seed" not in body.get("options", {})
+ if "bogus" in options:
+ assert body["options"] == {"speed": 1.5}
+ assert b.last_generation_stats == {"seed": sent and int(sent), "ignored_options": ignored}
diff --git a/studio/backend/tests/test_audio_cpp_music_requests.py b/studio/backend/tests/test_audio_cpp_music_requests.py
index 4668724f68d..424def264a2 100644
--- a/studio/backend/tests/test_audio_cpp_music_requests.py
+++ b/studio/backend/tests/test_audio_cpp_music_requests.py
@@ -450,7 +450,7 @@ def test_stable_audio_batches_variations_as_a_string(starts, tmp_path):
"batch_size": "3",
**STABLE_AUDIO_DEFAULTS,
}
- and "seed" not in request
+ and "seed" in request
)
assert rate == 44100 and wav[:4] == b"RIFF"
manifest = json.loads((run / "outputs.json").read_text())
@@ -506,7 +506,7 @@ def test_sequential_variations_call_once_per_take_with_consecutive_seeds(tmp_pat
assert [_request(top, i)["seed"] for i in range(2)] == [str(2**31 - 1), "0"]
-def test_a_fixed_seed_family_gets_a_recorded_random_seed(tmp_path):
+def test_a_blank_seed_gets_a_recorded_random_seed(tmp_path):
b = _backend(_model("heartmula"))
_run(b, text = "pop", lyrics = "la", seed = None, output_dir = str(tmp_path))
seed = int(_request(b)["seed"])
@@ -514,7 +514,7 @@ def test_a_fixed_seed_family_gets_a_recorded_random_seed(tmp_path):
assert json.loads((tmp_path / "outputs.json").read_text())[0]["seed"] == seed
sa = _backend(_model("stable_audio", strict = False))
_run(sa, text = "house", seed = None)
- assert "seed" not in _request(sa)
+ assert int(_request(sa)["seed"]) == sa.last_generation_stats["seed"]
def test_the_wait_grows_with_the_audio_asked_for_and_is_capped():
@@ -714,3 +714,19 @@ def test_legacy_music_never_asks_past_the_page_maximum():
medium = _backend(_model("stable_audio", "Stable-Audio-3-Medium-GGUF", strict = False))
medium.generate_audio_response("ambient", instructions = "ambient", max_new_tokens = 4500)
assert _request(medium)["duration_seconds"] == 180.0
+
+
+ "seed, take, options, sent",
+ [
+ (40, 2, None, "42"),
+ (40, None, None, "40"),
+ (2**31 - 1, 1, None, "0"),
+ (None, None, {"seed": "12"}, "12"),
+ ],
+)
+def test_a_take_is_seeded_seed_plus_take_and_a_typed_seed_skips_options(seed, take, options, sent):
+ b = _backend(_model("controlfoley"))
+ _run(b, mode = "sfx", text = "door", seed = seed, take = take, options = options)
+ assert _request(b)["seed"] == sent and "seed" not in (_request(b).get("options") or {})
+ assert b.last_generation_stats == {"seed": int(sent), "ignored_options": []}
diff --git a/studio/backend/tests/test_audio_cpp_server_http.py b/studio/backend/tests/test_audio_cpp_server_http.py
index 95c7f77d4f4..7422e2b8edd 100644
--- a/studio/backend/tests/test_audio_cpp_server_http.py
+++ b/studio/backend/tests/test_audio_cpp_server_http.py
@@ -432,6 +432,95 @@ def test_other_early_exits_keep_pointing_at_the_model(fake_binary, tmp_path, out
assert "unknown tensor type 42" in message
+_GPU_FAILS = textwrap.dedent(
+ """
+ import json, sys
+ if json.load(open(sys.argv[sys.argv.index("--config") + 1], encoding="utf-8"))["backend"] != "cpu":
+ print({output!r}, flush=True)
+ sys.exit(1)
+ """
+)
+_NO_GPU = "ggml_cuda_init: failed to initialize CUDA: no CUDA-capable device is detected"
+
+
+def _backend_whose_gpu_fails(
+ tmp_path,
+ monkeypatch,
+ output,
+ preference = None,
+):
+ """The fake server exits with ``output`` unless launched on CPU."""
+ from core.inference import audio_cpp_backend as acb
+
+ (tmp_path / "fake_server.py").write_text(
+ _GPU_FAILS.format(output = output) + FAKE_SERVER, encoding = "utf-8"
+ )
+ starts = []
+
+ def select(binary, force_cpu):
+ starts.append(force_cpu)
+ return "cpu" if force_cpu else "cuda"
+
+ monkeypatch.setattr(srv, "select_backend", select)
+ monkeypatch.setattr(acb.audio_cpp_files, "materialize", lambda model: str(tmp_path / "m.gguf"))
+ monkeypatch.delenv("UNSLOTH_AUDIO_DEVICE", raising = False)
+ return acb.AudioCppBackend(preference), starts
+
+
+def test_gpu_unavailable_start_retries_once_on_cpu(fake_binary, tmp_path, monkeypatch):
+ backend, starts = _backend_whose_gpu_fails(tmp_path, monkeypatch, _NO_GPU)
+ try:
+ backend._start_server(KOKORO)
+ assert starts == [False, True]
+ assert (backend.device, backend._device_fallback, backend._server.backend) == (
+ "cpu",
+ "cpu",
+ "cpu",
+ )
+ backend._start_server(KOKORO)
+ assert starts == [False, True, True]
+ backend._model = KOKORO
+ fields = backend.runtime_fields()
+ assert (fields["audio_cpu"], fields["audio_device_fallback"]) == (True, "cpu")
+ finally:
+ backend._stop_server_locked()
+
+
+ "output, preference, code",
+ [
+ (_NO_GPU, "gpu", "gpu_unavailable"),
+ ("failed to allocate CUDA0 backend weight buffer", None, "out_of_memory"),
+ ],
+)
+def test_pinned_gpu_or_oom_does_not_retry(
+ fake_binary, tmp_path, monkeypatch, output, preference, code
+):
+ from core.inference.audio_cpp_failures import failure_of
+
+ backend, starts = _backend_whose_gpu_fails(tmp_path, monkeypatch, output, preference)
+ with pytest.raises(srv.AudioCppUnavailableError) as raised:
+ backend._start_server(KOKORO)
+ assert starts == [False] and backend._device_fallback is None
+ assert failure_of(raised.value).code == code
+
+
+def test_cancelled_start_does_not_retry(monkeypatch):
+ from core.inference import audio_cpp_backend as acb
+ from core.inference.audio_cpp_failures import AudioCppFailure, attach_failure
+
+ backend = acb.AudioCppBackend("auto")
+ gpu = attach_failure(
+ srv.AudioCppUnavailableError("x"), AudioCppFailure("gpu_unavailable", "m", 503)
+ )
+ assert backend._may_retry_on_cpu(gpu, threading.Event())
+ cancelled = threading.Event()
+ cancelled.set()
+ assert not backend._may_retry_on_cpu(gpu, cancelled)
+ monkeypatch.setattr("utils.process_lifetime.is_process_shutting_down", lambda: True)
+ assert not backend._may_retry_on_cpu(gpu, None)
+
+
def test_stop_survives_a_server_slow_to_exit_after_sigkill(tmp_path):
# A server switching task mid-request (Vevo2 Clone <-> Edit) failed the request when the old
# process outlived the SIGKILL wait in GPU teardown.
diff --git a/studio/backend/tests/test_audio_cpp_spec_placement.py b/studio/backend/tests/test_audio_cpp_spec_placement.py
index 0c48a888d25..d04120df596 100644
--- a/studio/backend/tests/test_audio_cpp_spec_placement.py
+++ b/studio/backend/tests/test_audio_cpp_spec_placement.py
@@ -184,10 +184,9 @@ def test_a_spec_derived_clone_runs_on_the_speech_endpoint(hub):
def test_spec_derived_music_and_sfx_get_modes(hub):
music = _resolve(hub, "new_music", MUSIC).music
song = music.mode("song")
- assert song.lyrics == "optional" and music.fixed_seed is False and music.mode("sfx") is None
+ assert song.lyrics == "optional" and music.mode("sfx") is None
sfx = _resolve(hub, "new_sfx", SFX).music
assert [m.id for m in sfx.modes] == ["sfx"] and sfx.mode("sfx").duration == (1.0, 60.0, 8.0)
- assert sfx.fixed_seed is True
sep = _resolve(hub, "tf_gridnet", {"tasks": ["sep"]})
assert sep.separation is not None
diff --git a/studio/backend/tests/test_audio_cpp_update.py b/studio/backend/tests/test_audio_cpp_update.py
index 1330386a736..b5494a51ee8 100644
--- a/studio/backend/tests/test_audio_cpp_update.py
+++ b/studio/backend/tests/test_audio_cpp_update.py
@@ -76,6 +76,7 @@ def managed(monkeypatch, tmp_path):
monkeypatch.setattr(audio_cpp_freshness, "latest_release_assets", assets)
monkeypatch.setattr(aupd.platform, "system", lambda: "Linux")
monkeypatch.setattr(aupd.platform, "machine", lambda: "x86_64")
+ monkeypatch.setattr(aupd._installer(), "detect_accelerator", lambda: "cpu")
return SimpleNamespace(tree = tree, binary = binary, script = script, lookups = lookups, state = state)
@@ -237,10 +238,49 @@ def test_a_binary_outside_the_managed_tree_is_unmanaged(managed, monkeypatch, tm
assert aupd.chained_phase_plan()["skip_reason"] == "unmanaged"
-def test_no_runtime_is_not_installed(managed, monkeypatch):
+def test_missing_runtime_offered_as_install(managed, monkeypatch):
monkeypatch.setattr(audio_cpp_server, "find_audio_cpp_server_binary", lambda: None)
plan = aupd.chained_phase_plan()
- assert plan["skip_reason"] == "not_installed" and plan["status"] is None
+ assert plan["update_available"] is True and plan["skip_reason"] is None
+ assert plan["status"] == {
+ "installed_tag": None,
+ "latest_tag": _LATEST,
+ "update_size_bytes": None,
+ }
+ tags = {"from_tag": None, "to_tag": _LATEST, "pin_release_tag": _LATEST, "repo": _REPO}
+ assert plan["phase"] == {
+ "install_dir": managed.tree,
+ "script": managed.script,
+ "accelerator": None,
+ **tags,
+ }
+ monkeypatch.setattr(aupd.platform, "system", lambda: "Darwin")
+ monkeypatch.setattr(aupd._installer(), "detect_accelerator", lambda: "metal")
+ managed.state.assets = {f"audio-{_LATEST}-bin-macos-x64-metal.tar.gz": 1}
+ assert aupd.chained_phase_plan()["update_available"] is True
+
+
+ "case",
+ [*_SETUP_SKIPS, "UNSLOTH_DISABLE_UPDATE_CHECK", "no_latest", "no_prebuilt", "no_installer"],
+)
+def test_missing_runtime_stays_not_installed_when_setup_would_skip(managed, monkeypatch, case):
+ monkeypatch.setattr(audio_cpp_server, "find_audio_cpp_server_binary", lambda: None)
+ if case == "no_latest":
+ managed.state.latest = None
+ elif case == "no_prebuilt":
+ managed.state.assets = {f"audio-{_LATEST}-bin-windows-x64-cuda12.8.zip": 1}
+ elif case == "no_installer":
+ monkeypatch.setattr(aupd, "_installer_script", lambda: None)
+ else:
+ monkeypatch.setenv(case, "1")
+ plan = aupd.chained_phase_plan()
+ assert plan == {
+ "status": None,
+ "update_available": False,
+ "skip_reason": "not_installed",
+ "phase": None,
+ }
@pytest.mark.parametrize("tag", [_LATEST, "v0.9.2-unsloth.1", "v1.0.0"])
@@ -797,3 +837,23 @@ def test_a_probe_that_raises_has_no_installed_version(managed, monkeypatch):
def test_the_hardware_details_report_the_installed_version():
main = (Path(aupd.__file__).resolve().parents[1] / "main.py").read_text(encoding = "utf-8")
assert 'body["audio_cpp"] = get_installed_audio_cpp_version()' in main
+
+
+def test_a_first_install_runs_and_the_runtime_is_found_after(run_env, managed, monkeypatch):
+ record = managed.tree / audio_cpp_server.INSTALL_RECORD
+ record.unlink()
+ monkeypatch.setattr(
+ audio_cpp_server,
+ "find_audio_cpp_server_binary",
+ lambda: str(managed.binary) if record.is_file() else None,
+ )
+ phase = aupd.chained_phase_plan()["phase"]
+ monkeypatch.setattr(update_flow, "stream_installer", lambda *a, **k: None)
+ with pytest.raises(aupd._AudioPhaseError, match = "could not be installed"):
+ aupd.run_chained_phase(phase, lambda fraction: None)
+ run_env.installer(new_tag = _LATEST)
+ result = aupd.run_chained_phase(phase, lambda fraction: None)
+ assert result["message"] == f"Installed the audio runtime {_LATEST}."
+ assert "--accelerator" not in run_env.calls["cmd"]
+ assert aupd.chained_phase_plan()["skip_reason"] == "up_to_date"
+ assert aupd.get_installed_audio_cpp_version() == _LATEST
diff --git a/studio/backend/tests/test_audio_device_guards.py b/studio/backend/tests/test_audio_device_guards.py
index c4f5c40f77a..91b07fc3ef1 100644
--- a/studio/backend/tests/test_audio_device_guards.py
+++ b/studio/backend/tests/test_audio_device_guards.py
@@ -552,3 +552,20 @@ def test_whisper_cpp_publishes_the_load_before_choosing_its_placement():
src = inspect.getsource(GgmlSttSidecar.load)
assert src.index("self._loading = True") < src.index("elif _training_active():")
+
+
+def test_a_model_that_fell_back_to_cpu_is_recorded_as_holding_no_gpu(monkeypatch):
+ """No VRAM counted for it, and a repeat Auto load does not retry the GPU."""
+ import inspect
+
+ from core.inference import audio_cpp_server, orchestrator
+
+ assert 'model_info.get("audio_cpp_backend") == "cpu"' in inspect.getsource(orchestrator)
+ monkeypatch.setattr(audio_cpp_server, "runtime_runs_on_cpu", lambda: False)
+ monkeypatch.delenv("UNSLOTH_AUDIO_DEVICE", raising = False)
+ resident = _backend(audio_cpu = True, audio_type = "audiocpp_tts")
+ resident.models["x/y"]["audio_device_fallback"] = "cpu"
+ assert ri._resident_audio_holds_no_gpu(resident)
+ assert ri._resident_audio_placement_matches(resident, _request("auto"))
+ assert ri._resident_audio_placement_matches(resident, _request(None))
+ assert not ri._resident_audio_placement_matches(resident, _request("gpu"))
diff --git a/studio/backend/tests/test_audio_run_route.py b/studio/backend/tests/test_audio_run_route.py
index c2fb19838c6..d5b8bddd335 100644
--- a/studio/backend/tests/test_audio_run_route.py
+++ b/studio/backend/tests/test_audio_run_route.py
@@ -181,7 +181,7 @@ def test_a_clone_run_hands_the_worker_an_account_path_and_saves_the_clip(stub, t
assert all(not isinstance(v, (bytes, bytearray)) for v in call.values())
assert body["audio"] is None
(clip,) = body["clips"]
- assert set(clip) == {"id", "role", "url", "sample_rate", "duration_s", "workflow"}
+ assert set(clip) == {"id", "role", "url", "sample_rate", "duration_s", "workflow", "seed"}
assert (clip["role"], clip["workflow"], clip["sample_rate"]) == ("output", "clone", 24000)
sidecar = _sidecar(tmp_path, clip["id"])
meta = json.loads(sidecar)
@@ -192,6 +192,7 @@ def test_a_clone_run_hands_the_worker_an_account_path_and_saves_the_clip(stub, t
"options": {"x_vector_only_mode": False},
"reference_text_used": True,
"speed": None,
+ "seed": None,
}
assert str(tmp_path) not in sidecar and "inputs" not in sidecar
@@ -397,13 +398,14 @@ def test_an_emotion_clip_reaches_a_family_that_takes_one(stub):
def test_a_failed_gallery_save_returns_the_audio_inline(stub, monkeypatch):
+ _reporting(stub["backend"], 77)
input_id = _input(ALICE)
monkeypatch.setattr(inference, "_persist_tts_clip", lambda *a, **k: None)
with _client(ALICE) as client:
response = _run(client, inputs = {"reference": {"input_id": input_id}, "reference_text": "x"})
body = response.json()
assert response.status_code == 200 and body["clips"] == []
- assert body["audio"]["sample_rate"] == 24000
+ assert (body["audio"]["sample_rate"], body["audio"]["seed"]) == (24000, 77)
assert base64.b64decode(body["audio"]["data"])[:4] == b"RIFF"
@@ -1040,7 +1042,7 @@ def test_a_separation_prepares_44k_and_saves_every_stem_as_one_group(sep, tmp_pa
assert body["audio"] is None and body["model"] and len(body["group_id"]) == 32
assert stem_bytes.status_code == 200 and stem_bytes.content[:4] == b"RIFF"
for clip in body["clips"]:
- assert set(clip) == {"id", "role", "url", "sample_rate", "duration_s", "workflow"}
+ assert set(clip) == {"id", "role", "url", "sample_rate", "duration_s", "workflow", "seed"}
assert (clip["workflow"], clip["sample_rate"], clip["duration_s"]) == (
"separate",
44100,
@@ -1070,6 +1072,26 @@ def test_a_mono_track_reaches_the_runtime_as_44k_mono(sep):
assert (rate, channels) == (44100, 1) and abs(frames - 44100) <= 1
+def test_a_separation_that_runs_out_of_memory_answers_with_its_code(sep):
+ from core.inference import audio_cpp_failures as af
+ from core.inference.audio_cpp_server import AudioCppUnavailableError
+
+ tail = "ggml_gallocr_reserve_n: failed to allocate CUDA0 buffer of size 9663676416"
+ crash = af.attach_failure(
+ AudioCppUnavailableError("The audio runtime stopped while serving the request."),
+ af.classify_audio_cpp_failure(tail, backend = "cuda"),
+ )
+
+ def fail(output_dir):
+ raise crash
+
+ sep.outputs = fail
+ with _client(ALICE) as client:
+ response = _separate(client, {"input_id": _input(ALICE, 1.0)})
+ assert response.status_code == 503, response.text
+ assert response.json()["detail"]["code"] == "out_of_memory"
+
+
def test_a_history_clip_can_be_separated_and_is_recorded(sep, tmp_path):
clip_id = _alice_sources()["clip_id"]
with _client(ALICE) as client:
@@ -1786,6 +1808,8 @@ def test_the_worker_and_orchestrator_carry_convert_and_the_running_task(monkeypa
def runtime_fields(self):
return {"audio_server_task": "vc", "audio_convert_route": None}
+ separate_audio = lambda self, **kwargs: []
+
responses: queue.Queue = queue.Queue()
convert = {"mode": "speech", "pitch": None, "pitch_auto": False, "style": "source"}
_handle_generate_audio(
@@ -1803,6 +1827,9 @@ def test_the_worker_and_orchestrator_carry_convert_and_the_running_task(monkeypa
assert seen[0]["convert"] == convert and seen[0]["workflow"] == "convert"
done = responses.get_nowait()
assert done["audio_runtime"] == {"audio_server_task": "vc", "audio_convert_route": None}
+ sep = {"workflow": "separate", "audio_inputs": {"source": "s"}, "output_dir": "o"}
+ _handle_generate_audio(_Backend(), sep, responses, threading.Event())
+ assert responses.get_nowait()["audio_runtime"]["audio_server_task"] == "vc"
orchestrator = InferenceOrchestrator.__new__(InferenceOrchestrator)
sent = []
@@ -2082,3 +2109,94 @@ def test_speech_pcm_is_openais_24k_mono_samples(stub, monkeypatch, rate, channel
assert abs(len(response.content) - 48000) <= 2 * 64
if (rate, channels) == (24000, 1):
assert response.content == buf.getvalue()[44:]
+
+
+def _reporting(
+ backend,
+ seed,
+ ignored = (),
+):
+ run = backend.generate_audio_response
+
+ def generate(**kwargs):
+ kwargs["stats_holder"]["stats"] = {"seed": seed, "ignored_options": list(ignored)}
+ return run(**kwargs)
+
+ backend.generate_audio_response = generate
+ return backend
+
+
+def test_seed_round_trip_run_response_and_gallery_settings(stub, tmp_path):
+ _reporting(stub["backend"], 77, ["top_k"])
+ with _client(ALICE) as client:
+ ref = {"reference": {"input_id": _input(ALICE)}, "reference_text": "Hi."}
+ response = _run(client, inputs = ref)
+ assert response.status_code == 200, response.text
+ body = response.json()
+ assert body["clips"][0]["seed"] == 77 and body["ignored_options"] == ["top_k"]
+ assert json.loads(_sidecar(tmp_path, body["clips"][0]["id"]))["settings"]["seed"] == 77
+
+
+def test_generate_json_returns_seed_and_persists_settings(stub, tmp_path):
+ _reporting(stub["use"](*_KOKORO), 5, ["mode"])
+ with _client(ALICE) as client:
+ body = _generate(client).json()
+ assert (body["seed"], body["ignored_options"]) == (5, ["mode"])
+ assert json.loads(_sidecar(tmp_path, body["clip_id"]))["settings"] == {"seed": 5}
+
+
+def test_edit_and_convert_report_ignored_options(stub):
+ from test_audio_edit_route import _edit, _load
+
+ _reporting(_load(stub), None, ["top_k"])
+ with _client(ALICE) as client:
+ edited = _edit(client, _input(ALICE))
+ assert edited.status_code == 200, edited.text
+ assert edited.json()["ignored_options"] == ["top_k"]
+ _reporting(_use(stub, "rvc", "RVC-GGUF"), 7, ["top_k"])
+ with _client(ALICE) as client:
+ converted = _convert(
+ client,
+ inputs = {"source": {"input_id": _input(ALICE, seconds = 2.0)}},
+ convert = {"voice": "manthos"},
+ )
+ assert converted.status_code == 200, converted.text
+ assert converted.json()["ignored_options"] == ["top_k"]
+
+
+def test_music_take_persists_group_role_variation_and_take_seed(stub, tmp_path, monkeypatch):
+ backend = stub["use"](STABLE_AUDIO, _music_info())
+ backend.__class__ = _MusicBackend
+ backend.takes, backend.run_dirs = 1, []
+ group = "ab" * 16
+ with _client(ALICE) as client:
+ response = _music(client, take = 2, group_id = group, seed = 40)
+ assert response.status_code == 200, response.text
+ body = response.json()
+ assert backend.calls[0]["music"]["take"] == 1 and body["group_id"] == group
+ (clip,) = body["clips"]
+ assert (clip["role"], clip["seed"]) == ("variation", 40)
+ meta = json.loads(_sidecar(tmp_path, clip["id"]))
+ assert (meta["group_id"], meta["role"]) == (group, "variation")
+ assert meta["settings"]["variation"] == 2
+ monkeypatch.setattr(inference, "_persist_tts_clip", lambda *a, **k: None)
+ with _client(ALICE) as client:
+ inline = _music(client, take = 1, group_id = group).json()
+ assert (inline["clips"], inline["audio"]["seed"]) == ([], 40)
+
+
+ "body",
+ [
+ {"workflow": "music", "mode": "song", "take": 1, "variations": 2},
+ {"workflow": "clone", "take": 1},
+ {"workflow": "speak", "group_id": "ab" * 16},
+ {"workflow": "music", "mode": "song", "group_id": "AB" * 16},
+ {"workflow": "music", "mode": "song", "take": 5},
+ {"workflow": "music", "mode": "song", "take": 2},
+ ],
+)
+def test_take_or_group_rejected_outside_single_variation_music(stub, body):
+ with _client(ALICE) as client:
+ response = client.post("/api/inference/audio/run", json = {"text": "x", **body})
+ assert response.status_code == 422, response.text
diff --git a/studio/backend/tests/test_gguf_load_cache_reuse.py b/studio/backend/tests/test_gguf_load_cache_reuse.py
index ec9d5ea5110..e394bd50af9 100644
--- a/studio/backend/tests/test_gguf_load_cache_reuse.py
+++ b/studio/backend/tests/test_gguf_load_cache_reuse.py
@@ -1215,6 +1215,8 @@ class TestLoadHubDownloadExclusion:
"audio_workflows",
"audio_reference_text",
"audio_required_inputs",
+ "audio_request_inputs",
+ "audio_device_fallback",
# Constant None: nor converts one.
"audio_options_by_workflow",
"audio_workflow_tasks",
diff --git a/studio/backend/tests/test_pr7699_worker_audio_mirror.py b/studio/backend/tests/test_pr7699_worker_audio_mirror.py
index 15d708f991b..bc4e3bfbc75 100644
--- a/studio/backend/tests/test_pr7699_worker_audio_mirror.py
+++ b/studio/backend/tests/test_pr7699_worker_audio_mirror.py
@@ -53,13 +53,14 @@ def _drive_handle_load(
mc,
entry = None,
device = "mlx",
+ load_model = lambda **kw: True,
):
"""Run _handle_load against a stub MLX backend, return the emitted model_info."""
backend = SimpleNamespace(
device = device,
active_model_name = mc.identifier,
models = {mc.identifier: entry or _mlx_entry_for(mc)},
- load_model = lambda **kw: True,
+ load_model = load_model,
)
monkeypatch.setattr(worker, "_build_model_config", lambda cfg: mc)
@@ -76,6 +77,8 @@ def _drive_handle_load(
loaded = [m for m in q.sent if m.get("type") == "loaded"]
assert loaded, f"no loaded response: {q.sent}"
+ if loaded[0].get("failure"):
+ return loaded[0]
assert loaded[0].get("success"), loaded[0]
return loaded[0]["model_info"]
@@ -137,8 +140,24 @@ def test_audio_cpp_workflow_fields_cross_the_worker_and_the_parent(monkeypatch):
"audio_music": {"modes": [{"id": "song", "variations": None}]},
# The /audio/run route sizes CPU waits from it.
"audio_cpp_backend": "cpu",
+ "audio_device_fallback": "cpu",
+ "audio_request_inputs": ["language"],
}
entry = {"is_audio": True, "audio_type": "audiocpp_tts", "has_audio_input": False, **fields}
info = _drive_handle_load(monkeypatch, mc, entry, device = "cuda")
entry = _mirrored_model_entry(info, mc.identifier)
assert {k: info[k] for k in fields} == {k: entry[k] for k in fields} == fields
+
+
+def test_a_classified_load_failure_crosses_the_worker_and_the_parent(monkeypatch):
+ from core.inference.audio_cpp_failures import AudioCppFailure, AudioCppFailureError, failure_of
+
+ failure = AudioCppFailure("runtime_missing", "Install the runtime.", 503)
+
+ def refuse(**_kw):
+ raise AudioCppFailureError("The audio runtime is not installed.", failure)
+
+ mc = _mc("audiocpp_tts", is_audio = True, has_audio_input = False)
+ loaded = _drive_handle_load(monkeypatch, mc, device = "cuda", load_model = refuse)
+ assert loaded["success"] is False and AudioCppFailure.from_payload(loaded["failure"]) == failure
+ assert failure_of(AudioCppFailureError(loaded["error"], failure)) is failure
diff --git a/studio/backend/utils/audio_cpp_update.py b/studio/backend/utils/audio_cpp_update.py
index 8527702d739..a2039442065 100644
--- a/studio/backend/utils/audio_cpp_update.py
+++ b/studio/backend/utils/audio_cpp_update.py
@@ -175,6 +175,65 @@ def _update_size_bytes(
return size
+def _release_assets(
+ repo: str,
+ latest: str,
+ *,
+ force_refresh: bool = False,
+) -> Optional[dict]:
+ assets = _freshness.latest_release_assets(repo, force_refresh = force_refresh)
+ # The tag can come from the 24h disk cache while the asset list is fetched fresh, so after a newer release the two can disagree: keep only the offered release's assets.
+ prefixes = (f"audio-{latest}-bin-", f"audio-{latest}-cudart-")
+ return {
+ name: size for name, size in (assets or {}).items() if name.startswith(prefixes)
+ } or None
+
+
+def _install_plan(plan: dict, *, force_refresh: bool = False) -> dict:
+ """No runtime at all: offer a first install into the managed tree, but only where setup would have installed one and this host has a bundle for the known release. Otherwise ``plan`` stays not_installed."""
+ from core.inference import audio_cpp_server
+
+ skipped = any(os.environ.get(name) for name in _SETUP_SKIP_VARS)
+ if (
+ skipped
+ or os.environ.get("UNSLOTH_SKIP_AUDIO_CPP_INSTALL") == "1"
+ or update_checks_disabled()
+ ):
+ return plan
+ repo, pin = _target()
+ latest = pin or _freshness.latest_published_release(repo, force_refresh = force_refresh)
+ assets = (
+ None
+ if pin or latest is None
+ else _release_assets(repo, latest, force_refresh = force_refresh)
+ )
+ script = _installer_script()
+ if (
+ latest is None
+ or script is None
+ # The installer's own pick: a macOS release has Metal bundles only.
+ or not _host_has_prebuilt(
+ list(assets) if assets else None, _installer().detect_accelerator()
+ )
+ ):
+ return plan
+ plan.update(
+ status = {"installed_tag": None, "latest_tag": latest, "update_size_bytes": None},
+ update_available = True,
+ skip_reason = None,
+ phase = dict(
+ install_dir = audio_cpp_server.managed_audio_cpp_dir(),
+ script = script,
+ accelerator = None,
+ from_tag = None,
+ to_tag = latest,
+ pin_release_tag = latest,
+ repo = repo,
+ ),
+ )
+ return plan
+
+
def _plan(*, force_refresh: bool = False) -> dict:
from core.inference import audio_cpp_server
@@ -182,7 +241,7 @@ def _plan(*, force_refresh: bool = False) -> dict:
binary = audio_cpp_server.find_audio_cpp_server_binary()
if binary is None:
plan["skip_reason"] = "not_installed"
- return plan
+ return _install_plan(plan, force_refresh = force_refresh)
record = audio_cpp_server.read_install_record(binary)
status = {"installed_tag": _tag(record), "latest_tag": None, "update_size_bytes": None}
plan["status"] = status
@@ -218,12 +277,7 @@ def _plan(*, force_refresh: bool = False) -> dict:
):
plan["skip_reason"] = "up_to_date"
return plan
- assets = _freshness.latest_release_assets(repo, force_refresh = force_refresh)
- # The tag can come from the 24h disk cache while the asset list is fetched fresh, so after a newer release the two can disagree: keep only the offered release's assets.
- prefixes = (f"audio-{latest}-bin-", f"audio-{latest}-cudart-")
- assets = {
- name: size for name, size in (assets or {}).items() if name.startswith(prefixes)
- } or None
+ assets = _release_assets(repo, latest, force_refresh = force_refresh)
names = list(assets) if assets else None
status["update_size_bytes"] = _update_size_bytes(assets, record, installed, latest)
installer = _installer()
@@ -371,7 +425,11 @@ def _install(phase: dict, set_progress, unloaded: bool) -> dict:
new_repo, new_tag = _installed_identity()
# Repo and tag together: switching UNSLOTH_AUDIO_CPP_REPO can replace a runtime with another repo's same tag.
# A runtime that is already the offered release (a setup run got there first) is not a kept old tree.
- if (new_repo, new_tag) == before and (new_repo, new_tag) != (
+ if before[1] is None and new_tag is None:
+ # A first install that exited 0 without a runtime (the release lookup could not answer).
+ message = "The audio runtime could not be installed right now. Try again later."
+ raise _AudioPhaseError(message, reload_required = unloaded)
+ elif (new_repo, new_tag) == before and (new_repo, new_tag) != (
phase.get("repo"),
phase.get("to_tag"),
):
@@ -380,6 +438,8 @@ def _install(phase: dict, set_progress, unloaded: bool) -> dict:
f"audio.cpp could not be updated right now, so the existing {new_tag} "
f"install was kept. Try again later.{reload_hint}"
)
+ elif before[1] is None:
+ message = f"Installed the audio runtime {new_tag}.{reload_hint}"
else:
message = f"Updated audio.cpp to {new_tag}.{reload_hint}"
logger.info("audio.cpp update: done", to_tag = new_tag)
diff --git a/studio/frontend/scripts/check-bundle-budget.ts b/studio/frontend/scripts/check-bundle-budget.ts
index c89c99260cf..91f0b94e65e 100644
--- a/studio/frontend/scripts/check-bundle-budget.ts
+++ b/studio/frontend/scripts/check-bundle-budget.ts
@@ -214,8 +214,11 @@ export const BUDGET = {
// 6,812,691 B raw, 2,049,298 -> 2,050,209 B transfer against f2ed00705f, one machine and build, Node 24, chunk
// count unchanged at 95): the picker rows and catalog hook live in the audio picker the startup chunks load.
// Raised by that growth.
- transferBytes: 2_048_519,
- rawBytes: 6_808_646,
+ // Audio failure actions, seeds and the single voice picker (#14075) add 492 B raw / 134 B transfer (6,812,691 ->
+ // 6,813,183 B raw, 2,050,209 -> 2,050,343 B transfer against 4bed2fa246, one machine and build, Node 24, chunk count
+ // unchanged at 95): the shared audio failure and seed helpers are imported by startup chunks. Raised by that growth.
+ transferBytes: 2_048_653,
+ rawBytes: 6_809_138,
};
// The chunk count is reported but not budgeted. Splitting a page out of the entry raises it while lowering the
diff --git a/studio/frontend/src/components/llama-update-banner.tsx b/studio/frontend/src/components/llama-update-banner.tsx
index 52c123731b2..84c2ab0cfde 100644
--- a/studio/frontend/src/components/llama-update-banner.tsx
+++ b/studio/frontend/src/components/llama-update-banner.tsx
@@ -152,6 +152,11 @@ function VersionLine({
];
const rowSize = bundled ? sizeLabelOf(row.sizeBytes) : null;
const sizeSuffix = rowSize ? ` · ${rowSize}` : "";
+ // no audio.cpp runtime yet, so the offer is a first install.
+ const lead =
+ row.component === "audio.cpp" && row.installedTag === null
+ ? "Install the audio runtime"
+ : null;
return (
<p
// one row per line keeps the changelog height calculation exact.
@@ -161,15 +166,17 @@ function VersionLine({
)}
title={
bundled
- ? `${row.component} ${from} \u2192 ${to}${sizeSuffix}`
+ ? `${lead ?? `${row.component} ${from} \u2192`} ${to}${sizeSuffix}`
: undefined
}
data-testid="llama-update-version-line"
>
- {bundled ? (
+ {lead ? `${lead} ` : null}
+ {bundled && !lead ? (
<span className="text-foreground">{row.component} </span>
) : null}
- {from} &rarr; <span className="font-medium text-foreground">{to}</span>
+ {lead ? null : <>{from} &rarr; </>}
+ <span className="font-medium text-foreground">{to}</span>
{sizeSuffix}
</p>
);
@@ -348,9 +355,16 @@ export function LlamaUpdateBanner({
const phaseIndex = rows.findIndex(
(row) => updateComponentKey(row.component) === runningPhase,
);
+ // no audio.cpp runtime yet, so this offer installs it.
+ const firstInstall =
+ !bundled &&
+ primary?.component === "audio.cpp" &&
+ primary.installedTag === null;
let title: string;
if (applying && !bundled) {
- title = `Updating ${label}...`;
+ title = firstInstall
+ ? "Installing the audio runtime..."
+ : `Updating ${label}...`;
} else if (applying) {
title =
phaseIndex >= 0
@@ -359,7 +373,11 @@ export function LlamaUpdateBanner({
} else if (bundled) {
title = `${rows.length} runtime updates`;
} else {
- title = backendOnly ? `New ${label} backend` : `New ${label} update`;
+ title = firstInstall
+ ? "Install the audio runtime"
+ : backendOnly
+ ? `New ${label} backend`
+ : `New ${label} update`;
}
const updateProgress = status?.job.progress ?? null;
const jobSucceeded = status?.job.state === "success";
diff --git a/studio/frontend/src/features/audio/api.ts b/studio/frontend/src/features/audio/api.ts
index aca6453fd9a..12bc333530d 100644
--- a/studio/frontend/src/features/audio/api.ts
+++ b/studio/frontend/src/features/audio/api.ts
@@ -20,7 +20,7 @@ import {
async function parseJson<T>(response: Response): Promise<T> {
if (!response.ok) {
- throw new Error(await readFastApiError(response));
+ throw await audioApiError(response);
}
return (await response.json()) as T;
}
@@ -29,6 +29,7 @@ export interface GeneratedAudio {
data: string;
format: string;
sample_rate: number;
+ seed?: number | null;
}
export interface GenerateAudioResponse {
@@ -36,6 +37,10 @@ export interface GenerateAudioResponse {
audio: GeneratedAudio;
clip_id?: string | null;
choices: { finish_reason: string }[];
+ /** The seed the take used; null when the model takes none. */
+ seed?: number | null;
+ /** Option names the model doesn't take, so they weren't sent. */
+ ignored_options?: string[];
}
export interface GenerateAudioOptions {
@@ -310,19 +315,34 @@ export async function deleteTranscript(id?: string): Promise<void> {
);
}
-/** Carries the status so callers can tell an expired upload (404) from a refusal. */
+/** Carries the status so callers can tell an expired upload (404) from a refusal, and `detail` with its `code`. */
export class AudioApiError extends Error {
readonly status: number;
- constructor(message: string, status: number) {
+ readonly code?: string;
+ readonly detail?: unknown;
+ constructor(message: string, status: number, detail?: unknown) {
super(message);
this.name = "AudioApiError";
this.status = status;
+ this.detail = detail;
+ const code = (detail as { code?: unknown } | null | undefined)?.code;
+ if (typeof code === "string") this.code = code;
}
}
+async function audioApiError(response: Response): Promise<AudioApiError> {
+ const copy = response.clone();
+ const message = await readFastApiError(response);
+ const detail = await copy.json().then(
+ (body: { detail?: unknown } | null) => body?.detail,
+ () => undefined,
+ );
+ return new AudioApiError(message, response.status, detail);
+}
+
async function parseAudioJson<T>(response: Response): Promise<T> {
if (!response.ok) {
- throw new AudioApiError(await readFastApiError(response), response.status);
+ throw await audioApiError(response);
}
return (await response.json()) as T;
}
@@ -471,11 +491,13 @@ export interface AudioRunResponse {
sample_rate: number;
duration_s: number;
workflow: string;
+ seed?: number | null;
}[];
/** One separation's stems share it; null for a single clip. */
group_id: string | null;
model: string;
audio: GeneratedAudio | null;
+ ignored_options?: string[];
}
export async function runAudio(
diff --git a/studio/frontend/src/features/audio/audio-failure-actions.ts b/studio/frontend/src/features/audio/audio-failure-actions.ts
new file mode 100644
index 00000000000..fe92542c341
--- /dev/null
+++ b/studio/frontend/src/features/audio/audio-failure-actions.ts
@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { GenerateAction } from "./pages/tts-workspace";
+import { useAudioWorkspaceStore } from "./stores/audio-workspace-store.ts";
+
+const RUNTIME_CODES = [
+ "runtime_missing",
+ "family_unknown_to_runtime",
+ "espeak_missing",
+];
+const AUDIO_FAILURE_CODES = [
+ ...RUNTIME_CODES,
+ "out_of_memory",
+ "gpu_unavailable",
+ "file_incomplete",
+];
+
+export interface AudioFailure {
+ code: string;
+ message: string;
+ smallerVariants: { variant: string; label: string }[];
+ /** The run was already on the CPU, so "Load into CPU RAM" cannot help. */
+ onCpu: boolean;
+}
+
+/** A structured audio.cpp failure from a FastAPI `detail`, or a body / `_deferred_error` wrapping one. */
+export function parseAudioFailure(
+ detail: unknown,
+ depth = 0,
+): AudioFailure | null {
+ if (!detail || typeof detail !== "object" || depth > 3) return null;
+ const body = detail as Record<string, unknown>;
+ if (typeof body.code !== "string" || !AUDIO_FAILURE_CODES.includes(body.code))
+ return parseAudioFailure(body._deferred_error ?? body.detail, depth + 1);
+ const variants = Array.isArray(body.smaller_variants)
+ ? (body.smaller_variants as { variant?: unknown; label?: unknown }[])
+ : [];
+ return {
+ code: body.code,
+ message: typeof body.message === "string" ? body.message : "",
+ onCpu: body.device === "cpu",
+ smallerVariants: variants.flatMap(({ variant, label } = {}) =>
+ typeof variant === "string" && variant
+ ? [
+ {
+ variant,
+ label: typeof label === "string" && label ? label : variant,
+ },
+ ]
+ : [],
+ ),
+ };
+}
+
+/** The failure an API error carries (AudioApiError / LoadModelError keep `detail`). */
+export function audioFailureOf(error: unknown): AudioFailure | null {
+ return error instanceof Error
+ ? parseAudioFailure((error as { detail?: unknown }).detail)
+ : null;
+}
+
+export interface AudioFailureContext {
+ deviceIsCpu: boolean;
+ /** MiniMax Music 3 needs CUDA, so CPU RAM is never offered for it. */
+ cpuUnsupported?: boolean;
+ canUpdateRuntime: boolean;
+ onUpdateRuntime: () => void;
+ onUseCpu: () => void;
+ onUseVariant: (variant: string) => void;
+ onChooseModel: () => void;
+}
+
+/** Actions for a failure, mapped onto existing controls; anything unclassified keeps "Choose a different model". */
+export function audioFailureActions(
+ failure: AudioFailure | null,
+ ctx: AudioFailureContext,
+): GenerateAction[] {
+ const actions: GenerateAction[] = [];
+ const smaller = failure?.smallerVariants[0];
+ if (failure && RUNTIME_CODES.includes(failure.code)) {
+ if (ctx.canUpdateRuntime)
+ actions.push({
+ label: "Update the audio runtime",
+ onClick: ctx.onUpdateRuntime,
+ });
+ } else if (
+ failure?.code === "out_of_memory" ||
+ failure?.code === "gpu_unavailable"
+ ) {
+ if (failure.code === "out_of_memory" && smaller)
+ actions.push({
+ label: `Use ${smaller.label}`,
+ onClick: () => ctx.onUseVariant(smaller.variant),
+ });
+ if (!ctx.deviceIsCpu && !ctx.cpuUnsupported && !failure.onCpu)
+ actions.push({ label: "Load into CPU RAM", onClick: ctx.onUseCpu });
+ }
+ return actions.length > 0
+ ? actions
+ : [{ label: "Choose a different model", onClick: ctx.onChooseModel }];
+}
+
+/** Records the failure behind a generation error, so the page can offer its actions while that
+ * error shows. An unclassified error clears it. */
+export function reportAudioFailure(error: unknown): AudioFailure | null {
+ const failure = audioFailureOf(error);
+ useAudioWorkspaceStore
+ .getState()
+ .setFailure(
+ failure && error instanceof Error
+ ? { message: error.message, failure }
+ : null,
+ );
+ return failure;
+}
diff --git a/studio/frontend/src/features/audio/audio-options.ts b/studio/frontend/src/features/audio/audio-options.ts
index 74c6232e571..bebc22d59b0 100644
--- a/studio/frontend/src/features/audio/audio-options.ts
+++ b/studio/frontend/src/features/audio/audio-options.ts
@@ -165,6 +165,20 @@ export function audioOptionLabel(name: string): string {
return words ? words[0].toUpperCase() + words.slice(1) : name;
}
+/** The toast after a run whose options the model doesn't take; null when it took them all. */
+export function ignoredOptionsWarning(
+ names: readonly string[],
+ modelLabel: string,
+): string | null {
+ const labels = names.map(audioOptionLabel);
+ if (labels.length === 0) return null;
+ const list =
+ labels.length === 1
+ ? labels[0]
+ : `${labels.slice(0, -1).join(", ")} or ${labels[labels.length - 1]}`;
+ return `${modelLabel} doesn't take ${list}, so ${labels.length === 1 ? "it wasn't" : "they weren't"} sent.`;
+}
+
// Kokoro voice ids lead with a language letter and a gender letter (hexgrad/Kokoro-82M VOICES.md).
const KOKORO_LANGUAGES: Record<string, string> = {
a: "American English",
diff --git a/studio/frontend/src/features/audio/audio-page.tsx b/studio/frontend/src/features/audio/audio-page.tsx
index 86051409ce5..5bb1e88d2b8 100644
--- a/studio/frontend/src/features/audio/audio-page.tsx
+++ b/studio/frontend/src/features/audio/audio-page.tsx
@@ -65,7 +65,10 @@ import {
audioCapabilityLine,
audioModelsForTask,
isMusicGenerationModel,
+ musicGenerationRequiresCuda,
} from "./catalog";
+import { audioFailureActions } from "./audio-failure-actions";
+import { useLlamaUpdateCheck } from "@/hooks/use-llama-update-check";
import type { ClipSendHandlers } from "./components/clip-card";
import { sendClipToMusic } from "./components/music-send-to";
import { SaveVoiceDialog } from "./components/save-voice-dialog";
@@ -492,6 +495,9 @@ export function AudioPage({
pendingTranscribeRelease,
handleModelSelect,
pickRecommendedModel,
+ pickModelVariant,
+ reloadOnCpu,
+ setLoadFailureHandlers,
handleEject,
trainedTtsModels,
} = useAudioModelSlot({
@@ -641,8 +647,14 @@ export function AudioPage({
downloadedSttArtifacts[0]?.repoId ??
lastSttRepo ??
null;
+ const cloneSttReady =
+ cloneSttRepo !== null &&
+ downloadedSttArtifacts.some(
+ (artifact) => artifact.repoId.toLowerCase() === cloneSttRepo.toLowerCase(),
+ );
const clone = useCloneGeneration({
status,
+ busy,
busyRef,
setBusy,
updateGenerationPhase,
@@ -660,6 +672,8 @@ export function AudioPage({
replayQueuedTtsPick,
audioOptionValues,
sttRepo: cloneSttRepo,
+ sttReady: cloneSttReady,
+ onClonePage: active && pageWorkflow === "clone",
});
const convert = useConvertGeneration({
status,
@@ -914,6 +928,26 @@ export function AudioPage({
},
[transitionWorkflow, setPrompt],
);
+ const handleReuseSeed = useCallback(
+ (seed: number) => {
+ const specs =
+ ttsWorkflow === "clone" ? clone.audioOptionSpecs : audioOptionSpecs;
+ if (!specs.some((spec) => spec.name === "seed")) {
+ toast.info("This model doesn't take a seed.");
+ return;
+ }
+ handleAudioOptionChange("seed", seed);
+ setAdvancedOpen(true);
+ toast.success(`Seed ${seed} set for the next take.`);
+ },
+ [
+ ttsWorkflow,
+ clone.audioOptionSpecs,
+ audioOptionSpecs,
+ handleAudioOptionChange,
+ setAdvancedOpen,
+ ],
+ );
const [voiceClip, setVoiceClip] = useState<{
id: string;
name: string;
@@ -1062,6 +1096,34 @@ export function AudioPage({
onClick: () => transitionWorkflow(loadedModelHome),
};
const openSelector = useCallback(() => setSelectorOpen(true), []);
+ const audioFailure = useAudioWorkspaceStore((state) => state.failure);
+ const setAudioFailure = useAudioWorkspaceStore((state) => state.setFailure);
+ const { status: runtimeUpdate, apply: applyRuntimeUpdate } =
+ useLlamaUpdateCheck({ enabled: active });
+ const handleUpdateRuntime = useCallback(async () => {
+ const result = await applyRuntimeUpdate();
+ if (result.ok) {
+ toast.success("Audio runtime updated. Load the model again.");
+ setAudioFailure(null);
+ await refreshStatus();
+ } else {
+ toast.error(`Update failed: ${result.error ?? "unknown error"}`);
+ }
+ }, [applyRuntimeUpdate, refreshStatus, setAudioFailure]);
+ const handleUseCpu = useCallback(() => {
+ setAudioDeviceState("cpu");
+ if (!reloadOnCpu()) openSelector();
+ }, [setAudioDeviceState, reloadOnCpu, openSelector]);
+ const canUpdateRuntime = runtimeUpdate?.audio?.update_available === true;
+ const onUpdateRuntime = () => void handleUpdateRuntime();
+ useEffect(() => {
+ setLoadFailureHandlers({
+ canUpdateRuntime,
+ onUpdateRuntime,
+ onChooseModel: openSelector,
+ selectCpuDevice: () => setAudioDeviceState("cpu"),
+ });
+ });
const chooseModelAction = { label: "Choose a model", onClick: openSelector };
const handlePickRecommended = useCallback(
(id: string) => void pickRecommendedModel(id),
@@ -1244,12 +1306,28 @@ export function AudioPage({
: musicStudio
? music.generationError
: generationError;
+ const activeModel = status?.active_model;
const generateFailure: GenerateBlocker | null = pageGenerationError
? {
reason: /[.!?]$/.test(pageGenerationError)
? pageGenerationError
: `${pageGenerationError}.`,
- actions: [{ label: "Choose a different model", onClick: openSelector }],
+ actions: audioFailureActions(
+ audioFailure?.message === pageGenerationError
+ ? audioFailure.failure
+ : null,
+ {
+ canUpdateRuntime,
+ onUpdateRuntime,
+ onChooseModel: openSelector,
+ deviceIsCpu: audioDevice === "cpu",
+ cpuUnsupported: musicGenerationRequiresCuda(activeModel, status?.audio_type),
+ onUseCpu: handleUseCpu,
+ onUseVariant: (variant) => {
+ if (activeModel) void pickModelVariant(activeModel, variant);
+ },
+ },
+ ),
}
: null;
const setCloneGenerationError = clone.setGenerationError;
@@ -1258,6 +1336,7 @@ export function AudioPage({
const setSeparateGenerationError = separate.setGenerationError;
const setMusicGenerationError = music.setGenerationError;
useEffect(() => {
+ setAudioFailure(null);
setGenerationError(null);
setCloneGenerationError(null);
setEditGenerationError(null);
@@ -1266,6 +1345,7 @@ export function AudioPage({
setMusicGenerationError(null);
}, [
status?.active_model,
+ setAudioFailure,
setGenerationError,
setCloneGenerationError,
setEditGenerationError,
@@ -1274,6 +1354,7 @@ export function AudioPage({
setMusicGenerationError,
]);
useEffect(() => {
+ if (busy === "generating") setAudioFailure(null);
if (busy === "generating") setGenerationError(null);
if (busy === "generating") setCloneGenerationError(null);
if (busy === "generating") setEditGenerationError(null);
@@ -1282,6 +1363,7 @@ export function AudioPage({
if (busy === "generating") setMusicGenerationError(null);
}, [
busy,
+ setAudioFailure,
setGenerationError,
setCloneGenerationError,
setEditGenerationError,
@@ -2125,6 +2207,7 @@ export function AudioPage({
handleArchiveClip,
handleDownloadClipById,
onUseTextAgain: handleUseTextAgain,
+ onReuseSeed: handleReuseSeed,
handleCopyPrompt,
freshClipId,
onFreshClipFocused: clearFreshClip,
diff --git a/studio/frontend/src/features/audio/audio-run-request.ts b/studio/frontend/src/features/audio/audio-run-request.ts
index c73cc7b1b9c..4c1c7cffa2b 100644
--- a/studio/frontend/src/features/audio/audio-run-request.ts
+++ b/studio/frontend/src/features/audio/audio-run-request.ts
@@ -165,6 +165,9 @@ export interface AudioTextRunRequest {
speed?: number | null;
seed?: number | null;
max_tokens?: number | null;
+ /** One take of a sequential music run: 1-based, with the run's 32-hex group id. */
+ take?: number | null;
+ group_id?: string | null;
}
function cleanRef(
@@ -268,6 +271,8 @@ export function buildAudioRunBody(
body.max_tokens = request.max_tokens;
if (request.workflow === "music" && request.music) {
Object.assign(body, musicRunFields(request.music));
+ if (Number.isInteger(request.take) && request.group_id)
+ Object.assign(body, { take: request.take, group_id: request.group_id });
}
return body;
}
diff --git a/studio/frontend/src/features/audio/clone-policy.ts b/studio/frontend/src/features/audio/clone-policy.ts
index 0d216677d03..b390c48e833 100644
--- a/studio/frontend/src/features/audio/clone-policy.ts
+++ b/studio/frontend/src/features/audio/clone-policy.ts
@@ -132,3 +132,42 @@ export function cloneBlocker(
if (input.panelError) return { kind: "panel", reason: input.panelError };
return null;
}
+
+/** Transcribe the reference by itself: only for a model that needs its words, a blank field,
+ * a usable clip, an STT model on disk, and once per reference. */
+export function shouldAutoTranscribeReference(input: {
+ mode: ReferenceTextField;
+ referenceText: string;
+ referenceId: string | null;
+ referenceBusy: boolean;
+ referenceExpired: boolean;
+ sttReady: boolean;
+ doneFor: string | null;
+}): boolean {
+ return (
+ input.mode === "required" &&
+ !input.referenceText.trim() &&
+ input.referenceId !== null &&
+ !input.referenceBusy &&
+ !input.referenceExpired &&
+ input.sttReady &&
+ input.referenceId !== input.doneFor
+ );
+}
+
+const seconds = (value: number) =>
+ `${Number(value.toFixed(1)).toLocaleString("en-US")} s`;
+
+/** The line under a reference clip within the length cap; null when its length is fine. */
+export function referenceLengthHint(
+ durationS: number | null,
+ ideal: readonly [number, number],
+): string | null {
+ if (durationS === null || !Number.isFinite(durationS)) return null;
+ const [low, high] = ideal;
+ if (durationS < low)
+ return `${seconds(durationS)}. ${low} to ${high} s of one clear voice clones best.`;
+ if (durationS > high)
+ return `Longer than needed; ${low} to ${high} s works best.`;
+ return null;
+}
diff --git a/studio/frontend/src/features/audio/components/audio-source-input.tsx b/studio/frontend/src/features/audio/components/audio-source-input.tsx
index 431d6ade91e..6e52833ab7f 100644
--- a/studio/frontend/src/features/audio/components/audio-source-input.tsx
+++ b/studio/frontend/src/features/audio/components/audio-source-input.tsx
@@ -35,6 +35,7 @@ import {
REFERENCE_MAX_SECONDS,
clipReference,
} from "../audio-run-request";
+import { referenceLengthHint } from "../clone-policy";
import {
type AudioSourceStatus,
REFERENCE_EXPIRED_MESSAGE,
@@ -107,6 +108,7 @@ export function AudioSourceInput({
expiredMessage = REFERENCE_EXPIRED_MESSAGE,
usesFirstSeconds = REFERENCE_MAX_SECONDS,
recordHint = "Read a sentence or two in a quiet room.",
+ idealSeconds,
}: {
id: string;
label: string;
@@ -124,6 +126,8 @@ export function AudioSourceInput({
expiredMessage?: string;
usesFirstSeconds?: number | null;
recordHint?: string;
+ /** Seconds that work best, e.g. a clone reference's 5 to 15 s; adds a length hint. */
+ idealSeconds?: readonly [number, number];
}) {
const active = useContext(AudioActiveContext);
const source = useAudioSource({ value, onChange, maxRecordSeconds, active });
@@ -179,6 +183,9 @@ export function AudioSourceInput({
];
const durationS = preview.durationS ?? value?.durationS ?? null;
+ const lengthHint = idealSeconds
+ ? referenceLengthHint(durationS, idealSeconds)
+ : null;
const name = status.phase === "uploading" ? status.name : (value?.name ?? "");
return (
@@ -330,6 +337,10 @@ export function AudioSourceInput({
? `Uses the first ${usesFirstSeconds / 60} min.`
: `Uses the first ${usesFirstSeconds} s.`}
</p>
+ ) : lengthHint ? (
+ <p className="text-ui-11p5 leading-snug text-muted-foreground">
+ {lengthHint}
+ </p>
) : null}
</div>
) : (
diff --git a/studio/frontend/src/features/audio/hooks/use-audio-model-slot.ts b/studio/frontend/src/features/audio/hooks/use-audio-model-slot.ts
index 1ed5a97e4e1..e24ba22ea47 100644
--- a/studio/frontend/src/features/audio/hooks/use-audio-model-slot.ts
+++ b/studio/frontend/src/features/audio/hooks/use-audio-model-slot.ts
@@ -28,6 +28,11 @@ import { confirmRemoteCodeIfNeeded } from "@/features/security";
import { fetchSystemInfo } from "@/hooks/use-system";
import { toast } from "@/lib/toast";
import { getAudioDownloadPlan } from "../api";
+import {
+ type AudioFailureContext,
+ audioFailureActions,
+ audioFailureOf,
+} from "../audio-failure-actions";
import {
audioCppRuntimeProblem,
canTransitionAudioMode,
@@ -73,6 +78,12 @@ import type { SttSidecar } from "./use-stt-sidecar";
const STT_STATUS_POLL_MS = 30_000;
+/** What the page lends a failed load's toast action: it owns the selector, device and runtime update. */
+export type AudioLoadFailureHandlers = Pick<
+ AudioFailureContext,
+ "canUpdateRuntime" | "onUpdateRuntime" | "onChooseModel"
+> & { selectCpuDevice: () => void };
+
export function useAudioModelSlot({
active,
activeRef,
@@ -145,6 +156,13 @@ export function useAudioModelSlot({
| "sttStatusRefreshGeneration"
>) {
const ttsLoadInFlight = useRef(false);
+ const loadFailureHandlers = useRef<AudioLoadFailureHandlers | null>(null);
+ const setLoadFailureHandlers = useCallback(
+ (handlers: AudioLoadFailureHandlers) => {
+ loadFailureHandlers.current = handlers;
+ },
+ [],
+ );
const pendingRoutedTtsPick = useRef<{
repoId: string;
ggufFilename?: string | null;
@@ -152,6 +170,7 @@ export function useAudioModelSlot({
audioType?: string | null;
remoteCodeApproval?: RemoteCodeApproval;
isGguf?: boolean | null;
+ deviceOverride?: "cpu";
} | null>(null);
const ttsLoadGeneration = useRef(0);
const pendingTtsLoad = useRef<{
@@ -176,6 +195,11 @@ export function useAudioModelSlot({
generation: number;
} | null>(null);
const stagedTtsLoadDeferred = useRef(false);
+ const pickModelVariantRef = useRef<
+ (id: string, quant?: string) => Promise<void>
+ >(async () => {});
+ // Repeats the last successful load, so a generation failure's "Load into CPU RAM" reloads the resident model.
+ const lastTtsLoad = useRef<((device: "cpu") => Promise<void>) | null>(null);
const loadTtsModel = useCallback(
async (
@@ -186,6 +210,8 @@ export function useAudioModelSlot({
audioType?: string | null,
remoteCodeApproval?: RemoteCodeApproval,
isGguf?: boolean | null,
+ // "Load into CPU RAM" from a failed load: the device choice has not re-rendered yet.
+ deviceOverride?: "cpu",
) => {
// ?model= is already cleared, so a pick arriving mid-teardown is replayed from the finally below.
if (ttsLoadInFlight.current || busyRef.current === "generating") {
@@ -196,6 +222,7 @@ export function useAudioModelSlot({
audioType,
remoteCodeApproval,
isGguf,
+ deviceOverride,
};
return;
}
@@ -233,6 +260,16 @@ export function useAudioModelSlot({
return;
}
const generation = ++ttsLoadGeneration.current;
+ const retryLoad = (device: "cpu") =>
+ loadTtsModelRef.current(
+ repoId,
+ ggufFilename,
+ loadId,
+ audioType,
+ remoteCodeApproval,
+ isGguf,
+ device,
+ );
const controller = new AbortController();
const loadRequestId = crypto.randomUUID();
const pending = {
@@ -275,7 +312,7 @@ export function useAudioModelSlot({
);
if (controller.signal.aborted || !isCurrent()) return;
}
- const wantsCpu = audioDevice === "cpu";
+ const wantsCpu = deviceOverride === "cpu" || audioDevice === "cpu";
const isGgufLoad = isGgufTtsTarget({ repoId, ggufFilename, loadId, isGguf });
const res = await loadModel(
{
@@ -323,6 +360,8 @@ export function useAudioModelSlot({
duration: offloadNotice ? 8000 : undefined,
},
);
+ // Only on success: a failed attempt leaves the previous model resident.
+ lastTtsLoad.current = retryLoad;
const loadedWorkflow = workflowForLoadedModel({
current: useAudioWorkspaceStore.getState().workflow,
audioWorkflows: res.audio_workflows,
@@ -331,6 +370,12 @@ export function useAudioModelSlot({
const workspace = useAudioWorkspaceStore.getState();
workspace.rememberModel(loadedWorkflow, repoId);
if (modeRef.current === "speak") workspace.commitWorkflow(loadedWorkflow);
+ if (res.audio_device_fallback === "cpu" && !wantsCpu) {
+ toast.warning(
+ "No usable GPU, so the model loaded into CPU RAM. Generation will be slower.",
+ { duration: 8000 },
+ );
+ }
if (
wantsCpu &&
!isGgufLoad &&
@@ -347,7 +392,26 @@ export function useAudioModelSlot({
});
}
} catch (error) {
- if (isCurrent()) {
+ const failure = audioFailureOf(error);
+ const handlers = loadFailureHandlers.current;
+ if (isCurrent() && failure && handlers) {
+ const [action] = audioFailureActions(failure, {
+ ...handlers,
+ deviceIsCpu: deviceOverride === "cpu" || audioDevice === "cpu",
+ cpuUnsupported: musicGenerationRequiresCuda(repoId, audioType),
+ onUseVariant: (variant) =>
+ void pickModelVariantRef.current(repoId, variant),
+ onUseCpu: () => {
+ handlers.selectCpuDevice();
+ void retryLoad("cpu");
+ },
+ });
+ toast.error((error as Error).message, {
+ id: toastId,
+ duration: 12000,
+ action: action && { label: action.label, onClick: action.onClick },
+ });
+ } else if (isCurrent()) {
toast.error(
error instanceof Error ? error.message : "Model load failed.",
{ id: toastId },
@@ -372,6 +436,11 @@ export function useAudioModelSlot({
const loadTtsModelRef = useRef(loadTtsModel);
loadTtsModelRef.current = loadTtsModel;
+ /** Repeat the last load into CPU RAM; false when there is none to repeat. */
+ const reloadOnCpu = useCallback(() => {
+ void lastTtsLoad.current?.("cpu");
+ return lastTtsLoad.current !== null;
+ }, []);
/** Start a pick that lost the race with a load still settling. Visible pages only: a load started
* while hidden outlives the deactivation effect that would cancel it. */
const replayQueuedTtsPick = useCallback(() => {
@@ -385,6 +454,7 @@ export function useAudioModelSlot({
queued.audioType,
queued.remoteCodeApproval,
queued.isGguf,
+ queued.deviceOverride,
);
}, []);
const invalidatePendingStagedTts = useCallback(() => {
@@ -1074,17 +1144,18 @@ export function useAudioModelSlot({
};
}, [active, isMac]);
- const pickRecommendedModel = useCallback(
- async (id: string) => {
+ /** Pick one quant of a repo (a failed load's smaller variant), or the auto choice without one. */
+ const pickModelVariant = useCallback(
+ async (id: string, quant?: string) => {
if (busyRef.current !== null) return;
try {
const listing = await listGgufVariants(id, hfApiToken(getHfToken()));
- const variant = selectAutoGgufVariant(
- listing.variants,
- listing.default_variant,
- );
+ const wanted = quant?.toLowerCase();
+ const variant = wanted
+ ? listing.variants.find((v) => v.quant.toLowerCase() === wanted)
+ : selectAutoGgufVariant(listing.variants, listing.default_variant);
if (!variant) {
- toast.error(`${id} does not publish a runnable GGUF file.`);
+ toast.error(`${id} does not publish a ${quant ? `${quant} file` : "runnable GGUF file"}.`);
return;
}
await handleModelSelect(id, {
@@ -1104,6 +1175,13 @@ export function useAudioModelSlot({
},
[busyRef, handleModelSelect],
);
+ useEffect(() => {
+ pickModelVariantRef.current = pickModelVariant;
+ }, [pickModelVariant]);
+ const pickRecommendedModel = useCallback(
+ (id: string) => pickModelVariant(id),
+ [pickModelVariant],
+ );
return {
replayQueuedTtsPick,
@@ -1112,6 +1190,9 @@ export function useAudioModelSlot({
pendingTranscribeRelease,
handleModelSelect,
pickRecommendedModel,
+ pickModelVariant,
+ reloadOnCpu,
+ setLoadFailureHandlers,
handleEject,
trainedTtsModels,
};
diff --git a/studio/frontend/src/features/audio/hooks/use-clone-generation.ts b/studio/frontend/src/features/audio/hooks/use-clone-generation.ts
index 3ab6e74c4ca..f69b4eff44f 100644
--- a/studio/frontend/src/features/audio/hooks/use-clone-generation.ts
+++ b/studio/frontend/src/features/audio/hooks/use-clone-generation.ts
@@ -9,11 +9,13 @@ import {
fetchAudioBlob,
runAudio,
} from "../api";
+import { reportAudioFailure } from "../audio-failure-actions";
import {
type AudioOptionValues,
audioOptionLabel,
audioOptionSpecsFor,
audioOptionsForRequest,
+ ignoredOptionsWarning,
missingRequiredAudioOptions,
} from "../audio-options";
import { persistedClipForGeneration } from "../audio-page-policy";
@@ -22,7 +24,12 @@ import {
selectionExpired,
sourceRefOf,
} from "../audio-run-request";
-import { cloneBlocker, referenceTextField } from "../clone-policy";
+import { audioModelLabel } from "../audio-workspace-utils";
+import {
+ cloneBlocker,
+ referenceTextField,
+ shouldAutoTranscribeReference,
+} from "../clone-policy";
import type { AudioSourceInputHandle } from "../components/audio-source-input";
import type { GenerateBlocker } from "../pages/tts-workspace";
import { useAudioCloneStore } from "../stores/audio-clone-store";
@@ -31,6 +38,7 @@ import {
audioModelContextFor,
claimedOptionNames,
collectToolRequest,
+ readsRequestInput,
toolValueKey,
} from "../tools/select";
import type { AudioHostState } from "./audio-host-state";
@@ -44,6 +52,17 @@ import { useReferenceTranscribe } from "./use-reference-transcribe";
export const CLONE_TEXT_FIELD_ID = "clone-text";
export const CLONE_REFERENCE_TEXT_FIELD_ID = "clone-reference-text";
+export function warnIgnoredOptions(
+ names: readonly string[] | undefined,
+ model: string | null | undefined,
+): void {
+ const message = ignoredOptionsWarning(
+ names ?? [],
+ model ? audioModelLabel(model) : "This model",
+ );
+ if (message) toast.warning(message);
+}
+
export async function showRunResult({
response,
text,
@@ -60,6 +79,7 @@ export async function showRunResult({
AudioGallery,
"refreshGallery" | "selectClip" | "setFallbackClip" | "setSelectedId"
>): Promise<void> {
+ warnIgnoredOptions(response.ignored_options, response.model);
// An edit whose output was not saved returns only its source clip: play the inline audio.
// Other runs name their clips by role (variation, edit, a stem): the first one is the result.
const clip =
@@ -104,6 +124,7 @@ export async function showRunResult({
/** Mirrors useSpeechGeneration's flow so Stop, phases and errors behave the same. */
export function useCloneGeneration({
status,
+ busy,
busyRef,
setBusy,
updateGenerationPhase,
@@ -121,9 +142,12 @@ export function useCloneGeneration({
replayQueuedTtsPick,
audioOptionValues,
sttRepo,
+ sttReady,
+ onClonePage,
}: Pick<
AudioHostState,
| "status"
+ | "busy"
| "busyRef"
| "setBusy"
| "updateGenerationPhase"
@@ -141,6 +165,10 @@ export function useCloneGeneration({
Pick<AudioModelSlot, "pendingTranscribeRelease" | "replayQueuedTtsPick"> & {
audioOptionValues: AudioOptionValues;
sttRepo: string | null;
+ /** The STT model is on disk, so transcribing never starts a download. */
+ sttReady: boolean;
+ /** Audio is the visible tab and Clone its page: auto-transcribe runs only then. */
+ onClonePage: boolean;
}) {
const reference = useAudioCloneStore((state) => state.reference);
const referenceText = useAudioCloneStore((state) => state.referenceText);
@@ -244,6 +272,8 @@ export function useCloneGeneration({
[audioOptionSpecs, claimedOptions],
);
const transcriptField = referenceTextField(toolContext, toolRequest.patch);
+ // Strict models that read no language (F5, CosyVoice3) get none.
+ const languageShown = readsRequestInput(toolContext, "language");
const [now, setNow] = useState(() => Date.now());
useEffect(() => {
@@ -256,11 +286,46 @@ export function useCloneGeneration({
selectionExpired(reference, now) ||
(reference !== null && reference.id === expiredReferenceId);
+ const referenceBusy =
+ referenceStatus.phase === "uploading" ||
+ referenceStatus.phase === "recording";
+ // A model that needs the clip's words transcribes each new reference once by itself.
+ const autoTranscribed = useRef<string | null>(null);
+ const transcribeOnce = transcriber.transcribe;
+ useEffect(() => {
+ if (
+ !onClonePage ||
+ !reference ||
+ // A busy page would refuse the run; try again once it settles.
+ busy !== null ||
+ !shouldAutoTranscribeReference({
+ mode: transcriptField,
+ referenceText,
+ referenceId: reference.id,
+ referenceBusy,
+ referenceExpired,
+ sttReady,
+ doneFor: autoTranscribed.current,
+ })
+ )
+ return;
+ autoTranscribed.current = reference.id;
+ void transcribeOnce(reference);
+ }, [
+ onClonePage,
+ reference,
+ busy,
+ transcriptField,
+ referenceText,
+ referenceBusy,
+ referenceExpired,
+ sttReady,
+ transcribeOnce,
+ ]);
+
const inputBlocker = cloneBlocker({
reference,
- referenceBusy:
- referenceStatus.phase === "uploading" ||
- referenceStatus.phase === "recording",
+ referenceBusy,
referenceExpired,
referenceError:
referenceStatus.phase === "error" ? referenceStatus.message : null,
@@ -344,7 +409,7 @@ export function useCloneGeneration({
{
workflow: "clone",
text: draftText,
- language: state.language || null,
+ language: languageShown ? state.language || null : null,
instructions: patch.instructions ?? null,
inputs: {
reference: sourceRefOf(state.reference),
@@ -375,6 +440,7 @@ export function useCloneGeneration({
} catch (error) {
if (!controller.signal.aborted) {
updateGenerationPhase("finishing");
+ reportAudioFailure(error);
const expired =
error instanceof AudioApiError &&
error.status === 404 &&
@@ -417,6 +483,7 @@ export function useCloneGeneration({
toolRequest,
generateAbort,
transcriptField,
+ languageShown,
refreshGallery,
selectClip,
setFallbackClip,
@@ -441,6 +508,7 @@ export function useCloneGeneration({
setReferenceStatus,
referenceExpired,
transcriptField,
+ languageShown,
transcriber,
toolContext,
toolPanels,
diff --git a/studio/frontend/src/features/audio/hooks/use-convert-generation.ts b/studio/frontend/src/features/audio/hooks/use-convert-generation.ts
index a75a49478f9..3e7381b5759 100644
--- a/studio/frontend/src/features/audio/hooks/use-convert-generation.ts
+++ b/studio/frontend/src/features/audio/hooks/use-convert-generation.ts
@@ -4,6 +4,7 @@
import { toast } from "@/lib/toast";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { AudioApiError, runAudio } from "../api";
+import { reportAudioFailure } from "../audio-failure-actions";
import {
type AudioOptionValues,
audioOptionLabel,
@@ -419,6 +420,7 @@ export function useConvertGeneration({
} catch (error) {
if (!controller.signal.aborted) {
updateGenerationPhase("finishing");
+ reportAudioFailure(error);
// Only the expired-upload 404: a deleted clip or voice says otherwise and leaves uploads alone.
const expiredRole =
error instanceof AudioApiError && error.status === 404
diff --git a/studio/frontend/src/features/audio/hooks/use-edit-generation.ts b/studio/frontend/src/features/audio/hooks/use-edit-generation.ts
index 4d0c8bd2885..40ba3a2f8d9 100644
--- a/studio/frontend/src/features/audio/hooks/use-edit-generation.ts
+++ b/studio/frontend/src/features/audio/hooks/use-edit-generation.ts
@@ -4,6 +4,7 @@
import { toast } from "@/lib/toast";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { AudioApiError, runAudio } from "../api";
+import { reportAudioFailure } from "../audio-failure-actions";
import {
type AudioOptionValues,
audioOptionLabel,
@@ -336,6 +337,7 @@ export function useEditGeneration({
} catch (error) {
if (!controller.signal.aborted) {
updateGenerationPhase("finishing");
+ reportAudioFailure(error);
const expired =
error instanceof AudioApiError &&
error.status === 404 &&
diff --git a/studio/frontend/src/features/audio/hooks/use-music-generation.ts b/studio/frontend/src/features/audio/hooks/use-music-generation.ts
index a66db0b48bc..e826851cb08 100644
--- a/studio/frontend/src/features/audio/hooks/use-music-generation.ts
+++ b/studio/frontend/src/features/audio/hooks/use-music-generation.ts
@@ -4,6 +4,7 @@
import { toast } from "@/lib/toast";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { runAudio } from "../api";
+import { reportAudioFailure } from "../audio-failure-actions";
import {
type AudioOptionSpec,
type AudioOptionValues,
@@ -19,6 +20,7 @@ import {
effectiveMusicMode,
musicBlocker,
reloadNotice,
+ runMusicTakes,
variationsFor,
withWaitingEdit,
} from "../music/music-policy";
@@ -242,20 +244,29 @@ export function useMusicGeneration({
generateAbort.current = controller;
updateGenerationPhase("generating");
try {
- const response = await runAudio(request, controller.signal);
- updateGenerationPhase("finishing");
- await showRunResult({
- response,
- text: request.text || request.music?.lyrics || "",
- workflow: "music",
- refreshGallery,
- selectClip,
- setFallbackClip,
- setSelectedId,
+ await runMusicTakes({
+ request,
+ count: variations,
+ how: rule.variations?.how ?? null,
+ signal: controller.signal,
+ run: (take) => runAudio(take, controller.signal),
+ onStatus: setRunStatus,
+ onTake: (response) =>
+ showRunResult({
+ response,
+ text: request.text || request.music?.lyrics || "",
+ workflow: "music",
+ refreshGallery,
+ selectClip,
+ setFallbackClip,
+ setSelectedId,
+ }),
});
+ updateGenerationPhase("finishing");
if (reloads) await refreshStatus();
} catch (error) {
if (!controller.signal.aborted) {
+ reportAudioFailure(error);
updateGenerationPhase("finishing");
const message =
error instanceof Error ? error.message : "Music generation failed.";
diff --git a/studio/frontend/src/features/audio/hooks/use-separate-generation.ts b/studio/frontend/src/features/audio/hooks/use-separate-generation.ts
index cf3c747020a..1cd09695350 100644
--- a/studio/frontend/src/features/audio/hooks/use-separate-generation.ts
+++ b/studio/frontend/src/features/audio/hooks/use-separate-generation.ts
@@ -4,6 +4,7 @@
import { toast } from "@/lib/toast";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { AudioApiError, runAudio } from "../api";
+import { reportAudioFailure } from "../audio-failure-actions";
import { selectionExpired, sourceRefOf } from "../audio-run-request";
import type { AudioSourceInputHandle } from "../components/audio-source-input";
import type { GenerateBlocker } from "../pages/tts-workspace";
@@ -243,6 +244,7 @@ export function useSeparateGeneration({
} catch (error) {
if (!controller.signal.aborted) {
updateGenerationPhase("finishing");
+ reportAudioFailure(error);
const expired =
error instanceof AudioApiError &&
error.status === 404 &&
diff --git a/studio/frontend/src/features/audio/hooks/use-speech-generation.ts b/studio/frontend/src/features/audio/hooks/use-speech-generation.ts
index 527a0ed9610..809e6217326 100644
--- a/studio/frontend/src/features/audio/hooks/use-speech-generation.ts
+++ b/studio/frontend/src/features/audio/hooks/use-speech-generation.ts
@@ -41,6 +41,11 @@ import { galleryCache } from "./use-audio-gallery";
import { useAudioCloneStore } from "../stores/audio-clone-store";
import { useAudioVoicesStore } from "../stores/audio-voices-store";
import { useAudioWorkspaceStore } from "../stores/audio-workspace-store";
+import {
+ speakVoiceLogic,
+ speakVoiceStored,
+ voiceOptionName,
+} from "../tools/panel-logic";
import { audioToolPanelsFor, isInstructionPanel } from "../tools/registry";
import {
audioModelContextFor,
@@ -48,8 +53,9 @@ import {
collectToolRequest,
toolValueKey,
} from "../tools/select";
-import { showRunResult } from "./use-clone-generation";
+import { showRunResult, warnIgnoredOptions } from "./use-clone-generation";
import type { AudioWorkflowId } from "../workflows";
+import { reportAudioFailure } from "../audio-failure-actions";
import type { AudioGallery } from "./use-audio-gallery";
import type { AudioModelSlot } from "./use-audio-model-slot";
@@ -236,8 +242,20 @@ export function useSpeechGeneration({
musicNeedsDescription,
}),
savedVoiceIds: voicesLoaded ? voices.map((voice) => voice.id) : null,
+ voicesWithoutTranscript: voices
+ .filter((voice) => !voice.transcript?.trim())
+ .map((voice) => voice.id),
+ voiceOption: voiceOptionName(audioOptionSpecs),
}),
- [status, workflow, cudaMusicGeneration, musicNeedsDescription, voices, voicesLoaded],
+ [
+ status,
+ workflow,
+ cudaMusicGeneration,
+ musicNeedsDescription,
+ voices,
+ voicesLoaded,
+ audioOptionSpecs,
+ ],
);
const toolPanels = useMemo(
() => audioToolPanelsFor(workflow, toolContext),
@@ -247,13 +265,19 @@ export function useSpeechGeneration({
const toolValues = useMemo(() => {
const values: Record<string, unknown> = {};
for (const panel of toolPanels) {
+ const stored =
+ storedToolValues[toolValueKey(audioOptionsModel, workflow, panel.id)];
values[panel.id] = isInstructionPanel(panel.id)
? { instructions: audioInstructions, language: audioLanguage }
- : storedToolValues[toolValueKey(audioOptionsModel, workflow, panel.id)];
+ : panel.id === speakVoiceLogic.id
+ ? speakVoiceStored(stored, audioOptionValues, toolContext.voiceOption)
+ : stored;
}
return values;
}, [
toolPanels,
+ audioOptionValues,
+ toolContext.voiceOption,
audioInstructions,
audioLanguage,
storedToolValues,
@@ -384,6 +408,7 @@ export function useSpeechGeneration({
} catch (error) {
if (!voiceController.signal.aborted) {
updateGenerationPhase("finishing");
+ reportAudioFailure(error);
const message =
error instanceof Error ? error.message : "Audio generation failed.";
setGenerationError(message);
@@ -424,6 +449,7 @@ export function useSpeechGeneration({
: {}),
signal: controller.signal,
});
+ warnIgnoredOptions(generated.ignored_options, generated.model);
if (generated.choices[0]?.finish_reason === "length")
toast.warning(
maxTokens < TTS_MAX_TOKENS
@@ -463,6 +489,7 @@ export function useSpeechGeneration({
} catch (error) {
if (!controller.signal.aborted) {
updateGenerationPhase("finishing");
+ reportAudioFailure(error);
setGenerationError(
error instanceof Error ? error.message : "Audio generation failed.",
);
diff --git a/studio/frontend/src/features/audio/music/music-policy.ts b/studio/frontend/src/features/audio/music/music-policy.ts
index 1e4e25a94a9..9ab657602ef 100644
--- a/studio/frontend/src/features/audio/music/music-policy.ts
+++ b/studio/frontend/src/features/audio/music/music-policy.ts
@@ -360,3 +360,59 @@ function editSourceRef(source: AudioSourceSelection | null) {
if (!source || source.kind === "voice") return null;
return sourceRefOf(source);
}
+
+/** The id one run's takes share, as the server expects it: 32 lowercase hex digits. */
+export function newMusicGroupId(): string {
+ // Not randomUUID: Unsloth on a LAN address is not a secure context.
+ return Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) =>
+ byte.toString(16).padStart(2, "0"),
+ ).join("");
+}
+
+/** Sequential variations go one request per take, so Stop keeps the finished takes. Later takes
+ * reuse take 1's seed (the server offsets it by take); batch and single takes stay one request. */
+export async function runMusicTakes<
+ R extends {
+ clips: readonly { seed?: number | null }[];
+ audio?: { seed?: number | null } | null;
+ },
+>({
+ request,
+ count,
+ how,
+ run,
+ onTake,
+ onStatus,
+ signal,
+ groupId,
+}: {
+ request: AudioTextRunRequest;
+ count: number;
+ how: "batch" | "sequential" | null;
+ run: (request: AudioTextRunRequest) => Promise<R>;
+ onTake: (response: R) => Promise<void>;
+ onStatus: (status: string) => void;
+ signal?: AbortSignal;
+ groupId?: string;
+}): Promise<void> {
+ if (how !== "sequential" || count <= 1 || !request.music) {
+ await onTake(await run(request));
+ return;
+ }
+ const group = groupId ?? newMusicGroupId();
+ let seed: number | null = null;
+ for (let take = 1; take <= count; take++) {
+ if (signal?.aborted) return;
+ onStatus(`Take ${take} of ${count}…`);
+ const response = await run({
+ ...request,
+ ...(seed !== null ? { seed } : {}),
+ music: { ...request.music, variations: 1 },
+ take,
+ group_id: group,
+ });
+ if (take === 1)
+ seed = response.clips[0]?.seed ?? response.audio?.seed ?? null;
+ await onTake(response);
+ }
+}
diff --git a/studio/frontend/src/features/audio/pages/clone-page.tsx b/studio/frontend/src/features/audio/pages/clone-page.tsx
index 761920536c7..c29fbf83b76 100644
--- a/studio/frontend/src/features/audio/pages/clone-page.tsx
+++ b/studio/frontend/src/features/audio/pages/clone-page.tsx
@@ -67,6 +67,7 @@ function CloneInputs({
id="clone-reference"
label="Reference"
hint="5 to 15 s of one clear voice works best."
+ idealSeconds={[5, 15]}
value={reference}
onChange={adoptReference}
disabled={disabled}
@@ -174,13 +175,15 @@ function CloneInputs({
</div>
)}
</div>
- <LanguageSelect
- id="clone-language"
- label="Language"
- value={clone.language}
- onChange={setLanguage}
- hint="The language of the text to speak. Auto lets the model tell."
- />
+ {clone.languageShown ? (
+ <LanguageSelect
+ id="clone-language"
+ label="Language"
+ value={clone.language}
+ onChange={setLanguage}
+ hint="The language of the text to speak. Auto lets the model tell."
+ />
+ ) : null}
</AudioHistoryProvider>
);
}
diff --git a/studio/frontend/src/features/audio/pages/tts-workspace.tsx b/studio/frontend/src/features/audio/pages/tts-workspace.tsx
index 4c113c3117b..53d87a520e2 100644
--- a/studio/frontend/src/features/audio/pages/tts-workspace.tsx
+++ b/studio/frontend/src/features/audio/pages/tts-workspace.tsx
@@ -20,6 +20,7 @@ import { toast } from "@/lib/toast";
import { cn } from "@/lib/utils";
import {
Copy01Icon,
+ DiceFaces03Icon,
FloppyDiskIcon,
SparklesIcon,
StopIcon,
@@ -468,6 +469,7 @@ export function TtsOutput({
handleArchiveClip,
handleDownloadClipById,
onUseTextAgain,
+ onReuseSeed,
handleCopyPrompt,
sendHandlersFor,
onSaveVoice,
@@ -505,6 +507,8 @@ export function TtsOutput({
selectedClipSrc: string | undefined;
handleClearGallery: () => Promise<void>;
onUseTextAgain: (clip: AudioGalleryClip) => void;
+ /** Puts the seed a clip was made with into the next take. */
+ onReuseSeed?: (seed: number) => void;
sendHandlersFor: (clip: AudioGalleryClip) => ClipSendHandlers;
onSaveVoice: (clip: AudioGalleryClip) => void;
pending: {
@@ -593,6 +597,18 @@ export function TtsOutput({
/>
{useAgainLabel}
</DropdownMenuItem>
+ {onReuseSeed && typeof clip.settings?.seed === "number" ? (
+ <DropdownMenuItem
+ onClick={() => onReuseSeed(Number(clip.settings?.seed))}
+ >
+ <HugeiconsIcon
+ icon={DiceFaces03Icon}
+ strokeWidth={1.75}
+ className="size-icon"
+ />
+ Reuse seed
+ </DropdownMenuItem>
+ ) : null}
{showCopyText ? (
<DropdownMenuItem onClick={() => void handleCopyPrompt(clip.prompt)}>
<HugeiconsIcon
diff --git a/studio/frontend/src/features/audio/stores/audio-workspace-store.ts b/studio/frontend/src/features/audio/stores/audio-workspace-store.ts
index cae0ef4cff8..3b51bacceb0 100644
--- a/studio/frontend/src/features/audio/stores/audio-workspace-store.ts
+++ b/studio/frontend/src/features/audio/stores/audio-workspace-store.ts
@@ -3,6 +3,7 @@
import { create } from "zustand";
import { persist } from "zustand/middleware";
+import type { AudioFailure } from "../audio-failure-actions";
import type { AudioWorkflowId } from "../workflows";
export const AUDIO_WORKSPACE_STORAGE_KEY = "unsloth_audio_workspace";
@@ -15,6 +16,9 @@ interface AudioWorkspaceState {
requestedWorkflow: AudioWorkflowId | null;
navExpanded: boolean;
lastModelByWorkflow: Partial<Record<AudioWorkflowId, string>>;
+ /** The structured failure behind the last generation error; never persisted. */
+ failure: { message: string; failure: AudioFailure } | null;
+ setFailure: (failure: AudioWorkspaceState["failure"]) => void;
commitWorkflow: (workflow: AudioWorkflowId) => void;
adoptWorkflow: (workflow: AudioWorkflowId) => void;
requestWorkflow: (workflow: AudioWorkflowId) => void;
@@ -32,6 +36,8 @@ export const useAudioWorkspaceStore = create<AudioWorkspaceState>()(
requestedWorkflow: null,
navExpanded: false,
lastModelByWorkflow: {},
+ failure: null,
+ setFailure: (failure) => set({ failure }),
// Any committed switch settles a pending request, so a stale one never fires later.
commitWorkflow: (workflow) =>
set({ workflow, workflowChosen: true, requestedWorkflow: null }),
diff --git a/studio/frontend/src/features/audio/tools/panel-logic.ts b/studio/frontend/src/features/audio/tools/panel-logic.ts
index 27d612e33aa..8930a5ff7bf 100644
--- a/studio/frontend/src/features/audio/tools/panel-logic.ts
+++ b/studio/frontend/src/features/audio/tools/panel-logic.ts
@@ -7,7 +7,7 @@ import type { AudioOptionSpec } from "../audio-options";
import { type AudioSourceSelection, sourceRefOf } from "../audio-run-request";
import { INDEX_TTS2_EMOTIONS, emotionVectorString } from "../clone-policy";
import type { AudioSourceStatus } from "../hooks/audio-source-state";
-import type { AudioRunPatch, AudioToolPanel } from "./types";
+import type { AudioModelContext, AudioRunPatch, AudioToolPanel } from "./types";
type AudioToolPanelLogic<V> = Omit<AudioToolPanel<V>, "Component">;
@@ -239,37 +239,84 @@ export const f5SpeedDialectLogic: AudioToolPanelLogic<SpeedDialectValue> = {
export interface SpeakVoiceValue {
source: "builtin" | "saved";
voiceId: string | null;
+ /** The built-in voice; null leaves the model's default. */
+ builtin: string | number | boolean | null;
}
export const SAVED_VOICE_MISSING =
"Pick a saved voice, or switch Voice to Built-in.";
export const SAVED_VOICE_DELETED =
"That saved voice was deleted. Pick another one, or switch Voice to Built-in.";
+export const SAVED_VOICE_NO_TRANSCRIPT =
+ "This voice has no transcript, and this model needs one. Add it on Clone, or pick another voice.";
+
+const VOICE_OPTION_NAMES = ["voice", "voice_id", "speaker"] as const;
+
+/** Saved voices clone, so a model that cannot clone always uses its built-in voice. */
+export const usesSavedVoice = (value: SpeakVoiceValue, ctx?: AudioModelContext) =>
+ value.source === "saved" && ctx?.audioWorkflows?.includes("clone") === true;
+
+/** The option that picks a built-in voice: the first choice list among voice, voice_id and
+ * speaker, else the first of them the model declares at all. */
+export function voiceOptionName(
+ specs: readonly AudioOptionSpec[],
+): string | null {
+ const declared = VOICE_OPTION_NAMES.map((name) =>
+ specs.find((spec) => spec.name === name),
+ ).filter((spec) => spec !== undefined);
+ return (
+ (declared.find((spec) => spec.type === "enum") ?? declared[0])?.name ??
+ null
+ );
+}
+
+/** The kept picker value; one saved before the picker held built-in voices takes the voice
+ * chosen in Advanced, which the picker now claims. */
+export function speakVoiceStored(
+ stored: unknown,
+ optionValues: Readonly<Record<string, unknown>>,
+ voiceOption: string | null | undefined,
+): unknown {
+ const saved = voiceOption ? optionValues[voiceOption] : undefined;
+ if (saved === undefined || saved === null) return stored;
+ if (stored === undefined) return { builtin: saved };
+ if (typeof stored === "object" && stored !== null && !("builtin" in stored))
+ return { ...stored, builtin: saved };
+ return stored;
+}
export const speakVoiceLogic: AudioToolPanelLogic<SpeakVoiceValue> = {
id: "speak-voice",
families: [],
workflows: ["speak"],
title: "Voice",
- claims: [],
- // Speak sends no transcript, so a model that needs one (Fish Audio) clones only on Clone.
+ claims: VOICE_OPTION_NAMES,
appliesTo: (ctx) =>
Boolean(
ctx.audioWorkflows?.includes("speak") &&
- ctx.audioWorkflows.includes("clone") &&
- ctx.referenceTextMode !== "required",
+ (ctx.voiceOption || ctx.audioWorkflows.includes("clone")),
),
- initial: () => ({ source: "builtin", voiceId: null }),
- toRequest: (value) =>
- value.source === "saved" && value.voiceId
- ? { inputs: { reference: { voice_id: value.voiceId } } }
- : {},
+ initial: () => ({ source: "builtin", voiceId: null, builtin: null }),
+ toRequest: (value, ctx) => {
+ if (usesSavedVoice(value, ctx)) {
+ return value.voiceId
+ ? { inputs: { reference: { voice_id: value.voiceId } } }
+ : {};
+ }
+ return ctx?.voiceOption && value.builtin !== null
+ ? { options: { [ctx.voiceOption]: value.builtin } }
+ : {};
+ },
validate: (value, _core, ctx) => {
- if (value.source !== "saved") return null;
+ if (!usesSavedVoice(value, ctx)) return null;
if (!value.voiceId) return SAVED_VOICE_MISSING;
// Deleting a voice on Clone does not reach the choice kept here.
- return ctx.savedVoiceIds && !ctx.savedVoiceIds.includes(value.voiceId)
- ? SAVED_VOICE_DELETED
+ if (ctx.savedVoiceIds && !ctx.savedVoiceIds.includes(value.voiceId))
+ return SAVED_VOICE_DELETED;
+ // The server falls back to the voice's transcript, so only an empty one blocks.
+ return ctx.referenceTextMode === "required" &&
+ ctx.voicesWithoutTranscript?.includes(value.voiceId)
+ ? SAVED_VOICE_NO_TRANSCRIPT
: null;
},
};
diff --git a/studio/frontend/src/features/audio/tools/registry.tsx b/studio/frontend/src/features/audio/tools/registry.tsx
index 5c2d863a40e..af795e8e972 100644
--- a/studio/frontend/src/features/audio/tools/registry.tsx
+++ b/studio/frontend/src/features/audio/tools/registry.tsx
@@ -16,6 +16,7 @@ import {
instructionsKindFor,
legacyMusicDescription,
panelApplies,
+ readsRequestInput,
} from "./select";
import { SPEAK_TOOL_PANELS } from "./speak-panels";
import type {
@@ -54,7 +55,9 @@ function instructionsPanel(
claims: [],
appliesTo: (ctx) =>
instructionsKindFor(ctx) === kind &&
- (kind !== "music" || legacyMusicDescription(ctx)),
+ (kind !== "music" || legacyMusicDescription(ctx)) &&
+ // A strict model that reads no instruction (Kokoro) would drop the description.
+ (kind !== "voice" || readsRequestInput(ctx, "instruct", "instruction")),
initial: () => ({ instructions: "", language: "" }),
Component: ({ value, onChange, ctx }) => (
<>
diff --git a/studio/frontend/src/features/audio/tools/select.ts b/studio/frontend/src/features/audio/tools/select.ts
index 9377c3fdc04..e9dd40ebed4 100644
--- a/studio/frontend/src/features/audio/tools/select.ts
+++ b/studio/frontend/src/features/audio/tools/select.ts
@@ -64,6 +64,7 @@ export function audioModelContextFor(
audio_family?: string | null;
audio_workflows?: readonly string[] | null;
audio_required_inputs?: readonly string[] | null;
+ audio_request_inputs?: readonly string[] | null;
audio_reference_text?: string | null;
audio_convert?: AudioConvertCaps | null;
audio_music?: unknown;
@@ -92,11 +93,25 @@ export function audioModelContextFor(
REFERENCE_TEXT_MODES.has(referenceText)
? (referenceText as AudioReferenceTextMode)
: null,
+ requestInputs: Array.isArray(status?.audio_request_inputs)
+ ? status.audio_request_inputs
+ : null,
audioMusic: parseMusicCapabilities(status?.audio_music) !== null,
convert: convertCapsOf(status?.audio_convert),
};
}
+/** Whether the model reads one of these request inputs; unknown (null) counts as yes. */
+export function readsRequestInput(
+ ctx: Pick<AudioModelContext, "requestInputs">,
+ ...names: string[]
+): boolean {
+ return (
+ ctx.requestInputs == null ||
+ names.some((name) => ctx.requestInputs?.includes(name))
+ );
+}
+
function convertCapsOf(value: unknown): AudioConvertCaps | null {
if (!isPlainObject(value)) return null;
const caps = value as Partial<AudioConvertCaps>;
diff --git a/studio/frontend/src/features/audio/tools/speak-panels.tsx b/studio/frontend/src/features/audio/tools/speak-panels.tsx
index 90eb45c7c12..29de52b5b17 100644
--- a/studio/frontend/src/features/audio/tools/speak-panels.tsx
+++ b/studio/frontend/src/features/audio/tools/speak-panels.tsx
@@ -2,45 +2,79 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { PillTabs } from "@/features/model-picker/components/model-selector/pill-tabs";
+import type { AudioOptionSpec } from "../audio-options";
+import { AudioOptionFields } from "../audio-options-fields";
import { formatVibeVoiceScript } from "../clone-policy";
import { VoicePicker } from "../components/voice-picker";
import {
type SpeakVoiceValue,
speakVoiceLogic,
+ usesSavedVoice,
vibeVoiceDialogueLogic,
} from "./panel-logic";
-import type { AudioToolPanel } from "./types";
+import type { AudioModelContext, AudioToolPanel } from "./types";
+
+/** The model's built-in voice list, unless a saved voice is in use. */
+const builtinVoiceSpecs = (
+ specs: readonly AudioOptionSpec[],
+ value: SpeakVoiceValue,
+ ctx: AudioModelContext,
+) =>
+ usesSavedVoice(value, ctx)
+ ? []
+ : specs.filter((spec) => spec.name === ctx.voiceOption);
const speakVoicePanel: AudioToolPanel<SpeakVoiceValue> = {
...speakVoiceLogic,
- Component: ({ value, onChange, disabled }) => (
+ Component: ({ value, onChange, disabled, specs, ctx }) => (
<div className="grid gap-2">
- <span className="text-ui-13 font-medium text-foreground">Voice</span>
- <PillTabs
- ariaLabel="Voice"
- value={value.source}
- onValueChange={(source) =>
- onChange({
- ...value,
- source: source === "saved" ? "saved" : "builtin",
- })
- }
- disabled={disabled}
- fit={true}
- compact={true}
- className="[&>button]:px-3"
- tabs={[
- { value: "builtin", label: "Built-in" },
- { value: "saved", label: "Saved" },
- ]}
- />
- {value.source === "saved" ? (
+ {ctx.audioWorkflows?.includes("clone") ? (
+ <>
+ {/* The voice list carries its own label. */}
+ {builtinVoiceSpecs(specs, value, ctx).length === 0 ? (
+ <span className="text-ui-13 font-medium text-foreground">
+ Voice
+ </span>
+ ) : null}
+ <PillTabs
+ ariaLabel="Voice"
+ value={value.source}
+ onValueChange={(source) =>
+ onChange({
+ ...value,
+ source: source === "saved" ? "saved" : "builtin",
+ })
+ }
+ disabled={disabled}
+ fit={true}
+ compact={true}
+ className="[&>button]:px-3"
+ tabs={[
+ { value: "builtin", label: "Built-in" },
+ { value: "saved", label: "Saved" },
+ ]}
+ />
+ </>
+ ) : null}
+ {usesSavedVoice(value, ctx) ? (
<VoicePicker
selectedId={value.voiceId}
disabled={disabled}
onSelect={(voice) => onChange({ ...value, voiceId: voice.id })}
onDeselect={() => onChange({ ...value, voiceId: null })}
/>
+ ) : ctx.voiceOption && builtinVoiceSpecs(specs, value, ctx).length > 0 ? (
+ <AudioOptionFields
+ specs={builtinVoiceSpecs(specs, value, ctx)}
+ values={
+ value.builtin === null ? {} : { [ctx.voiceOption]: value.builtin }
+ }
+ onChange={(_name, builtin) =>
+ onChange({ ...value, builtin: builtin ?? null })
+ }
+ disabled={disabled}
+ family={ctx.audioFamily}
+ />
) : (
<p className="text-ui-11p5 leading-snug text-muted-foreground">
The model's own voice, shaped by a voice description when you give
diff --git a/studio/frontend/src/features/audio/tools/types.ts b/studio/frontend/src/features/audio/tools/types.ts
index a59158d5703..91f5573d6a7 100644
--- a/studio/frontend/src/features/audio/tools/types.ts
+++ b/studio/frontend/src/features/audio/tools/types.ts
@@ -28,6 +28,12 @@ export interface AudioModelContext {
audioMusic?: boolean;
/** Ids of the saved voices, once the list has loaded. */
savedVoiceIds?: readonly string[] | null;
+ /** Ids of saved voices with no transcript. */
+ voicesWithoutTranscript?: readonly string[];
+ /** The Speak option that picks a built-in voice: voice, voice_id or speaker. */
+ voiceOption?: string | null;
+ /** Request inputs a strict model reads; null when it reads any. */
+ requestInputs?: readonly string[] | null;
}
export interface AudioRunPatch {
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index 3b4b5ffd944..1e0a0432327 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -270,7 +270,7 @@ function parseErrorText(status: number, body: unknown): string {
* which commits the status early: a later failure can only arrive as `_deferred_error`. */
function deferredError(
body: unknown,
-): { status: number; message: string } | null {
+): { status: number; message: string; detail: unknown } | null {
const deferred =
body && typeof body === "object"
? (
@@ -285,9 +285,21 @@ function deferredError(
return {
status,
message: parseErrorText(status, { detail: deferred.detail }),
+ detail: deferred.detail,
};
}
+/** Keeps the server's `detail`, so a structured audio.cpp failure (`{code, message}`) reaches the caller. */
+export class LoadModelError extends Error {
+ readonly status: number;
+ readonly detail: unknown;
+ constructor(message: string, status: number, detail: unknown) {
+ super(message);
+ this.status = status;
+ this.detail = detail;
+ }
+}
+
/** `paddedLabel` opts a caller into `assertCompletedPaddedBody`; only the two padded routes may,
* since a truncated body means unfinished there but is legitimate elsewhere. */
async function parseJsonOrThrow<T>(
@@ -296,11 +308,12 @@ async function parseJsonOrThrow<T>(
): Promise<T> {
const body = await response.json().catch(() => null);
if (!response.ok) {
- throw new Error(parseErrorText(response.status, body));
+ const detail = (body as { detail?: unknown } | null)?.detail;
+ throw new LoadModelError(parseErrorText(response.status, body), response.status, detail);
}
const deferred = deferredError(body);
if (deferred) {
- throw new Error(deferred.message);
+ throw new LoadModelError(deferred.message, deferred.status, deferred.detail);
}
if (paddedLabel !== undefined) {
assertCompletedPaddedBody(body, paddedLabel);
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 4b02f03da9a..8ab8f124abc 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -262,6 +262,7 @@ export interface LoadModelResponse {
is_audio?: boolean;
audio_type?: string | null;
audio_workflows?: string[] | null;
+ audio_device_fallback?: "cpu" | null;
has_audio_input?: boolean;
has_video_input?: boolean;
inference?: {
@@ -404,6 +405,10 @@ export interface InferenceStatusResponse {
audio_convert?: AudioConvertCaps | null;
/** e.g. Maya1: "instruct" (its voice description). */
audio_required_inputs?: string[] | null;
+ /** Request inputs a strict model reads (e.g. "instruct"); null when the model takes any. */
+ audio_request_inputs?: string[] | null;
+ /** "cpu" after a GPU start failed and the model loaded into CPU RAM instead. */
+ audio_device_fallback?: "cpu" | null;
/** Unknown-shaped on purpose: validated by parseMusicCapabilities. */
audio_music?: unknown;
has_audio_input?: boolean;
diff --git a/studio/frontend/tests/audio-api-error.test.ts b/studio/frontend/tests/audio-api-error.test.ts
new file mode 100644
index 00000000000..df7616116e8
--- /dev/null
+++ b/studio/frontend/tests/audio-api-error.test.ts
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc } from "./helpers/kit.ts";
+import { loadWithStubs } from "./helpers/module-stubs.ts";
+
+const DETAIL = {
+ code: "out_of_memory",
+ message: "Not enough GPU memory to load Qwen3-TTS.",
+ smaller_variants: [{ variant: "Q4_K_M", label: "Q4_K_M" }],
+};
+
+let reply: Response = new Response("{}");
+const api = loadWithStubs<typeof import("../src/features/audio/api.ts")>(
+ new URL("../src/features/audio/api.ts", import.meta.url),
+ {
+ "@/features/auth": {
+ authFetch: async () => reply,
+ getAuthToken: () => "t",
+ },
+ "@/lib/account-transition": { accountTransitionPending: () => false },
+ "@/lib/api-base": { apiUrl: (path: string) => path },
+ "@/lib/format-fastapi-error": {
+ formatApiErrorBody: () => null,
+ readFastApiError: async (response: Response) =>
+ ((await response.json()) as { detail: { message: string } }).detail
+ .message,
+ },
+ "./audio-run-request": {
+ buildAudioRunBody: () => ({}),
+ buildVoiceCreateBody: () => ({}),
+ transcribeUrl: () => "/t",
+ },
+ },
+);
+
+test("AudioApiError keeps the detail and its code; a string detail has no code", () => {
+ const structured = new api.AudioApiError("m", 503, DETAIL);
+ assert.deepEqual(
+ [structured.code, structured.detail],
+ ["out_of_memory", DETAIL],
+ );
+ assert.equal(new api.AudioApiError("m", 501, "plain").code, undefined);
+});
+
+test("generateAudio and runAudio throw AudioApiError with the server's message, status and code", async () => {
+ for (const call of [
+ () => api.generateAudio("hi"),
+ () => api.runAudio({ workflow: "speak", text: "hi" }),
+ ]) {
+ reply = new Response(JSON.stringify({ detail: DETAIL }), { status: 503 });
+ await assert.rejects(call(), (error: unknown) => {
+ assert.ok(error instanceof api.AudioApiError);
+ assert.deepEqual(
+ [error.message, error.status, error.code],
+ [DETAIL.message, 503, "out_of_memory"],
+ );
+ return true;
+ });
+ }
+});
+
+test("chat loads throw LoadModelError with the detail, for both an error status and _deferred_error", () => {
+ const chat = readSrc("features/chat/api/chat-api.ts");
+ assert.match(chat, /export class LoadModelError extends Error \{/);
+ assert.match(
+ chat,
+ /throw new LoadModelError\(parseErrorText\(response\.status, body\), response\.status, detail\)/,
+ );
+ assert.match(
+ chat,
+ /throw new LoadModelError\(deferred\.message, deferred\.status, deferred\.detail\)/,
+ );
+ assert.match(chat, /detail: deferred\.detail,/);
+ assert.doesNotMatch(chat, /throw new Error\(deferred\.message\)/);
+});
diff --git a/studio/frontend/tests/audio-clone-auto-transcribe.test.ts b/studio/frontend/tests/audio-clone-auto-transcribe.test.ts
new file mode 100644
index 00000000000..c95161765de
--- /dev/null
+++ b/studio/frontend/tests/audio-clone-auto-transcribe.test.ts
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ referenceLengthHint,
+ shouldAutoTranscribeReference,
+} from "../src/features/audio/clone-policy.ts";
+import { readSrc } from "./helpers/kit.ts";
+
+const ready = {
+ mode: "required" as const,
+ referenceText: "",
+ referenceId: "ref-1",
+ referenceBusy: false,
+ referenceExpired: false,
+ sttReady: true,
+ doneFor: null,
+};
+
+test("a required transcript fills itself once per usable reference", () => {
+ for (const [field, value, expected] of [
+ ["mode", "required", true],
+ ["mode", "optional", false],
+ ["mode", "hidden", false],
+ ["referenceText", "Hello there.", false],
+ ["referenceText", " ", true],
+ ["referenceId", null, false],
+ ["referenceBusy", true, false],
+ ["referenceExpired", true, false],
+ ["sttReady", false, false],
+ ["doneFor", "ref-1", false],
+ ["doneFor", "ref-0", true],
+ ] as const) {
+ const input = { ...ready, [field]: value };
+ assert.equal(shouldAutoTranscribeReference(input), expected, field);
+ }
+});
+
+test("the clone hook runs the gate with the page's downloaded STT model", () => {
+ assert.match(
+ readSrc("features/audio/hooks/use-clone-generation.ts"),
+ /busy !== null \|\|\s*!shouldAutoTranscribeReference\(\{[\s\S]*doneFor: autoTranscribed\.current[\s\S]*autoTranscribed\.current = reference\.id;\s*void transcribeOnce\(reference\)/,
+ );
+ assert.match(
+ readSrc("features/audio/audio-page.tsx"),
+ /const cloneSttReady =\s*cloneSttRepo !== null &&\s*downloadedSttArtifacts\.some[\s\S]*sttReady: cloneSttReady/,
+ );
+});
+
+test("the reference length hint", () => {
+ const hint = (seconds: number | null) =>
+ referenceLengthHint(seconds, [5, 15]);
+ assert.equal(hint(4.21), "4.2 s. 5 to 15 s of one clear voice clones best.");
+ for (const fine of [5, 15, null]) assert.equal(hint(fine), null);
+ assert.equal(hint(22), "Longer than needed; 5 to 15 s works best.");
+ assert.match(
+ readSrc("features/audio/pages/clone-page.tsx"),
+ /idealSeconds=\{\[5, 15\]\}/,
+ );
+});
+
+test("auto-transcribe runs only while Audio is visible on the Clone page", () => {
+ assert.match(
+ readSrc("features/audio/hooks/use-clone-generation.ts"),
+ /if \(\s*!onClonePage \|\|\s*!reference \|\|/,
+ );
+ assert.match(
+ readSrc("features/audio/audio-page.tsx"),
+ /onClonePage: active && pageWorkflow === "clone",/,
+ );
+});
diff --git a/studio/frontend/tests/audio-clone-panels.test.ts b/studio/frontend/tests/audio-clone-panels.test.ts
index d14c2a530b7..67530757d64 100644
--- a/studio/frontend/tests/audio-clone-panels.test.ts
+++ b/studio/frontend/tests/audio-clone-panels.test.ts
@@ -21,6 +21,7 @@ const {
EMOTION_AUDIO_MISSING,
SAVED_VOICE_DELETED,
SAVED_VOICE_MISSING,
+ SAVED_VOICE_NO_TRANSCRIPT,
chatterboxExpressivenessLogic,
cosyVoiceModeLogic,
emotionSourceProblem,
@@ -28,7 +29,9 @@ const {
indexTts2EmotionLogic,
qwen3TimbreLogic,
speakVoiceLogic,
+ speakVoiceStored,
vibeVoiceDialogueLogic,
+ voiceOptionName,
} = await import("../src/features/audio/tools/panel-logic.ts");
const {
cloneBlocker,
@@ -70,7 +73,7 @@ test("each clone family gets its one panel, only on Clone", () => {
assert.deepEqual(shown("qwen3_tts", "speak"), []);
});
-test("the saved-voice choice shows on Speak only for models that also clone", () => {
+test("the Voice panel shows on Speak for models that clone or declare a voice", () => {
assert.equal(
panelApplies(
speakVoiceLogic,
@@ -89,7 +92,15 @@ test("the saved-voice choice shows on Speak only for models that also clone", ()
"speak",
ctx({ audioWorkflows: ["speak", "clone"], referenceTextMode: "required" }),
),
- false,
+ true,
+ );
+ assert.equal(
+ panelApplies(
+ speakVoiceLogic,
+ "speak",
+ ctx({ audioWorkflows: ["speak"], voiceOption: "voice_id" }),
+ ),
+ true,
);
assert.equal(
panelApplies(
@@ -360,19 +371,20 @@ test("Maya1's required voice description reaches the tool context", () => {
});
test("a saved voice on Speak becomes the run's reference", () => {
- assert.deepEqual(
- speakVoiceLogic.toRequest({ source: "saved", voiceId: "v1" }),
- {
- inputs: { reference: { voice_id: "v1" } },
- },
- );
- assert.deepEqual(
- speakVoiceLogic.toRequest({ source: "builtin", voiceId: "v1" }),
- {},
- );
+ const speak = ctx({ audioWorkflows: ["speak", "clone"], voiceOption: "voice" });
+ const request = (source: "saved" | "builtin", c = speak) =>
+ speakVoiceLogic.toRequest(
+ { source, voiceId: "v1", builtin: source === "saved" ? "af_bella" : null },
+ c,
+ );
+ assert.deepEqual(request("saved"), {
+ inputs: { reference: { voice_id: "v1" } },
+ });
+ assert.deepEqual(request("builtin"), {});
+ assert.deepEqual(request("saved", ctx({ audioWorkflows: ["speak"] })), {});
assert.equal(
speakVoiceLogic.validate?.(
- { source: "saved", voiceId: null },
+ { source: "saved", voiceId: null, builtin: null },
{ text: "" },
ctx(),
),
@@ -381,7 +393,7 @@ test("a saved voice on Speak becomes the run's reference", () => {
});
test("a saved voice deleted on Clone holds Speak's Generate", () => {
- const saved = { source: "saved" as const, voiceId: "v1" };
+ const saved = { source: "saved" as const, voiceId: "v1", builtin: null };
const check = (savedVoiceIds: readonly string[] | null) =>
speakVoiceLogic.validate?.(saved, { text: "hi" }, ctx({ savedVoiceIds }));
assert.equal(check(["v2"]), SAVED_VOICE_DELETED);
@@ -390,6 +402,39 @@ test("a saved voice deleted on Clone holds Speak's Generate", () => {
assert.equal(check(null), null);
});
+test("the built-in voice goes under the model's own option name", () => {
+ const builtin = { source: "builtin" as const, voiceId: null, builtin: "x" };
+ // Magpie and NeuTTS keep voice_id: top-level voice breaks them on audio.cpp v0.9.1.
+ for (const name of ["voice", "voice_id", "speaker", null]) {
+ assert.deepEqual(
+ speakVoiceLogic.toRequest(builtin, ctx({ voiceOption: name })),
+ name ? { options: { [name]: "x" } } : {},
+ );
+ }
+ assert.deepEqual([...speakVoiceLogic.claims], ["voice", "voice_id", "speaker"]);
+ const spec = (name: string, type: "enum" | "string" = "enum") =>
+ ({ name, type, values: ["a"] }) as const;
+ assert.equal(voiceOptionName([spec("speaker"), spec("voice")]), "voice");
+ assert.equal(
+ voiceOptionName([spec("voice", "string"), spec("voice_id")]),
+ "voice_id",
+ );
+ assert.equal(voiceOptionName([spec("voice", "string")]), "voice");
+ assert.equal(voiceOptionName([spec("speaker_id")]), null);
+});
+
+test("a saved voice without a transcript holds Speak only when the model needs one", () => {
+ const check = (referenceTextMode: "required" | "optional", voiceId = "v1") =>
+ speakVoiceLogic.validate?.(
+ { source: "saved", voiceId, builtin: null },
+ { text: "hi" },
+ ctx({ referenceTextMode, voicesWithoutTranscript: ["v1"] }),
+ );
+ assert.equal(check("required"), SAVED_VOICE_NO_TRANSCRIPT);
+ assert.equal(check("optional"), null);
+ assert.equal(check("required", "v2"), null);
+});
+
test("formatVibeVoiceScript prefixes plain text only", () => {
assert.equal(
formatVibeVoiceScript("Hello there."),
@@ -529,3 +574,31 @@ test("transcribing the reference holds the page busy until it ends", () => {
assert.match(body, /finally \{\s*if \(busyRef\.current === "transcribing"\) \{\s*busyRef\.current = null;\s*setBusy\(null\);/);
assert.match(body, /transcribe: transcribeReference/);
});
+
+test("a voice chosen in Advanced before the picker carries into the picker", () => {
+ const send = (stored: unknown, saved: Record<string, unknown>, name: string) =>
+ speakVoiceLogic.toRequest(
+ panelValue(
+ speakVoiceLogic,
+ { [speakVoiceLogic.id]: speakVoiceStored(stored, saved, name) },
+ [],
+ ),
+ ctx({ voiceOption: name }),
+ );
+ // Kokoro's am_adam and Magpie's Jason were kept in Advanced, which the picker now claims.
+ assert.deepEqual(send(undefined, { voice: "am_adam" }, "voice"), {
+ options: { voice: "am_adam" },
+ });
+ assert.deepEqual(
+ send({ source: "builtin", voiceId: null }, { speaker: "Jason" }, "speaker"),
+ { options: { speaker: "Jason" } },
+ );
+ // A choice made in the picker wins, including going back to the default.
+ const picked = { source: "builtin", voiceId: null, builtin: null };
+ assert.deepEqual(send(picked, { voice: "am_adam" }, "voice"), {});
+ assert.deepEqual(send(undefined, {}, "voice"), {});
+ assert.match(
+ readSrc("features/audio/hooks/use-speech-generation.ts"),
+ /speakVoiceStored\(stored, audioOptionValues, toolContext\.voiceOption\)/,
+ );
+});
diff --git a/studio/frontend/tests/audio-failure-actions.test.ts b/studio/frontend/tests/audio-failure-actions.test.ts
new file mode 100644
index 00000000000..3a553f78478
--- /dev/null
+++ b/studio/frontend/tests/audio-failure-actions.test.ts
@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { installLocalStorageFake, readSrc } from "./helpers/kit.ts";
+
+const { store } = installLocalStorageFake();
+const { audioFailureActions, parseAudioFailure, reportAudioFailure } =
+ await import("../src/features/audio/audio-failure-actions.ts");
+const { useAudioWorkspaceStore } = await import(
+ "../src/features/audio/stores/audio-workspace-store.ts"
+);
+
+const OOM = {
+ code: "out_of_memory",
+ message: "Not enough GPU memory.",
+ smaller_variants: [
+ { variant: "Q4_K_M", label: "Q4_K_M", size_bytes: 1, estimate_gb: 3.1 },
+ { variant: "Q3_K_M" },
+ ],
+};
+const CHOOSE = "Choose a different model";
+const CPU = "Load into CPU RAM";
+const RUNTIME = [
+ "runtime_missing",
+ "family_unknown_to_runtime",
+ "espeak_missing",
+];
+
+function actionsFor(detail: unknown, overrides: Record<string, unknown> = {}) {
+ const calls: string[] = [];
+ const actions = audioFailureActions(parseAudioFailure(detail), {
+ deviceIsCpu: false,
+ canUpdateRuntime: false,
+ onUpdateRuntime: () => calls.push("update"),
+ onUseCpu: () => calls.push("cpu"),
+ onUseVariant: (variant: string) => calls.push(`variant:${variant}`),
+ onChooseModel: () => calls.push("choose"),
+ ...overrides,
+ });
+ for (const action of actions) action.onClick();
+ return { labels: actions.map((action) => action.label), calls };
+}
+
+test("parses a detail, a body wrapping it and a deferred load error; anything else is null", () => {
+ assert.deepEqual(parseAudioFailure(OOM), {
+ code: "out_of_memory",
+ message: "Not enough GPU memory.",
+ smallerVariants: [
+ { variant: "Q4_K_M", label: "Q4_K_M" },
+ { variant: "Q3_K_M", label: "Q3_K_M" },
+ ],
+ onCpu: false,
+ });
+ assert.equal(parseAudioFailure({ detail: OOM })?.code, "out_of_memory");
+ const deferred = { status_code: 503, detail: { code: "gpu_unavailable" } };
+ assert.equal(
+ parseAudioFailure({ _deferred_error: deferred })?.code,
+ "gpu_unavailable",
+ );
+ for (const other of ["boom", null, [{ msg: "x" }], { code: "new" }, {}]) {
+ assert.equal(parseAudioFailure(other), null);
+ }
+});
+
+test("each code maps onto its actions; unknown codes keep today's action", () => {
+ const bareOom = { code: "out_of_memory", message: "m" };
+ const up = { canUpdateRuntime: true };
+ const cases: [unknown, Record<string, unknown>, string[], string[]][] = [
+ [OOM, {}, ["Use Q4_K_M", CPU], ["variant:Q4_K_M", "cpu"]],
+ [OOM, { deviceIsCpu: true }, ["Use Q4_K_M"], ["variant:Q4_K_M"]],
+ [OOM, { cpuUnsupported: true }, ["Use Q4_K_M"], ["variant:Q4_K_M"]],
+ [bareOom, {}, [CPU], ["cpu"]],
+ [bareOom, { deviceIsCpu: true }, [CHOOSE], ["choose"]],
+ [{ ...OOM, device: "cpu" }, {}, ["Use Q4_K_M"], ["variant:Q4_K_M"]],
+ [{ code: "gpu_unavailable" }, {}, [CPU], ["cpu"]],
+ [{ code: "file_incomplete" }, {}, [CHOOSE], ["choose"]],
+ [{ code: "something_new" }, up, [CHOOSE], ["choose"]],
+ [null, up, [CHOOSE], ["choose"]],
+ ];
+ for (const code of RUNTIME) {
+ cases.push([{ code }, up, ["Update the audio runtime"], ["update"]]);
+ cases.push([{ code }, {}, [CHOOSE], ["choose"]]);
+ }
+ for (const [detail, overrides, labels, calls] of cases) {
+ const label = `${JSON.stringify(detail)} ${JSON.stringify(overrides)}`;
+ assert.deepEqual(actionsFor(detail, overrides), { labels, calls }, label);
+ }
+});
+
+test("reportAudioFailure keeps the failure with the message it explains, never persisted", () => {
+ const error = Object.assign(new Error("Not enough GPU memory."), {
+ detail: OOM,
+ });
+ assert.equal(reportAudioFailure(error)?.code, "out_of_memory");
+ const stored = useAudioWorkspaceStore.getState().failure;
+ assert.equal(stored?.message, "Not enough GPU memory.");
+ assert.equal(stored?.failure.code, "out_of_memory");
+ useAudioWorkspaceStore.getState().rememberModel("speak", "org/model");
+ assert.doesNotMatch(
+ store.get("unsloth_audio_workspace") ?? "",
+ /failure|out_of_memory/,
+ );
+ assert.equal(reportAudioFailure(new Error("plain")), null);
+ assert.equal(useAudioWorkspaceStore.getState().failure, null);
+});
+
+test("generation hooks report failures and the page uses them only for the error on screen", () => {
+ for (const hook of ["speech", "clone", "edit", "convert", "separate"]) {
+ assert.match(
+ readSrc(`features/audio/hooks/use-${hook}-generation.ts`),
+ /updateGenerationPhase\("finishing"\);\s*reportAudioFailure\(error\);/,
+ );
+ }
+ const page = readSrc("features/audio/audio-page.tsx");
+ assert.match(
+ page,
+ /audioFailure\?\.message === pageGenerationError\s*\?\s*audioFailure\.failure\s*:\s*null/,
+ );
+ assert.match(page, /useLlamaUpdateCheck\(\{ enabled: active \}\)/);
+ const slot = readSrc("features/audio/hooks/use-audio-model-slot.ts");
+ assert.match(slot, /res\.audio_device_fallback === "cpu" && !wantsCpu/);
+ assert.match(slot, /duration: 12000,\s*action: action &&/);
+ assert.match(slot, /queued\.isGguf,\s*queued\.deviceOverride,/);
+});
+
+test("CPU recovery after a generation failure reloads the resident model, not a failed attempt", () => {
+ const slot = readSrc("features/audio/hooks/use-audio-model-slot.ts");
+ const success = slot.indexOf("if (res.is_audio && isTtsAudioType(res.audio_type))");
+ const failure = slot.indexOf("const failure = audioFailureOf(error);");
+ assert.ok(success > 0 && failure > success);
+ const records = [...slot.matchAll(/lastTtsLoad\.current = /g)].map((m) => m.index);
+ // Recorded only inside the success branch, so a failed load B keeps A as the retry target.
+ assert.equal(records.length, 1);
+ assert.ok(records[0] > success && records[0] < failure);
+ // The failed load's own toast still retries that attempt.
+ assert.match(slot, /handlers\.selectCpuDevice\(\);\s*void retryLoad\("cpu"\);/);
+});
diff --git a/studio/frontend/tests/audio-model-eject.test.ts b/studio/frontend/tests/audio-model-eject.test.ts
index d1eacf9d9b9..b11371f1c0d 100644
--- a/studio/frontend/tests/audio-model-eject.test.ts
+++ b/studio/frontend/tests/audio-model-eject.test.ts
@@ -61,7 +61,7 @@ test("a Speak load asks the same question and forces from the answer", () => {
// The slot is claimed before the await, so a routed pick arriving mid-dialog queues.
assert.match(
source,
- /if \(ttsLoadInFlight\.current \|\| busyRef\.current === "generating"\) \{\s*pendingRoutedTtsPick\.current = \{\s*repoId,\s*ggufFilename,\s*loadId,\s*audioType,\s*remoteCodeApproval,\s*isGguf,\s*\};\s*return;\s*\}[\s\S]{0,400}?ttsLoadInFlight\.current = true;/,
+ /if \(ttsLoadInFlight\.current \|\| busyRef\.current === "generating"\) \{\s*pendingRoutedTtsPick\.current = \{\s*repoId,\s*ggufFilename,\s*loadId,\s*audioType,\s*remoteCodeApproval,\s*isGguf,\s*deviceOverride,\s*\};\s*return;\s*\}[\s\S]{0,400}?ttsLoadInFlight\.current = true;/,
);
// Declining releases the slot and drops the queued pick, which would else re-ask.
assert.match(
diff --git a/studio/frontend/tests/audio-music-takes.test.ts b/studio/frontend/tests/audio-music-takes.test.ts
new file mode 100644
index 00000000000..54fcfab6418
--- /dev/null
+++ b/studio/frontend/tests/audio-music-takes.test.ts
@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { AudioTextRunRequest } from "../src/features/audio/audio-run-request.ts";
+import { readSrc, registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+const { buildAudioRunBody } = await import(
+ "../src/features/audio/audio-run-request.ts"
+);
+const { newMusicGroupId, runMusicTakes } = await import(
+ "../src/features/audio/music/music-policy.ts"
+);
+
+const request: AudioTextRunRequest = {
+ workflow: "music",
+ text: "lofi",
+ options: { seed: 7 },
+ music: { mode: "song", lyrics: "la", duration_s: 30, variations: 3 },
+};
+const GROUP = "a".repeat(32);
+
+/** Runs the takes with a fake server whose take n returns seed 1000 + n. */
+function takes({
+ count = 3,
+ how = "sequential" as "batch" | "sequential" | null,
+ failOn = 0,
+ stopAfter = 0,
+}) {
+ const sent: AudioTextRunRequest[] = [];
+ const shown: number[] = [];
+ const statuses: string[] = [];
+ const controller = new AbortController();
+ const done = runMusicTakes({
+ request,
+ count,
+ how,
+ signal: controller.signal,
+ groupId: GROUP,
+ run: async (take) => {
+ sent.push(take);
+ if (sent.length === failOn) throw new Error("take failed");
+ return { clips: [{ seed: 1000 + sent.length }] };
+ },
+ onTake: async (response) => {
+ shown.push(response.clips[0].seed);
+ if (shown.length === stopAfter) controller.abort();
+ },
+ onStatus: (status) => statuses.push(status),
+ });
+ return { done, sent, shown, statuses };
+}
+
+test("sequential takes run one request each and reuse take 1's seed", async () => {
+ const h = takes({});
+ await h.done;
+ assert.deepEqual(h.statuses, [
+ "Take 1 of 3…",
+ "Take 2 of 3…",
+ "Take 3 of 3…",
+ ]);
+ assert.deepEqual(
+ h.sent.map((t) => [t.take, t.group_id, t.music?.variations, t.seed]),
+ [
+ [1, GROUP, 1, undefined],
+ [2, GROUP, 1, 1001],
+ [3, GROUP, 1, 1001],
+ ],
+ );
+ assert.deepEqual(h.sent[0].options, { seed: 7 });
+ assert.deepEqual(h.shown, [1001, 1002, 1003]);
+ const body = buildAudioRunBody(h.sent[1]);
+ assert.deepEqual(
+ [body.take, body.group_id, body.seed, body.variations],
+ [2, GROUP, 1001, undefined],
+ );
+});
+
+test("an inline take 1 (history could not keep it) still hands its seed on", async () => {
+ const sent: AudioTextRunRequest[] = [];
+ await runMusicTakes({
+ request,
+ count: 2,
+ how: "sequential",
+ run: async (take) => {
+ sent.push(take);
+ return { clips: [], audio: { seed: 1001 } };
+ },
+ onTake: async () => {},
+ onStatus: () => {},
+ });
+ assert.deepEqual(sent.map((t) => t.seed), [undefined, 1001]);
+});
+
+test("Stop after take 2 keeps two takes; a failed take 2 keeps take 1 and rejects", async () => {
+ const stopped = takes({ stopAfter: 2 });
+ await stopped.done;
+ assert.deepEqual([stopped.sent.length, stopped.shown], [2, [1001, 1002]]);
+ const failed = takes({ failOn: 2 });
+ await assert.rejects(failed.done, /take failed/);
+ assert.deepEqual(failed.shown, [1001]);
+});
+
+test("batch and single takes stay one request", async () => {
+ for (const [how, count] of [
+ ["batch", 3],
+ ["sequential", 1],
+ [null, 2],
+ ] as const) {
+ const h = takes({ how, count });
+ await h.done;
+ assert.deepEqual([h.sent.length, h.statuses], [1, []]);
+ assert.equal(h.sent[0], request);
+ }
+ assert.match(newMusicGroupId(), /^[0-9a-f]{32}$/);
+ assert.doesNotMatch(
+ readSrc("features/audio/music/music-policy.ts"),
+ /randomUUID\(/,
+ );
+ const speak = buildAudioRunBody({
+ workflow: "speak",
+ text: "hi",
+ take: 2,
+ group_id: GROUP,
+ });
+ assert.equal(speak.take, undefined);
+});
+
+test("the music hook drives the takes and shows status text only", () => {
+ const hook = readSrc("features/audio/hooks/use-music-generation.ts");
+ assert.match(
+ hook,
+ /await runMusicTakes\(\{[\s\S]*how: rule\.variations\?\.how \?\? null,[\s\S]*onStatus: setRunStatus/,
+ );
+ assert.match(hook, /reportAudioFailure\(error\)/);
+ assert.doesNotMatch(hook, /<Progress/);
+});
diff --git a/studio/frontend/tests/audio-request-inputs.test.ts b/studio/frontend/tests/audio-request-inputs.test.ts
new file mode 100644
index 00000000000..848f45920aa
--- /dev/null
+++ b/studio/frontend/tests/audio-request-inputs.test.ts
@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc, registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+const { audioModelContextFor, readsRequestInput } = await import(
+ "../src/features/audio/tools/select.ts"
+);
+
+const page = {
+ musicGeneration: false,
+ cudaMusicGeneration: false,
+ musicNeedsDescription: false,
+};
+const inputsOf = (audioRequestInputs: unknown) =>
+ audioModelContextFor({ audio_request_inputs: audioRequestInputs as [] }, page)
+ .requestInputs;
+
+test("audio_request_inputs reaches the context; anything but a list is unknown", () => {
+ for (const unknown of [undefined, null, "instruct"])
+ assert.equal(inputsOf(unknown), null);
+ assert.deepEqual(inputsOf([]), []);
+ assert.deepEqual(inputsOf(["instruct", "language"]), [
+ "instruct",
+ "language",
+ ]);
+});
+
+test("a model that may read an input keeps its field; a strict one without it loses it", () => {
+ const reads = (requestInputs: string[] | null, ...names: string[]) =>
+ readsRequestInput({ requestInputs }, ...names);
+ const description = ["instruct", "instruction"];
+ assert.equal(reads(null, ...description) && reads(null, "language"), true);
+ assert.equal(reads([], ...description) || reads([], "language"), false);
+ assert.equal(reads(["instruction"], ...description), true);
+ assert.equal(reads(["instruct"], "language"), false);
+ assert.equal(reads(["language"], "language"), true);
+});
+
+test("the voice description and Clone's language follow the gate", () => {
+ const registry = readSrc("features/audio/tools/registry.tsx");
+ assert.match(
+ registry,
+ /kind !== "voice" \|\| readsRequestInput\(ctx, "instruct", "instruction"\)/,
+ );
+ const clone = readSrc("features/audio/hooks/use-clone-generation.ts");
+ assert.match(
+ clone,
+ /languageShown = readsRequestInput\(toolContext, "language"\)/,
+ );
+ assert.match(
+ clone,
+ /language: languageShown \? state\.language \|\| null : null/,
+ );
+ assert.match(
+ readSrc("features/audio/pages/clone-page.tsx"),
+ /\{clone\.languageShown \? \(\s*<LanguageSelect/,
+ );
+});
diff --git a/studio/frontend/tests/audio-seed-reuse.test.ts b/studio/frontend/tests/audio-seed-reuse.test.ts
new file mode 100644
index 00000000000..fe7b2c2c25e
--- /dev/null
+++ b/studio/frontend/tests/audio-seed-reuse.test.ts
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ audioOptionUsesSlider,
+ ignoredOptionsWarning,
+ parseAudioOptions,
+} from "../src/features/audio/audio-options.ts";
+import { readSrc } from "./helpers/kit.ts";
+
+test("the seed row is a blank number box, not a slider", () => {
+ const [seed] = parseAudioOptions([
+ { name: "seed", type: "int", min: 0, max: 2147483647, default: null },
+ ]);
+ assert.equal(seed.default, null);
+ assert.equal(audioOptionUsesSlider(seed), false);
+});
+
+test("Reuse seed shows only for a clip with a numeric seed and fills the field", () => {
+ const workspace = readSrc("features/audio/pages/tts-workspace.tsx");
+ assert.match(
+ workspace,
+ /\{onReuseSeed && typeof clip\.settings\?\.seed === "number" \? \([\s\S]{0,400}Reuse seed/,
+ );
+ const page = readSrc("features/audio/audio-page.tsx");
+ const handler = page.slice(page.indexOf("const handleReuseSeed"));
+ assert.match(handler, /specs\.some\(\(spec\) => spec\.name === "seed"\)/);
+ assert.match(handler, /toast\.info\("This model doesn't take a seed\."\)/);
+ assert.match(
+ handler,
+ /handleAudioOptionChange\("seed", seed\);\s*setAdvancedOpen\(true\);\s*toast\.success\(`Seed \$\{seed\} set for the next take\.`\)/,
+ );
+ assert.match(page, /onReuseSeed: handleReuseSeed/);
+});
+
+test("ignored options read as one sentence", () => {
+ const warn = (...names: string[]) => ignoredOptionsWarning(names, "Kokoro");
+ const them = "so they weren't sent.";
+ assert.equal(warn(), null);
+ assert.equal(
+ warn("exaggeration"),
+ "Kokoro doesn't take Exaggeration, so it wasn't sent.",
+ );
+ assert.equal(
+ warn("exaggeration", "top_k"),
+ `Kokoro doesn't take Exaggeration or Top k, ${them}`,
+ );
+ assert.equal(warn("a", "b", "c"), `Kokoro doesn't take A, B or C, ${them}`);
+ assert.match(
+ readSrc("features/audio/hooks/use-clone-generation.ts"),
+ /warnIgnoredOptions\(response\.ignored_options, response\.model\)/,
+ );
+ assert.match(
+ readSrc("features/audio/hooks/use-speech-generation.ts"),
+ /warnIgnoredOptions\(generated\.ignored_options, generated\.model\)/,
+ );
+});
diff --git a/studio/frontend/tests/update-banner-flex-priority.test.ts b/studio/frontend/tests/update-banner-flex-priority.test.ts
index a029767da4c..771acf56ecb 100644
--- a/studio/frontend/tests/update-banner-flex-priority.test.ts
+++ b/studio/frontend/tests/update-banner-flex-priority.test.ts
@@ -327,9 +327,7 @@ function darkShadow(source: string): {
blur: number;
spread: number;
} {
- const seen = source.match(
- /dark:shadow-\[0_(\d+)px_(\d+)px_(-?\d+)px_/,
- );
+ const seen = source.match(/dark:shadow-\[0_(\d+)px_(\d+)px_(-?\d+)px_/);
assert.ok(seen, "the card has no dark-mode shadow to size the gutter from");
return { y: Number(seen[1]), blur: Number(seen[2]), spread: Number(seen[3]) };
}
@@ -496,3 +494,14 @@ test("the rail is anchored to its corner, not placed from JS", () => {
);
}
});
+
+test("a missing audio.cpp runtime reads as a first install, not unknown → latest", () => {
+ assert.match(
+ LLAMA,
+ /row\.component === "audio\.cpp" && row\.installedTag === null\s*\?\s*"Install the audio runtime"[\s\S]*\{lead \? `\$\{lead\} ` : null\}/,
+ );
+ assert.match(
+ LLAMA,
+ /title = firstInstall\s*\?\s*"Installing the audio runtime\.\.\."/,
+ );
+});