Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: add audio.cpp as a native engine for speech, music and dictation (#12342)
Etherlcd9162f49e66
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERSindex 99715c71cc8..8582bc0edb2 100644--- a/.github/CODEOWNERS+++ b/.github/CODEOWNERS@@ -264,6 +264,8 @@/studio/setup.sh @danielhanchen/studio/setup.ps1 @danielhanchen/studio/setup.bat @danielhanchen+/studio/audio_cpp_prebuilt_pins.json @danielhanchen+/studio/install_audio_cpp_prebuilt.py @danielhanchen/studio/install_manifest.py @danielhanchen/studio/install_python_stack.py @danielhanchen/studio/install_llama_prebuilt.py @danielhanchendiff --git a/.github/workflows/studio-update-smoke.yml b/.github/workflows/studio-update-smoke.ymlindex 25dd9d0323b..4225bcdd77e 100644--- a/.github/workflows/studio-update-smoke.yml+++ b/.github/workflows/studio-update-smoke.yml@@ -20,11 +20,16 @@ on:- 'studio/install_python_stack.py'- 'studio/install_llama_prebuilt.py'- 'studio/install_whisper_prebuilt.py'+ - 'studio/install_audio_cpp_prebuilt.py'+ # install_audio_cpp_prebuilt.py imports its archive helpers from here.+ - 'studio/install_sd_cpp_prebuilt.py'- 'studio/install_node_prebuilt.py'- 'studio/install_manifest.py'- 'studio/prebuilt_core.py'# install_node_prebuilt.py reads the default version and archive digests from here.- 'studio/node_prebuilt_pins.json'+ # install_audio_cpp_prebuilt.py checks every runtime archive against these digests.+ - 'studio/audio_cpp_prebuilt_pins.json'- 'studio/setup.ps1'- 'install.ps1'- 'studio/backend/requirements/**'@@ -88,11 +93,16 @@ on:- 'studio/install_python_stack.py'- 'studio/install_llama_prebuilt.py'- 'studio/install_whisper_prebuilt.py'+ - 'studio/install_audio_cpp_prebuilt.py'+ # install_audio_cpp_prebuilt.py imports its archive helpers from here.+ - 'studio/install_sd_cpp_prebuilt.py'- 'studio/install_node_prebuilt.py'- 'studio/install_manifest.py'- 'studio/prebuilt_core.py'# install_node_prebuilt.py reads the default version and archive digests from here.- 'studio/node_prebuilt_pins.json'+ # install_audio_cpp_prebuilt.py checks every runtime archive against these digests.+ - 'studio/audio_cpp_prebuilt_pins.json'- 'studio/setup.ps1'- 'install.ps1'- 'studio/backend/requirements/**'@@ -376,9 +386,11 @@ jobs:for p in \"$HOME/.unsloth/studio" \"$HOME/.unsloth/whisper.cpp" \+ "$HOME/.unsloth/audio.cpp" \"$HOME/.unsloth/.llama.cpp.install.lock" \"$HOME/.unsloth/.node.install.lock" \"$HOME/.unsloth/.whisper.cpp.install.lock" \+ "$HOME/.unsloth/.audio.cpp.install.lock" \"$HOME/.local/share/unsloth" \"$HOME/Desktop/Unsloth Studio.desktop" \"$HOME/.local/bin/unsloth"; dodiff --git a/.github/workflows/studio-windows-update-smoke.yml b/.github/workflows/studio-windows-update-smoke.ymlindex b69fee63d18..180621726a1 100644--- a/.github/workflows/studio-windows-update-smoke.yml+++ b/.github/workflows/studio-windows-update-smoke.yml@@ -45,6 +45,7 @@ on:- 'studio/backend/utils/**'- 'studio/install_*.py'- 'studio/node_prebuilt_pins.json'+ - 'studio/audio_cpp_prebuilt_pins.json'- 'unsloth_cli/**'# frontend-dist-restore keys its cache on exactly these three globs, and a miss# makes the checked-out setup.ps1 run npm run build (setup.ps1:5060), so a@@ -75,6 +76,7 @@ on:- 'studio/backend/utils/**'- 'studio/install_*.py'- 'studio/node_prebuilt_pins.json'+ - 'studio/audio_cpp_prebuilt_pins.json'- 'unsloth_cli/**'- 'studio/frontend/*'- 'studio/frontend/src/**'@@ -439,9 +441,11 @@ jobs:"$env:USERPROFILE\.unsloth\studio\unsloth_studio","$env:USERPROFILE\.unsloth\studio\bin\unsloth.exe","$env:USERPROFILE\.unsloth\whisper.cpp",+ "$env:USERPROFILE\.unsloth\audio.cpp","$env:USERPROFILE\.unsloth\.llama.cpp.install.lock","$env:USERPROFILE\.unsloth\.node.install.lock",- "$env:USERPROFILE\.unsloth\.whisper.cpp.install.lock"+ "$env:USERPROFILE\.unsloth\.whisper.cpp.install.lock",+ "$env:USERPROFILE\.unsloth\.audio.cpp.install.lock")) {if (Test-Path -LiteralPath $p) {Write-Host "::error::leak: $p"diff --git a/README.md b/README.mdindex e28f90fcfe5..22942cf4ef4 100644--- a/README.md+++ b/README.md@@ -411,6 +411,13 @@ $env:UNSLOTH_LLAMA_CPP_BACKEND="vulkan" # or cpu, cuda, rocm, autoirm https://unsloth.ai/install.ps1 | iex```+#### audio.cpp audio engine:++Setup also installs [audio.cpp](https://github.com/0xShug0/audio.cpp) (prebuilt by [unslothai/audio.cpp](https://github.com/unslothai/audio.cpp)), which runs the audio.cpp speech, music and speech-to-text models on the Audio page, in Voice settings and behind `/v1/audio/*`. It is optional and never blocks setup:+- `UNSLOTH_SKIP_AUDIO_CPP_INSTALL=1` skips it.+- `UNSLOTH_AUDIO_CPP_ACCELERATOR=cpu` (or `cuda`, `vulkan`, `metal`) picks the bundle instead of auto-detecting.+- `AUDIOCPP_SERVER_PATH=/path/to/audiocpp_server` uses your own build.+#### Uninstall**MacOS, WSL, Linux:** `curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.sh | sh`diff --git a/docker/DOCKERHUB.md b/docker/DOCKERHUB.mdindex b3854beb32a..4ecb9e23c6c 100644--- a/docker/DOCKERHUB.md+++ b/docker/DOCKERHUB.md@@ -1,6 +1,6 @@# Unsloth Docker Image-Fine-tune and run LLMs, vision, audio and diffusion models with no setup. Every image carries the training stack (PyTorch 2.11 with CUDA 12.8, [Unsloth](https://github.com/unslothai/unsloth), unsloth-zoo, bitsandbytes, TRL, PEFT, plus xformers on `linux/amd64`), JupyterLab with the [Unsloth notebooks](https://github.com/unslothai/notebooks), and prebuilt llama.cpp. The `latest` image adds whisper.cpp for Unsloth Studio's speech-to-text.+Fine-tune and run LLMs, vision, audio and diffusion models with no setup. Every image carries the training stack (PyTorch 2.11 with CUDA 12.8, [Unsloth](https://github.com/unslothai/unsloth), unsloth-zoo, bitsandbytes, TRL, PEFT, plus xformers on `linux/amd64`), JupyterLab with the [Unsloth notebooks](https://github.com/unslothai/notebooks), and prebuilt llama.cpp. The `latest` image adds whisper.cpp for Unsloth Studio's speech-to-text and audio.cpp (CUDA build on `linux/amd64`) for its text-to-speech, music and transcription models.Source: [`docker/`](https://github.com/unslothai/unsloth/tree/main/docker). Guide: [docs.unsloth.ai](https://docs.unsloth.ai/get-started/install/docker).diff --git a/docker/Dockerfile.studio b/docker/Dockerfile.studioindex 672b9bc354e..12354e419bd 100644--- a/docker/Dockerfile.studio+++ b/docker/Dockerfile.studio@@ -90,6 +90,8 @@ COPY studio_home.sh /usr/local/bin/unsloth-studio-home# base's baked bundle so the installer skips a second ~400MB download; the# .unsloth-studio-owned marker satisfies setup.sh's ownership assertion.# UNSLOTH_LLAMA_KEEP_PREBUILT=1 keeps it: no GPU is visible here, so setup.sh's detection would install the CPU bundle over it.+# UNSLOTH_AUDIO_CPP_ACCELERATOR does the same for audio.cpp: amd64 names the CUDA bundle outright+# (arm64 has no audio.cpp bundle; auto leaves it to setup's non-fatal "no prebuilt" line).## UNSLOTH_TORCH_INDEX_FAMILY pins the Studio venv's torch index (no nvidia-smi at# build time would land on cpu/cu126). cu128 on both arches, mirroring the base.@@ -106,7 +108,8 @@ COPY studio_home.sh /usr/local/bin/unsloth-studio-home# UNSLOTH_ALLOW_CPU=1 is inline for install.sh only: the build has no GPU, and the image ENV must not carry it (see above).RUN set -eux \&& case "${TARGETARCH:-amd64}" in \- amd64|arm64) TORCH_FAMILY="cu128" ;; \+ amd64) TORCH_FAMILY="cu128"; AUDIO_CPP_ACCELERATOR="cuda" ;; \+ arm64) TORCH_FAMILY="cu128"; AUDIO_CPP_ACCELERATOR="auto" ;; \*) echo "ERROR: unsupported TARGETARCH=${TARGETARCH}" >&2; exit 1 ;; \esac \&& mkdir -p "${UNSLOTH_STUDIO_HOME}" \@@ -122,6 +125,7 @@ RUN set -eux \UNSLOTH_ZOO_REF="${UNSLOTH_STUDIO_ZOO_REF}" \UNSLOTH_LLAMA_TAG="${LLAMA_PREBUILT_TAG}" \UNSLOTH_LLAMA_KEEP_PREBUILT=1 \+ UNSLOTH_AUDIO_CPP_ACCELERATOR="${AUDIO_CPP_ACCELERATOR}" \UNSLOTH_PYTHON=3.12 \UNSLOTH_ALLOW_CPU=1 \bash install.sh --local \diff --git a/scripts/uninstall.ps1 b/scripts/uninstall.ps1index a811cbed350..3ad7592dbd8 100644--- a/scripts/uninstall.ps1+++ b/scripts/uninstall.ps1@@ -40,8 +40,9 @@ Stops running Unsloth Studio servers, then removes the install dir, launcherdata, CLI shim, desktop and Start Menu shortcuts, the user PATH entry and thePathBackup registry key. In a default-mode install it also removes the sharedprebuilts that sit beside the install dir:-%USERPROFILE%\.unsloth\{llama.cpp,node,whisper.cpp,.cache}. The Hugging Face-cache is left in place, as is anything else you keep under %USERPROFILE%\.unsloth.+%USERPROFILE%\.unsloth\{llama.cpp,node,whisper.cpp,audio.cpp,.cache}. The Hugging+Face cache is left in place (only audio.cpp's unsloth-audiocpp-links beside it+goes), as is anything else you keep under %USERPROFILE%\.unsloth.Options:-Help, -h, --help, -?, /? Print this message and exit without removing anything.@@ -145,7 +146,7 @@ Environment:# The exact shape prebuilt_core.py leaves: a component lock name, ".stale.", and the pid it# moved aside. The leading dot alone also matched ".backup.install.lock.stale.copy", which in# a user-chosen master root is theirs. uninstall.sh applies the same shape.- $script:StaleLockPattern = '^\.(llama\.cpp|node|whisper\.cpp|sd\.cpp)\.install\.lock\.stale\.[0-9]+$'+ $script:StaleLockPattern = '^\.(llama\.cpp|node|whisper\.cpp|audio\.cpp|sd\.cpp)\.install\.lock\.stale\.[0-9]+$'# An install lock, and only an install lock. prebuilt_core.install_lock creates these with# O_CREAT | O_EXCL, so a lock is always a regular file, while _RemovePath deletes recursively@@ -874,7 +875,7 @@ Environment:param([string[]]$Roots)# Everything setup.ps1 / the prebuilt installers place inside an Unsloth home.$managed = @(- "unsloth_studio", "share", "bin", "llama.cpp", "whisper.cpp", "node",+ "unsloth_studio", "share", "bin", "llama.cpp", "whisper.cpp", "audio.cpp", "node","stable-diffusion.cpp", ".cache", ".venv_t5_510", ".venv_t5_530", ".venv_t5_550")$out = @()@@ -973,6 +974,8 @@ Environment:# Managed whisper.cpp dictation engine (setup.ps1 installs it at $UnslothHome\whisper.cpp), a# default-mode sibling of studio. No-op in env/custom mode and when absent.$defaultWhisperCpp = if ($defaultUnslothHome) { Join-Path $defaultUnslothHome "whisper.cpp" } else { $null }+ # Managed audio.cpp engine (setup.ps1 installs it at $UnslothHome\audio.cpp), same rules.+ $defaultAudioCpp = if ($defaultUnslothHome) { Join-Path $defaultUnslothHome "audio.cpp" } else { $null }# Build known-root list FIRST so the port-file kill can verify ownership.$customRoots = @(_CustomStudioRoots)@@ -1089,7 +1092,7 @@ Environment:$masterRootToStop = _MasterRoot$masterChildrenToStop = @()if ($masterRootToStop -and -not (_IsUnsafeRoot $masterRootToStop)) {- foreach ($childName in @("llama.cpp", "node", "whisper.cpp", "stable-diffusion.cpp")) {+ foreach ($childName in @("llama.cpp", "node", "whisper.cpp", "audio.cpp", "stable-diffusion.cpp")) {$childPath = Join-Path $masterRootToStop $childName# Only the trees this uninstall is going to delete, so an unmarked neighbour's# process is never killed.@@ -1100,7 +1103,7 @@ Environment:}# $ownedRoots, not $knownRoots: see the note where the two lists are built. The master# children are already marker-gated above, so they carry their own proof of ownership.- $stopRoots = @($ownedRoots) + @($defaultDataDir, $defaultLlamaCpp, $defaultCache, $defaultNode, $defaultWhisperCpp) + @($defaultSdCppToStop | Where-Object { $_ }) + @($customSdCppToStop) + @($masterChildrenToStop)+ $stopRoots = @($ownedRoots) + @($defaultDataDir, $defaultLlamaCpp, $defaultCache, $defaultNode, $defaultWhisperCpp, $defaultAudioCpp) + @($defaultSdCppToStop | Where-Object { $_ }) + @($customSdCppToStop) + @($masterChildrenToStop)# The reparse expansion turns one path into generic subdirectories of wherever it points# (node, bin, unsloth_studio), so it is gated for the same reason._StopProcessesLockingRoots -Roots ($stopRoots + @(_ManagedPathsUnderReparseTargets $ownedRoots))@@ -1177,7 +1180,7 @@ Environment:$masterRoot = $null}if ($masterRoot) {- foreach ($childName in @("llama.cpp", "node", "whisper.cpp", "stable-diffusion.cpp")) {+ foreach ($childName in @("llama.cpp", "node", "whisper.cpp", "audio.cpp", "stable-diffusion.cpp")) {$childPath = Join-Path $masterRoot $childNameif ((Test-Path -LiteralPath $childPath) -and-not (Test-Path -LiteralPath (Join-Path $childPath ".unsloth-studio-owned") -PathType Leaf)) {@@ -1187,7 +1190,7 @@ Environment:}}foreach ($lockName in @(".llama.cpp.install.lock", ".node.install.lock",- ".whisper.cpp.install.lock", ".sd.cpp.install.lock")) {+ ".whisper.cpp.install.lock", ".audio.cpp.install.lock", ".sd.cpp.install.lock")) {_RemoveLockFile (Join-Path $masterRoot $lockName)}# The prebuilt installers SHARE <root>\.staging and prune it only when empty, so@@ -1221,10 +1224,32 @@ Environment:# Managed whisper.cpp prebuilt, a sibling of studio under ~/.unsloth. Only present when one# matching the pinned llama.cpp build existed at install time, so many installs lack it.if ($defaultWhisperCpp) { _RemovePath $defaultWhisperCpp }+ # The installer always marks its tree and refuses an unmarked one, so an unmarked one is the user's.+ if ($defaultAudioCpp -and (Test-Path -LiteralPath $defaultAudioCpp) -and -not (Test-Path -LiteralPath (Join-Path $defaultAudioCpp ".unsloth-studio-owned") -PathType Leaf)) {+ _Substep "keeping audio.cpp without Unsloth owner marker: $defaultAudioCpp" "Yellow"+ } elseif ($defaultAudioCpp) {+ _RemovePath $defaultAudioCpp+ }+ # audio.cpp lays its models out as links (copies across volumes) in unsloth-audiocpp-links beside+ # the Hugging Face hub cache (audio_cpp_files.py). The cache itself stays, as the note below says.+ $hfHub = if ($env:HF_HUB_CACHE) { $env:HF_HUB_CACHE }+ elseif ($env:HUGGINGFACE_HUB_CACHE) { $env:HUGGINGFACE_HUB_CACHE }+ elseif ($env:HF_HOME) { Join-Path $env:HF_HOME "hub" }+ elseif ($env:XDG_CACHE_HOME) { Join-Path (Join-Path $env:XDG_CACHE_HOME "huggingface") "hub" }+ elseif ($env:USERPROFILE) { Join-Path $env:USERPROFILE ".cache\huggingface\hub" }+ else { $null }+ $hfParent = if ($hfHub) { Split-Path -Parent $hfHub } else { $null }+ if ($hfParent) { _RemovePath (Join-Path $hfParent "unsloth-audiocpp-links") }+ # The audio.cpp server's scratch home when the Studio root was unusable (audio_cpp_server.py).+ # %TEMP% is per user, and the name carries this user's, so no other account's is reached.+ if ($env:USERNAME) {+ $audioCppHome = Join-Path ([System.IO.Path]::GetTempPath()) "unsloth-audiocpp-home-$env:USERNAME"+ if (Test-Path -LiteralPath $audioCppHome -PathType Container) { _RemovePath $audioCppHome }+ }# Prebuilt install locks: every prebuilt serializes on <parent>\.<name>.install.lock# (prebuilt_core.py), and a stray lock keeps ~/.unsloth from being pruned below.if ($defaultUnslothHome) {- foreach ($lockName in @(".llama.cpp.install.lock", ".node.install.lock", ".whisper.cpp.install.lock")) {+ foreach ($lockName in @(".llama.cpp.install.lock", ".node.install.lock", ".whisper.cpp.install.lock", ".audio.cpp.install.lock")) {_RemoveLockFile (Join-Path $defaultUnslothHome $lockName)}# Taking over an abandoned lock renames it to .stale.<pid> before unlinking; a crashdiff --git a/scripts/uninstall.sh b/scripts/uninstall.shindex e38deac8c7a..9afd2781d7b 100755--- a/scripts/uninstall.sh+++ b/scripts/uninstall.sh@@ -27,9 +27,10 @@ is not (dash, busybox sh) the shell exits with "Illegal option -h".Stops running Unsloth Studio servers, then removes the install dir, launcherdata dir, CLI shim, desktop shortcut, macOS .app bundle and Launch Servicesentry. In a default-mode install it also removes the shared prebuilts that sit-beside the install dir: ~/.unsloth/{llama.cpp,node,whisper.cpp,.cache}. The-Hugging Face cache at ~/.cache/huggingface is left in place, as is anything-else you keep under ~/.unsloth.+beside the install dir: ~/.unsloth/{llama.cpp,node,whisper.cpp,audio.cpp,.cache}.+The Hugging Face cache at ~/.cache/huggingface is left in place (only audio.cpp's+unsloth-audiocpp-links beside it goes), as is anything else you keep under+~/.unsloth.On WSL it also removes this distro's Windows-side shortcuts under /mnt/*/Users,strips the Unsloth block from ~/.bashrc, and uses sudo to delete@@ -833,7 +834,7 @@ _unsloth_uninstall_main() {if _is_unsafe_root "$_mr_root"; thenecho " refusing to remove unsafe path: $_mr_root" >&2else- for _mr_child in llama.cpp node whisper.cpp stable-diffusion.cpp; do+ for _mr_child in llama.cpp node whisper.cpp audio.cpp stable-diffusion.cpp; do_mr_path="$_mr_root/$_mr_child"if _is_unsafe_root "$_mr_path"; thenecho " refusing to remove unsafe path: $_mr_path" >&2@@ -848,7 +849,7 @@ _unsloth_uninstall_main() {fidonefor _mr_lock in .llama.cpp.install.lock .node.install.lock \- .whisper.cpp.install.lock .sd.cpp.install.lock; do+ .whisper.cpp.install.lock .audio.cpp.install.lock .sd.cpp.install.lock; do_remove_lock_file "$_mr_root/$_mr_lock"done# The prebuilt installers SHARE <root>/.staging and prune it only when empty, so@@ -858,7 +859,7 @@ _unsloth_uninstall_main() {# The exact shape prebuilt_core.py leaves: a component lock name, ".stale.", and the# pid. A bare .*.install.lock.stale.* also matched .backup.install.lock.stale.copy.for _mr_lock in .llama.cpp.install.lock .node.install.lock \- .whisper.cpp.install.lock .sd.cpp.install.lock; do+ .whisper.cpp.install.lock .audio.cpp.install.lock .sd.cpp.install.lock; dofor _mr_stale in "$_mr_root/$_mr_lock".stale.*; docase "${_mr_stale##*.stale.}" in''|*[!0-9]*) continue ;;@@ -909,11 +910,32 @@ _unsloth_uninstall_main() {# Managed whisper.cpp dictation engine (install_whisper_prebuilt.py), a default-mode sibling.# Only present when a prebuilt matching the pinned llama.cpp build existed at install time._remove_path "$HOME/.unsloth/whisper.cpp"+ # Managed audio.cpp engine (install_audio_cpp_prebuilt.py), a default-mode sibling. The installer+ # always marks its tree and refuses an unmarked one, so an unmarked one is the user's own build.+ _default_audio_cpp="$HOME/.unsloth/audio.cpp"+ if { [ -e "$_default_audio_cpp" ] || [ -L "$_default_audio_cpp" ]; } \+ && [ ! -f "$_default_audio_cpp/.unsloth-studio-owned" ]; then+ echo " keeping audio.cpp without Unsloth owner marker: $_default_audio_cpp" >&2+ else+ _remove_path "$_default_audio_cpp"+ fi# Prebuilt install locks: every prebuilt serializes on <parent>/.<name>.install.lock# (prebuilt_core.py), and a stray lock keeps ~/.unsloth from being pruned below._remove_lock_file "$HOME/.unsloth/.llama.cpp.install.lock"_remove_lock_file "$HOME/.unsloth/.node.install.lock"_remove_lock_file "$HOME/.unsloth/.whisper.cpp.install.lock"+ _remove_lock_file "$HOME/.unsloth/.audio.cpp.install.lock"+ # audio.cpp lays its models out as links (copies across volumes) in unsloth-audiocpp-links beside+ # the Hugging Face hub cache (audio_cpp_files.py). The cache itself stays, as the note below says.+ _hf_hub="${HF_HUB_CACHE:-${HUGGINGFACE_HUB_CACHE:-${HF_HOME:-${XDG_CACHE_HOME:-$HOME/.cache}/huggingface}/hub}}"+ _remove_path "$(dirname "$_hf_hub")/unsloth-audiocpp-links"+ # The audio.cpp server's scratch home when the Studio root was unusable (audio_cpp_server.py);+ # per uid, so another user's is never touched, and only a real directory this user owns.+ _audiocpp_home="${TMPDIR:-/tmp}"+ _audiocpp_home="${_audiocpp_home%/}/unsloth-audiocpp-home-$(id -u 2>/dev/null)"+ if [ -d "$_audiocpp_home" ] && [ ! -L "$_audiocpp_home" ] && [ -O "$_audiocpp_home" ]; then+ _remove_path "$_audiocpp_home"+ fi# Taking over an abandoned lock renames it to .stale.<pid> before unlinking# (install_node_prebuilt.py); a crash between the two strands the rename, and a stranded one# blocks the rmdir below. Unmatched globs stay literal, hence the existence test.@@ -921,7 +943,7 @@ _unsloth_uninstall_main() {# anything else kept under ~/.unsloth is left in place, and .backup.install.lock.stale.copy# is dotted too.for _lock in .llama.cpp.install.lock .node.install.lock \- .whisper.cpp.install.lock .sd.cpp.install.lock; do+ .whisper.cpp.install.lock .audio.cpp.install.lock .sd.cpp.install.lock; dofor _stale in "$HOME/.unsloth/$_lock".stale.*; docase "${_stale##*.stale.}" in''|*[!0-9]*) continue ;;diff --git a/studio/audio_cpp_prebuilt_pins.json b/studio/audio_cpp_prebuilt_pins.jsonnew file mode 100644index 00000000000..a004c45d998--- /dev/null+++ b/studio/audio_cpp_prebuilt_pins.json@@ -0,0 +1,43 @@+{+ "schema_version": 1,+ "comment": "Trust anchor for install_audio_cpp_prebuilt.py: sha256 of each audio.cpp runtime archive, copied from the GitHub release asset digests. Generated; do not edit by hand. To bump: change DEFAULT_TAG / UPSTREAM_FALLBACK_TAG, then run `python studio/install_audio_cpp_prebuilt.py --write-pins` (the same digests `gh release view <tag> -R <repo> --json assets` lists).",+ "releases": {+ "unslothai/audio.cpp": {+ "v0.9.0-unsloth.1": {+ "audio-v0.9.0-unsloth.1-bin-macos-arm64-metal.tar.gz": "8eb13c99d0b1d9fec07b0cea2ab0b2b54cd10c95286c6b628494c8f168fa1f34",+ "audio-v0.9.0-unsloth.1-bin-macos-x64-metal.tar.gz": "da2e7211b507ba456e7c1e3581e1f16f46c8caafd0214d3896854e9680ce9549",+ "audio-v0.9.0-unsloth.1-bin-ubuntu-arm64-cpu.tar.gz": "1ce3a1c976216bbd451a3a16f0db0de6aed94602e652fa9208e03ac447319b9f",+ "audio-v0.9.0-unsloth.1-bin-ubuntu-x64-cpu-portable.tar.gz": "46cc9315efa010bb8a00f20a269bd0f98ddb02d6abaa32a4eef06d20c2457385",+ "audio-v0.9.0-unsloth.1-bin-ubuntu-x64-cpu.tar.gz": "10aecb17d4ea4e45a38c5b206909ad5ab8800ee6203e1cc307ff40f1cc99e680",+ "audio-v0.9.0-unsloth.1-bin-ubuntu-x64-cuda12.tar.gz": "1f7ca305d8ec35560f71e6e928d85826cbd9be8c8fe6f5f87ae87d07fab8682e",+ "audio-v0.9.0-unsloth.1-bin-ubuntu-x64-cuda13.tar.gz": "c4085661930256e66cecb21c3ee578407f17e5d2514e9abdf7f46f047da44cd1",+ "audio-v0.9.0-unsloth.1-bin-ubuntu-x64-vulkan.tar.gz": "9b6e243196d42ac9890a3f0499eb4a0c9d0f6075cb36e0ad06cf327024476793",+ "audio-v0.9.0-unsloth.1-bin-windows-x64-cpu-portable.zip": "05193187d2aaa47806e5dce1f8417cd31ef1a94d544041e4d083f882315ae8c2",+ "audio-v0.9.0-unsloth.1-bin-windows-x64-cpu.zip": "3c3979d2b801b4ae562ee8e00d2d3a657c55f84b80fb5380ab7c779caf20713e",+ "audio-v0.9.0-unsloth.1-bin-windows-x64-cuda12.zip": "ad157f2bd50abbd4d71b9fd370e6e9e73148bae2e3709e5b787fc360c3b08ff6",+ "audio-v0.9.0-unsloth.1-bin-windows-x64-cuda13.zip": "09ee47dd7338dc16722512da2bdad51e1570238f5dca89d307f14aecd1171371",+ "audio-v0.9.0-unsloth.1-bin-windows-x64-vulkan.zip": "ad6eb033d1d5fef44ab8000ec0db2650116f732658a1bc8244b02b0832778264",+ "audio-v0.9.0-unsloth.1-cudart-windows-x64-cuda12.zip": "78ff03c3215e254c5c38c8689a9054287d39d9490626a7c475babd88b326f2a6",+ "audio-v0.9.0-unsloth.1-cudart-windows-x64-cuda13.zip": "3853900a3056a147737f09ffe5f440c3ca8047d4b1ae0554d1799b193db6bd7b"+ }+ },+ "0xShug0/audio.cpp": {+ "v0.9.0": {+ "audio-v0.9.0-bin-macos-arm64-metal.tar.gz": "7cea9219d5f06475011c5d225d71d988cecef633ff7d098ee8a4c7b08583b1b4",+ "audio-v0.9.0-bin-macos-x64-metal.tar.gz": "f6e50c776bfe3b23cb5e420f1dd31b11661ed3dc01207cf05cf780dfdadca1c9",+ "audio-v0.9.0-bin-ubuntu-x64-cpu-portable.tar.gz": "cf87b6baa46cf45fc8a2816b8f04f0f3f3fce32cca297231a4da56543f19fe87",+ "audio-v0.9.0-bin-ubuntu-x64-cpu.tar.gz": "d0f0db4ab13bd3de1c15b6d60256e615d2bac65892fdd4fccc9a2b678db47635",+ "audio-v0.9.0-bin-ubuntu-x64-cuda12.8-colab.tar.gz": "c9ed906f918246669c324f0d31f1b7dd80cbe003c35cf8a54932f333b57ca3f6",+ "audio-v0.9.0-bin-ubuntu-x64-vulkan-portable.tar.gz": "ce661a7b39add12e91f1c7cc590d55854a39ec0a2fd04c004b3fed29cb978398",+ "audio-v0.9.0-bin-ubuntu-x64-vulkan.tar.gz": "9f01f7bedb7aff67d553360ad62fa11db5b638ddbb85d49dd718127575f7d799",+ "audio-v0.9.0-bin-windows-x64-cpu-portable.zip": "3ee19466a1a2b5366364ca8447a4794391dd89671e655ffd01aa421ac1668bfa",+ "audio-v0.9.0-bin-windows-x64-cpu.zip": "6e65c6f112aee53e9f02cee134222915f3a88edf3c7bd0bc7db065683c07dfc5",+ "audio-v0.9.0-bin-windows-x64-cuda12.4.zip": "f935d399b1cabb96422d9b35278dcabbbe7c16638a0e100a9b983421511eeb91",+ "audio-v0.9.0-bin-windows-x64-cuda13.3.zip": "46eb928af284babb3526fc5198da12a4fe4e4445812d60e90a04e82cb5a87786",+ "audio-v0.9.0-bin-windows-x64-vulkan.zip": "f884538138e44528a0bf17bb75dbe7ff7350cb91a14cb72c3e9cc1d4a31d6f1f",+ "audio-v0.9.0-cudart-windows-x64-cuda12.4.zip": "155377e0b18d568002a6cb252a36dc2b96aaa93606c0e44ace945ec3123564fe",+ "audio-v0.9.0-cudart-windows-x64-cuda13.3.zip": "2c7b1054df88a3cb357c005d5284a5d9d6faf14a13885f6cf0e74d966d74c013"+ }+ }+ }+}diff --git a/studio/backend/core/inference/audio_cpp_backend.py b/studio/backend/core/inference/audio_cpp_backend.pynew file mode 100644index 00000000000..11feeed83ab--- /dev/null+++ b/studio/backend/core/inference/audio_cpp_backend.py@@ -0,0 +1,446 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Worker backend for audio.cpp speech and music models in the main audio slot.++Selected by the inference worker in place of ``NativeAudioBackend`` when the model+is an audio.cpp TTS or music GGUF, so loading, auto-switching, idle eviction,+cancellation and the Audio page, read-aloud and ``/v1/audio/speech`` all work+through the machinery every other main-slot audio model uses. The weights run in+an ``audiocpp_server`` child; this class only downloads, starts, proxies and stops.++A cancelled request cannot interrupt GPU work already queued inside the server, and+the server would make the next request wait for it (minutes, for music). So a cancel+stops the server and the next request starts it again from the warm file cache.+"""++from __future__ import annotations++import base64+import io+import json+import threading+import wave+from typing import Any, Optional, Tuple++from core.inference import audio_cpp_files+from core.inference.audio_cpp_models import (+ AudioCppModel,+ AudioCppModelError,+ require_runnable,+ resolve,+ validate_options,+)+from core.inference.audio_cpp_server import (+ AudioCppRequestCancelledError,+ AudioCppRequestError,+ AudioCppServer,+ AudioCppStartCancelledError,+)+from loggers import get_logger+from utils.gpu_memory_events import invalidates_gpu_memory as _invalidates_gpu_memory++logger = get_logger(__name__)++# Upper bound for one request; music generation at long durations takes minutes.+_GENERATE_TIMEOUT_SECONDS = 3600.0+# Frames of a 30-second clip, the MiniMax convention the Audio page's music budget speaks in.+_DEFAULT_MUSIC_SECONDS = 30.0+_MAX_MUSIC_SECONDS = 240.0+++def _raise_if_cancelled(cancel_event) -> None:+ if cancel_event is not None and cancel_event.is_set():+ from core.inference.audio_errors import AudioGenerationCancelledError+ raise AudioGenerationCancelledError("Audio generation cancelled")+++def _wav_sample_rate(wav_bytes: bytes) -> int:+ with wave.open(io.BytesIO(wav_bytes)) as w:+ return int(w.getframerate())+++def _music_seconds(max_new_tokens: Optional[int]) -> float:+ """Map the shared speech-token budget onto a clip length.++ The Audio page sends MiniMax's 25-frames-per-second budget for music; the same+ number here means the same length, so one duration control drives every model.+ """+ try:+ frames = int(max_new_tokens or 0)+ except (TypeError, ValueError):+ frames = 0+ if frames <= 0:+ return _DEFAULT_MUSIC_SECONDS+ return max(5.0, min(_MAX_MUSIC_SECONDS, frames / 25.0))+++def model_info_fields(model: AudioCppModel) -> dict[str, Any]:+ """What status reports for a loaded audio.cpp model, beyond the common audio fields."""+ return {+ "audio_family": model.family,+ "audio_options": [dict(option) for option in model.options],+ "gguf_variant": model.variant.key,+ }+++class AudioCppBackend:+ """One-model backend proxying to an ``audiocpp_server`` child."""++ def __init__(self, device_preference: Optional[str] = None) -> None:+ from core.inference.audio_device import audio_device_forces_cpu++ self.device_preference = device_preference+ self._force_cpu = audio_device_forces_cpu(device_preference)+ self.device = "cpu" if self._force_cpu else "gpu"+ self.models: dict[str, dict[str, Any]] = {}+ self.active_model_name: Optional[str] = None+ self.loading_models: set[str] = set()+ self._model: Optional[AudioCppModel] = None+ self._server: Optional[AudioCppServer] = None+ self._server_lock = threading.RLock()++ # Loading++ @_invalidates_gpu_memory("audio load")+ def load_model(+ self,+ config,+ max_seq_length: int = 2048,+ dtype = None,+ load_in_4bit: bool = False,+ hf_token: Optional[str] = None,+ trust_remote_code: bool = False,+ gpu_ids: Optional[list[int]] = None,+ **_ignored,+ ) -> bool:+ del max_seq_length, dtype, load_in_4bit, trust_remote_code+ model_name = config.identifier+ model = getattr(config, "audio_cpp", None) or resolve(+ model_name, getattr(config, "gguf_variant", None), hf_token+ )+ if model is None:+ raise RuntimeError(f"'{model_name}' is not an audio GGUF.")+ try:+ require_runnable(model, "tts")+ except AudioCppModelError as exc:+ raise RuntimeError(str(exc)) from exc+ if gpu_ids is not None and len(gpu_ids) > 1:+ raise RuntimeError(+ "Audio GGUF models run on a single GPU; multi-GPU sharding is not supported."+ )+ if (+ model_name in self.models+ and self._model == model+ and self._server is not None+ and self._server.alive()+ ):+ self.active_model_name = model_name+ return True+ # Before any download: a runtime that cannot serve this model must fail fast, not after gigabytes.+ from core.inference.audio_cpp_server import model_runtime_problem++ problem = model_runtime_problem(model)+ if problem:+ raise RuntimeError(problem)+ self.loading_models.add(model_name)+ try:+ self._ensure_downloaded(model, hf_token)+ self._start_server(model)+ self._model = model+ self.models = {+ model_name: {+ "is_audio": True,+ "audio_type": model.audio_type,+ "has_audio_input": False,+ "model_path": model.id,+ # No token window: speech length is bounded by the server, music by duration.+ "context_length": 0,+ **model_info_fields(model),+ "audio_cpp_backend": self._server.backend if self._server else None,+ }+ }+ self.active_model_name = model_name+ return True+ finally:+ self.loading_models.discard(model_name)++ def _ensure_downloaded(self, model: AudioCppModel, hf_token: Optional[str]) -> None:+ missing = audio_cpp_files.missing_files(model)+ if not missing:+ return+ from huggingface_hub import hf_hub_download++ from utils.hf_cache_settings import active_hf_hub_cache++ cache_dir = str(active_hf_hub_cache())+ for path, _size in missing:+ logger.info("audio.cpp: downloading %s from %s", path, model.repo_id)+ hf_hub_download(+ model.repo_id,+ path,+ token = hf_token or None,+ cache_dir = cache_dir,+ )++ def _start_server(+ self,+ model: AudioCppModel,+ cancel_event = None,+ ) -> None:+ with self._server_lock:+ self._stop_server_locked()+ model_path = audio_cpp_files.materialize(model)+ try:+ self._server = AudioCppServer.start(+ model, 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+ self.device = "cpu" if self._server.backend == "cpu" else self._server.backend++ def _stop_server_locked(self) -> None:+ server = self._server+ self._server = None+ if server is not None:+ server.stop()++ def _running_server(self, model: AudioCppModel, cancel_event) -> AudioCppServer:+ with self._server_lock:+ if self._server is None or not self._server.alive() or self._server.model != model:+ logger.info("audio.cpp: (re)starting the server for %s", model.id)+ self._start_server(model, cancel_event)+ return self._server++ # Generation++ def generate_audio_response(+ self,+ text: str,+ temperature: float = 0.6,+ top_p: float = 0.95,+ top_k: int = 50,+ min_p: float = 0.0,+ max_new_tokens: int = 2048,+ repetition_penalty: float = 1.0,+ use_adapter = None,+ cancel_event = None,+ instructions: Optional[str] = None,+ language: Optional[str] = None,+ seed: Optional[int] = None,+ audio_options: Optional[dict] = None,+ ) -> Tuple[bytes, int]:+ del top_k, min_p, repetition_penalty, use_adapter+ if not self.active_model_name or self.active_model_name not in self.models:+ raise RuntimeError("No active audio model")+ model = self._model+ if model is None:+ raise RuntimeError("No active audio model")+ _raise_if_cancelled(cancel_event)+ options = validate_options(model.options, audio_options)+ server = self._running_server(model, cancel_event)+ try:+ if model.task == "music":+ wav = self._generate_music(+ server, model, text, instructions, max_new_tokens, seed, options, cancel_event+ )+ else:+ wav = self._generate_speech(+ server,+ model,+ text,+ instructions,+ language,+ temperature,+ top_p,+ seed,+ options,+ cancel_event,+ )+ except AudioCppRequestCancelledError:+ self._restart_after_cancel()+ _raise_if_cancelled(cancel_event)+ raise+ except AudioCppRequestError as exc:+ raise RuntimeError(f"The audio runtime could not generate audio: {exc.detail}") from exc+ _raise_if_cancelled(cancel_event)+ return wav, _wav_sample_rate(wav)++ def _restart_after_cancel(self) -> None:+ # The server keeps computing the abandoned request; stopping it frees the GPU now and the next+ # request starts a fresh one.+ with self._server_lock:+ self._stop_server_locked()++ @staticmethod+ def _generate_speech(+ server: AudioCppServer,+ model: AudioCppModel,+ text: str,+ instructions: Optional[str],+ language: Optional[str],+ temperature: float,+ top_p: float,+ seed: Optional[int],+ options: dict,+ cancel_event,+ ) -> bytes:+ defaults = dict(model.request_defaults)+ default_options = dict(defaults.pop("options", None) or {})+ body: dict[str, Any] = {"model": server.model_id, "input": text, **defaults}+ # Family defaults win: Studio's generic temperature can stop one emitting its stop token (MOSS-TTS-Nano).+ del temperature, top_p+ chosen = dict(options)+ voice = chosen.pop("voice", None)+ if voice:+ body["voice"] = voice+ default_options.update(chosen)+ requested: dict[str, Any] = {}+ if instructions and str(instructions).strip():+ # Voice-design and style-capable families read the description as the instruction.+ requested["instruct"] = str(instructions).strip()+ if language and str(language).strip():+ requested["language"] = str(language).strip()+ merged = {**default_options, **requested}+ if merged:+ body["options"] = merged+ if seed is not None:+ body["seed"] = str(int(seed))+ try:+ _ctype, data = server.post_json(+ "/v1/audio/speech",+ body,+ timeout = _GENERATE_TIMEOUT_SECONDS,+ cancel_event = cancel_event,+ )+ except AudioCppRequestError as exc:+ # 503 is a busy model, not a refused option. The server answers an option a family lacks with a+ # 4xx or a 500 depending on where the family validates it, so both count as a refusal here.+ if not requested or exc.status == 503 or not 400 <= exc.status < 600:+ raise+ # The request's own description and language are hints; the package's defaults and the+ # user's options are not.+ logger.info(+ "audio.cpp: %s rejected %s (%s); retrying without them",+ model.family,+ sorted(requested),+ exc.detail,+ )+ if default_options:+ body["options"] = default_options+ else:+ body.pop("options", None)+ _ctype, data = server.post_json(+ "/v1/audio/speech",+ body,+ timeout = _GENERATE_TIMEOUT_SECONDS,+ cancel_event = cancel_event,+ )+ return data++ @staticmethod+ def _generate_music(+ server: AudioCppServer,+ model: AudioCppModel,+ text: str,+ instructions: Optional[str],+ max_new_tokens: Optional[int],+ seed: Optional[int],+ options: dict,+ cancel_event,+ ) -> bytes:+ # The Audio page's music form sends the description as instructions and the lyrics as text (the MiniMax+ # convention).+ description = str(instructions or "").strip()+ lyrics = str(text or "").strip()+ seconds = _music_seconds(max_new_tokens)+ request: dict[str, Any] = {}+ request_options: dict[str, Any] = dict(options)+ if model.family == "minimax_music3":+ if not lyrics:+ raise RuntimeError("MiniMax Music 3 needs lyrics.")+ # The caption is the input. The task route maps duration_seconds onto the duration_sec+ # option; sending both is refused as "conflicting option values", even when equal.+ request.update(+ {"text": description or lyrics, "lyrics": lyrics, "duration_seconds": seconds}+ )+ request_options["lyrics"] = lyrics+ elif model.family == "yue2":+ if not description:+ raise RuntimeError("YuE2 needs a style description.")+ request["text"] = lyrics or description+ request_options["style"] = description+ if lyrics:+ request_options["lyrics"] = lyrics+ # YuE2's length is its semantic token budget at 25 frames per second (default 9000, six+ # minutes), and its default floor of 200 frames would outlast a short request.+ frames = int(round(seconds * 25))+ request_options["semantic_max_tokens"] = frames+ request_options["semantic_min_tokens"] = min(200, frames)+ else:+ # A lone prompt with no description is the description.+ if not description:+ description, lyrics = lyrics, ""+ request["text"] = description+ request["duration_seconds"] = seconds+ if lyrics and model.family != "stable_audio":+ request["lyrics"] = lyrics+ if request_options:+ request["options"] = request_options+ if seed is not None:+ request["seed"] = str(int(seed))+ ctype, data = server.post_json(+ "/v1/tasks/run",+ {"model": server.model_id, "request": request},+ timeout = _GENERATE_TIMEOUT_SECONDS,+ cancel_event = cancel_event,+ )+ return _audio_from_task_response(ctype, data)++ # Unloading++ @_invalidates_gpu_memory("audio unload")+ def unload_model(self, model_name: str) -> bool:+ self.models.pop(model_name, None)+ if self.active_model_name == model_name:+ self.active_model_name = None+ self._model = None+ with self._server_lock:+ self._stop_server_locked()+ return True++ def reset_generation_state(self, caller_cancel_event = None) -> None:+ del caller_cancel_event+++def _audio_from_task_response(content_type: str, data: bytes) -> bytes:+ """WAV bytes from ``/v1/tasks/run``: raw audio, or JSON carrying base64 audio."""+ if content_type.startswith("audio/") or data[:4] == b"RIFF":+ return data+ try:+ payload = json.loads(data.decode("utf-8"))+ except ValueError as exc:+ raise RuntimeError("The audio runtime returned an unreadable music response.") from exc+ for candidate in _audio_candidates(payload):+ try:+ decoded = base64.b64decode(candidate, validate = False)+ except Exception: # noqa: BLE001 - not base64+ continue+ if decoded[:4] == b"RIFF":+ return decoded+ raise RuntimeError("The audio runtime returned no audio for the music request.")+++def _audio_candidates(node: Any):+ if isinstance(node, dict):+ for key in ("audio", "wav", "data", "b64_json", "audio_base64"):+ value = node.get(key)+ if isinstance(value, str):+ yield value.split(",", 1)[-1]+ for value in node.values():+ if isinstance(value, (dict, list)):+ yield from _audio_candidates(value)+ elif isinstance(node, list):+ for item in node:+ yield from _audio_candidates(item)diff --git a/studio/backend/core/inference/audio_cpp_files.py b/studio/backend/core/inference/audio_cpp_files.pynew file mode 100644index 00000000000..1c1d69f8452--- /dev/null+++ b/studio/backend/core/inference/audio_cpp_files.py@@ -0,0 +1,364 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Where an audio.cpp model's files live, and how audio.cpp is shown them.++The weights are ordinary Hub files in the shared HF cache, downloaded like any GGUF+variant, so the Model Hub, Download Manager and deletion all see them. audio.cpp,+however, picks a loader by file extension after resolving symlinks, and an HF cache+snapshot entry is a symlink to an extension-less blob, so it cannot be handed the+snapshot path. ``materialize`` hardlinks the variant's files under their real names+into a small link farm beside the hub cache (same volume, so no copy and no extra+disk). A cache without symlinks already stores real files and is used as is, except+on Windows, where every model goes through the farm's short per-model path: the+Windows server cannot open a path of 260 characters or more.+"""++from __future__ import annotations++import json+import os+import shutil+import sys+import time+import uuid+from pathlib import Path+from typing import Optional++from core.inference.audio_cpp_models import AudioCppModel, snapshot_dirs+from loggers import get_logger++logger = get_logger(__name__)++_LINK_FARM_DIRNAME = "unsloth-audiocpp-links"+# Records which repo files a farm entry mirrors, so pruning needs no catalog.+_SOURCE_MARKER = ".unsloth-source.json"+# The Windows audiocpp_server fails to open a model path this long ("model path does not exist"),+# and the long-path prefix does not help.+_WINDOWS_MAX_MODEL_PATH = 259+++def _hub_cache() -> Path:+ from utils.hf_cache_settings import active_hf_hub_cache+ return Path(active_hf_hub_cache())+++def _file_complete(path: Path, size: int = 0) -> bool:+ try:+ if not path.is_file():+ return False+ actual = path.stat().st_size+ return actual > 0 and (size <= 0 or actual == size)+ except OSError:+ return False+++def _find(model: AudioCppModel, hub_cache: Path) -> Optional[tuple[Path, list[Path]]]:+ """The first snapshot holding every file of the model's variant, with those files."""+ if model.local_path:+ path = Path(model.local_path)+ return (path.parent, [path]) if _file_complete(path) else None+ for snapshot in snapshot_dirs(model.repo_id, hub_cache):+ found = []+ for f in model.variant.files:+ path = snapshot / f.path+ if not _file_complete(path, f.size):+ break+ found.append(path)+ else:+ return snapshot, found+ return None+++def cached_files(model: AudioCppModel, *, hub_cache: Optional[Path] = None) -> Optional[list[Path]]:+ """The variant's files in the HF cache (snapshot paths), or None when not fully downloaded."""+ root = hub_cache if hub_cache is not None else _hub_cache()+ try:+ found = _find(model, root)+ except OSError:+ return None+ return found[1] if found else None+++def is_downloaded(model: AudioCppModel) -> bool:+ try:+ return cached_files(model) is not None+ except Exception: # noqa: BLE001 - a probe never fails its caller+ return False+++def missing_files(+ model: AudioCppModel, *, hub_cache: Optional[Path] = None+) -> list[tuple[str, int]]:+ """``(repo path, size)`` of the variant's files the best snapshot still lacks."""+ if model.local_path:+ return []+ root = hub_cache if hub_cache is not None else _hub_cache()+ snapshots = snapshot_dirs(model.repo_id, root)+ first: Optional[list[tuple[str, int]]] = None+ for snapshot in snapshots:+ missing = [+ (f.path, f.size)+ for f in model.variant.files+ if not _file_complete(snapshot / f.path, f.size)+ ]+ if not missing:+ return []+ if first is None:+ first = missing+ # Measured against refs/main (listed first), where the unpinned downloads land: the fewest+ # missing in an older snapshot would leave both incomplete.+ return first if first is not None else [(f.path, f.size) for f in model.variant.files]+++def _relative(model: AudioCppModel, repo_path: str) -> Path:+ """A variant file's path below the model's own folder: the umbrella folder prefix dropped."""+ path = repo_path.replace("\\", "/")+ prefix = f"{model.folder}/" if model.folder else ""+ if prefix and path.startswith(prefix):+ path = path[len(prefix) :]+ parts = path.split("/")+ # Repo file names are untrusted: "embeddings/..\\..\\x" would land outside the farm.+ if any(p in ("", ".", "..") or ":" in p for p in parts):+ from core.inference.audio_cpp_server import AudioCppUnavailableError+ raise AudioCppUnavailableError(f"Refusing the model file path {repo_path!r}.")+ return Path(*parts)+++def _served_path(model: AudioCppModel, farm: Path) -> Path:+ return farm if model.is_package else farm / _relative(model, model.variant.primary)+++def materialize(model: AudioCppModel, *, hub_cache: Optional[Path] = None) -> str:+ """Path of the model for the server config: its GGUF under its real name, or a package's directory.++ Raises ``FileNotFoundError`` when the variant is not downloaded.+ """+ root = hub_cache if hub_cache is not None else _hub_cache()+ found = _find(model, root)+ if found is None:+ raise FileNotFoundError(f"{model.display_name} ({model.variant.key}) is not downloaded.")+ snapshot, files = found+ windows = sys.platform == "win32"+ if model.local_path:+ problem = served_path_problem(model, hub_cache = root)+ if problem:+ from core.inference.audio_cpp_server import AudioCppUnavailableError+ raise AudioCppUnavailableError(problem)+ return str(files[0])+ if not windows and not any(p.is_symlink() for p in files):+ base = snapshot / model.folder if model.folder else snapshot+ return str(base if model.is_package else snapshot / model.variant.primary)+ prune_link_farm(root)+ # One short directory per model and variant: the files keep their layout below the model's+ # folder (PocketTTS reads embeddings/ beside its GGUF, a package reads config/ and tokenizer/).+ farm_root = _link_farm_root(root)+ if _is_link(farm_root):+ _unlink_link(farm_root)+ farm = farm_root / model.key+ problem = served_path_problem(model, hub_cache = root)+ if problem:+ from core.inference.audio_cpp_server import AudioCppUnavailableError+ raise AudioCppUnavailableError(problem)+ for src, entry in zip(files, model.variant.files):+ rel = _relative(model, entry.path)+ dst = farm / rel+ blob = Path(os.path.realpath(src))+ # A link planted anywhere between the farm and the file would take the write elsewhere.+ for parent in [dst.parent, *dst.parent.parents]:+ if parent == farm_root.parent:+ break+ if _is_link(parent):+ _unlink_link(parent)+ if _already_materialized(dst, blob):+ continue+ try:+ dst.parent.mkdir(parents = True, exist_ok = True)+ except OSError as exc:+ from core.inference.audio_cpp_server import AudioCppUnavailableError+ raise AudioCppUnavailableError(+ f"The audio runtime needs a writable folder beside the Hugging Face cache ({farm_root}): "+ f"{exc}. Move the Hugging Face cache in Settings."+ ) from exc+ # Unique per call: two first loads of one model (dictation materializes outside its load lock)+ # must not unlink each other's staging file.+ tmp = dst.with_name(f"{dst.name}.unsloth-tmp-{os.getpid()}-{uuid.uuid4().hex[:8]}")+ try:+ try:+ os.link(blob, tmp)+ except OSError as exc:+ # Another volume or a filesystem without hardlinks: a copy is the only way to give the file its name.+ logger.info("audio.cpp: hardlink failed for %s (%s); copying", rel, exc)+ shutil.copyfile(blob, tmp)+ shutil.copystat(blob, tmp)+ os.replace(tmp, dst)+ finally:+ tmp.unlink(missing_ok = True)+ try:+ (farm / _SOURCE_MARKER).write_text(+ json.dumps(+ {+ "repo_id": model.repo_id,+ "files": [[f.path, f.size] for f in model.variant.files],+ }+ ),+ encoding = "utf-8",+ )+ except OSError as exc:+ logger.debug("audio.cpp: could not record the farm entry's source: %s", exc)+ return str(_served_path(model, farm))+++def served_path_problem(model: AudioCppModel, *, hub_cache: Optional[Path] = None) -> Optional[str]:+ """Why the Windows server could not open the path ``materialize`` would hand it, or None. Checked+ before any download or eviction, so a refused model costs nothing."""+ if sys.platform != "win32":+ return None+ if model.local_path:+ longest = Path(model.local_path)+ else:+ root = hub_cache if hub_cache is not None else _hub_cache()+ farm = _link_farm_root(root) / model.key+ longest = max(+ (farm / _relative(model, f.path) for f in model.variant.files),+ key = lambda p: len(str(p)),+ default = _served_path(model, farm),+ )+ if len(str(longest)) <= _WINDOWS_MAX_MODEL_PATH:+ return None+ return (+ f"The path the audio runtime would load {model.display_name} from is {len(str(longest))} "+ f"characters, over the {_WINDOWS_MAX_MODEL_PATH} Windows allows. Move the Hugging Face cache "+ "to a shorter path in Settings and download the model again."+ )+++def _link_farm_root(hub_cache: Path) -> Path:+ return hub_cache.parent / _LINK_FARM_DIRNAME+++def _already_materialized(dst: Path, blob: Path) -> bool:+ """The farm already holds ``blob`` at ``dst``: the same inode, or (a copy) the same size and mtime."""+ try:+ if not dst.is_file():+ return False+ if os.path.samefile(dst, blob):+ return True+ a, b = dst.stat(), blob.stat()+ return a.st_size == b.st_size and int(a.st_mtime) == int(b.st_mtime)+ except OSError:+ return False+++def _source_still_cached(model_dir: Path, hub_cache: Path) -> bool:+ """Whether the repo files a farm entry mirrors are all still in the cache."""+ try:+ source = json.loads((model_dir / _SOURCE_MARKER).read_text(encoding = "utf-8"))+ repo_id = str(source["repo_id"])+ files = [(str(path), int(size)) for path, size in source["files"]]+ except (OSError, ValueError, KeyError, TypeError):+ return False+ if not files:+ return False+ for snapshot in snapshot_dirs(repo_id, hub_cache):+ if all(_file_complete(snapshot / path, size) for path, size in files):+ return True+ return False+++def prune_link_farm(hub_cache: Optional[Path] = None) -> int:+ """Drop farm entries whose files are no longer downloaded, so a deleted model frees its disk.++ A hardlink keeps the blob's data alive after the cache deletes it, and a copy is a second+ full copy, so either way the farm entry must go once the cache no longer holds the model.+ Entries without a source record (an earlier layout) go too.+ Returns the number of files removed. Never raises.+ """+ removed = 0+ try:+ root = hub_cache if hub_cache is not None else _hub_cache()+ farm = _link_farm_root(root)+ if _is_link(farm) or not farm.is_dir():+ return 0+ for model_dir in list(farm.iterdir()):+ if _is_link(model_dir):+ # Never materialize's work: drop the link itself, never what it points at.+ _unlink_link(model_dir)+ continue+ if not model_dir.is_dir():+ continue+ keep = _source_still_cached(model_dir, root)+ if not keep and not (model_dir / _SOURCE_MARKER).exists():+ # A materialize in flight writes its marker last; only an old entry lacks one for long.+ try:+ if time.time() - model_dir.stat().st_mtime < 3600:+ keep = True+ except OSError:+ pass+ files, dirs = _walk_no_links(model_dir)+ for path in files:+ try:+ # Staging files of a live materialize are young; only a crashed one is old.+ stale_tmp = (+ ".unsloth-tmp" in path.name and time.time() - path.stat().st_mtime > 3600+ )+ if not keep or stale_tmp:+ path.unlink()+ removed += 1+ except OSError:+ continue+ if keep:+ # A kept model's empty folders may be ones a concurrent materialize has just made.+ continue+ for directory in sorted([*dirs, model_dir], key = lambda p: -len(p.parts)):+ try:+ directory.rmdir()+ except OSError:+ pass+ except Exception as exc: # noqa: BLE001 - housekeeping never fails a load or delete+ logger.debug("audio.cpp: link farm prune failed: %s", exc)+ return removed+++def _is_link(path: Path) -> bool:+ """A symlink or (Windows) junction: something the farm must never traverse or write through."""+ try:+ if path.is_symlink():+ return True+ attrs = getattr(os.lstat(path), "st_file_attributes", 0)+ return bool(attrs & getattr(os, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)) if attrs else False+ except OSError:+ return False+++def _unlink_link(path: Path) -> None:+ try:+ path.unlink()+ except OSError:+ try:+ os.rmdir(+ path+ ) # a Windows junction is removed as a directory, without touching its target+ except OSError:+ pass+++def _walk_no_links(top: Path) -> tuple[list[Path], list[Path]]:+ """Files and directories under ``top``, never descending into (or returning) a link."""+ files: list[Path] = []+ dirs: list[Path] = []+ pending = [top]+ while pending:+ try:+ entries = list(pending.pop().iterdir())+ except OSError:+ continue+ for entry in entries:+ if _is_link(entry):+ _unlink_link(entry)+ elif entry.is_dir():+ dirs.append(entry)+ pending.append(entry)+ elif entry.is_file():+ files.append(entry)+ return files, dirsdiff --git a/studio/backend/core/inference/audio_cpp_models.py b/studio/backend/core/inference/audio_cpp_models.pynew file mode 100644index 00000000000..8306cbbbeba--- /dev/null+++ b/studio/backend/core/inference/audio_cpp_models.py@@ -0,0 +1,1782 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Recognise a GGUF that audio.cpp runs, and work out what Studio needs to run it.++Every GGUF audio.cpp writes declares ``general.architecture = "audiocpp"`` and, in+most cases, names its loader in ``audiocpp.model_spec.family`` and embeds the full+model spec in ``audiocpp.model_spec.json``. The server has no auto-detection, so+Studio reads the family itself and hands it over together with a runtime task token.++A model is any Hub repo (or local file) holding such GGUFs. The ``audio-cpp/audio.cpp-gguf``+repo publishes many models side by side, one per top-level folder, so a model there is+named by three segments (``audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF``); three segments+cannot collide with a real ``owner/name`` repo id. Variants are the quants in that repo+or folder, like any llama.cpp GGUF repo. A few families (MiniMax Music 3, YuE2) are+packages of several GGUFs plus config files that load as one directory; their variants+are the component mixes the package defines.++Everything that needs the repo, the files, the family or the variant goes through+``resolve``; nothing else parses the id.+"""++from __future__ import annotations++import hashlib+import io+import json+import os+import re+import struct+import threading+import time+from dataclasses import dataclass, field+from pathlib import Path+from typing import Any, BinaryIO, Iterable, Optional, Sequence++from loggers import get_logger++logger = get_logger(__name__)++AUDIO_CPP_REPO = "audio-cpp/audio.cpp-gguf"+AUDIO_CPP_ARCHITECTURE = "audiocpp"+_UMBRELLA_PREFIX = AUDIO_CPP_REPO.lower() + "/"++# The audio_type Studio records for a model served by audio.cpp, per task.+AUDIO_CPP_TTS_AUDIO_TYPE = "audiocpp_tts"+AUDIO_CPP_MUSIC_AUDIO_TYPE = "audiocpp_music"+AUDIO_CPP_AUDIO_TYPES = frozenset((AUDIO_CPP_TTS_AUDIO_TYPE, AUDIO_CPP_MUSIC_AUDIO_TYPE))++# Studio task -> the Hub pipeline task its rows carry.+HUB_TASKS = {+ "tts": "text-to-speech",+ "music": "text-to-audio",+ "asr": "automatic-speech-recognition",+}++DEFAULT_AUDIO_CPP_STT_MODEL = f"{AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF"+++@dataclass(frozen = True)+class AudioCppPackageVariant:+ """One component mix of a package family: its files and the session options that pick them."""++ key: str+ files: tuple[str, ...]+ session_options: dict = field(default_factory = dict, hash = False, compare = False)+++@dataclass(frozen = True)+class AudioCppFamily:+ family: str+ # Studio task: ``tts`` (speech), ``music`` (generation) or ``asr``; empty when Studio has no feature for it.+ task: str+ # audiocpp_server task when it is not the Studio task's default (a voice-design package runs "vdes").+ server_task: Optional[str] = None+ # Phonemizes with eSpeak-ng, so it needs a bundle built with AUDIOCPP_STATIC_ESPEAK.+ needs_espeak: bool = False+ # Default request fields for speech (e.g. a built-in ``voice``). An ``options`` dict here is merged+ # under the request's own options.+ request_defaults: dict = field(default_factory = dict, hash = False, compare = False)+ # Values injected into the server config's model entry.+ model_options: dict = field(default_factory = dict, hash = False, compare = False)+ # Package families load a directory of several GGUFs; their variants are the package's mixes.+ package: tuple[AudioCppPackageVariant, ...] = ()+ # Request options Studio shows when neither the runtime nor the GGUF offers a current spec.+ options: tuple[dict, ...] = ()+ # Built-in speakers when the spec lists none (the published Qwen3-TTS GGUFs embed a legacy spec).+ voices: tuple[str, ...] = ()+ # Why Studio refuses this family, when it does.+ unsupported: Optional[str] = None++ @property+ def default_server_task(self) -> str:+ if self.server_task:+ return self.server_task+ return "gen" if self.task == "music" else self.task+++def _minimax_package(key: str, lm: str, rvq: str, flow: str) -> AudioCppPackageVariant:+ files = (+ "config.json",+ "config/language_model.json",+ "config/rvq_depth_decoder.json",+ "config/condition_encoder.json",+ "config/transformer.json",+ "config/vocoder.json",+ "tokenizer/tokenizer.json",+ "tokenizer/tokenizer_config.json",+ f"language_model_{lm}.gguf",+ f"rvq_depth_decoder_{rvq}.gguf",+ "condition_encoder.gguf",+ f"transformer_{flow}.gguf",+ "vocoder.gguf",+ )+ return AudioCppPackageVariant(+ key,+ files,+ {+ "minimax_music3.language_model_gguf": f"language_model_{lm}.gguf",+ "minimax_music3.rvq_depth_decoder_gguf": f"rvq_depth_decoder_{rvq}.gguf",+ "minimax_music3.flow_transformer_gguf": f"transformer_{flow}.gguf",+ },+ )+++def _yue2_package(key: str, quant: str) -> AudioCppPackageVariant:+ main = f"yue2-3b-{quant}.gguf"+ return AudioCppPackageVariant(+ key,+ (+ "sidecars/yue2-model-config.json",+ "sidecars/yue2-generation-config.json",+ "sidecars/yue2-qwen.tiktoken",+ "sidecars/yue2-vae-config.json",+ main,+ "yue2-vae-f16.gguf",+ ),+ {"yue2.model_gguf": main, "yue2.vae_gguf": "yue2-vae-f16.gguf"},+ )+++def _opt(name: str, type_: str, description: str, **kw) -> dict:+ return {"name": name, "type": type_, "description": description, **kw}+++_FAMILY_LIST: tuple[AudioCppFamily, ...] = (+ # Text to speech. Kokoro, KittenTTS, Piper and Inflect phonemize with eSpeak-ng, which the Unsloth+ # bundles link statically (GPL-3.0-or-later) with its data file beside the server.+ AudioCppFamily("kokoro_tts", "tts", needs_espeak = True),+ AudioCppFamily("kitten_tts", "tts", needs_espeak = True),+ AudioCppFamily("piper_tts", "tts", needs_espeak = True),+ AudioCppFamily("inflect_v2", "tts", needs_espeak = True),+ AudioCppFamily("pocket_tts", "tts", request_defaults = {"voice": "alba"}),+ AudioCppFamily("supertonic", "tts", request_defaults = {"voice": "F1"}),+ AudioCppFamily("qwen3_tts", "tts"),+ *(+ AudioCppFamily(name, "tts")+ for name in (+ "moss_tts_nano",+ "moss_tts_local",+ "moss_tts_v15",+ "moss_ttsd",+ "chatterbox",+ "chatterbox_turbo",+ "voxcpm1",+ "voxcpm2",+ "neutts",+ "magpie_tts",+ "miotts",+ "cosyvoice3",+ "fish_audio",+ "higgs_audio_tts",+ "index_tts2",+ "irodori_tts",+ "breeze_tts",+ "dots_tts",+ "dramabox",+ "fireredtts3",+ "firered_audio",+ "omnivoice",+ "confucius4_tts",+ "vibevoice",+ "vevo2",+ "echo_tts",+ "f5_tts",+ "glm_tts",+ "outetts",+ "sanotts",+ "soprano_tts",+ "zipvoice",+ "vieneu_v3_turbo",+ "audio8_tts",+ )+ ),+ # Voice design only: every voice is designed from the instruction.+ AudioCppFamily(+ "moss_voicegen",+ "tts",+ server_task = "vdes",+ request_defaults = {+ "options": {+ "instruct": "A warm, clear, natural adult voice speaking at a relaxed pace."+ }+ },+ ),+ # Music generation.+ *(+ AudioCppFamily(name, "music")+ for name in ("ace_step", "stable_audio", "heartmula", "midashenglm_gen", "controlfoley")+ ),+ AudioCppFamily(+ "minimax_music3",+ "music",+ package = (+ _minimax_package("Q4_0", "q4_0", "q8_0", "q4_0"),+ _minimax_package("Q8_0", "q8_0", "q8_0", "q8_0"),+ _minimax_package("BF16", "bf16", "bf16", "bf16"),+ ),+ # The runtime's current spec; the one embedded in the published GGUFs predates it.+ options = (+ _opt(+ "num_inference_steps",+ "int",+ "Flow matching Euler steps per chunk.",+ min = 1,+ default = 30,+ ),+ _opt(+ "guidance_scale",+ "float",+ "Flow transformer classifier-free guidance scale.",+ min = 0.0,+ default = 1.7,+ ),+ _opt(+ "ar_guidance_scale",+ "float",+ "Autoregressive semantic and depth CFG scale.",+ min = 0.0,+ default = 1.5,+ ),+ _opt(+ "top_k",+ "int",+ "Top-k sampling for semantic and residual code sampling.",+ min = 1,+ default = 50,+ ),+ ),+ ),+ AudioCppFamily(+ "yue2",+ "music",+ package = (+ _yue2_package("Q8_0", "q8_0"),+ _yue2_package("BF16", "bf16"),+ _yue2_package("Q4_0", "q4_0"),+ ),+ options = (+ _opt(+ "cot",+ "enum",+ "Symbolic planning route. off skips ABC generation; melody/full generate ABC before music tokens.",+ values = ["off", "melody", "full"],+ default = "full",+ ),+ _opt("num_inference_steps", "int", "NAR midpoint ODE steps.", min = 1, default = 8),+ _opt(+ "guidance_scale",+ "float",+ "Semantic classifier-free guidance scale.",+ min = 0.0,+ max = 20.0,+ ),+ _opt(+ "semantic_temperature",+ "float",+ "Semantic codec sampling temperature.",+ min = 0.0,+ max = 5.0,+ ),+ _opt(+ "semantic_top_p",+ "float",+ "Semantic codec nucleus sampling probability.",+ min = 0.0,+ max = 1.0,+ ),+ _opt("semantic_top_k", "int", "Semantic codec top-k sampling limit.", min = 1),+ ),+ ),+ # Speech to text.+ *(+ AudioCppFamily(name, "asr")+ for name in (+ "qwen3_asr",+ "parakeet_tdt",+ "canary_asr",+ "citrinet_asr",+ "cohere_asr",+ "higgs_audio_stt",+ "granite5asr",+ "kroko_asr",+ "moonshine_asr",+ "moss_transcribe_diarize",+ "nemotron_asr",+ "niagara_asr",+ "voxtral_realtime",+ "vibevoice_asr",+ "vibevoice_asr_streaming",+ "hviske_asr",+ "fun_asr_nano",+ "sense_asr",+ "confucius4_r2t2",+ "audio8_asr",+ )+ ),+ # Package families Studio does not lay out yet.+ *(+ AudioCppFamily(+ name,+ "",+ unsupported = "This model ships as a multi-file package Studio cannot load yet.",+ )+ for name in ("minimax_h3", "auk", "liveavatar", "vibeasr")+ ),+ # Tasks Studio has no page for.+ *(+ AudioCppFamily(name, "", unsupported = f"{what} models are not supported in Studio yet.")+ for names, what in (+ (("qwen3_forced_aligner", "mms_forced_aligner"), "Forced-alignment"),+ (("sortformer_diar", "sortformer_diar_v2", "nemotron_3_diar"), "Speaker diarization"),+ (("htdemucs", "bs_roformer", "mel_band_roformer"), "Source separation"),+ (("pulsevad", "silero_vad", "marblenet_vad"), "Voice activity detection"),+ (("muscriptor", "sheetsage2"), "Music transcription"),+ (("meanvc2", "rvc", "seed_vc", "miocodec"), "Voice conversion"),+ (("apollo", "audiosr", "universr", "personaplex"), "Speech-to-speech"),+ )+ for name in names+ ),+)++FAMILIES: dict[str, AudioCppFamily] = {f.family: f for f in _FAMILY_LIST}++# Spec task names that are not runtime task tokens.+_SPEC_TO_SERVER_TASK = {+ "music": "gen",+ "sfx": "gen",+ "edit": "gen",+ "clone": "clon",+ "design": "vdes",+ "speaker": "spk",+}+_SERVER_TO_STUDIO_TASK = {"tts": "tts", "gen": "music", "asr": "asr"}+_TASK_NAMES = {+ "align": "Forced-alignment",+ "diar": "Speaker diarization",+ "sep": "Source separation",+ "vad": "Voice activity detection",+ "midi": "Music transcription",+ "vc": "Voice conversion",+ "svc": "Voice conversion",+ "s2s": "Speech-to-speech",+ "spk": "Speaker embedding",+}+++def _family_from_spec_tasks(family: str, spec: Optional[dict]) -> AudioCppFamily:+ """Policy for a family Studio does not list, from the tasks its spec declares."""+ tasks = [str(t).lower() for t in (spec or {}).get("tasks") or [] if isinstance(t, str)]+ tokens = [_SPEC_TO_SERVER_TASK.get(t, t) for t in tasks]+ # Speech first, then music, then transcription: a model that speaks is most useful spoken.+ for token in ("tts", "vdes", "clon", "gen", "asr"):+ if token in tokens:+ if token == "clon":+ break+ studio = "tts" if token == "vdes" else _SERVER_TO_STUDIO_TASK[token]+ return AudioCppFamily(family, studio, server_task = token)+ if "clon" in tokens:+ return AudioCppFamily(+ family,+ "",+ unsupported = "This model only clones a reference voice, which Studio does not send yet.",+ )+ if tokens:+ what = _TASK_NAMES.get(tokens[0], tokens[0])+ return AudioCppFamily(+ family, "", unsupported = f"{what} models are not supported in Studio yet."+ )+ return AudioCppFamily(+ family,+ "",+ unsupported = f"Studio does not know what the model family '{family}' does.",+ )+++def family_policy(+ family: str,+ spec: Optional[dict] = None,+ names: Iterable[str] = (),+) -> AudioCppFamily:+ """What Studio does with ``family``: the table entry, else what its spec says it does.++ ``names`` (repo, folder and file names) pick the Qwen3-TTS package kind, which the family+ alone does not say: CustomVoice needs a speaker, VoiceDesign designs one, Base only clones.+ """+ policy = FAMILIES.get(family) or _family_from_spec_tasks(family, spec)+ if family == "qwen3_tts":+ text = " ".join(names).lower()+ if "voicedesign" in text or "voice-design" in text:+ return AudioCppFamily(+ family,+ "tts",+ server_task = "vdes",+ request_defaults = {+ "options": {+ "instruct": "A warm, clear, natural adult voice speaking at a relaxed pace."+ }+ },+ )+ if "customvoice" in text or "custom-voice" in text:+ # A speaker is mandatory: the package's spk_id table.+ return AudioCppFamily(+ family,+ "tts",+ request_defaults = {"voice": "vivian"},+ voices = (+ "vivian",+ "serena",+ "ryan",+ "aiden",+ "ono_anna",+ "sohee",+ "uncle_fu",+ "eric",+ "dylan",+ ),+ )+ if "base" in text:+ return AudioCppFamily(+ family,+ "",+ unsupported = "Qwen3-TTS Base only clones a reference voice, which Studio does not send yet.",+ )+ return policy+++# Legacy dictation keys and the sub-folder ids of earlier builds, mapped to the folder row and+# the variant they named. Saved settings keep working through these.+_LEGACY_KEYS: dict[str, tuple[str, Optional[str]]] = {+ "audiocpp-kokoro-82m": ("Kokoro-82M-GGUF", None),+ "audiocpp-kitten-tts-mini": ("KittenTTS-GGUF", None),+ "audiocpp-piper-en-us-lessac": ("Piper-TTS-GGUF", None),+ "audiocpp-inflect-micro-v2": ("Inflect-Micro-v2-GGUF", None),+ "audiocpp-pocket-tts-en": ("PocketTTS-GGUF", "english/Q8_0"),+ "audiocpp-moss-tts-nano": ("MOSS-TTS-Nano-100M-GGUF", None),+ "audiocpp-supertonic-3": ("Supertonic-3-GGUF", None),+ "audiocpp-chatterbox-turbo": ("Chatterbox-Turbo-GGUF", None),+ "audiocpp-voxcpm2": ("VoxCPM2-GGUF", None),+ "audiocpp-qwen3-tts-1.7b-customvoice": ("Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF", None),+ "audiocpp-qwen3-tts-1.7b-voicedesign": ("Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF", None),+ "audiocpp-ace-step-1.5-turbo": ("ACE-Step1.5-GGUF", "turbo/Q8_0"),+ "audiocpp-ace-step-1.5-base": ("ACE-Step1.5-GGUF", "base/Q8_0"),+ "audiocpp-stable-audio-3-small-music": ("Stable-Audio-3-Small-Music-GGUF", None),+ "audiocpp-qwen3-asr-0.6b": ("Qwen3-ASR-0.6B-GGUF", None),+ "audiocpp-qwen3-asr-1.7b": ("Qwen3-ASR-1.7B-GGUF", None),+ "audiocpp-parakeet-tdt-0.6b-v3": ("Parakeet-TDT-0.6B-v3-GGUF", None),+ "audiocpp-canary-180m-flash": ("Canary-180M-Flash-GGUF", None),+ "audiocpp-moonshine-tiny": ("Moonshine-Streaming-GGUF", "tiny/Q8_0"),+ "audiocpp-moonshine-small": ("Moonshine-Streaming-GGUF", "small/Q8_0"),+ "audiocpp-nemotron-3.5-asr-0.6b": ("Nemotron-3.5-ASR-Streaming-0.6B-GGUF", None),+}+_LEGACY_SUBFOLDER_VARIANTS = {+ "moonshine-streaming-gguf/tiny": "tiny/Q8_0",+ "moonshine-streaming-gguf/small": "small/Q8_0",+}+++@dataclass(frozen = True)+class AudioCppRef:+ """Where a Studio id points: a repo, a folder in it (umbrella rows), or a local GGUF."""++ id: str+ repo_id: Optional[str]+ folder: str = ""+ variant_hint: Optional[str] = None+ local_path: Optional[str] = None++ @property+ def display_name(self) -> str:+ if self.local_path:+ return Path(self.local_path).stem+ if self.folder:+ return self.folder+ return str(self.repo_id).split("/")[-1]+++_REPO_ID_RE = re.compile(r"^[A-Za-z0-9][\w.\-]*/[\w.\-]+$")+++def is_legacy_key(identifier: Optional[str]) -> bool:+ """A dictation key saved by earlier builds (``audiocpp-parakeet-tdt-0.6b-v3``). No I/O."""+ return bool(identifier) and str(identifier).strip() in _LEGACY_KEYS+++def legacy_keys() -> tuple[str, ...]:+ return tuple(_LEGACY_KEYS)+++def is_umbrella_id(identifier: Optional[str]) -> bool:+ """A folder row of the audio.cpp umbrella repo, or a legacy dictation key. No I/O."""+ if not identifier:+ return False+ text = str(identifier).strip()+ return text in _LEGACY_KEYS or text.lower().startswith(_UMBRELLA_PREFIX)+++def parse_identifier(identifier: Optional[str]) -> Optional[AudioCppRef]:+ """The ref ``identifier`` names, without any I/O; None when it cannot name an audio.cpp model."""+ if not identifier:+ return None+ text = str(identifier).strip().rstrip("/")+ if not text:+ return None+ legacy = _LEGACY_KEYS.get(text)+ if legacy is not None:+ folder, hint = legacy+ return AudioCppRef(f"{AUDIO_CPP_REPO}/{folder}", AUDIO_CPP_REPO, folder, hint)+ if text.lower().startswith(_UMBRELLA_PREFIX):+ rest = text[len(_UMBRELLA_PREFIX) :].replace("\\", "/").strip("/")+ parts = [p for p in rest.split("/") if p]+ if not parts or any(p in (".", "..") for p in parts):+ return None+ folder = parts[0]+ sub = "/".join(parts[1:])+ hint = None+ if sub:+ hint = _LEGACY_SUBFOLDER_VARIANTS.get(f"{folder}/{sub}".lower(), sub)+ return AudioCppRef(f"{AUDIO_CPP_REPO}/{folder}", AUDIO_CPP_REPO, folder, hint)+ if text.lower().endswith(".gguf"):+ path = Path(text).expanduser()+ try:+ if path.is_file():+ return AudioCppRef(str(path), None, local_path = str(path))+ except OSError:+ return None+ return None+ if _REPO_ID_RE.match(text):+ return AudioCppRef(text, text)+ return None+++def split_variant_ref(identifier: str) -> tuple[str, Optional[str]]:+ """``repo:Q8_0`` -> ``("repo", "Q8_0")``, ``row:tiny/Q8_0`` -> ``("row", "tiny/Q8_0")``; a bare id+ keeps no variant. Paths are left whole."""+ text = str(identifier or "").strip()+ if ":" in text and not re.match(r"^[A-Za-z]:[\\/]", text):+ base, _, variant = text.rpartition(":")+ if base and variant and not variant.startswith(("/", "\\")):+ return base, variant+ return text, None+++_FIXED_SIZES = {0: 1, 1: 1, 2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 10: 8, 11: 8, 12: 8}+_WANTED_KEYS = (+ "general.architecture",+ "audiocpp.model_spec.family",+ "audiocpp.model_spec.json",+)+++@dataclass(frozen = True)+class AudioCppHeader:+ architecture: Optional[str]+ family: Optional[str]+ spec: Optional[dict] = field(default = None, hash = False, compare = False)+ # False when the read stopped before the header's end (a remote prefix): absent keys may lie beyond it.+ complete: bool = True++ @property+ def is_audio_cpp(self) -> bool:+ return (self.architecture or "").strip().lower() == AUDIO_CPP_ARCHITECTURE+++def parse_header(stream: BinaryIO) -> Optional[AudioCppHeader]:+ """The audio.cpp keys of a GGUF header, reading only up to the last one wanted.++ Truncation-safe: a prefix that stops early answers with what it read and ``complete=False``.+ """+ try:+ head = stream.read(24)+ if len(head) < 24:+ return None+ magic, _version, _tensors, kv_count = struct.unpack("<IIQQ", head)+ if magic != 0x46554747 or kv_count > 1 << 20:+ return None+ found: dict[str, str] = {}+ for _ in range(kv_count):+ raw = stream.read(8)+ if len(raw) < 8:+ return _header(found, complete = False)+ (klen,) = struct.unpack("<Q", raw)+ if klen > 1 << 16:+ return _header(found, complete = False)+ key_bytes = stream.read(klen)+ type_bytes = stream.read(4)+ if len(key_bytes) < klen or len(type_bytes) < 4:+ return _header(found, complete = False)+ key = key_bytes.decode("utf-8", "replace")+ (vtype,) = struct.unpack("<I", type_bytes)+ if key in _WANTED_KEYS and vtype == 8:+ raw = stream.read(8)+ if len(raw) < 8:+ return _header(found, complete = False)+ (slen,) = struct.unpack("<Q", raw)+ if slen > 1 << 26:+ return _header(found, complete = False)+ value = stream.read(slen)+ if len(value) < slen:+ return _header(found, complete = False)+ found[key] = value.decode("utf-8", "replace")+ if all(k in found for k in _WANTED_KEYS):+ break+ continue+ if not _skip_value(stream, vtype):+ return _header(found, complete = False)+ return _header(found, complete = True)+ except (OSError, struct.error, ValueError):+ return None+++def _skip_value(stream: BinaryIO, vtype: int) -> bool:+ if vtype == 8:+ raw = stream.read(8)+ if len(raw) < 8:+ return False+ stream.seek(struct.unpack("<Q", raw)[0], 1)+ return True+ if vtype == 9:+ raw = stream.read(12)+ if len(raw) < 12:+ return False+ atype, alen = struct.unpack("<IQ", raw)+ if atype == 8:+ for _ in range(alen):+ raw = stream.read(8)+ if len(raw) < 8:+ return False+ stream.seek(struct.unpack("<Q", raw)[0], 1)+ return True+ size = _FIXED_SIZES.get(atype)+ if size is None:+ return False+ stream.seek(size * alen, 1)+ return True+ size = _FIXED_SIZES.get(vtype)+ if size is None:+ return False+ stream.seek(size, 1)+ return True+++def _header(found: dict[str, str], *, complete: bool) -> AudioCppHeader:+ spec = None+ raw = found.get("audiocpp.model_spec.json")+ if raw:+ try:+ parsed = json.loads(raw)+ spec = parsed if isinstance(parsed, dict) else None+ except ValueError:+ spec = None+ family = found.get("audiocpp.model_spec.family") or (spec or {}).get("family")+ return AudioCppHeader(+ architecture = found.get("general.architecture"),+ family = str(family).strip() if family else None,+ spec = spec,+ complete = complete,+ )+++_header_cache: dict[tuple, Optional[AudioCppHeader]] = {}+_header_lock = threading.Lock()+_HEADER_CACHE_MAX = 512+++def _cached_header(key: tuple, compute) -> Optional[AudioCppHeader]:+ with _header_lock:+ if key in _header_cache:+ return _header_cache[key]+ value = compute()+ with _header_lock:+ while len(_header_cache) >= _HEADER_CACHE_MAX:+ _header_cache.pop(next(iter(_header_cache)))+ _header_cache[key] = value+ return value+++def read_local_header(path: str | Path) -> Optional[AudioCppHeader]:+ """The audio.cpp header keys of a local GGUF, memoized on its size and mtime. Never raises."""+ try:+ stat = os.stat(path)+ except OSError:+ return None+ key = ("local", os.path.realpath(path), stat.st_size, int(stat.st_mtime))++ def compute():+ try:+ with open(path, "rb") as f:+ return parse_header(f)+ except OSError:+ return None++ return _cached_header(key, compute)+++def read_remote_header(+ repo_id: str,+ filename: str,+ hf_token: Optional[str] = None,+ *,+ size: Optional[int] = None,+) -> Optional[AudioCppHeader]:+ """The audio.cpp header keys of a Hub GGUF from a ranged read of its first bytes.++ The architecture is the first key, so 64 KiB answers "is this audio.cpp". Some writers put the+ spec after the embedded sidecar files, so an audio.cpp file whose prefix held no family is read+ again further in.+ """++ def compute():+ from core.inference.diffusion_compat import _read_gguf_header++ header = None+ for max_bytes in (1 << 16, 1 << 22):+ if size is not None and 0 < size <= max_bytes // 2 and header is not None:+ break+ data = _read_gguf_header(+ repo_id, filename, hf_token, max_bytes = max_bytes, timeout_seconds = 10+ )+ if not data:+ return header+ header = parse_header(io.BytesIO(data))+ if header is None or not header.is_audio_cpp or header.family or header.complete:+ return header+ return header++ # Per credential, as resolve() is: a gated file an anonymous probe could not read is not missing.+ token_id = hashlib.sha256(hf_token.encode()).hexdigest()[:16] if hf_token else ""+ return _cached_header(("remote", repo_id.lower(), filename, size, token_id), compute)+++@dataclass(frozen = True)+class RepoFile:+ path: str+ size: int = 0+++def hub_offline() -> bool:+ return os.environ.get("HF_HUB_OFFLINE", "").strip().lower() in ("1", "true", "yes", "on")+++def _hub_cache() -> Path:+ from utils.hf_cache_settings import active_hf_hub_cache+ return Path(active_hf_hub_cache())+++def snapshot_dirs(repo_id: str, hub_cache: Optional[Path] = None) -> list[Path]:+ """Cached snapshots of ``repo_id``: ``refs/main`` first, then newest."""+ root = hub_cache if hub_cache is not None else _hub_cache()+ repo_dir = root / ("models--" + repo_id.replace("/", "--"))+ try:+ candidates = [p for p in (repo_dir / "snapshots").iterdir() if p.is_dir()]+ except OSError:+ if hub_cache is not None:+ return []+ # A cached repo whose casing differs from the request.+ try:+ wanted = repo_dir.name.lower()+ match = next((p for p in root.iterdir() if p.name.lower() == wanted), None)+ except OSError:+ match = None+ if match is None:+ return []+ return snapshot_dirs(match.name[len("models--") :].replace("--", "/"), root)+ try:+ main_sha = (repo_dir / "refs" / "main").read_text(encoding = "utf-8").strip()+ except OSError:+ main_sha = ""++ def order(p: Path) -> tuple[int, float]:+ try:+ mtime = p.stat().st_mtime+ except OSError:+ mtime = 0.0+ return (0 if p.name == main_sha else 1, -mtime)++ return sorted(candidates, key = order)+++def _cached_listing(repo_id: str, folder: str) -> list[RepoFile]:+ """Every file under ``folder`` in any cached snapshot, from disk."""+ seen: dict[str, RepoFile] = {}+ for snapshot in snapshot_dirs(repo_id):+ base = snapshot / folder if folder else snapshot+ if not base.is_dir():+ continue+ for dirpath, _dirs, files in os.walk(base):+ for name in files:+ full = Path(dirpath) / name+ rel = full.relative_to(snapshot).as_posix()+ if rel in seen:+ continue+ try:+ size = full.stat().st_size+ except OSError:+ continue+ seen[rel] = RepoFile(rel, size)+ return sorted(seen.values(), key = lambda f: f.path)+++def _hub_listing(repo_id: str, folder: str, hf_token: Optional[str]) -> list[RepoFile]:+ from huggingface_hub import HfApi++ api = HfApi(token = hf_token or None)+ entries = api.list_repo_tree(+ repo_id, path_in_repo = folder or None, recursive = True, repo_type = "model"+ )+ out = []+ for entry in entries:+ size = getattr(entry, "size", None)+ if size is None: # a folder+ continue+ out.append(RepoFile(str(entry.path), int(size or 0)))+ return sorted(out, key = lambda f: f.path)+++_listing_cache: dict[tuple, tuple[float, list[RepoFile], bool]] = {}+_listing_lock = threading.Lock()+_LISTING_TTL_SECONDS = 300.0+++def list_files(+ repo_id: str,+ folder: str = "",+ hf_token: Optional[str] = None,+ *,+ network: bool = True,+) -> tuple[list[RepoFile], bool]:+ """``(files, from_hub)`` under ``folder``: the Hub listing, else the cached copy."""+ from hub.utils.hf_tokens import normalize_token++ token = normalize_token(hf_token) if hf_token is not False else None+ use_hub = network and not hub_offline()+ key = (repo_id.lower(), folder.lower(), hashlib.sha1(str(token).encode()).hexdigest()[:8])+ if use_hub:+ with _listing_lock:+ hit = _listing_cache.get(key)+ if hit is not None and time.monotonic() - hit[0] < _LISTING_TTL_SECONDS:+ return list(hit[1]), hit[2]+ try:+ files = _hub_listing(repo_id, folder, token)+ with _listing_lock:+ _listing_cache[key] = (time.monotonic(), files, True)+ return list(files), True+ except Exception as exc: # noqa: BLE001 - offline, refused or gone: the cache may still hold it+ logger.debug("audio.cpp: Hub listing of %s/%s failed: %s", repo_id, folder, exc)+ return _cached_listing(repo_id, folder), False+++_QUANT_RE = re.compile(+ r"(?:^|[-_.])((?:i?q\d(?:_[a-z0-9]+)*)|bf16|f16|f32|fp16|fp32|orig)(?=$|[-_.])", re.IGNORECASE+)+_QUANT_PREFERENCE = ("Q8_0", "F16", "BF16", "ORIG", "Q6_K", "Q5_K_M", "Q4_K_M", "Q4_0", "F32")+_PREFERRED_SCOPES = ("turbo", "english", "tiny")+_SKIP_FILE_RE = re.compile(+ r"(^|/)(readme[^/]*|license[^/]*|\.gitattributes|[^/]*\.(md|mp4|mp3|wav|png|jpe?g|gif))$", re.I+)+++def _is_quant(word: str) -> bool:+ """Whether ``word`` is a quant label (``Q8_0``, ``BF16``, ``orig``) rather than a name."""+ return bool(_QUANT_RE.fullmatch(f"-{word}"))+++def quant_label(filename: str) -> str:+ """``kokoro-82m-q8_0.gguf`` -> ``Q8_0``; the stem's last word when no quant is named."""+ stem = Path(filename).name+ if stem.lower().endswith(".gguf"):+ stem = stem[: -len(".gguf")]+ matches = list(_QUANT_RE.finditer(stem))+ if matches:+ token = matches[-1].group(1)+ # "orig" (unquantized as published) is a word, not a quant token.+ return token.lower() if token.lower() == "orig" else token.upper()+ return re.split(r"[-_.]", stem)[-1].upper() or stem.upper()+++@dataclass(frozen = True)+class AudioCppVariant:+ key: str+ files: tuple[RepoFile, ...]+ # Repo path the server opens; empty for a package, which loads as a directory.+ primary: str+ session_options: dict = field(default_factory = dict, hash = False, compare = False)+ label: Optional[str] = None++ @property+ def size_bytes(self) -> int:+ return sum(f.size for f in self.files)++ @property+ def main_file(self) -> str:+ """The GGUF that stands for this variant in listings."""+ if self.primary:+ return self.primary+ ggufs = [f for f in self.files if f.path.lower().endswith(".gguf")]+ return max(ggufs, key = lambda f: f.size).path if ggufs else self.files[0].path+++def _single_file_variants(files: Sequence[RepoFile], folder: str) -> list[AudioCppVariant]:+ prefix = f"{folder}/" if folder else ""+ ggufs = [+ f+ for f in files+ if f.path.lower().endswith(".gguf")+ and "mmproj" not in f.path.lower()+ and "imatrix" not in f.path.lower()+ ]+ rows = []+ for gguf in ggufs:+ rel = gguf.path[len(prefix) :] if gguf.path.startswith(prefix) else gguf.path+ sub = rel.rpartition("/")[0]+ rows.append((gguf, sub, quant_label(rel)))+ groups: dict[str, list[str]] = {}+ for gguf, sub, quant in rows:+ k = f"{sub}/{quant}" if sub else quant+ groups.setdefault(k.lower(), []).append(Path(gguf.path).name[: -len(".gguf")])+ variants = []+ for gguf, sub, quant in rows:+ key = f"{sub}/{quant}" if sub else quant+ label = None+ stems = groups[key.lower()]+ if len(stems) > 1:+ # Several files at one quant in one place (Moonshine tiny, small and medium): the words their+ # names do not share tell them apart, and name the row like a sub-folder would.+ scope = _distinct_part(Path(gguf.path).name[: -len(".gguf")], stems)+ key = f"{sub}/{scope}/{quant}" if sub else f"{scope}/{quant}"+ label = f"{quant} · {scope}"+ elif sub:+ label = f"{quant} · {sub}"+ gguf_dir = gguf.path.rpartition("/")[0]+ # Voices and other extras audio.cpp reads beside the GGUF (PocketTTS's embeddings/*.safetensors).+ extras = tuple(+ f+ for f in files+ if f.path.startswith(f"{gguf_dir}/embeddings/" if gguf_dir else "embeddings/")+ )+ variants.append(AudioCppVariant(key, (gguf, *extras), gguf.path, label = label))+ return variants+++def _distinct_part(stem: str, stems: Sequence[str]) -> str:+ """The words of ``stem`` its siblings do not share: ``moonshine-streaming-tiny-q8_0`` among+ ``...-small-q8_0`` gives ``tiny``. The whole stem when nothing is left."""+ split = [re.split(r"[-_.]", s) for s in stems]+ words = re.split(r"[-_.]", stem)+ head = 0+ while all(len(w) > head for w in split) and len({w[head].lower() for w in split}) == 1:+ head += 1+ tail = 0+ while (+ all(len(w) > head + tail for w in split) and len({w[-1 - tail].lower() for w in split}) == 1+ ):+ tail += 1+ middle = words[head : len(words) - tail]+ return "-".join(middle) or stem+++def _package_variants(+ policy: AudioCppFamily, files: Sequence[RepoFile], folder: str+) -> list[AudioCppVariant]:+ prefix = f"{folder}/" if folder else ""+ by_path = {f.path: f for f in files}+ variants = []+ for package in policy.package:+ found = [by_path.get(prefix + rel) for rel in package.files]+ if any(f is None for f in found):+ continue+ variants.append(+ AudioCppVariant(+ package.key, tuple(found), "", session_options = dict(package.session_options)+ )+ )+ return variants+++def _variant_rank(variant: AudioCppVariant) -> tuple:+ sub = variant.key.rpartition("/")[0].lower()+ scope_rank = (+ 0 if not sub else (1 + _PREFERRED_SCOPES.index(sub) if sub in _PREFERRED_SCOPES else 10)+ )+ quant = quant_label(variant.main_file)+ quant_rank = (+ _QUANT_PREFERENCE.index(quant) if quant in _QUANT_PREFERENCE else len(_QUANT_PREFERENCE)+ )+ stem = Path(variant.main_file).name.lower()+ stem_rank = min(+ (i for i, word in enumerate(_PREFERRED_SCOPES) if word in stem),+ default = len(_PREFERRED_SCOPES),+ )+ return (scope_rank, stem_rank, quant_rank, variant.key.lower())+++def match_variant(+ variants: Sequence[AudioCppVariant], wanted: Optional[str]+) -> Optional[AudioCppVariant]:+ """The variant ``wanted`` names: its key, its file, or a quant that picks one row.++ A bare quant shared by several rows (ACE-Step ``turbo/Q8_0`` and ``base/Q8_0``) picks the default+ ordering's first, which is what the folder row loads by default.+ """+ text = (wanted or "").strip().replace("\\", "/")+ if not text:+ return None+ low = text.lower()+ for variant in variants:+ if variant.key.lower() == low:+ return variant+ for variant in variants:+ main = variant.main_file.lower()+ if main == low or main.rsplit("/", 1)[-1] in (low, f"{low}.gguf"):+ return variant+ quant = low.rsplit("/", 1)[-1]+ matches = [+ v+ for v in variants+ if quant_label(v.main_file).lower() == quant+ and ("/" not in low or v.key.lower().endswith(low))+ ]+ if matches:+ return sorted(matches, key = _variant_rank)[0]+ # A sub-folder alone (legacy ``.../PocketTTS-GGUF/english``).+ scoped = [v for v in variants if v.key.lower().startswith(low + "/")]+ if scoped:+ return sorted(scoped, key = _variant_rank)[0]+ return _match_by_words(variants, low)+++def _match_by_words(variants: Sequence[AudioCppVariant], low: str) -> Optional[AudioCppVariant]:+ """A key named by the words of its file (``tiny/Q8_0`` or ``tiny``), whatever the listing keyed it.++ Which rows need a name beyond their quant depends on the listing: with only Moonshine tiny in+ the cache it is simply ``Q8_0``, while the Hub listing (and /gguf-variants) calls it+ ``tiny/Q8_0``. Matching the scope words against the file keeps both spellings loading it.+ """+ parts = [part for part in low.split("/") if part]+ if not parts:+ return None+ quant = parts[-1] if _is_quant(parts[-1]) else None+ scopes = parts[:-1] if quant else parts+ if not scopes:+ return None+ matches = [+ v+ for v in variants+ if all(scope in re.split(r"[-_./]", v.main_file.lower()) for scope in scopes)+ and (quant is None or quant_label(v.main_file).lower() == quant)+ ]+ return sorted(matches, key = _variant_rank)[0] if matches else None+++_STUDIO_DRIVEN_OPTIONS = frozenset(+ {+ "input",+ "text",+ "language",+ "seed",+ "instruct",+ "instruction",+ "instructions",+ "reference_text",+ "voice_ref",+ "phonemes",+ "return_timestamps",+ "stop_after",+ "export_semantic",+ "abc",+ # A JSON array of codec indices: a debugging hook, not a setting.+ "semantic_prefix",+ }+)+# The music form fills these from its lyrics, description and duration fields.+_MUSIC_DRIVEN_OPTIONS = frozenset(+ {"lyrics", "style", "caption", "prompt", "tags", "duration", "duration_sec", "duration_seconds"}+)+_RENDERABLE_TYPES = frozenset({"bool", "int", "float", "string", "enum"})+_MAX_STRING_OPTION = 4000+++def runtime_spec(family: str) -> Optional[dict]:+ """``model_specs/<family>.json`` of the installed runtime, the spec the binary was built with."""+ if not family or not re.fullmatch(r"[a-z0-9_]+", family):+ return None+ try:+ from core.inference.audio_cpp_server import find_audio_cpp_server_binary+ binary = find_audio_cpp_server_binary()+ except Exception: # noqa: BLE001 - no runtime, no runtime spec+ return None+ if not binary:+ return None+ for parent in list(Path(binary).resolve().parents)[:3]:+ path = parent / "model_specs" / f"{family}.json"+ try:+ with open(path, "r", encoding = "utf-8") as f:+ data = json.load(f)+ return data if isinstance(data, dict) else None+ except (OSError, ValueError):+ continue+ return None+++def _clean_option(raw: Any) -> Optional[dict]:+ if not isinstance(raw, dict):+ return None+ name = str(raw.get("name") or "").strip()+ kind = str(raw.get("type") or "").strip().lower()+ if not name or "." in name or kind not in _RENDERABLE_TYPES:+ return None+ if name in _STUDIO_DRIVEN_OPTIONS or name.endswith(("_file", "_path", "_dir")):+ return None+ option: dict[str, Any] = {+ "name": name,+ "type": kind,+ "description": str(raw.get("description") or ""),+ "required": bool(raw.get("required", False)),+ "default": raw.get("default"),+ "min": raw.get("min"),+ "max": raw.get("max"),+ "values": None,+ }+ if kind == "enum":+ values = raw.get("values")+ if not isinstance(values, list) or not values:+ return None+ option["values"] = [str(v) for v in values]+ for bound in ("min", "max"):+ if not isinstance(option[bound], (int, float)) or isinstance(option[bound], bool):+ option[bound] = None+ if kind in ("int", "float") and (+ isinstance(option["default"], bool) or not isinstance(option["default"], (int, float))+ ):+ option["default"] = None+ if kind == "bool" and not isinstance(option["default"], bool):+ option["default"] = None+ if kind in ("string", "enum") and option["default"] is not None:+ option["default"] = str(option["default"])+ return option+++def option_schema(+ policy: AudioCppFamily, spec: Optional[dict], embedded: Optional[dict]+) -> tuple[dict, ...]:+ """The request options Studio offers for this model, in the spec's order.++ A family with a Studio-side list (MiniMax Music 3, YuE2) shows that list: their specs carry+ dozens of planner and debugging knobs, and the published GGUFs embed a stale copy. Everyone+ else gets the runtime's spec, else the one embedded in the GGUF.+ """+ if policy.options:+ source = {"options": {"request": list(policy.options)}}+ else:+ source = spec+ if source is None or not ((source.get("options") or {}).get("request")):+ source = embedded+ raw = ((source or {}).get("options") or {}).get("request") or []+ driven = _MUSIC_DRIVEN_OPTIONS if policy.task == "music" else frozenset()+ out = []+ names = set()+ for item in raw:+ option = _clean_option(item)+ if option is None or option["name"] in driven or option["name"] in names:+ continue+ if option["name"] == "voice":+ continue+ names.add(option["name"])+ out.append(option)+ if policy.task == "tts" and policy.default_server_task != "vdes":+ ui = (source or {}).get("ui") or (embedded or {}).get("ui") or {}+ voices = (ui.get("builtin_voices") if isinstance(ui, dict) else None) or list(policy.voices)+ if isinstance(voices, list) and voices and all(isinstance(v, str) for v in voices):+ default = policy.request_defaults.get("voice") or ui.get("default_voice")+ out.insert(+ 0,+ {+ "name": "voice",+ "type": "enum",+ "description": "Built-in speaker.",+ "required": False,+ "default": str(default) if default in voices else None,+ "min": None,+ "max": None,+ "values": list(voices),+ },+ )+ return tuple(out)+++def validate_options(schema: Sequence[dict], values: Optional[dict]) -> dict:+ """``values`` checked against ``schema``: unknown names and values of the wrong kind are dropped,+ numbers are clamped to their bounds."""+ if not isinstance(values, dict):+ return {}+ by_name = {o["name"]: o for o in schema}+ out: dict[str, Any] = {}+ for name, value in values.items():+ option = by_name.get(str(name))+ if option is None or value is None:+ continue+ kind = option["type"]+ try:+ if kind == "bool":+ if isinstance(value, str):+ if value.strip().lower() not in ("true", "false", "1", "0"):+ continue+ value = value.strip().lower() in ("true", "1")+ elif not isinstance(value, (bool, int)):+ continue+ out[name] = bool(value)+ elif kind in ("int", "float"):+ if isinstance(value, bool):+ continue+ number = float(value)+ if number != number or number in (float("inf"), float("-inf")):+ continue+ if option.get("min") is not None:+ number = max(float(option["min"]), number)+ if option.get("max") is not None:+ number = min(float(option["max"]), number)+ out[name] = int(round(number)) if kind == "int" else number+ elif kind == "enum":+ if str(value) in (option.get("values") or []):+ out[name] = str(value)+ elif kind == "string":+ text = str(value)+ if text.strip():+ out[name] = text[:_MAX_STRING_OPTION]+ except (TypeError, ValueError):+ continue+ return out+++@dataclass(frozen = True)+class AudioCppModel:+ """One loadable audio.cpp model: a repo (or folder, or local file) at one variant."""++ id: str+ repo_id: Optional[str]+ folder: str+ display_name: str+ family: str+ task: str+ server_task: str+ variant: AudioCppVariant+ variants: tuple[AudioCppVariant, ...]+ default_variant: str+ needs_espeak: bool = False+ request_defaults: dict = field(default_factory = dict, hash = False, compare = False)+ model_options: dict = field(default_factory = dict, hash = False, compare = False)+ options: tuple[dict, ...] = field(default = (), hash = False, compare = False)+ unsupported: Optional[str] = None+ local_path: Optional[str] = None+ tags: tuple[str, ...] = ()++ @property+ def is_package(self) -> bool:+ return not self.variant.primary++ @property+ def files(self) -> tuple[str, ...]:+ return tuple(f.path for f in self.variant.files)++ @property+ def gguf_file(self) -> str:+ return self.variant.main_file++ @property+ def size_bytes(self) -> int:+ return self.variant.size_bytes++ @property+ def audio_type(self) -> Optional[str]:+ if self.task == "tts":+ return AUDIO_CPP_TTS_AUDIO_TYPE+ if self.task == "music":+ return AUDIO_CPP_MUSIC_AUDIO_TYPE+ return None++ @property+ def hub_task(self) -> Optional[str]:+ return HUB_TASKS.get(self.task)++ @property+ def key(self) -> str:+ """A short name, unique per model and variant, for the link farm."""+ stem = re.sub(r"[^a-z0-9]+", "-", self.display_name.lower()).strip("-")[:24] or "model"+ digest = hashlib.sha1(f"{self.id.lower()}@{self.variant.key.lower()}".encode()).hexdigest()+ return f"{stem}-{digest[:8]}"++ @property+ def canonical_id(self) -> str:+ """``id:variant``: what dictation records, so a reload picks the same files."""+ return f"{self.id}:{self.variant.key}"++ def with_variant(self, variant: AudioCppVariant) -> "AudioCppModel":+ from dataclasses import replace++ model_options = dict(self.model_options)+ if variant.session_options:+ model_options["session_options"] = {+ **dict(model_options.get("session_options") or {}),+ **variant.session_options,+ }+ return replace(self, variant = variant, model_options = model_options)+++class AudioCppModelError(ValueError):+ """The id names an audio.cpp model Studio cannot run (task, package or variant)."""+++def _names_for(ref: AudioCppRef, files: Sequence[RepoFile]) -> tuple[str, ...]:+ return (+ ref.id,+ ref.folder,+ *(Path(f.path).name for f in files if f.path.lower().endswith(".gguf")),+ )+++_TAG_FAMILY_RE = re.compile(r"^[a-z0-9_]+$")+++def family_from_names(names: Iterable[str]) -> Optional[str]:+ text = " ".join(names).lower().replace(".", "")+ for family in sorted(FAMILIES, key = len, reverse = True):+ pattern = re.escape(family).replace(r"\_", "[-_]?")+ if re.search(pattern, text):+ return family+ hints = (+ (r"minimax[-_]?music[-_]?3", "minimax_music3"),+ (r"yue[-_]?2", "yue2"),+ (r"moonshine", "moonshine_asr"),+ (r"qwen3[-_]?asr", "qwen3_asr"),+ (r"qwen3[-_]?tts", "qwen3_tts"),+ (r"parakeet", "parakeet_tdt"),+ (r"canary", "canary_asr"),+ (r"nemotron.*asr", "nemotron_asr"),+ (r"pocket[-_]?tts", "pocket_tts"),+ (r"kokoro", "kokoro_tts"),+ (r"kitten", "kitten_tts"),+ (r"piper", "piper_tts"),+ (r"inflect", "inflect_v2"),+ (r"ace[-_]?step", "ace_step"),+ (r"stable[-_]?audio", "stable_audio"),+ (r"voxtral", "voxtral_realtime"),+ )+ for pattern, family in hints:+ if re.search(pattern, text):+ return family+ return None+++def _probe_header(+ ref: AudioCppRef, candidates: Sequence[RepoFile], hf_token: Optional[str], network: bool+) -> Optional[AudioCppHeader]:+ """The first header among ``candidates`` that names a family, else the first one read."""+ first = None+ local_first: list[tuple[RepoFile, Optional[Path]]] = []+ for f in candidates:+ local = None+ if ref.local_path:+ local = Path(ref.local_path)+ elif ref.repo_id:+ for snapshot in snapshot_dirs(ref.repo_id):+ path = snapshot / f.path+ if path.is_file():+ local = path+ break+ local_first.append((f, local))+ local_first.sort(key = lambda item: item[1] is None)+ for f, local in local_first[:4]:+ header = None+ if local is not None:+ header = read_local_header(local)+ elif network and not hub_offline() and ref.repo_id:+ header = read_remote_header(ref.repo_id, f.path, hf_token, size = f.size or None)+ if header is None:+ continue+ if not header.is_audio_cpp:+ return header+ if header.family:+ return header+ first = first or header+ return first+++_resolve_cache: dict[tuple, tuple[float, Optional["AudioCppModel"]]] = {}+_resolve_lock = threading.Lock()+_RESOLVE_TTL_SECONDS = 300.0+_known_audio_cpp_ids: set[str] = set()+++def looks_like_audio_cpp(identifier: Optional[str]) -> bool:+ """An umbrella row, a legacy key, or an id this process already resolved as audio.cpp. No I/O."""+ if is_umbrella_id(identifier):+ return True+ base, _variant = split_variant_ref(str(identifier or ""))+ return base.lower() in _known_audio_cpp_ids+++def resolve(+ identifier: Optional[str],+ variant: Optional[str] = None,+ hf_token: Optional[str] = None,+ *,+ network: bool = True,+ tags: Sequence[str] = (),+ gguf_hint: Optional[str] = None,+) -> Optional[AudioCppModel]:+ """The audio.cpp model ``identifier`` names at ``variant`` (default when None), else None.++ None means "not an audio.cpp model". A model Studio cannot run (unsupported task, missing+ variant) still resolves, with ``unsupported`` set, so callers can refuse it clearly.+ ``network=False`` answers from the HF cache only. ``gguf_hint`` names a GGUF the caller+ already found in the repo: its header alone rules out an ordinary llama.cpp repo, before+ any listing.+ """+ if identifier is None:+ return None+ base, ref_variant = split_variant_ref(str(identifier))+ ref = parse_identifier(base)+ if ref is None:+ return None+ wanted = variant or ref_variant or ref.variant_hint+ # Per credential: a gated repo one caller cannot list must not read as missing for another.+ token_id = hashlib.sha256(hf_token.encode()).hexdigest()[:16] if hf_token else ""+ key = (+ ref.id.lower(),+ (wanted or "").lower(),+ bool(network),+ token_id,+ tuple(tags),+ gguf_hint or "",+ )+ with _resolve_lock:+ hit = _resolve_cache.get(key)+ if hit is not None and time.monotonic() - hit[0] < (_RESOLVE_TTL_SECONDS if network else 20.0):+ return hit[1]+ if gguf_hint and ref.repo_id and not is_umbrella_id(ref.id):+ header = _probe_header(ref, [RepoFile(gguf_hint)], hf_token, network)+ if header is not None and not header.is_audio_cpp:+ with _resolve_lock:+ _resolve_cache[key] = (time.monotonic(), None)+ return None+ model = _resolve_uncached(ref, wanted, hf_token, network, tuple(tags))+ with _resolve_lock:+ if len(_resolve_cache) > 256:+ _resolve_cache.clear()+ _resolve_cache[key] = (time.monotonic(), model)+ if model is not None:+ _known_audio_cpp_ids.add(model.id.lower())+ return model+++def forget(identifier: Optional[str] = None) -> None:+ """Drop memoized resolutions (after a download or delete changed the cache)."""+ with _resolve_lock:+ # What is downloaded changed too, so the next status poll must not reuse the old listing.+ _downloaded_cache.clear()+ if identifier is None:+ _resolve_cache.clear()+ return+ low = split_variant_ref(str(identifier))[0].lower()+ for key in [k for k in _resolve_cache if k[0] == low]:+ _resolve_cache.pop(key, None)+++def _resolve_uncached(+ ref: AudioCppRef,+ wanted: Optional[str],+ hf_token: Optional[str],+ network: bool,+ tags: tuple[str, ...],+) -> Optional[AudioCppModel]:+ if ref.local_path:+ files = [RepoFile(Path(ref.local_path).name, _size(ref.local_path))]+ else:+ files, _from_hub = list_files(ref.repo_id, ref.folder, hf_token, network = network)+ files = [f for f in files if not _SKIP_FILE_RE.search(f.path)]+ ggufs = [f for f in files if f.path.lower().endswith(".gguf")]+ if not ggufs:+ return None+ header = _probe_header(ref, ggufs, hf_token, network)+ names = _names_for(ref, files)+ umbrella = ref.repo_id is not None and ref.repo_id.lower() == AUDIO_CPP_REPO.lower()+ if header is not None and not header.is_audio_cpp:+ return None+ family = header.family if header is not None else None+ if header is None:+ # Unread (offline, not cached): only a repo that says it is audio.cpp counts.+ owner = str(ref.repo_id or "").split("/")[0].lower()+ text = " ".join(names).lower()+ tagged = any(t.lower() in ("audio.cpp", "audiocpp") for t in tags)+ if not (+ umbrella or owner == "audio-cpp" or tagged or "audiocpp" in text or "audio.cpp" in text+ ):+ return None+ if not family:+ family = next(+ (t for t in tags if _TAG_FAMILY_RE.match(t) and t in FAMILIES), None+ ) or family_from_names(names)+ if not family:+ reason = "Studio could not tell which model family this audio GGUF is."+ variant = AudioCppVariant(quant_label(ggufs[0].path), (ggufs[0],), ggufs[0].path)+ return AudioCppModel(+ id = ref.id,+ repo_id = ref.repo_id,+ folder = ref.folder,+ display_name = ref.display_name,+ family = "",+ task = "",+ server_task = "",+ variant = variant,+ variants = (variant,),+ default_variant = variant.key,+ unsupported = reason,+ local_path = ref.local_path,+ )+ spec = runtime_spec(family)+ embedded = header.spec if header is not None else None+ policy = family_policy(family, spec or embedded, names)+ if policy.package:+ # In the package's own order: its first mix is the one the runtime defaults to.+ variants = _package_variants(policy, files, ref.folder)+ else:+ variants = _single_file_variants(files, ref.folder)+ if ref.local_path:+ variants = [+ AudioCppVariant(v.key, v.files, ref.local_path, label = v.label) for v in variants+ ]+ variants.sort(key = _variant_rank)+ unsupported = policy.unsupported+ if not variants:+ unsupported = (+ unsupported or "This repository does not publish every file this model package needs."+ )+ variants = [AudioCppVariant(quant_label(ggufs[0].path), (ggufs[0],), ggufs[0].path)]+ default = variants[0]+ chosen = match_variant(variants, wanted) if wanted else default+ if (+ chosen is not None+ and wanted+ and "/" not in chosen.key+ and chosen.key.lower() != wanted.lower()+ ):+ # A partial cache listing named the row by quant alone; keep the name the full listing gives+ # it (``tiny/Q8_0``), so status and /gguf-variants agree on the variant that is loaded.+ text = wanted.strip().strip("/")+ head, _, tail = text.rpartition("/")+ scope = head if tail.lower() == chosen.key.lower() else ""+ if not scope and re.fullmatch(r"[A-Za-z0-9]+", text) and not _is_quant(text):+ scope = text # a bare sub-variant name ("tiny"), not a quant or a file stem+ if scope:+ chosen = AudioCppVariant(+ f"{scope}/{chosen.key}",+ chosen.files,+ chosen.primary,+ dict(chosen.session_options),+ f"{chosen.key} · {scope.rsplit('/', 1)[-1]}",+ )+ if chosen is None:+ unsupported = unsupported or (+ f"Variant '{wanted}' not found. Available variants: "+ + ", ".join(v.key for v in variants)+ )+ chosen = default+ model = AudioCppModel(+ id = ref.id,+ repo_id = ref.repo_id,+ folder = ref.folder,+ display_name = ref.display_name,+ family = family,+ task = policy.task,+ server_task = policy.default_server_task,+ variant = default,+ variants = tuple(variants),+ default_variant = default.key,+ needs_espeak = policy.needs_espeak,+ request_defaults = dict(policy.request_defaults),+ model_options = dict(policy.model_options),+ options = option_schema(policy, spec, embedded),+ unsupported = unsupported,+ local_path = ref.local_path,+ tags = tuple(tags),+ )+ return model.with_variant(chosen)+++def _size(path: str) -> int:+ try:+ return os.stat(path).st_size+ except OSError:+ return 0+++def package_variant_files(names: Iterable[str]) -> Optional[dict[str, tuple[str, ...]]]:+ """``{variant key: repo paths}`` when ``names`` (a repo's root listing) is an audio.cpp package+ layout Studio knows, else None. A pure function of the names, for the GGUF download planner."""+ present = set(names)+ for policy in _FAMILY_LIST:+ if not policy.package:+ continue+ found = {+ variant.key: variant.files+ for variant in policy.package+ if all(path in present for path in variant.files)+ }+ if found:+ return found+ return None+++def download_target(+ identifier: Optional[str],+ variant: Optional[str],+ hf_token: Optional[str] = None,+) -> Optional[tuple[str, str]]:+ """``(repo, variant key)`` the Hub GGUF downloader fetches for an umbrella folder row, else None.++ The frontend names an umbrella model as ``audio-cpp/audio.cpp-gguf/<Folder>`` plus a quant, like+ any GGUF repo; the downloader and its progress work on the real repo and the path-qualified key+ its variant planner derives from the file.+ """+ if not is_umbrella_id(identifier):+ return None+ model = resolve(identifier, variant, hf_token, network = not hub_offline())+ if model is None or not model.repo_id or not model.variant.primary:+ return None+ from hub.utils.gguf import gguf_variant_key++ return model.repo_id, gguf_variant_key(model.variant.primary)+++def folder_row_for_download(repo_id: str, variant: Optional[str]) -> Optional[tuple[str, str]]:+ """``(folder row id, variant key)`` for an umbrella download job, the inverse of+ ``download_target``: jobs run on the umbrella repo, but Studio names them by row. None for+ any other job. Answered from the cache, falling back to reading the planner key's path."""+ if str(repo_id or "").lower() != AUDIO_CPP_REPO.lower() or not variant or "/" not in variant:+ return None+ parts = variant.replace("\\", "/").split("/")+ row_id = f"{AUDIO_CPP_REPO}/{parts[0]}"+ try:+ model = resolve(row_id, network = False)+ except Exception: # noqa: BLE001 - the path-derived key below still names it+ model = None+ if model is not None:+ from hub.utils.gguf import gguf_variant_key+ for candidate in model.variants:+ if candidate.primary and gguf_variant_key(candidate.primary).lower() == variant.lower():+ return row_id, candidate.key+ return row_id, "/".join([*parts[1:-1], quant_label(f"{parts[-1]}.gguf")])+++def require_runnable(model: AudioCppModel, task: Optional[str] = None) -> None:+ """Raise ``AudioCppModelError`` when Studio cannot run ``model`` (for ``task`` when given)."""+ if model.unsupported:+ raise AudioCppModelError(model.unsupported)+ if task == "asr" and model.task != "asr":+ raise AudioCppModelError(f"{model.display_name} is not a speech-to-text model.")+ if task in ("tts", "music") and model.task not in ("tts", "music"):+ if model.task == "asr":+ raise AudioCppModelError(+ f"{model.display_name} is a speech-to-text model; choose it for dictation in "+ "Settings, then Voice."+ )+ raise AudioCppModelError(f"{model.display_name} is not a speech or music model.")+++def repo_of(identifier: Optional[str]) -> Optional[str]:+ """The Hub repo that holds ``identifier``'s files. No I/O."""+ base, _variant = split_variant_ref(str(identifier or ""))+ ref = parse_identifier(base) if not base.lower().endswith(".gguf") else None+ return ref.repo_id if ref is not None else None+++# Recommended ASR rows for dictation, in the order the Voice settings list them.+RECOMMENDED_STT_MODELS: tuple[str, ...] = tuple(+ f"{AUDIO_CPP_REPO}/{folder}"+ for folder in (+ "Qwen3-ASR-0.6B-GGUF",+ "Qwen3-ASR-1.7B-GGUF",+ "Parakeet-TDT-0.6B-v3-GGUF",+ "Canary-180M-Flash-GGUF",+ "Moonshine-Streaming-GGUF",+ "Nemotron-3.5-ASR-Streaming-0.6B-GGUF",+ )+)+++_downloaded_cache: dict[Optional[str], tuple[float, list[AudioCppModel]]] = {}+_DOWNLOADED_TTL_SECONDS = 10.0+++def downloaded_models(task: Optional[str] = None) -> list[AudioCppModel]:+ """audio.cpp models with a variant fully in the HF cache, found by header.++ Walks the active hub cache's repos, reading only GGUF headers (memoized). Umbrella folders+ are listed per folder. Status polls call this, so the answer is kept for a few seconds.+ """+ with _resolve_lock:+ hit = _downloaded_cache.get(task)+ if hit is not None and time.monotonic() - hit[0] < _DOWNLOADED_TTL_SECONDS:+ return list(hit[1])+ out = _scan_downloaded(task)+ with _resolve_lock:+ _downloaded_cache[task] = (time.monotonic(), out)+ return list(out)+++def _scan_downloaded(task: Optional[str]) -> list[AudioCppModel]:+ from core.inference import audio_cpp_files++ out: list[AudioCppModel] = []+ root = _hub_cache()+ try:+ repo_dirs = [p for p in root.iterdir() if p.name.startswith("models--") and p.is_dir()]+ except OSError:+ return out+ for repo_dir in repo_dirs:+ repo_id = repo_dir.name[len("models--") :].replace("--", "/")+ snapshots = snapshot_dirs(repo_id, root)+ if not snapshots:+ continue+ ids: list[str] = []+ if repo_id.lower() == AUDIO_CPP_REPO.lower():+ folders = set()+ for snapshot in snapshots:+ try:+ folders.update(p.name for p in snapshot.iterdir() if p.is_dir())+ except OSError:+ continue+ ids = [f"{AUDIO_CPP_REPO}/{name}" for name in sorted(folders)]+ else:+ first_gguf = None+ for snapshot in snapshots:+ # The root or one folder down, where audio.cpp repos keep their GGUFs; a full walk of+ # every cached checkpoint on each status poll would cost more than it finds.+ first_gguf = next(+ iter(sorted([*snapshot.glob("*.gguf"), *snapshot.glob("*/*.gguf")])), None+ )+ if first_gguf is not None:+ break+ if first_gguf is None:+ continue+ header = read_local_header(first_gguf)+ if header is None or not header.is_audio_cpp:+ continue+ ids = [repo_id]+ for model_id in ids:+ try:+ model = resolve(model_id, network = False)+ except Exception: # noqa: BLE001 - one unreadable repo never hides the rest+ model = None+ if model is None or (model.unsupported and not model.family):+ continue+ if task is not None and model.task != task:+ continue+ ready = next(+ (v for v in model.variants if audio_cpp_files.cached_files(model.with_variant(v))),+ None,+ )+ if ready is not None:+ out.append(model.with_variant(ready))+ return outdiff --git a/studio/backend/core/inference/audio_cpp_server.py b/studio/backend/core/inference/audio_cpp_server.pynew file mode 100644index 00000000000..8389c468094--- /dev/null+++ b/studio/backend/core/inference/audio_cpp_server.py@@ -0,0 +1,654 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""One ``audiocpp_server`` child process serving one audio.cpp model.++Shared by the dictation sidecar (speech to text) and the audio worker (speech and+music), which each own an instance. The server is bound to 127.0.0.1 on an+ephemeral port and configured with exactly one model under a per-launch random id,+so the readiness probe can tell our child from any other process that won the bind+race: it must answer ``/health`` and list that id in ``/v1/models``.++Binary discovery mirrors whisper.cpp's: ``AUDIOCPP_SERVER_PATH`` (the binary),+``UNSLOTH_AUDIO_CPP_PATH`` (an install dir), the managed ``<UNSLOTH_HOME>/audio.cpp``+tree ``install_audio_cpp_prebuilt.py`` writes, then PATH.+"""++from __future__ import annotations++import http.client+import json+import os+import shutil+import socket+import subprocess+import sys+import tempfile+import threading+import time+import uuid+from pathlib import Path+from typing import Any, Optional++from core.inference.audio_cpp_models import AudioCppModel+from loggers import get_logger+from utils.prebuilt.child_env import isolate_home, scrub_env+from utils.prebuilt.runtime_libs import dedupe_existing_dirs+from utils.process_lifetime import (+ adopt_pid,+ child_popen_kwargs,+ forget_pid,+ is_process_shutting_down,+)++logger = get_logger(__name__)++BINARY_NAME = "audiocpp_server.exe" if sys.platform == "win32" else "audiocpp_server"+INSTALL_RECORD = "UNSLOTH_AUDIO_CPP_PREBUILT_INFO.json"++# Model load happens before the server answers, and a multi-GB music model can take a while from a cold disk.+_SERVER_START_TIMEOUT_SECONDS = 600.0+_PROBE_TIMEOUT_SECONDS = 2.0+# 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+++class AudioCppUnavailableError(RuntimeError):+ """audiocpp_server is missing, failed to start, or stopped answering."""+++class AudioCppStartCancelledError(RuntimeError):+ """A start was cancelled (training pre-empted it, or Unsloth is shutting down)."""+++class AudioCppRequestCancelledError(RuntimeError):+ """The caller's cancel event fired while a request was in flight."""+++class AudioCppRequestError(RuntimeError):+ """audiocpp_server answered a request with a non-2xx status."""++ def __init__(self, status: int, detail: str) -> None:+ super().__init__(f"The audio runtime returned HTTP {status}: {detail}")+ self.status = status+ self.detail = detail+++def managed_audio_cpp_dir() -> Path:+ """``<UNSLOTH_HOME>/audio.cpp``, else ``<STUDIO_HOME>/audio.cpp`` in custom mode, else ``~/.unsloth/audio.cpp``."""+ legacy = Path.home() / ".unsloth" / "audio.cpp"+ try:+ from utils.paths.storage_roots import studio_root, unsloth_home++ master = unsloth_home()+ if master is not None:+ return master / "audio.cpp"+ resolved = studio_root()+ legacy_studio = Path.home() / ".unsloth" / "studio"+ try:+ is_legacy = resolved.resolve() == legacy_studio.resolve()+ except (OSError, ValueError):+ is_legacy = resolved == legacy_studio+ return legacy if is_legacy else (resolved / "audio.cpp")+ except (ImportError, OSError, ValueError):+ override = (+ os.environ.get("UNSLOTH_STUDIO_HOME") or os.environ.get("STUDIO_HOME") or ""+ ).strip()+ if override:+ return Path(override).expanduser() / "audio.cpp"+ return legacy+++def _is_runnable(p: Path) -> bool:+ try:+ return p.is_file() and (sys.platform == "win32" or os.access(p, os.X_OK))+ except OSError:+ # An unreadable install dir reads as engine-unavailable, never a 500.+ return False+++def _layout_candidates(d: Path) -> list[Path]:+ recorded: list[Path] = []+ try:+ with open(d / INSTALL_RECORD, "r", encoding = "utf-8") as f:+ relpath = json.load(f).get("server_relpath")+ if isinstance(relpath, str) and relpath and ".." not in Path(relpath).parts:+ recorded.append(d / relpath)+ except (OSError, ValueError, AttributeError):+ pass+ return [+ *recorded,+ d / BINARY_NAME,+ d / "bin" / BINARY_NAME,+ d / "build" / "bin" / BINARY_NAME,+ d / "build" / "bin" / "Release" / BINARY_NAME,+ ]+++def find_audio_cpp_server_binary() -> Optional[str]:+ env_path = os.environ.get("AUDIOCPP_SERVER_PATH")+ if env_path and _is_runnable(Path(env_path)):+ return str(Path(env_path))+ custom_dir = os.environ.get("UNSLOTH_AUDIO_CPP_PATH")+ if custom_dir:+ for p in _layout_candidates(Path(custom_dir)):+ if _is_runnable(p):+ return str(p)+ for p in _layout_candidates(managed_audio_cpp_dir()):+ if _is_runnable(p):+ return str(p)+ return shutil.which(BINARY_NAME)+++def read_install_record(binary: str) -> dict:+ """The prebuilt install record beside or above ``binary``, or ``{}`` for a custom build."""+ path = Path(binary).resolve()+ for parent in list(path.parents)[:4]:+ record = parent / INSTALL_RECORD+ try:+ with open(record, "r", encoding = "utf-8") as f:+ data = json.load(f)+ return data if isinstance(data, dict) else {}+ except (OSError, ValueError):+ continue+ return {}+++def is_available() -> bool:+ return find_audio_cpp_server_binary() is not None+++def ensure_binary() -> str:+ binary = find_audio_cpp_server_binary()+ if binary is None:+ raise AudioCppUnavailableError(+ "The audio runtime is not installed. Run `unsloth studio update` to install it."+ )+ return binary+++_ESPEAK_DATA_NAMES = ("espeak-ng-data.bin", "espeak-ng-data.gguf", "espeak-ng-data")+++def binary_has_espeak(binary: Optional[str]) -> bool:+ """Whether this build can phonemize with eSpeak-ng: a static build ships its data beside the server.++ Upstream bundles are built without it, so Kokoro, Piper, KittenTTS and Inflect cannot run on them.+ """+ if not binary:+ return False+ # The data itself, not the install record: an install whose data was removed or quarantined+ # would pass preflight and fail only at launch.+ bin_dir = Path(binary).parent+ return any((bin_dir / name).exists() for name in _ESPEAK_DATA_NAMES)+++def model_runtime_problem(model: AudioCppModel, binary: Optional[str] = None) -> Optional[str]:+ """Why ``model`` cannot run on the installed runtime, or None when it can."""+ if model.unsupported:+ return model.unsupported+ binary = binary if binary is not None else find_audio_cpp_server_binary()+ if binary is None:+ return "The audio runtime is not installed. Run `unsloth studio update` to install it."+ if model.needs_espeak and not binary_has_espeak(binary):+ return (+ f"{model.display_name} needs an audio runtime built with eSpeak-ng, and the installed one "+ "has none. Run `unsloth studio update` to install the Unsloth audio runtime."+ )+ from core.inference.audio_cpp_files import served_path_problem++ try:+ return served_path_problem(model)+ except Exception: # noqa: BLE001 - an unreadable cache setting is materialize's to report+ return None+++def select_backend(binary: str, force_cpu: bool) -> str:+ """The ``--backend`` for this launch: CPU when asked, else what the install was built for."""+ if force_cpu:+ return "cpu"+ override = (os.environ.get("UNSLOTH_AUDIO_CPP_BACKEND") or "").strip().lower()+ if override:+ return override+ recorded = str(read_install_record(binary).get("backend") or "").strip().lower()+ if recorded in ("cpu", "cuda", "vulkan", "metal", "hip"):+ return recorded+ # A custom build with no record: what it was compiled with, preferring the host's GPU.+ built = compiled_backends(binary)+ if sys.platform == "darwin":+ return "metal" if built is None or "metal" in built else "cpu"+ if shutil.which("nvidia-smi") and (built is None or "cuda" in built):+ return "cuda"+ if built and "vulkan" in built:+ return "vulkan"+ return "cpu"+++_compiled_cache: dict[tuple[str, float], Optional[frozenset[str]]] = {}+++def compiled_backends(binary: str) -> Optional[frozenset[str]]:+ """Backends the binary reports in ``--version`` (``backends: cpu,cuda``), or None when it cannot say."""+ try:+ key = (str(Path(binary).resolve()), os.path.getmtime(binary))+ except OSError:+ return None+ if key in _compiled_cache:+ return _compiled_cache[key]+ found: Optional[frozenset[str]] = None+ try:+ out = subprocess.run(+ [binary, "--version"],+ capture_output = True,+ text = True,+ encoding = "utf-8",+ errors = "replace",+ timeout = 15,+ env = child_env(binary),+ check = False,+ ).stdout+ for line in out.splitlines():+ name, _, value = line.partition(":")+ if name.strip().lower() == "backends":+ found = frozenset(b.strip().lower() for b in value.split(",") if b.strip()) or None+ break+ except (OSError, subprocess.SubprocessError):+ found = None+ _compiled_cache[key] = found+ return found+++def runtime_runs_on_cpu() -> bool:+ """Whether an Auto-placed audio.cpp model launches on the CPU anyway (a CPU-only bundle or override)."""+ binary = find_audio_cpp_server_binary()+ return bool(binary) and select_backend(binary, False) == "cpu"+++def child_env(binary: str) -> dict[str, str]:+ """Secrets scrubbed, home repointed at a scratch dir, co-located libs first on the loader path."""+ binary = str(Path(binary).resolve())+ env = scrub_env(os.environ)+ # Per user and outside the install dir: eSpeak extracts data here, so a shared path lets another account plant it.+ isolate_home(env, str(_child_home_dir()))+ bin_dir = str(Path(binary).parent)+ runtime_dirs: list[str] = []+ if read_install_record(binary).get("backend") == "cuda" or not read_install_record(binary):+ # A CUDA bundle installed without its cudart archive relies on the CUDA runtime torch ships,+ # after the bundle's own directory so co-located DLLs still win.+ try:+ from utils.prebuilt.runtime_libs import python_runtime_dirs+ runtime_dirs = python_runtime_dirs()+ except Exception: # noqa: BLE001 - no torch runtime to offer+ runtime_dirs = []+ if sys.platform == "win32":+ var = "PATH"+ elif sys.platform == "darwin":+ var, runtime_dirs = "DYLD_LIBRARY_PATH", []+ else:+ var = "LD_LIBRARY_PATH"+ existing = [p for p in env.get(var, "").split(os.pathsep) if p]+ env[var] = os.pathsep.join(dedupe_existing_dirs([bin_dir, *runtime_dirs, *existing]))+ return env+++# eSpeak-ng keeps its data dir in a fixed buffer (N_PATH_HOME: 160 bytes on POSIX, 230 on Windows), and+# audio.cpp extracts it ~65 bytes below the child home (.cache/audio.cpp/espeak-data/<id>/espeak-ng-data).+_MAX_CHILD_HOME_LEN = 150 if sys.platform == "win32" else 85+++def _child_home_dir() -> Path:+ """A private scratch home for the child: ``<studio_root>/cache/audiocpp-home``, else (unusable or+ too long for eSpeak-ng) a per-user temp dir."""+ try:+ from utils.paths.storage_roots import studio_root+ home = studio_root() / "cache" / "audiocpp-home"+ if len(str(home)) <= _MAX_CHILD_HOME_LEN:+ home.mkdir(parents = True, exist_ok = True)+ return home+ except Exception: # noqa: BLE001 - an unusable studio root falls back to the temp dir+ pass+ user = str(os.getuid()) if hasattr(os, "getuid") else (os.environ.get("USERNAME") or "user")+ home = Path(tempfile.gettempdir()) / f"unsloth-audiocpp-home-{user}"+ home.mkdir(mode = 0o700, parents = True, exist_ok = True)+ if hasattr(os, "getuid"):+ info = home.stat()+ if info.st_uid != os.getuid() or info.st_mode & 0o077:+ raise AudioCppUnavailableError(+ f"{home} is not a private directory of this user; remove it and retry."+ )+ return home+++def _cpu_threads() -> Optional[int]:+ """``UNSLOTH_CPU_THREADS`` as a positive int, the thread budget the other native engines honour."""+ try:+ value = int(os.environ.get("UNSLOTH_CPU_THREADS") or 0)+ except ValueError:+ return None+ return value if value > 0 else None+++def _reserve_free_port() -> tuple[socket.socket, int]:+ s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)+ s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)+ s.bind(("127.0.0.1", 0))+ return s, s.getsockname()[1]+++def _abort_connection(connection: http.client.HTTPConnection) -> None:+ try:+ if connection.sock is not None:+ connection.sock.shutdown(socket.SHUT_RDWR)+ except OSError:+ pass+ try:+ connection.close()+ except Exception: # noqa: BLE001 - best effort+ pass+++class AudioCppServer:+ """One running ``audiocpp_server`` bound to one model. Not thread-safe; owners serialise."""++ def __init__(+ self,+ process: subprocess.Popen,+ port: int,+ model: AudioCppModel,+ model_id: str,+ backend: str,+ config_dir: Path,+ ) -> None:+ self.process = process+ self.port = port+ self.model = model+ self.model_id = model_id+ self.backend = backend+ self._config_dir = config_dir++ @classmethod+ def start(+ cls,+ model: AudioCppModel,+ model_path: str,+ *,+ force_cpu: bool = False,+ cancel_event: Optional[threading.Event] = None,+ on_process: Optional[Any] = None,+ ) -> "AudioCppServer":+ """Launch the server for ``model`` loaded from ``model_path`` and wait until it serves.++ ``on_process`` is called with the Popen as soon as it exists, so an owner can+ terminate a start that training pre-empts.+ """+ binary = ensure_binary()+ problem = model_runtime_problem(model, binary)+ if problem:+ raise AudioCppUnavailableError(problem)+ backend = select_backend(binary, force_cpu)+ model_id = f"studio-{uuid.uuid4().hex[:12]}"+ entry: dict[str, Any] = {+ "id": model_id,+ "family": model.family,+ "path": model_path,+ "task": model.server_task,+ "mode": "offline",+ }+ entry.update(model.model_options)+ config_dir = Path(tempfile.mkdtemp(prefix = "unsloth-audiocpp-"))+ reservation, port = _reserve_free_port()+ config = {+ "host": "127.0.0.1",+ "port": port,+ "backend": backend,+ "lazy_load": False,+ "max_loaded_models": 1,+ # Music generation can take minutes; the owner bounds its own wait and cancels.+ "busy_timeout_ms": 0,+ "models": [entry],+ }+ config_path = config_dir / "server.json"+ config_path.write_text(json.dumps(config), encoding = "utf-8")+ log_path = config_dir / "server.log"+ command = [binary, "--config", str(config_path), "--no-ui"]+ threads = _cpu_threads()+ if threads is None and backend != "cpu":+ # The runtime's default is every core; on a many-core host its host-side work thrashes+ # (Piper 0.44 s -> 0.18 s, Moonshine tiny 0.085 s -> 0.035 s per request at 8 on a B200).+ threads = min(os.cpu_count() or 1, _GPU_HOST_THREADS)+ if threads:+ command += ["--threads", str(threads)]+ logger.info(+ "Starting audiocpp_server (%s, %s) for %s on 127.0.0.1:%s",+ model.family,+ backend,+ model.id,+ port,+ )+ if is_process_shutting_down():+ reservation.close()+ shutil.rmtree(config_dir, ignore_errors = True)+ raise AudioCppStartCancelledError(+ "Unsloth is shutting down; not starting audiocpp_server."+ )+ env = child_env(binary)+ if model.family in _NO_CUDA_GRAPH_FAMILIES:+ env.setdefault("GGML_CUDA_DISABLE_GRAPHS", "1")+ # Released as late as possible: the server binds the port moments after this close.+ reservation.close()+ try:+ with open(log_path, "wb") as log:+ process = subprocess.Popen(+ command,+ stdout = log,+ stderr = subprocess.STDOUT,+ stdin = subprocess.DEVNULL,+ env = env,+ cwd = str(config_dir),+ **child_popen_kwargs(),+ )+ except OSError as exc:+ # A corrupt, quarantined or wrong-architecture binary: report it like any other runtime failure.+ shutil.rmtree(config_dir, ignore_errors = True)+ raise AudioCppUnavailableError(+ f"The audio runtime could not be started: {exc}"+ ) from exc+ adopt_pid(process.pid)+ if on_process is not None:+ on_process(process)+ server = cls(process, port, model, model_id, backend, config_dir)+ try:+ if is_process_shutting_down():+ raise AudioCppStartCancelledError(+ "Unsloth is shutting down; not starting audiocpp_server."+ )+ server._wait_until_ready(cancel_event)+ except BaseException:+ server.stop()+ raise+ return server++ def log_tail(self, limit: int = 2000) -> str:+ try:+ data = (self._config_dir / "server.log").read_bytes()+ except OSError:+ return ""+ return data[-limit:].decode("utf-8", "replace").strip()++ def alive(self) -> bool:+ return self.process.poll() is None++ def _wait_until_ready(self, cancel_event: Optional[threading.Event]) -> None:+ deadline = time.monotonic() + _SERVER_START_TIMEOUT_SECONDS+ while time.monotonic() < deadline:+ if cancel_event is not None and cancel_event.is_set():+ raise AudioCppStartCancelledError("Audio model loading was cancelled.")+ if not self.alive():+ tail = self.log_tail()+ logger.warning("audiocpp_server exited during startup: %s", tail)+ raise AudioCppUnavailableError(+ "The audio runtime exited before becoming ready; the model file may be "+ "incomplete or unsupported by this build."+ + (f" Last output: {tail[-400:]}" if tail else "")+ )+ if self._probe():+ return+ time.sleep(0.25)+ raise AudioCppUnavailableError("The audio runtime did not start in time.")++ def _get_json(self, path: str) -> Optional[dict]:+ # http.client, not urllib: urlopen routes loopback through an ambient HTTP_PROXY.+ connection = http.client.HTTPConnection(+ "127.0.0.1", self.port, timeout = _PROBE_TIMEOUT_SECONDS+ )+ try:+ connection.request("GET", path)+ with connection.getresponse() as response:+ return json.loads(response.read(65536).decode("utf-8"))+ except Exception:+ return None+ finally:+ connection.close()++ def _probe(self) -> bool:+ """Ready only when our child is alive, reports ok, and lists this launch's model id."""+ health = self._get_json("/health")+ if not isinstance(health, dict) or health.get("status") != "ok":+ return False+ models = self._get_json("/v1/models")+ if not self.alive() or not isinstance(models, dict):+ return False+ ids = {str(m.get("id")) for m in models.get("data") or [] if isinstance(m, dict)}+ return self.model_id in ids++ def request(+ self,+ method: str,+ path: str,+ *,+ body: bytes = b"",+ content_type: str = "application/json",+ timeout: float = 3600.0,+ cancel_event: Optional[threading.Event] = None,+ ) -> tuple[int, str, bytes]:+ """One HTTP round trip. A set ``cancel_event`` closes the socket and raises."""+ if cancel_event is not None and cancel_event.is_set():+ raise AudioCppRequestCancelledError("Request cancelled.")+ connection = http.client.HTTPConnection("127.0.0.1", self.port, timeout = timeout)+ done = threading.Event()+ outcome: dict = {}++ def round_trip() -> None:+ try:+ connection.request(method, path, body = body, headers = {"Content-Type": content_type})+ with connection.getresponse() as response:+ payload = response.read()+ outcome["result"] = (+ response.status,+ response.getheader("Content-Type") or "",+ payload,+ )+ except BaseException as exc: # noqa: BLE001 - re-raised on the caller's thread+ outcome["error"] = exc+ finally:+ done.set()++ try:+ if cancel_event is None:+ round_trip()+ else:+ # Windows does not wake a blocked recv when another thread shuts the socket down, so+ # the round trip runs on its own thread and a cancel returns without waiting for it.+ threading.Thread(target = round_trip, daemon = True).start()+ while not done.wait(0.1):+ if cancel_event.is_set():+ _abort_connection(connection)+ raise AudioCppRequestCancelledError("Request cancelled.")+ if "error" in outcome:+ raise outcome["error"]+ return outcome["result"]+ except AudioCppRequestCancelledError:+ raise+ except Exception as exc:+ if cancel_event is not None and cancel_event.is_set():+ raise AudioCppRequestCancelledError("Request cancelled.") from exc+ if not self.alive():+ raise AudioCppUnavailableError(+ "The audio runtime stopped while serving the request."+ + (f" Last output: {self.log_tail()[-400:]}" if self.log_tail() else "")+ ) from exc+ raise AudioCppUnavailableError(f"The audio runtime did not answer: {exc}") from exc+ finally:+ done.set()+ connection.close()++ def post_json(self, path: str, payload: dict, **kwargs) -> tuple[str, bytes]:+ status, ctype, data = self.request(+ "POST", path, body = json.dumps(payload).encode("utf-8"), **kwargs+ )+ if not 200 <= status < 300:+ raise AudioCppRequestError(status, _error_detail(data))+ return ctype, data++ def post_multipart(+ self,+ path: str,+ fields: dict[str, str],+ file_name: str,+ file_bytes: bytes,+ file_type: str,+ **kwargs,+ ) -> tuple[str, bytes]:+ boundary = uuid.uuid4().hex+ parts: list[bytes] = []+ for name, value in fields.items():+ parts.append(+ f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'.encode(+ "utf-8"+ )+ )+ parts.append(+ f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{file_name}"\r\n'+ f"Content-Type: {file_type}\r\n\r\n".encode("utf-8")+ + file_bytes+ + b"\r\n"+ )+ parts.append(f"--{boundary}--\r\n".encode("utf-8"))+ status, ctype, data = self.request(+ "POST",+ path,+ body = b"".join(parts),+ content_type = f"multipart/form-data; boundary={boundary}",+ **kwargs,+ )+ if not 200 <= status < 300:+ raise AudioCppRequestError(status, _error_detail(data))+ return ctype, data++ def stop(self) -> None:+ process = self.process+ if process.poll() is None:+ process.terminate()+ try:+ process.wait(timeout = 10)+ except subprocess.TimeoutExpired:+ process.kill()+ process.wait(timeout = 10)+ forget_pid(process.pid)+ shutil.rmtree(self._config_dir, ignore_errors = True)+++def _error_detail(data: bytes) -> str:+ text = data[:2000].decode("utf-8", "replace").strip()+ try:+ parsed = json.loads(text)+ except ValueError:+ return text or "no detail"+ if isinstance(parsed, dict):+ err = parsed.get("error")+ if isinstance(err, dict):+ return str(err.get("message") or err)+ if err:+ return str(err)+ return textdiff --git a/studio/backend/core/inference/audio_device.py b/studio/backend/core/inference/audio_device.pyindex 86c9f7226d9..0a55bb98a47 100644--- a/studio/backend/core/inference/audio_device.py+++ b/studio/backend/core/inference/audio_device.py@@ -87,6 +87,20 @@ def audio_device_forces_cpu(value: Optional[str]) -> bool:return normalize_audio_device(value) == "cpu"+def audio_load_runs_on_cpu(audio_type: Optional[str], value: Optional[str]) -> bool:+ """True when a native audio load of this type ends up in CPU RAM: asked for, or a GGUF+ audio model on an audio.cpp runtime that only runs on the CPU (Auto cannot place it on a GPU)."""+ if audio_device_forces_cpu(value):+ return True+ from core.inference.audio_cpp_models import AUDIO_CPP_AUDIO_TYPES++ if audio_type not in AUDIO_CPP_AUDIO_TYPES:+ return False+ from core.inference.audio_cpp_server import runtime_runs_on_cpu++ return runtime_runs_on_cpu()++def mask_accelerators_for_cpu_audio(env: dict) -> None:"""Hide CUDA/ROCm from a worker whose weights stay in CPU RAM.diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.pyindex ea2395c8023..f7d0183458e 100644--- a/studio/backend/core/inference/llama_cpp.py+++ b/studio/backend/core/inference/llama_cpp.py@@ -519,6 +519,7 @@ from utils.code_integrity import code_integrity_block_reason, code_integrity_use# Unsloth's Python is, so it must not make the whole models package a hard import dependency.from utils.gguf_archs import (SPEECH_GGUF_ARCHS as _SPEECH_GGUF_ARCHS,+ is_audio_cpp_gguf_architecture,is_speech_gguf_architecture,)@@ -20389,6 +20390,7 @@ class LlamaCppBackend:if (arch not in self._DIFFUSION_ARCHESand not is_speech_gguf_architecture(arch)+ and not is_audio_cpp_gguf_architecture(arch)and not getattr(self, "_gguf_header_parsed", False)):return None@@ -20397,6 +20399,11 @@ class LlamaCppBackend:# name-based branch below name a page.arch = ""if arch:+ if is_audio_cpp_gguf_architecture(arch):+ return (+ "This is an audio GGUF (speech, music or transcription), which cannot run as "+ "a chat model. Open it from the Audio page instead."+ )if is_speech_gguf_architecture(arch):# Points at the Transformers build, not this file on the Audio page: that page# cannot list a speech GGUF either, so it would promise a row that is not there.@@ -21202,6 +21209,11 @@ class LlamaCppBackend:arch_match = re.search(r"unknown model architecture:\s*'([^']+)'", lowered)if arch_match:arch = arch_match.group(1)+ if is_audio_cpp_gguf_architecture(arch):+ return (+ "This is an audio GGUF (speech, music or transcription), which llama-server "+ "cannot run as a chat/completion model. Open it from Unsloth's Audio page instead."+ )if is_speech_gguf_architecture(arch):# Same wording rule as the pre-launch refusal above: name the build that runs,# not a page this file will not appear on.diff --git a/studio/backend/core/inference/model_ids.py b/studio/backend/core/inference/model_ids.pyindex 0d86d16b18c..13e03ec56b6 100644--- a/studio/backend/core/inference/model_ids.py+++ b/studio/backend/core/inference/model_ids.py@@ -30,6 +30,11 @@ def _looks_like_path(identifier: str) -> bool:"""if identifier.lower().endswith(_GGUF_SUFFIX):return True+ # An audio.cpp umbrella id names a model folder of one Hub repo; three segments, not a path.+ if identifier.lower().startswith("audio-cpp/audio.cpp-gguf/"):+ from core.inference.audio_cpp_models import parse_identifier+ if parse_identifier(identifier) is not None:+ return Falseif identifier.startswith(("/", "\\", "./", "../", ".\\", "..\\", "~")):return Trueif len(identifier) >= 2 and identifier[1] == ":":diff --git a/studio/backend/core/inference/native_audio.py b/studio/backend/core/inference/native_audio.pyindex 031f4166324..f9c60ea4903 100644--- a/studio/backend/core/inference/native_audio.py+++ b/studio/backend/core/inference/native_audio.py@@ -56,7 +56,10 @@ NATIVE_AUDIO_MODEL_TYPES = {"minimax_music3": "minimax_music3",}-NATIVE_AUDIO_TYPES = frozenset(NATIVE_AUDIO_MODEL_TYPES.values())+# audio.cpp speech and music models ride the same worker path; their weights run in audiocpp_server.+from core.inference.audio_cpp_models import AUDIO_CPP_AUDIO_TYPES # noqa: E402++NATIVE_AUDIO_TYPES = frozenset(NATIVE_AUDIO_MODEL_TYPES.values()) | AUDIO_CPP_AUDIO_TYPESREMOTE_CODE_AUDIO_TYPES = frozenset(("moss_tts_local", "moss_tts_nano", "higgs_tts3"))PYTHON310_AUDIO_TYPES = frozenset(("higgs_tts2", "higgs_tts3", "minimax_music3"))MOSS_LOCAL_CODEC_REPO = "OpenMOSS-Team/MOSS-Audio-Tokenizer-v2"@@ -380,9 +383,33 @@ def _native_audio_type(model_name: str) -> Optional[str]:curated = NATIVE_AUDIO_MODEL_IDS.get(normalized.lower())if curated:return curated+ audio_cpp_type = audio_cpp_audio_type(normalized)+ if audio_cpp_type:+ return audio_cpp_typereturn native_audio_type_from_local_path(normalized)+def audio_cpp_audio_type(model_name: str) -> Optional[str]:+ """The audio_type of an audio.cpp speech or music id, from the HF cache alone.++ Only ids that name the umbrella repo, a legacy key, or a repo this process already+ resolved are looked at, so an ordinary model name costs nothing here.+ """+ from core.inference.audio_cpp_models import looks_like_audio_cpp, resolve++ if not looks_like_audio_cpp(model_name):+ return None+ try:+ model = resolve(model_name, network = False)+ except Exception: # noqa: BLE001 - a probe never fails its caller+ return None+ return model.audio_type if model is not None else None+++def is_audio_cpp_audio_model(model_name: str) -> bool:+ return audio_cpp_audio_type(model_name) is not None++def is_native_audio_model(model_name: str) -> bool:"""Whether ``model_name`` belongs in the portable native-audio worker.@@ -398,6 +425,11 @@ def native_audio_security_targets(hf_token: Optional[str] = None,) -> list[str]:"""Repositories whose code or weights are loaded for this audio model."""+ from core.inference.audio_cpp_models import AUDIO_CPP_AUDIO_TYPES, looks_like_audio_cpp, repo_of++ if audio_type in AUDIO_CPP_AUDIO_TYPES or looks_like_audio_cpp(model_name):+ # An umbrella id names a subfolder; the weights, and so the scan, belong to the repo that holds it.+ return [repo_of(model_name) or model_name]targets = [model_name]resolved_type = audio_type or _native_audio_type(model_name)if resolved_type == "moss_tts_local":@@ -671,6 +703,12 @@ def native_audio_download_plan(model_name: str, hf_token: Optional[str] = None)normalized = str(model_name or "").strip()if not normalized:raise ValueError("A model repository is required.")+ from core.inference.audio_cpp_models import looks_like_audio_cpp++ if looks_like_audio_cpp(normalized):+ raise ValueError(+ "This is a GGUF model: download it as a GGUF variant from the model picker or the Model Hub."+ )local_checkpoint = Path(normalized).expanduser().exists()audio_type = _native_audio_type(normalized)if audio_type in PYTHON310_AUDIO_TYPES and sys.version_info < (3, 10):diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.pyindex 75329ce9aa1..4d682b054b6 100644--- a/studio/backend/core/inference/orchestrator.py+++ b/studio/backend/core/inference/orchestrator.py@@ -23,7 +23,7 @@ import uuidfrom io import BytesIOfrom pathlib import Pathfrom typing import Any, Callable, Generator, Mapping, Optional, Sequence, Tuple, Union-from core.inference.audio_device import audio_device_forces_cpu+from core.inference.audio_device import audio_device_forces_cpu, audio_load_runs_on_cpufrom core.inference.context_refusal import ContextBudgetExceededfrom core.inference.native_audio import NATIVE_AUDIO_TYPES, is_native_audio_modelfrom core.inference.audio_errors import (@@ -380,6 +380,10 @@ def _mirrored_model_entry(model_info: dict, model_name: str) -> dict:"context_length_fitted": model_info.get("context_length_fitted"),"context_unbounded_when_batched": model_info.get("context_unbounded_when_batched"),"mlx_context_budget": model_info.get("mlx_context_budget"),+ # audio.cpp GGUFs: the loader family, its per-model request options and the variant loaded.+ "audio_family": model_info.get("audio_family"),+ "audio_options": model_info.get("audio_options"),+ "gguf_variant": model_info.get("gguf_variant"),}@@ -2055,7 +2059,17 @@ class InferenceOrchestrator:sub_config["anonymous_hf_access"] = Trueif audio_codec_path is not None:sub_config["audio_codec_path"] = audio_codec_path- if audio_device_forces_cpu(audio_device) and is_native_audio_model(model_name):+ audio_cpp_model = getattr(config, "audio_cpp", None) is not None+ if audio_cpp_model:+ # The worker picks its backend from this: a Hub id alone does not say audio.cpp.+ sub_config["audio_cpp"] = True+ if audio_load_runs_on_cpu(getattr(config, "audio_type", None), audio_device):+ # A CPU-only runtime runs Auto on the CPU too: say so, so no card is chosen and the worker hides them.+ audio_device = "cpu"+ sub_config["audio_device"] = audio_device+ if audio_device_forces_cpu(audio_device) and (+ audio_cpp_model or is_native_audio_model(model_name)+ ):# Choosing a card for a load that takes none harms it twice: several GPUs are rejected as unsupported# sharding, and required_gb becomes expected_free_gb, so the settle wait raises on a busy card.resolved_gpu_ids, gpu_selection = None, {"selection_mode": "cpu_audio"}@@ -2267,9 +2281,11 @@ class InferenceOrchestrator:# Lets the already-loaded shortcut tell a CPU request from the GPU# model it would otherwise report as satisfied. Native audio only:# marking anything else tells training a GPU model holds no VRAM.- self.models[self.active_model_name]["audio_cpu"] = model_info.get(- "audio_type"- ) in NATIVE_AUDIO_TYPES and audio_device_forces_cpu(audio_device)+ _audio_type = model_info.get("audio_type")+ self.models[self.active_model_name]["audio_cpu"] = (+ _audio_type in NATIVE_AUDIO_TYPES+ and audio_load_runs_on_cpu(_audio_type, audio_device)+ )self.models[self.active_model_name].update(_mlx_runtime_mirror_fields(model_info))@@ -3322,6 +3338,7 @@ class InferenceOrchestrator:instructions: Optional[str] = None,language: Optional[str] = None,seed: Optional[int] = None,+ audio_options: Optional[dict] = None,) -> Tuple[bytes, int]:"""Generate TTS audio. Returns (wav_bytes, sample_rate). Blocking: sends the command andwaits for the full audio response."""@@ -3391,6 +3408,8 @@ class InferenceOrchestrator:cmd["language"] = languageif seed is not None:cmd["seed"] = int(seed)+ if audio_options:+ cmd["audio_options"] = dict(audio_options)# Same shared-queue hazard as _generate_inner: see _direct_reader.read_one, _drain, release_mailbox = self._direct_reader(request_id, cancel_event)diff --git a/studio/backend/core/inference/stt_audiocpp_sidecar.py b/studio/backend/core/inference/stt_audiocpp_sidecar.pynew file mode 100644index 00000000000..0bd79f7ac02--- /dev/null+++ b/studio/backend/core/inference/stt_audiocpp_sidecar.py@@ -0,0 +1,849 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""audio.cpp speech-to-text sidecar for Unsloth dictation.++Serves any audio.cpp ASR GGUF (Qwen3-ASR, Parakeet, Canary, Moonshine, Nemotron and+whatever else audio.cpp transcribes) through one ``audiocpp_server`` child, with the same lifecycle as the+whisper.cpp sidecar: loads on demand, stays warm for the keep-alive window, yields+to training, and is paused while the managed runtime is being replaced. Audio is+decoded with PyAV like every other engine and sent as 16 kHz mono WAV, since the+default server build reads WAV only.+"""++from __future__ import annotations++import json+import subprocess+import threading+from contextlib import contextmanager+from pathlib import Path+from typing import Iterator, Optional++from core.inference import audio_cpp_files, audio_cpp_server+from core.inference.audio_cpp_models import (+ DEFAULT_AUDIO_CPP_STT_MODEL,+ is_legacy_key,+ legacy_keys,+ RECOMMENDED_STT_MODELS,+ AudioCppModel,+ AudioCppModelError,+ downloaded_models,+ parse_identifier,+ require_runnable,+ resolve,+ split_variant_ref,+)+from core.inference.audio_cpp_server import (+ AudioCppRequestCancelledError,+ AudioCppRequestError,+ AudioCppServer,+ AudioCppStartCancelledError,+ AudioCppUnavailableError,+)+from core.inference.stt_ggml_sidecar import _pcm_to_wav_bytes+from core.inference.stt_sidecar import (+ STT_KEEP_ALIVE_SECONDS,+ SttAudioDecodeError,+ SttLoadCancelledError,+ SttModelIdError,+ SttModelNotDownloadedError,+ SttTranscriptionCancelledError,+ SttUnavailableError,+ _capture_stt_hub_cache,+ _claim_stt_repository,+ _decode_audio_bounded,+ _downloaded_file_bytes,+ _HF_COMMIT_SHA,+ _prepare_stt_cache_for_http,+ _TARGET_SAMPLE_RATE,+ _training_active,+ normalize_whisper_language,+)+from hub.utils.hf_errors import modelscope_missing+from hub.utils.hf_tokens import normalize_token+from loggers import get_logger++logger = get_logger(__name__)++_TRANSCRIBE_TIMEOUT_SECONDS = 600.0+++class SttEngineUnavailableError(SttUnavailableError):+ """audiocpp_server is not installed or stopped serving; the audio.cpp dictation engine is off."""+++# Rows the dictation picker recommends, in order; any other audio.cpp ASR GGUF works too.+AUDIO_CPP_STT_MODELS: tuple[str, ...] = RECOMMENDED_STT_MODELS+++def resolve_audio_cpp_stt_model(+ model: Optional[str],+ variant: Optional[str] = None,+ *,+ network: bool = False,+ hf_token: Optional[str] = None,+) -> AudioCppModel:+ """The audio.cpp ASR model a repo id, umbrella folder id or legacy key names.++ ``network=False`` (loads and transcriptions) resolves from the HF cache, so dictation works+ offline once downloaded; downloads resolve against the Hub.+ """+ if model is None or not str(model).strip():+ model = DEFAULT_AUDIO_CPP_STT_MODEL+ base, ref_variant = split_variant_ref(str(model).strip())+ if parse_identifier(base) is None:+ raise SttModelIdError(+ f"STT model '{model}' is not an audio GGUF the audio runtime can transcribe with."+ )+ found = resolve(base, variant or ref_variant, hf_token, network = network)+ if found is None and not network:+ raise SttModelNotDownloadedError(+ f"STT model '{base}' is not downloaded. Download it in Settings, then Voice, before loading it."+ )+ if found is None:+ raise SttModelIdError(+ f"STT model '{model}' is not an audio GGUF the audio runtime can transcribe with."+ )+ try:+ require_runnable(found, "asr")+ except AudioCppModelError as exc:+ raise SttModelIdError(str(exc)) from exc+ return found+++def resolve_audio_cpp_stt_model_id(model: Optional[str]) -> str:+ """The name dictation reports for ``model``: a legacy key stays that key (Settings compares+ against it), anything else becomes its row id."""+ if model is None or not str(model).strip():+ return DEFAULT_AUDIO_CPP_STT_MODEL+ base, variant = split_variant_ref(str(model).strip())+ ref = parse_identifier(base)+ if ref is None:+ raise SttModelIdError(+ f"STT model '{model}' is not an audio GGUF the audio runtime can transcribe with."+ )+ if variant is None and is_legacy_key(base):+ return base+ return ref.id+++def _reported_name(requested: Optional[str], entry: AudioCppModel) -> str:+ """How status names a model loaded through ``requested``: its legacy key, else its row id."""+ base, variant = split_variant_ref(str(requested or "").strip())+ return base if variant is None and is_legacy_key(base) else entry.id+++def is_model_downloaded(model: Optional[str]) -> bool:+ try:+ return audio_cpp_files.is_downloaded(resolve_audio_cpp_stt_model(model))+ except Exception: # noqa: BLE001 - a probe never fails its caller+ return False+++def downloaded_model_ids() -> list[str]:+ """Row ids of the ASR models with a variant in the HF cache (found by header), plus every legacy+ key whose own folder and variant is downloaded, which Settings and dictation compare against."""+ try:+ ids = list(dict.fromkeys(m.id for m in downloaded_models("asr")))+ except Exception: # noqa: BLE001 - status never fails on a cache walk+ return []+ for key in legacy_keys():+ if acm_resolve_folder(key) not in {i.lower() for i in ids}:+ continue+ try:+ model = resolve(key, network = False)+ except Exception: # noqa: BLE001 - one unreadable key never hides the rest+ continue+ if (+ model is not None+ and model.task == "asr"+ and model.unsupported is None+ and audio_cpp_files.is_downloaded(model)+ ):+ ids.append(key)+ return ids+++def acm_resolve_folder(key: str) -> str:+ """The lowercased row id a legacy key names."""+ return acm_row_id(key).lower()+++def acm_row_id(model: Optional[str]) -> str:+ """The row id any STT name (legacy key, ``id:variant``, folder or repo id) refers to, else ""."""+ base, _variant = split_variant_ref(str(model or "").strip())+ ref = parse_identifier(base)+ return ref.id if ref is not None else ""+++# Diagnostics only: with no engine to fall back to, one bad clip must not mark audio.cpp unavailable.+_runtime_inference_failure: Optional[str] = None+_runtime_failure_lock = threading.Lock()+++def note_runtime_inference_failure(reason: str) -> None:+ global _runtime_inference_failure+ with _runtime_failure_lock:+ if _runtime_inference_failure is None:+ logger.warning("audio.cpp runtime failed to serve a transcription (%s)", reason)+ _runtime_inference_failure = reason+++def clear_runtime_inference_failure() -> None:+ global _runtime_inference_failure+ with _runtime_failure_lock:+ _runtime_inference_failure = None+++def runtime_inference_failure() -> Optional[str]:+ with _runtime_failure_lock:+ return _runtime_inference_failure+++def is_available() -> bool:+ if not audio_cpp_server.is_available():+ return False+ try:+ import av # noqa: F401+ except Exception:+ # No PyAV means every transcription fails on decode.+ return False+ return True+++def ensure_engine_available() -> str:+ try:+ return audio_cpp_server.ensure_binary()+ except AudioCppUnavailableError as exc:+ raise SttEngineUnavailableError(str(exc)) from exc+++class _AudioCppDownloadState:+ """One background download of an audio.cpp ASR model's files."""++ def __init__(self) -> None:+ self._lock = threading.Lock()+ self._thread: Optional[threading.Thread] = None+ self._process: Optional[subprocess.Popen] = None+ self._model_id: Optional[str] = None+ self._error: Optional[str] = None+ self._total_bytes: Optional[int] = None+ self._etag: Optional[str] = None+ self._revision: Optional[str] = None+ self._hub_cache: Optional[Path] = None+ self._repo: Optional[str] = None+ self._filename: Optional[str] = None+ self._cancelled = False++ def status(self) -> dict:+ with self._lock:+ downloading = self._thread is not None and self._thread.is_alive()+ # Callers track the row they picked; a variant pick arrives folded in as ``row:variant``.+ row = split_variant_ref(self._model_id)[0] if self._model_id else None+ snapshot = {+ "downloading": downloading,+ "model": row if downloading else None,+ "error": self._error,+ "cancelled": self._cancelled,+ "cancelled_model": row if self._cancelled else None,+ "bytes_total": self._total_bytes if downloading else None,+ }+ captured = (+ self._repo,+ self._filename,+ self._etag,+ self._total_bytes,+ self._hub_cache,+ self._revision,+ )+ snapshot["bytes_done"] = self._downloaded_bytes(*captured) if downloading else None+ return snapshot++ def cancel(self) -> bool:+ with self._lock:+ if self._thread is None or not self._thread.is_alive():+ return False+ self._cancelled = True+ process = self._process+ if process is not None and process.poll() is None:+ from core.inference.stt_download_worker import terminate_download+ terminate_download(process)+ return True++ @staticmethod+ def _downloaded_bytes(repo, filename, etag, total, hub_cache, revision) -> Optional[int]:+ try:+ if not repo or not filename or not etag or total is None or hub_cache is None:+ return None+ return _downloaded_file_bytes(+ hub_cache = hub_cache,+ repo = repo,+ filename = filename,+ size = total,+ blob_key = etag,+ revision = revision,+ )+ except Exception:+ return None++ def start(+ self,+ model_id: str,+ hf_token: Optional[str] = None,+ ) -> None:+ model_id = str(model_id or DEFAULT_AUDIO_CPP_STT_MODEL).strip()+ resolve_audio_cpp_stt_model_id(model_id)+ hub_cache = _capture_stt_hub_cache()+ with self._lock:+ if self._thread is not None and self._thread.is_alive():+ if self._model_id == model_id:+ if not self._cancelled:+ return+ raise SttModelIdError(+ f"'{model_id}' is still cancelling; try again in a moment."+ )+ raise SttModelIdError(+ f"Another dictation model ('{self._model_id}') is still downloading; "+ "wait for it to finish."+ )+ self._model_id = model_id+ self._error = None+ self._total_bytes = None+ self._etag = None+ self._revision = None+ self._repo = None+ self._filename = None+ self._hub_cache = hub_cache+ self._cancelled = False+ self._process = None+ thread = threading.Thread(+ target = self._run, args = (model_id, hf_token, hub_cache), daemon = True+ )+ self._thread = thread+ thread.start()++ def _run(self, model_id: str, hf_token: Optional[str], hub_cache: Path) -> None:+ registry = None+ owner = None+ repo = None+ try:+ model = resolve_audio_cpp_stt_model(model_id, network = True, hf_token = hf_token)+ repo = model.repo_id+ if not repo:+ raise RuntimeError("a local model file has nothing to download")+ filename = model.gguf_file+ from huggingface_hub import get_hf_file_metadata, hf_hub_url++ try:+ meta = get_hf_file_metadata(+ hf_hub_url(repo, filename),+ token = normalize_token(hf_token),+ )+ total_bytes = int(meta.size or 0)+ except (AttributeError, TypeError, ValueError) as exc:+ raise RuntimeError("could not resolve the download metadata") from exc+ revision = meta.commit_hash+ etag = meta.etag+ if not isinstance(revision, str) or not _HF_COMMIT_SHA.fullmatch(revision):+ raise RuntimeError("could not resolve an immutable revision")+ if not isinstance(etag, str) or not etag or total_bytes <= 0:+ raise RuntimeError("could not resolve the file identity")+ with self._lock:+ if self._cancelled:+ return+ registry, owner = _claim_stt_repository(repo)+ with self._lock:+ if self._cancelled:+ return+ _prepare_stt_cache_for_http(repo, hub_cache)+ with self._lock:+ self._repo = repo+ self._filename = filename+ self._total_bytes = total_bytes+ self._etag = etag+ self._revision = revision+ from core.inference.stt_download_worker import (+ reap_download,+ spawn_download,+ terminate_download,+ )++ file_args = [arg for path in model.files for arg in ("--filename", path)]+ process = spawn_download(+ ["--repo-id", repo, "--revision", revision, *file_args],+ hf_token = normalize_token(hf_token),+ hub_cache = hub_cache,+ )+ with self._lock:+ if self._cancelled:+ terminate_download(process)+ self._process = process+ stderr = reap_download(process)+ with self._lock:+ if self._process is process:+ self._process = None+ cancelled = self._cancelled+ if process.returncode == 0 and not cancelled:+ if audio_cpp_files.cached_files(model, hub_cache = hub_cache) is None:+ raise RuntimeError("downloaded file is missing from the captured cache")+ from core.inference.audio_cpp_models import forget++ forget(model.id)+ return+ with self._lock:+ if cancelled or process.returncode < 0:+ self._cancelled = True+ return+ detail = (stderr or b"").decode("utf-8", "replace").strip()+ logger.warning("audio.cpp STT download failed for %s: %s", model_id, detail)+ with self._lock:+ self._error = modelscope_missing(detail) or f"Download failed for '{model_id}'."+ except SttModelIdError as exc:+ with self._lock:+ self._error = str(exc)+ except Exception as exc:+ with self._lock:+ if not self._cancelled:+ logger.warning("audio.cpp STT download failed for %s: %s", model_id, exc)+ self._error = modelscope_missing(exc) or f"Download failed for '{model_id}'."+ finally:+ if registry is not None and owner is not None and repo is not None:+ registry.release_repository_owner(repo, owner)+++_download_state = _AudioCppDownloadState()+++def start_model_download(model: Optional[str], hf_token: Optional[str] = None) -> None:+ model = get_audio_cpp_stt_sidecar().keep_loaded_variant(model)+ _download_state.start(str(model or DEFAULT_AUDIO_CPP_STT_MODEL).strip(), hf_token)+++def download_status() -> dict:+ return _download_state.status()+++def cancel_model_download() -> bool:+ return _download_state.cancel()+++class AudioCppSttSidecar:+ """Owns one audiocpp_server serving an ASR model and proxies dictation to it."""++ def __init__(self, keep_alive_seconds: float = STT_KEEP_ALIVE_SECONDS) -> None:+ self._lock = threading.RLock()+ self._load_state_lock = threading.Lock()+ self._server: Optional[AudioCppServer] = None+ self._model_id: Optional[str] = None+ self._model: Optional[AudioCppModel] = None+ # The name the last client used for the loaded model: a legacy key (what Settings and dictation+ # save) is reported back as that key, so their string comparisons keep matching.+ self._loaded_as: Optional[str] = None+ self._forced_cpu = False+ # Where the server actually runs: training also puts it on the CPU, without the user asking.+ self._launched_cpu = False+ self._idle_timer: Optional[threading.Timer] = None+ self._idle_generation = 0+ self._keep_alive_seconds = keep_alive_seconds+ self._loading = False+ self._loading_model: Optional[str] = None+ self._load_cancel_event: Optional[threading.Event] = None+ self._load_owner_cancel_event: Optional[threading.Event] = None+ self._starting_process: Optional[subprocess.Popen] = None+ self._update_in_progress = False++ @property+ def loaded_model(self) -> Optional[str]:+ # Lock-free: transcribe() holds _lock for the whole inference, and status polls must not queue behind it.+ if not self._server_alive():+ return None+ return self._loaded_as or self._model_id++ @property+ def loaded_variant(self) -> Optional[str]:+ model = self._model+ return model.variant.key if model is not None and self._server_alive() else None++ @property+ def device(self) -> Optional[str]:+ server = self._server+ return server.backend if server is not None and server.alive() else None++ @property+ def _gpu_disabled(self) -> Optional[bool]:+ """Whether the live server runs on the CPU backend: the fact training admission reads, not the preference."""+ server = self._server+ if server is None or not server.alive():+ return None+ return server.backend == "cpu"++ def keep_loaded_variant(self, model: Optional[str]) -> Optional[str]:+ """``model`` pinned to the variant already loaded for that same row when it names none.++ A variantless id means "this row", not "this row's default": Settings and dictation send the+ bare row id, and resolving it afresh would swap a loaded Moonshine small for the default+ tiny. An explicit variant, or another row, is left alone.+ """+ loaded = self._model+ if loaded is None or not self._server_alive() or model is None or not str(model).strip():+ return model+ base, variant = split_variant_ref(str(model).strip())+ if variant is not None:+ return model+ ref = parse_identifier(base)+ # A legacy key or sub-folder id names its own variant (``audiocpp-moonshine-tiny``).+ if ref is None or ref.variant_hint or ref.id.lower() != loaded.id.lower():+ return model+ return loaded.canonical_id++ def is_loading(self) -> bool:+ with self._load_state_lock:+ return self._loading++ @property+ def loading_model(self) -> Optional[str]:+ """The row id a load in flight is reading, so a delete of its repo can wait for it."""+ with self._load_state_lock:+ return self._loading_model if self._loading else None++ @property+ def keep_alive_seconds(self) -> float:+ return self._keep_alive_seconds++ def _server_alive(self) -> bool:+ server = self._server+ return server is not None and server.alive()++ def _cancel_idle_unload_locked(self) -> None:+ self._idle_generation += 1+ if self._idle_timer is not None:+ self._idle_timer.cancel()+ self._idle_timer = None++ def _schedule_idle_unload_locked(self) -> None:+ self._cancel_idle_unload_locked()+ if not self._server_alive():+ return+ generation = self._idle_generation+ timer = threading.Timer(self._keep_alive_seconds, self._idle_unload, args = (generation,))+ timer.daemon = True+ self._idle_timer = timer+ timer.start()++ def _idle_unload(self, generation: int) -> None:+ with self._lock:+ if generation != self._idle_generation:+ return+ logger.info("Unloading idle audio.cpp STT model %s", self._model_id)+ self._release_locked()++ def _release_locked(self) -> None:+ self._cancel_idle_unload_locked()+ server = self._server+ self._server = None+ self._model_id = None+ self._model = None+ self._loaded_as = None+ self._forced_cpu = False+ self._launched_cpu = False+ if server is not None:+ server.stop()++ def _holds_expected_model(self, expected: Optional[str]) -> bool:+ if expected is None:+ return True+ current = self._model_id+ if current is None:+ return False+ try:+ # Row ids on both sides: a legacy key and its folder id name the same model.+ return current == acm_row_id(expected)+ except Exception: # noqa: BLE001 - an unresolvable name is not this model+ return False++ def unload(+ self,+ wait: bool = True,+ expected_model: Optional[str] = None,+ ) -> None:+ if not self._lock.acquire(blocking = wait):+ return+ try:+ if not self._holds_expected_model(expected_model):+ return+ self._release_locked()+ finally:+ self._lock.release()++ def _raise_if_update_in_progress(self) -> None:+ if self._update_in_progress:+ raise SttEngineUnavailableError(+ "The audio runtime is being updated. Try dictation again shortly."+ )++ @contextmanager+ def update_maintenance(self) -> Iterator[bool]:+ """Block new loads while the managed audio.cpp tree is replaced.++ The runtime is pinned in source and replaced only by setup, which runs while Studio is+ stopped, so nothing calls this today. It is kept so an in-app updater can reuse the+ whisper.cpp update flow unchanged.+ """+ self._update_in_progress = True+ try:+ with self._lock:+ model_was_active = self._server_alive()+ self._release_locked()+ yield model_was_active+ finally:+ self._update_in_progress = False++ def cancel_pending_load(self) -> bool:+ with self._load_state_lock:+ event = self._load_cancel_event+ if not self._loading or event is None:+ return False+ event.set()+ process = self._starting_process+ if process is not None and process.poll() is None:+ try:+ process.terminate()+ except Exception:+ pass+ return True++ def _cancel_owned_load(self, owner: threading.Event) -> bool:+ with self._load_state_lock:+ event = self._load_cancel_event+ if not self._loading or event is None or self._load_owner_cancel_event is not owner:+ return False+ event.set()+ process = self._starting_process+ if process is not None and process.poll() is None:+ try:+ process.terminate()+ except Exception:+ pass+ return True++ def wait_for_load_to_settle(self) -> None:+ with self._lock:+ pass++ def _ensure_model_downloaded(self, model: AudioCppModel) -> str:+ try:+ return audio_cpp_files.materialize(model)+ except FileNotFoundError:+ raise SttModelNotDownloadedError(+ f"STT model '{model.display_name}' ({model.variant.key}) is not downloaded. "+ "Download it in Settings, then Voice, before loading it."+ ) from None+ except AudioCppUnavailableError as exc:+ # A path the runtime cannot open (Windows MAX_PATH) is a runtime limit, not a missing download.+ raise SttEngineUnavailableError(str(exc)) from exc++ def load(+ self,+ model: Optional[str] = None,+ request_cancel_event: Optional[threading.Event] = None,+ device: Optional[str] = None,+ ) -> None:+ """Start (or switch) audiocpp_server for the requested audio.cpp ASR model."""+ from core.inference.audio_device import audio_device_forces_cpu++ if request_cancel_event is not None and request_cancel_event.is_set():+ raise SttTranscriptionCancelledError("Transcription cancelled.")+ self._raise_if_update_in_progress()+ entry = resolve_audio_cpp_stt_model(self.keep_loaded_variant(model))+ with self._lock:+ if request_cancel_event is not None and request_cancel_event.is_set():+ raise SttTranscriptionCancelledError("Transcription cancelled.")+ self._raise_if_update_in_progress()+ ensure_engine_available()+ force_cpu = (+ self._forced_cpu+ if device is None and self._server_alive()+ else audio_device_forces_cpu(device)+ )+ if (+ self._server_alive()+ and self._model == entry+ and self._forced_cpu == force_cpu+ # A server training moved to the CPU goes back to the GPU once training ends.+ and self._launched_cpu == (force_cpu or _training_active())+ ):+ self._loaded_as = _reported_name(model, entry)+ self._schedule_idle_unload_locked()+ return+ model_path = self._ensure_model_downloaded(entry)+ cancel_event = (+ request_cancel_event if request_cancel_event is not None else threading.Event()+ )+ with self._load_state_lock:+ self._load_cancel_event = cancel_event+ self._load_owner_cancel_event = request_cancel_event+ self._loading = True+ self._loading_model = entry.id+ try:+ if cancel_event.is_set():+ raise SttLoadCancelledError("Dictation model loading was cancelled.")+ # Decided under the loading flag: training admission reads is_loading() without the lock. During training+ # the model goes to CPU so a dictation cannot reclaim the VRAM training just freed.+ run_on_cpu = force_cpu or _training_active()+ self._release_locked()++ def _track(process: subprocess.Popen) -> None:+ with self._load_state_lock:+ self._starting_process = process++ try:+ server = AudioCppServer.start(+ entry,+ model_path,+ force_cpu = run_on_cpu,+ cancel_event = cancel_event,+ on_process = _track,+ )+ except AudioCppStartCancelledError as exc:+ raise SttLoadCancelledError(str(exc)) from exc+ except AudioCppUnavailableError as exc:+ raise SttEngineUnavailableError(str(exc)) from exc+ self._server = server+ self._model_id = entry.id+ self._model = entry+ self._loaded_as = _reported_name(model, entry)+ self._forced_cpu = force_cpu+ self._launched_cpu = run_on_cpu+ self._schedule_idle_unload_locked()+ finally:+ with self._load_state_lock:+ self._loading = False+ self._loading_model = None+ self._load_cancel_event = None+ self._load_owner_cancel_event = None+ self._starting_process = None++ def transcribe(+ self,+ audio: bytes,+ model: Optional[str] = None,+ language: Optional[str] = None,+ fast: bool = False,+ cancel_event: Optional[threading.Event] = None,+ ) -> dict:+ """Transcribe encoded audio bytes via audiocpp_server. Returns {text, language, duration, model}."""+ del fast # audio.cpp ASR families decode greedily; there is no beam knob to trade.+ self._raise_if_update_in_progress()+ ensure_engine_available()+ target = self.keep_loaded_variant(model)+ entry = resolve_audio_cpp_stt_model(target)+ lang = normalize_whisper_language(language)+ if cancel_event is not None and cancel_event.is_set():+ raise SttTranscriptionCancelledError("Transcription cancelled.")+ # A missing model fails before decoding so a long clip does not burn CPU only to 409. The+ # cheap probe first: materialize prunes the link farm, which a warm request does not need.+ if not audio_cpp_files.is_downloaded(entry):+ self._ensure_model_downloaded(entry)+ decoded_audio = _decode_audio_bounded(audio, cancel_event)+ if cancel_event is not None and cancel_event.is_set():+ raise SttTranscriptionCancelledError("Transcription cancelled.")+ wav_bytes = _pcm_to_wav_bytes(decoded_audio)+ with self._lock:+ try:+ # The caller's own name, so a legacy key stays the name status reports.+ if cancel_event is None:+ self.load(target)+ else:+ self.load(target, request_cancel_event = cancel_event)+ text = self._post_transcription(wav_bytes, lang, cancel_event)+ if cancel_event is not None and cancel_event.is_set():+ raise SttTranscriptionCancelledError("Transcription cancelled.")+ except Exception:+ if cancel_event is not None and cancel_event.is_set():+ raise SttTranscriptionCancelledError("Transcription cancelled.")+ raise+ finally:+ self._schedule_idle_unload_locked()+ duration = (len(decoded_audio) / _TARGET_SAMPLE_RATE) if len(decoded_audio) else None+ return {+ "text": text,+ "language": lang,+ "duration": duration,+ "model": _reported_name(model, entry),+ }++ def cancel_transcription(self, cancel_event: threading.Event) -> bool:+ already_cancelled = cancel_event.is_set()+ cancel_event.set()+ return self._cancel_owned_load(cancel_event) or not already_cancelled++ def _post_transcription(+ self, wav_bytes: bytes, lang: Optional[str], cancel_event: Optional[threading.Event]+ ) -> str:+ server = self._server+ if server is None:+ raise SttEngineUnavailableError("The audio runtime is not running.")+ fields = {"model": server.model_id}+ if lang:+ fields["language"] = lang++ def post(form: dict[str, str]) -> bytes:+ return server.post_multipart(+ "/v1/audio/transcriptions",+ form,+ "dictation.wav",+ wav_bytes,+ "audio/wav",+ timeout = _TRANSCRIBE_TIMEOUT_SECONDS,+ cancel_event = cancel_event,+ )[1]++ try:+ try:+ data = post(fields)+ except AudioCppRequestError as exc:+ if "language" not in fields or not 400 <= exc.status < 500:+ raise+ # English-only families (Moonshine, Nemotron, Parakeet) reject a language option; a+ # dictation language preference is a hint, so transcribe without it rather than fail.+ logger.info(+ "audio.cpp: %s rejected language %r (%s); retrying without it",+ server.model.family,+ fields["language"],+ exc.detail,+ )+ data = post({k: v for k, v in fields.items() if k != "language"})+ payload = json.loads(data.decode("utf-8"))+ except AudioCppRequestCancelledError as exc:+ # The server keeps decoding the abandoned clip and would queue the next request behind it;+ # stop it, as speech generation does (the caller holds self._lock).+ self._release_locked()+ raise SttTranscriptionCancelledError("Transcription cancelled.") from exc+ except AudioCppRequestError as exc:+ if 400 <= exc.status < 500:+ # The server rejected this clip or option (e.g. an unsupported language), not a broken runtime.+ raise SttAudioDecodeError(exc.detail) from exc+ note_runtime_inference_failure(str(exc))+ raise SttEngineUnavailableError(f"The audio runtime failed: {exc.detail}") from exc+ except (AudioCppUnavailableError, ValueError) as exc:+ if cancel_event is None or not cancel_event.is_set():+ note_runtime_inference_failure(f"{type(exc).__name__}: {exc}")+ raise SttEngineUnavailableError(+ "The audio runtime did not answer the request."+ ) from exc+ text = payload.get("text") if isinstance(payload, dict) else None+ if not isinstance(text, str):+ raise SttAudioDecodeError("Could not decode the audio.")+ clear_runtime_inference_failure()+ return " ".join(part.strip() for part in text.splitlines() if part.strip()).strip()+++_sidecar: Optional[AudioCppSttSidecar] = None+++def get_audio_cpp_stt_sidecar() -> AudioCppSttSidecar:+ global _sidecar+ if _sidecar is None:+ _sidecar = AudioCppSttSidecar()+ return _sidecardiff --git a/studio/backend/core/inference/stt_registry.py b/studio/backend/core/inference/stt_registry.pyindex cdf30396718..467bd3d5088 100644--- a/studio/backend/core/inference/stt_registry.py+++ b/studio/backend/core/inference/stt_registry.py@@ -22,7 +22,7 @@ logger = get_logger(__name__)# Every engine a dictation model can be resident on. Order is the order an unload sweeps them, which matters only for# logging.-STT_ENGINES = ("transformers", "gguf", "mtmd")+STT_ENGINES = ("transformers", "gguf", "mtmd", "audiocpp")# Serialises load-then-release so two loads on different engines cannot leave both resident._load_lock = threading.Lock()@@ -36,6 +36,9 @@ def sidecar_for(engine: str) -> Any:if engine == "gguf":from core.inference.stt_ggml_sidecar import get_ggml_stt_sidecarreturn get_ggml_stt_sidecar()+ if engine == "audiocpp":+ from core.inference.stt_audiocpp_sidecar import get_audio_cpp_stt_sidecar+ return get_audio_cpp_stt_sidecar()from core.inference.stt_sidecar import get_stt_sidecarreturn get_stt_sidecar()@@ -91,6 +94,13 @@ def _model_is_downloaded(engine: str, model: str) -> bool:if engine == "gguf":from core.inference import stt_ggml_sidecarreturn stt_ggml_sidecar._cached_model_path(model) is not None+ if engine == "audiocpp":+ from core.inference import stt_audiocpp_sidecar++ # A missing runtime refuses the load just as surely as missing weights.+ return stt_audiocpp_sidecar.is_available() and stt_audiocpp_sidecar.is_model_downloaded(+ model+ )from core.inference import stt_sidecarreturn (diff --git a/studio/backend/core/inference/stt_sidecar.py b/studio/backend/core/inference/stt_sidecar.pyindex d6a22889ccb..a2b9cfe4d47 100644--- a/studio/backend/core/inference/stt_sidecar.py+++ b/studio/backend/core/inference/stt_sidecar.py@@ -1785,7 +1785,9 @@ class WhisperSttSidecar:if not self._lock.acquire(blocking = wait):returntry:- if not self._holds_expected_model(expected_model):+ # Nothing resident: the registry releases idle engines on every other engine's+ # transcription, and a full gc.collect each time cost ~130 ms per request.+ if self._model_id is None or not self._holds_expected_model(expected_model):returnself._release_engine_locked()finally:diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.pyindex 881ec60b431..b78e265586b 100644--- a/studio/backend/core/inference/worker.py+++ b/studio/backend/core/inference/worker.py@@ -778,7 +778,15 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:model_info.update({k: _entry[k]- for k in ("is_audio", "audio_type", "has_audio_input", "has_video_input")+ for k in (+ "is_audio",+ "audio_type",+ "has_audio_input",+ "has_video_input",+ "audio_family",+ "audio_options",+ "gguf_variant",+ )if k in _entry})@@ -1583,6 +1591,8 @@ def _handle_generate_audio(backend, cmd: dict, resp_queue: Any, cancel_event) ->request_id = cmd.get("request_id", "")try:logger.info("Starting audio generation for request_id=%s", request_id)+ # Only audio.cpp models take per-model options; other backends never see the keyword.+ extra = {"audio_options": cmd["audio_options"]} if cmd.get("audio_options") else {}wav_bytes, sample_rate = backend.generate_audio_response(text = cmd["text"],temperature = cmd.get("temperature", 0.6),@@ -1596,6 +1606,7 @@ def _handle_generate_audio(backend, cmd: dict, resp_queue: Any, cancel_event) ->instructions = cmd.get("instructions"),language = cmd.get("language"),seed = cmd.get("seed"),+ **extra,)# Send WAV bytes as base64 (bytes can't go through mp.Queue directly).@@ -1858,7 +1869,8 @@ def run_inference_process(# importing Unsloth; native_audio itself has no eager ML imports.from core.inference.native_audio import is_native_audio_model- _native_audio_worker = is_native_audio_model(model_name)+ # The route marks an audio.cpp GGUF, which a bare Hub id does not reveal without a header read.+ _native_audio_worker = bool(config.get("audio_cpp")) or is_native_audio_model(model_name)# Before detect_hardware(), whose probe would leave a CUDA context here; the route# skips the arbiter on the basis that this load reserves none.@@ -2224,7 +2236,12 @@ def run_inference_process(_ensure_backend_on_path()if _native_audio_worker:- from core.inference.native_audio import NativeAudioBackend as InferenceBackend+ from core.inference.native_audio import is_audio_cpp_audio_model+ if config.get("audio_cpp") or is_audio_cpp_audio_model(model_name):+ # Weights run in audiocpp_server; this worker only proxies to it.+ from core.inference.audio_cpp_backend import AudioCppBackend as InferenceBackend+ else:+ from core.inference.native_audio import NativeAudioBackend as InferenceBackendelse:# Recover from any namespace-package shadow before importing Unsloth.from core.import_guards import ensure_real_packagesdiff --git a/studio/backend/hub/services/models/cache_inventory.py b/studio/backend/hub/services/models/cache_inventory.pyindex 9debba84117..0c67d427926 100644--- a/studio/backend/hub/services/models/cache_inventory.py+++ b/studio/backend/hub/services/models/cache_inventory.py@@ -48,6 +48,7 @@ from hub.services.models.common import (from utils.paths.path_utils import is_appledouble_metadatafrom utils.audio_tokens import detect_local_tts_audio_typefrom utils.hidden_models import (+ is_audio_cpp_repo_id,is_curated_stt_repo_id,is_curated_tts_repo_id,is_hidden_model,@@ -474,7 +475,7 @@ def _cache_inventory_fields():capabilities["supports_vision"] = True# Qwen3-ASR's required mmproj is an audio projector, not a vision one, and stt_only covers any repo whose config sniffs as Whisper, curated or not: a third-party checkpoint or a user's own fine-tune is just as unchattable. can_chat is what auto-load and the chat picker filter on, neither of which looks at the task, so task-scoping alone would leave curated STT rows eligible for chat auto-load.- if stt_only or is_curated_stt_repo_id(repo_id):+ if stt_only or is_curated_stt_repo_id(repo_id) or is_audio_cpp_repo_id(repo_id):capabilities["supports_vision"] = Falsecapabilities["can_chat"] = False# The codec probe covers uncurated safetensors copies and native audio architectures are passed explicitly; a GGUF repo ships no tokenizer_config to probe, so the curated ids answer for those.@@ -544,6 +545,11 @@ def _cached_row_companion(repo_id: str, snapshot: Optional[Path] = None) -> boolreturn False+_AUDIO_ONLY_GGUF_TASKS = frozenset(+ {"text-to-speech", "text-to-audio", "automatic-speech-recognition", "audio-to-audio"}+)++def _cached_row_task(repo_info,*,@@ -630,7 +636,7 @@ def _scan_cached_gguf(str(repo_path),str(snapshot_path) if snapshot_path is not None else None,)- is_curated_stt = is_curated_stt_repo_id(repo_id)+ is_curated_stt = is_curated_stt_repo_id(repo_id) or is_audio_cpp_repo_id(repo_id)# Hide infra repos unless the user downloaded a variant: variant state only exists for user downloads, and curated STT repos are still emitted as management rows.if is_hidden_infra and not is_curated_stt and not has_variant_state:continue@@ -700,7 +706,8 @@ def _scan_cached_gguf(gguf_snapshot = gguf_snapshot,repo_info = repo_info,hidden_infra = is_hidden_infra,- tts_only = row_task == "text-to-speech",+ # Only the audio runtime serves these, standalone repos included (Yue2, MiniMax).+ tts_only = row_task in _AUDIO_ONLY_GGUF_TASKS,))# Preserve a snapshot-pinned load id for a single cache: refs/main can@@ -1095,7 +1102,7 @@ def _scan_cached_models(str(repo_path),str(snapshot_path) if snapshot_path is not None else None,)- is_curated_stt = is_curated_stt_repo_id(repo_id)+ is_curated_stt = is_curated_stt_repo_id(repo_id) or is_audio_cpp_repo_id(repo_id)snapshot_metadata = _cached_model_local_metadata(repo_path, snapshot_path)is_whisper_stt = bool(snapshot_metadata.get("_hidden_stt"))if is_hidden_infra and not is_curated_stt and not is_whisper_stt:diff --git a/studio/backend/hub/services/models/catalog_classification.py b/studio/backend/hub/services/models/catalog_classification.pyindex a5d39af0c57..08e717b9ff3 100644--- a/studio/backend/hub/services/models/catalog_classification.py+++ b/studio/backend/hub/services/models/catalog_classification.py@@ -16,7 +16,11 @@ from hub.services.models.common import (_iter_gguf_paths,_local_path_can_chat,)-from utils.gguf_archs import SPEECH_GGUF_ARCHS, is_speech_gguf_architecture+from utils.gguf_archs import (+ SPEECH_GGUF_ARCHS,+ is_audio_cpp_gguf_architecture,+ is_speech_gguf_architecture,+)from utils.paths.path_utils import file_contents_available_locally@@ -34,6 +38,8 @@ _VIDEO_GEN_TASK = "text-to-video"# and the media preflight all have to agree._SPEECH_GGUF_ARCHS = SPEECH_GGUF_ARCHS_SPEECH_TASK = "text-to-speech"+# An audio.cpp GGUF of a kind Studio has no page for (separation, diarization, ...): not chat either.+_AUDIO_CPP_UNSUPPORTED_TASK = "audio-to-audio"_UNSUPPORTED_DIFFUSION_TASK = "image-diffusion-unsupported"_H3_DENOISER_GGUF_PREFIXES = ("minimax_h3_fl2va", "minimax_h3_ref2va")_LOADABLE_MEDIA_GGUF_TASKS = frozenset({"text-to-image", _VIDEO_GEN_TASK})@@ -175,6 +181,39 @@ def _unhydrated_gguf_task(name_hints: tuple[Optional[str], ...]) -> Optional[strreturn _name_hint_media_task(leaves, None)+def _audio_cpp_classification(+ path: Optional[str | Path], name_hints: tuple[Optional[str], ...]+) -> tuple[str, Optional[str]]:+ """``(task, audio_type)`` of an audio.cpp GGUF: its family from the header when a path is given,+ else from the names, mapped to the page that runs it."""+ try:+ from core.inference import audio_cpp_models as acm+ except Exception:+ return _SPEECH_TASK, None+ header = acm.read_local_header(path) if path is not None else None+ names = tuple(str(hint) for hint in name_hints if hint)+ family = (header.family if header is not None else None) or acm.family_from_names(names)+ if not family:+ return _AUDIO_CPP_UNSUPPORTED_TASK, None+ policy = acm.family_policy(family, header.spec if header is not None else None, names)+ task = acm.HUB_TASKS.get(policy.task)+ if task is None or policy.unsupported:+ return _AUDIO_CPP_UNSUPPORTED_TASK, None+ audio_type = {+ "tts": acm.AUDIO_CPP_TTS_AUDIO_TYPE,+ "music": acm.AUDIO_CPP_MUSIC_AUDIO_TYPE,+ }.get(policy.task)+ return task, audio_type+++def _gguf_file_task(path: str | Path, name_hints: tuple[Optional[str], ...]) -> Optional[str]:+ """``_arch_to_task`` for a file on disk, which can also read an audio.cpp family."""+ arch = _gguf_architecture(str(path))+ if is_audio_cpp_gguf_architecture(arch):+ return _audio_cpp_classification(path, name_hints)[0]+ return _arch_to_task(arch, name_hints = name_hints)++def _arch_to_task(arch: Optional[str], name_hints: tuple[Optional[str], ...] = ()) -> Optional[str]:if any(_is_h3_bundle_gguf_hint(hint) for hint in name_hints):return _VIDEO_GEN_TASK@@ -182,6 +221,8 @@ def _arch_to_task(arch: Optional[str], name_hints: tuple[Optional[str], ...] = (# Qwen-Image-2.1 GGUFs have kv_count 0, so the name is the only evidence, as for a cloud placeholder.return _unhydrated_gguf_task(name_hints)normalized = arch.lower()+ if is_audio_cpp_gguf_architecture(normalized):+ return _audio_cpp_classification(None, name_hints)[0]if normalized == "qwen3" and any(_QWEN3_ASR_HINT.search(str(hint)) for hint in name_hints if hint):@@ -241,6 +282,8 @@ def _arch_to_audio_type(if arch is None:return Nonenormalized = arch.strip().lower()+ if is_audio_cpp_gguf_architecture(normalized):+ return _audio_cpp_classification(None, name_hints)[1]if normalized == "llama" and any(_ORPHEUS_GGUF_HINT.search(str(hint)) for hint in name_hints if hint):@@ -309,7 +352,7 @@ def _gguf_folder_task(hints = id_hints + (path.name,)try:if file_contents_available_locally(path):- task = _arch_to_task(_gguf_architecture(str(path)), name_hints = hints)+ task = _gguf_file_task(path, hints)else:# Its header stays unread, so a name that says nothing leaves the candidate unclassified rather than# voting text-generation for the whole folder.@@ -353,10 +396,12 @@ def _gguf_path_audio_type(# No extension check: an Ollama model is a blob named by its digest.paths = [model_path] if model_path.is_file() else _iter_gguf_paths(model_path)for gguf_path in paths:- audio_type = _arch_to_audio_type(- _gguf_architecture(str(gguf_path)),- name_hints = id_hints + (gguf_path.name,),- )+ hints = id_hints + (gguf_path.name,)+ arch = _gguf_architecture(str(gguf_path))+ if is_audio_cpp_gguf_architecture(arch):+ audio_type = _audio_cpp_classification(gguf_path, hints)[1]+ else:+ audio_type = _arch_to_audio_type(arch, name_hints = hints)if audio_type is not None:return audio_typeexcept Exception:@@ -379,10 +424,7 @@ def _gguf_path_task(path: str | Path, id_hints: tuple[Optional[str], ...] = ())hints = id_hints + (model_path.name,)if not file_contents_available_locally(model_path):return _unhydrated_gguf_task(hints)- return _arch_to_task(- _gguf_architecture(str(model_path)),- name_hints = hints,- )+ return _gguf_file_task(model_path, hints)return _gguf_folder_task(model_path, id_hints)except Exception:return Nonediff --git a/studio/backend/hub/services/models/deletion.py b/studio/backend/hub/services/models/deletion.pyindex 6462ff50d1e..7ae59ab58c6 100644--- a/studio/backend/hub/services/models/deletion.py+++ b/studio/backend/hub/services/models/deletion.py@@ -260,6 +260,28 @@ def _variant_keys_to_delete(target_repo, variant: str) -> set[str]:return aliased if len(aliased) == 1 else {wanted}+def _audio_cpp_package_scope(target_repo, variant: str) -> tuple[frozenset[str], frozenset[str]]:+ """``(own files, protected files)`` of an audio.cpp package mix being deleted.++ A package mix (MiniMax Music 3, YuE2) is several GGUFs plus configs, some of them shared with+ other mixes, so the quant key alone neither finds all of its files nor knows which a sibling+ still needs. Own files are the mix's whole file list; protected files are every file of the+ other mixes still fully on disk. Both empty for any other repo.+ """+ try:+ from core.inference.audio_cpp_models import package_variant_files+ except Exception: # noqa: BLE001 - no audio.cpp support, no package layout+ return frozenset(), frozenset()+ names = [name for _snap, _blob, name in _repo_file_matches(target_repo, lambda name: True)]+ packages = package_variant_files(names)+ if not packages:+ return frozenset(), frozenset()+ wanted = (variant or "").strip().lower()+ own = next((files for key, files in packages.items() if key.lower() == wanted), ())+ protected = {path for key, files in packages.items() if key.lower() != wanted for path in files}+ return frozenset(own), frozenset(protected)++def _delete_gguf_variant_from_repos(repo_id: str,variant: str,@@ -278,11 +300,18 @@ def _delete_gguf_variant_from_repos(for target_repo in target_repos:repo_dir = Path(target_repo.repo_path) if getattr(target_repo, "repo_path", None) else Nonewanted_keys = _variant_keys_to_delete(target_repo, variant)- matched = _repo_file_matches(- target_repo,- lambda name, keys = wanted_keys: _is_main_gguf_filename(name)- and gguf_variant_key(name).lower() in keys,- )+ package_files, protected = _audio_cpp_package_scope(target_repo, variant)+ matched = [+ match+ for match in _repo_file_matches(+ target_repo,+ lambda name, keys = wanted_keys: name in package_files+ or (_is_main_gguf_filename(name) and gguf_variant_key(name).lower() in keys),+ )+ # A component another downloaded mix still loads (MiniMax's Q4_0 and Q8_0 share one+ # depth decoder) stays.+ if match[2] not in protected+ ]for snap, _blob, name in matched:try:@@ -877,6 +906,8 @@ async def delete_cached_model_response(_inference_backend_blocks_delete(repo_id)):return "Unload the model before deleting"+ if _audio_cpp_blocks_delete(repo_id):+ return "Unload the audio model before deleting"return _diffusion_blocks_delete(repo_id) or _video_blocks_delete(repo_id)try:@@ -916,7 +947,7 @@ async def delete_cached_model_response(status_code = 400,detail = blocks_detail,)- return await asyncio.to_thread(+ result = await asyncio.to_thread(_delete_cached_model_blocking,repo_id,variant,@@ -924,11 +955,52 @@ async def delete_cached_model_response(cache_path,only_if_orphan = only_if_orphan,)+ # The audio.cpp link farm hardlinks the deleted blobs; without this they keep their disk space.+ # Any GGUF repo can be an audio.cpp model, and pruning an absent or current farm is a no-op.+ from core.inference.audio_cpp_files import prune_link_farm+ from hub.utils.hf_cache_state import hf_cache_roots++ # Every remembered root, not one recomputed from cache_path: an omitted path deletes from+ # the sole owning cache, which need not be the active one. Pruning drops only stale entries.+ def _prune_all() -> None:+ for root in hf_cache_roots():+ prune_link_farm(root)++ await asyncio.to_thread(_prune_all)+ from core.inference.audio_cpp_models import forget++ forget()+ return resultfinally:downloads.registry.end_delete(repo_key, variant)cache_inventory.invalidate_hf_cache_scans()+def _audio_cpp_blocks_delete(repo_id: str) -> bool:+ """Whether an audio.cpp model from this repo is resident or loading. An umbrella id names a+ subfolder of the repo, so the id comparisons of the other guards never match it."""+ from core.inference.audio_cpp_models import repo_of+ from core.inference.orchestrator import peek_inference_backend+ from core.inference.stt_audiocpp_sidecar import get_audio_cpp_stt_sidecar++ wanted = (repo_id or "").strip().lower()++ def holds(name) -> bool:+ repo = repo_of(name) if isinstance(name, str) else None+ return bool(repo and repo.lower() == wanted)++ backend = peek_inference_backend()+ active = getattr(backend, "active_model_name", None) if backend is not None else None+ loading = tuple(getattr(backend, "loading_models", ()) or ()) if backend is not None else ()+ sidecar = get_audio_cpp_stt_sidecar()+ return (+ holds(active)+ or any(holds(name) for name in loading)+ or holds(sidecar.loaded_model)+ or holds(sidecar.loading_model)+ )++def _delete_cached_model_blocking(repo_id: str,variant: Optional[str],diff --git a/studio/backend/hub/services/models/downloads.py b/studio/backend/hub/services/models/downloads.pyindex ec77bc73578..6ac72ebc3d1 100644--- a/studio/backend/hub/services/models/downloads.py+++ b/studio/backend/hub/services/models/downloads.py@@ -186,6 +186,33 @@ def _spawn_download_worker()+async def _audio_cpp_target(+ repo_id: str,+ variant: Optional[str],+ hf_token: Optional[str] = None,+) -> tuple[str, Optional[str]]:+ """``(repo, variant)`` a download of an audio.cpp umbrella folder row really works on.++ Studio names such a model ``audio-cpp/audio.cpp-gguf/<Folder>`` with a quant, like any GGUF+ repo; the job, its progress and its cancel run on the umbrella repo and the path-qualified key+ the variant planner gives that file. Anything else passes through unchanged.+ """+ text = (repo_id or "").strip()+ if not text.lower().startswith("audio-cpp/audio.cpp-gguf/"):+ return text, variant+ try:+ from core.inference.audio_cpp_models import download_target+ target = await asyncio.to_thread(+ download_target, text, (variant or "").strip() or None, hf_token+ )+ except Exception as exc: # noqa: BLE001 - an unresolvable row downloads nothing+ logger.warning("Could not resolve the audio model %s for download: %s", text, exc)+ target = None+ if target is None:+ raise HTTPException(status_code = 404, detail = f"No downloadable GGUF variant in {text}.")+ return target++async def download_model_response(body: DownloadModelRequest,hf_token: Optional[str] = None,@@ -203,6 +230,12 @@ async def download_model_response(raise HTTPException(status_code = 403, detail = "Account is retired")hf_token = account_access.account_hf_token(hf_token)allow_ambient_token = allow_ambient_token and not account_access.managed_account()+ if body.gguf_variant or not body.scope_id:+ target_repo, target_variant = await _audio_cpp_target(+ body.repo_id, body.gguf_variant, hf_token+ )+ if target_repo != body.repo_id.strip():+ body = body.model_copy(update = {"repo_id": target_repo, "gguf_variant": target_variant})repo_id = body.repo_id.strip()if not _is_valid_repo_id(repo_id):raise HTTPException(@@ -429,6 +462,9 @@ def retire_account_downloads() -> None:async def cancel_download_model_response(body: CancelDownloadRequest):"""Cancel an in-flight model download (SIGKILL; HF cache resumes on next download)."""+ target_repo, target_variant = await _audio_cpp_target(body.repo_id, body.gguf_variant)+ if target_repo != body.repo_id.strip():+ body = body.model_copy(update = {"repo_id": target_repo, "gguf_variant": target_variant})repo_id = body.repo_id.strip()if not _is_valid_repo_id(repo_id):raise HTTPException(@@ -461,18 +497,42 @@ async def cancel_download_model_response(body: CancelDownloadRequest):async def get_download_status_response(repo_id: str, gguf_variant: str = "") -> DownloadJobStatus:"""Return the latest state of a background download job."""+ requested = (repo_id or "").strip(), (gguf_variant or "").strip() or None+ try:+ repo_id, gguf_variant = await _audio_cpp_target(repo_id, gguf_variant)+ except HTTPException:+ return DownloadJobStatus(state = "idle")repo_id = repo_id.strip()if not _is_valid_repo_id(repo_id):return DownloadJobStatus(state = "idle")repo_id = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "model")variant = (gguf_variant or "").strip() or Nonekey = _download_job_key(repo_id, variant)- return _job_status(key, repo_id = repo_id, variant = variant)+ status = _job_status(key, repo_id = repo_id, variant = variant)+ if requested[0] != repo_id:+ # An umbrella folder row: echo the names the caller asked about, not the umbrella job's.+ update = {+ name: value+ for name, value in (("repo_id", requested[0]), ("variant", requested[1]))+ if name in type(status).model_fields+ }+ status = status.model_copy(update = update) if update else status+ return statusasync def get_active_downloads_response(repo_id: str = "") -> ActiveDownloadsResponse:- """Return every in-flight download for a repo in a single call."""+ """Return every in-flight download for a repo in a single call.++ Jobs of audio.cpp umbrella folder rows run on the umbrella repo; they are reported under the+ row id and variant Studio started them with, and a row id filters to that row's jobs.+ """+ from core.inference.audio_cpp_models import folder_row_for_download, repo_of+repo_id = repo_id.strip()+ row_filter = None+ if repo_id.lower().startswith("audio-cpp/audio.cpp-gguf/"):+ row_filter = repo_id.lower()+ repo_id = repo_of(repo_id) or repo_idif repo_id and not _is_valid_repo_id(repo_id):return ActiveDownloadsResponse(downloads = [])canonical_repo_id = (@@ -480,14 +540,24 @@ async def get_active_downloads_response(repo_id: str = "") -> ActiveDownloadsResif repo_idelse None)- return ActiveDownloadsResponse(- downloads = download_lifecycle.active_download_refs(- _registry,- canonical_repo_id,- with_variant = True,- )+ refs = download_lifecycle.active_download_refs(+ _registry,+ canonical_repo_id,+ with_variant = True,)+ def _as_rows():+ out = []+ for ref in refs:+ row = folder_row_for_download(ref.repo_id, ref.variant)+ if row is not None:+ ref = ref.model_copy(update = {"repo_id": row[0], "variant": row[1]})+ if row_filter is None or ref.repo_id.lower() == row_filter:+ out.append(ref)+ return out++ return ActiveDownloadsResponse(downloads = await asyncio.to_thread(_as_rows))+def _variant_transport_status(repo_id: str, variant: str, hf_token: Optional[str]) -> dict:incomplete_hashes = download_registry.incomplete_blob_hashes(@@ -552,6 +622,10 @@ async def get_model_transport_status_response(because ``hf_xet`` rewrites the destination from scratch on everycall (network resume happens transparently via its chunk cache)."""+ try:+ repo_id, gguf_variant = await _audio_cpp_target(repo_id, gguf_variant, hf_token)+ except HTTPException:+ passif account_access.managed_account():await asyncio.to_thread(account_access.require_download_progress_access, _registry, repo_id)hf_token = account_access.account_hf_token(hf_token)@@ -647,6 +721,11 @@ async def get_gguf_download_progress_response(hf_token: Optional[str] = None,) -> dict:"""Return download progress for a specific GGUF variant."""+ try:+ repo_id, variant = await _audio_cpp_target(repo_id, variant, hf_token)+ except HTTPException:+ pass+ variant = variant or ""if account_access.managed_account():await asyncio.to_thread(account_access.require_download_progress_access, _registry, repo_id)hf_token = account_access.account_hf_token(hf_token)diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.pyindex 62e5bfc551f..ad05a4cf3da 100644--- a/studio/backend/hub/services/models/gguf_variants.py+++ b/studio/backend/hub/services/models/gguf_variants.py@@ -1059,6 +1059,74 @@ def _default_variant_candidates(variants) -> list[str]:return root_rows or [v.filename for v in variants]+async def _audio_cpp_variants_answer(+ repo_id: str, hf_token: Optional[str], offline: bool+) -> Optional[VariantsAnswer]:+ """The listing for an audio.cpp umbrella folder row or package repo, else None.++ An umbrella folder (``audio-cpp/audio.cpp-gguf/<Folder>``) is not a repo the generic lister can+ read, and a package's quants are component mixes plus config files, which grouping GGUFs by quant+ would split into meaningless rows. Single-file audio.cpp repos list like any GGUF repo.+ """+ from core.inference import audio_cpp_models++ text = (repo_id or "").strip()+ umbrella = audio_cpp_models.is_umbrella_id(text)+ if not umbrella and not (_is_valid_repo_id(text) and text.lower().startswith("audio-cpp/")):+ return None+ real_repo = audio_cpp_models.repo_of(text) or text+ if account_access.managed_account():+ await asyncio.to_thread(account_access.require_model_access, real_repo)+ network = not (offline or audio_cpp_models.hub_offline())+ try:+ model = await asyncio.to_thread(+ audio_cpp_models.resolve, text, None, hf_token, network = network+ )+ except Exception as exc: # noqa: BLE001 - the generic lister reports an unreadable repo+ logger.debug("audio.cpp variants for %s unavailable: %s", text, exc)+ model = None+ if model is None:+ if umbrella:+ raise HTTPException(status_code = 404, detail = f"No GGUF variants found in {text}.")+ return None+ if not umbrella and not model.is_package:+ return None+ from core.inference import audio_cpp_files++ def _details():+ rows = []+ for variant in model.variants:+ downloaded = audio_cpp_files.cached_files(model.with_variant(variant)) is not None+ rows.append(+ GgufVariantDetail(+ filename = variant.main_file,+ quant = variant.key,+ display_label = variant.label,+ size_bytes = variant.size_bytes,+ download_size_bytes = variant.size_bytes,+ downloaded = downloaded,+ )+ )+ return rows++ details = await asyncio.to_thread(_details)+ loadable = [row.quant for row in details if row.downloaded]+ return VariantsAnswer(+ GgufVariantsResponse(+ repo_id = model.id,+ variants = details,+ has_vision = False,+ default_variant = model.default_variant,+ dependencies_resolved = True,+ loadable_variants = loadable,+ loadable = bool(loadable),+ ),+ None,+ # No llama.cpp context window to read off these files.+ cache_authorized = False,+ )++async def get_gguf_variants_answer(repo_id: str,prefer_local_cache: bool = False,@@ -1079,6 +1147,10 @@ async def get_gguf_variants_answer(if account_access.managed_account():await asyncio.to_thread(account_access.require_model_access, local_path)hf_token = account_access.account_hf_token(hf_token)+ if not local_path:+ audio_cpp_answer = await _audio_cpp_variants_answer(repo_id, hf_token, offline)+ if audio_cpp_answer is not None:+ return audio_cpp_answerif account_access.managed_account():try:await asyncio.to_thread(account_access.require_model_access, repo_id)diff --git a/studio/backend/hub/utils/gguf_plan.py b/studio/backend/hub/utils/gguf_plan.pyindex ebaf4552a3a..d661bef144e 100644--- a/studio/backend/hub/utils/gguf_plan.py+++ b/studio/backend/hub/utils/gguf_plan.py@@ -271,9 +271,86 @@ def dflash_plan_files(return eligible[best]+def _audio_cpp_package_plans(siblings: Sequence) -> Optional[dict[str, GgufVariantPlan]]:+ """Plans for an audio.cpp package repo (MiniMax Music 3, YuE2): each variant is a component mix+ plus the config, tokenizer and sidecar files the package loads with. Files every mix shares+ are companions, so deleting one mix never counts them as its own weights."""+ try:+ from core.inference.audio_cpp_models import package_variant_files+ except Exception:+ return None+ by_name = {+ name: sibling+ for sibling in siblings+ if isinstance(name := getattr(sibling, "rfilename", None), str)+ }+ packages = package_variant_files(by_name)+ if not packages:+ return None+ shared = set.intersection(*(set(files) for files in packages.values()))+ plans: dict[str, GgufVariantPlan] = {}+ for key, files in packages.items():+ expected = tuple(+ file+ for name in files+ if (file := expected_file_from_sibling(by_name[name])) is not None+ )+ main_files = tuple(+ file for file in expected if is_gguf_filename(file.path) and file.path not in shared+ )+ companions = tuple(file for file in expected if file.path in shared)+ plans[key.lower()] = GgufVariantPlan(+ main_filenames = frozenset(file.path for file in main_files),+ target_filenames = tuple(file.path for file in expected),+ main_hashes = frozenset(file.sha256 for file in main_files if file.sha256),+ required_hashes = frozenset(file.sha256 for file in expected if file.sha256),+ companion_hashes = frozenset(file.sha256 for file in companions if file.sha256),+ mmproj_filenames = frozenset(),+ mmproj_hashes = frozenset(),+ expected_files = expected,+ main_size_bytes = sum(max(0, int(file.size or 0)) for file in main_files),+ download_size_bytes = sum(max(0, int(file.size or 0)) for file in expected),+ )+ return plans+++def _with_audio_cpp_voices(plan: GgufVariantPlan, siblings: Sequence) -> GgufVariantPlan:+ """*plan* plus the voice embeddings audio.cpp reads beside its GGUF (``<dir>/embeddings/*``), as+ PocketTTS publishes them. A GGUF with no such folder beside it is returned unchanged."""+ dirs = {name.rpartition("/")[0] for name in plan.main_filenames}+ if len(dirs) != 1:+ return plan+ prefix = f"{next(iter(dirs))}/embeddings/".lstrip("/")+ extras = tuple(+ file+ for sibling in siblings+ if isinstance(name := getattr(sibling, "rfilename", None), str)+ and name.startswith(prefix)+ and name.lower().endswith(".safetensors")+ and (file := expected_file_from_sibling(sibling)) is not None+ )+ if not extras:+ return plan+ hashes = frozenset(file.sha256 for file in extras if file.sha256)+ from dataclasses import replace++ return replace(+ plan,+ target_filenames = (*plan.target_filenames, *(file.path for file in extras)),+ required_hashes = plan.required_hashes | hashes,+ companion_hashes = plan.companion_hashes | hashes,+ expected_files = (*plan.expected_files, *extras),+ download_size_bytes = plan.download_size_bytes+ + sum(max(0, int(file.size or 0)) for file in extras),+ )++def build_gguf_variant_plans(siblings: Sequence) -> dict[str, GgufVariantPlan]:# Family grouping keeps the family holding the lexicographically first name, which is the "._" one, so the plan fetched the sidecar and marked the variant complete, leaving header-based local discovery no main GGUF to load.siblings = drop_shadowed_appledouble_siblings(list(siblings))+ package_plans = _audio_cpp_package_plans(siblings)+ if package_plans is not None:+ return package_plansmain: dict[str, list] = {}all_mmproj = mmproj_siblings(siblings)all_mmproj_filenames = frozenset(@@ -331,11 +408,14 @@ def build_gguf_variant_plans(siblings: Sequence) -> dict[str, GgufVariantPlan]:*mtp_expected,*dflash_expected,)- plans[quant] = plan_from_expected_files(- quant,- expected_files,- all_mmproj_filenames = all_mmproj_filenames,- all_mmproj_hashes = all_mmproj_hashes,+ plans[quant] = _with_audio_cpp_voices(+ plan_from_expected_files(+ quant,+ expected_files,+ all_mmproj_filenames = all_mmproj_filenames,+ all_mmproj_hashes = all_mmproj_hashes,+ ),+ siblings,)return plansdiff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.pyindex c2a53858379..e5f18fbd8c7 100644--- a/studio/backend/models/inference.py+++ b/studio/backend/models/inference.py@@ -488,7 +488,8 @@ class TranscribeRequest(BaseModel):)engine: Optional[str] = Field(None,- description = "STT engine: 'transformers' (default) or 'gguf' (whisper.cpp)",+ description = "STT engine: 'transformers' (default), 'gguf' (whisper.cpp), 'mtmd' (llama.cpp) "+ "or 'audiocpp' (audio.cpp)",)device: Optional[Literal["auto", "cpu", "gpu"]] = Field(None,@@ -506,7 +507,8 @@ class SttLoadRequest(BaseModel):model: Optional[str] = Field(None, description = "STT model id; defaults server-side")engine: Optional[str] = Field(None,- description = "STT engine: 'transformers' (default) or 'gguf' (whisper.cpp)",+ description = "STT engine: 'transformers' (default), 'gguf' (whisper.cpp), 'mtmd' (llama.cpp) "+ "or 'audiocpp' (audio.cpp)",)device: Optional[Literal["auto", "cpu", "gpu"]] = Field(None,@@ -515,6 +517,32 @@ class SttLoadRequest(BaseModel):"'gpu' prefers the accelerator, 'auto' (default) detects."),)+ gguf_variant: Optional[str] = Field(+ None,+ description = (+ "Variant of an audio GGUF dictation model (engine 'audiocpp'): a quant or a named "+ "sub-variant such as 'tiny'. Omitted picks the model's default."+ ),+ )++ @model_validator(mode = "after")+ def _fold_audio_gguf_variant(self):+ # The audio.cpp sidecar takes ``id:variant``, so every route that resolves, downloads,+ # loads or compares the model sees the same string.+ engine = (self.engine or "").strip().lower()+ model = (self.model or "").strip()+ variant = (self.gguf_variant or "").strip()+ if (+ variant+ and model+ and ":" not in model+ and (+ engine in ("audiocpp", "audio_cpp", "audio.cpp")+ or model.lower().startswith(("audio-cpp/", "audiocpp-"))+ )+ ):+ self.model = f"{model}:{variant}"+ return selfclass ValidateModelRequest(LlamaCppConfigFields):@@ -1293,6 +1321,16 @@ class _InferenceRuntimeFields(BaseModel):description = "Audio codec or native generation architecture.",)has_audio_input: bool = Field(False, description = "Whether model accepts audio input (ASR)")+ audio_family: Optional[str] = Field(+ None, description = "Loader family of an audio GGUF model (e.g. kokoro_tts, minimax_music3)."+ )+ audio_options: Optional[List[Dict[str, Any]]] = Field(+ None,+ description = (+ "Request options an audio GGUF model accepts: {name, type (bool|int|float|string|enum), "+ "description, default, min, max, values, required}. Send chosen values as audio_options."+ ),+ )has_video_input: bool = Field(False,description = (@@ -2443,6 +2481,13 @@ class ChatCompletionRequest(BaseModel):None,description = "[x-unsloth] Target-language hint for native audio models that support it.",)+ audio_options: Optional[Dict[str, Any]] = Field(+ None,+ description = (+ "[x-unsloth] Per-model request options ({name: value}) for audio GGUF models, as listed "+ "in the loaded model's audio_options. Unknown names are dropped."+ ),+ )video_base64: Optional[str] = Field(None,description = (@@ -4974,6 +5019,13 @@ class AudioSpeechRequest(BaseModel):"Maximum generated audio tokens/frames; MiniMax Music 3 uses 25 frames per second."),)+ audio_options: Optional[Dict[str, Any]] = Field(+ None,+ description = (+ "[x-unsloth] Per-model request options ({name: value}) for audio GGUF models, as listed "+ "in the loaded model's audio_options. Unknown names are dropped."+ ),+ )provider_id: Optional[str] = Field(None,description = "[x-unsloth] Saved connection ID. When set, synthesis is proxied to that "diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.pyindex 2bdb41a6969..5dd1cc7992b 100644--- a/studio/backend/routes/inference.py+++ b/studio/backend/routes/inference.py@@ -553,6 +553,8 @@ _MIN_SPEECH_OUTPUT_TOKENS = 64# than this and 32 tokens off a 2048 context is not worth threading it up here._TTS_PROMPT_FORMAT_RESERVE = 32_MINIMAX_MUSIC3_DEFAULT_FRAMES = 750+# audio_cpp_backend caps a clip at 240 seconds; 25 frames per second.+_AUDIO_CPP_MUSIC_MAX_FRAMES = 240 * 25# A 24 GB-class card reports slightly less than 24.0 GiB through free-VRAM# telemetry even when idle. Keep the admission floor below that value._MINIMAX_MUSIC3_RESIDENT_GB = 23.0@@ -573,6 +575,9 @@ def _tts_max_new_tokens(both the Unsloth and OpenAI routes inherit it."""moss_generation = audio_type in ("moss_tts_local", "moss_tts_nano")+ # audio.cpp music reads the budget as a duration at MiniMax's 25 frames per second, so it+ # shares MiniMax's defaults under its own 240-second ceiling.+ music_generation = audio_type in ("minimax_music3", "audiocpp_music")context_length = _monitor_context_length() if moss_generation or prompt else Nonetoken_ceiling = (context_length or MOSS_TTS_MAX_FRAMES@@ -580,14 +585,18 @@ def _tts_max_new_tokens(else (MINIMAX_MUSIC_MAX_FRAMESif audio_type == "minimax_music3"- else AUDIO_GENERATION_MAX_TOKENS+ else (+ _AUDIO_CPP_MUSIC_MAX_FRAMES+ if audio_type == "audiocpp_music"+ else AUDIO_GENERATION_MAX_TOKENS+ )))budget = min(token_ceiling,max(1, int(_effective_max_tokens(payload) or 2048)),)- if speech_api_default_max_tokens and audio_type == "minimax_music3":+ if speech_api_default_max_tokens and music_generation:budget = min(budget, _MINIMAX_MUSIC3_DEFAULT_FRAMES)if prompt and context_length:budget = min(@@ -8077,6 +8086,9 @@ def _llama_runtime_fields(llama_backend: LlamaCppBackend) -> dict:context_length_enforced = True,context_length_fitted = None,context_unbounded_when_batched = False,+ # llama-server never serves an audio GGUF; those load through the audio worker.+ audio_family = None,+ audio_options = None,# Older/custom backend doubles predate this additive runtime field.preserve_thinking_default = bool(getattr(llama_backend, "preserve_thinking_default", False)),speculative_type = llama_backend.requested_spec_mode,@@ -10484,6 +10496,36 @@ def _own_local_model_for_alias(alias: str) -> Optional[str]:return None+def _audio_cpp_switch_target(requested_model: Optional[str]) -> Optional[tuple]:+ """Switch target for a downloaded audio.cpp speech or music GGUF, in the resolver's+ ``(target_id, variant, override_id, repo_level)`` shape, else None.++ Answered from the HF cache alone: an umbrella folder id cannot be keyed by the local index,+ and a dedicated repo's GGUF would otherwise be handed to llama-server.+ """+ from core.inference import audio_cpp_files+ from core.inference.audio_cpp_models import parse_identifier, resolve, split_variant_ref+ from core.inference.audio_cpp_server import model_runtime_problem++ if not isinstance(requested_model, str):+ return None+ base, _variant = split_variant_ref(requested_model)+ if parse_identifier(base) is None:+ return None+ try:+ model = resolve(requested_model, network = False)+ except Exception: # noqa: BLE001 - not resolvable from the cache: not a switch target+ return None+ if model is None or model.audio_type is None or not audio_cpp_files.is_downloaded(model):+ return None+ # A switch evicts the resident model before the new one starts, so a runtime that cannot+ # 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)+ return (model.id, model.variant.key, model.id, False)++async def _maybe_auto_switch_model(requested_model: Optional[str],fastapi_request: Request,@@ -10677,12 +10719,16 @@ async def _maybe_auto_switch_model(repo_level_companion_resolution = Falsestashed_gguf_companion_roots: tuple[str, ...] = ()if auto_switch_on and not reload_only:- # Use trusted hits immediately. The switch resolver refreshes stale hits- # and unconfirmed misses, keeping removed scan roots out of switches.- resolved = resolve_trusted_cached_local_gguf(- requested_model,- include_companion_scope = True,- )+ # An audio.cpp GGUF loads through the audio worker, never llama-server, and an umbrella+ # folder id is not a repo the local index can key; the HF cache answers both.+ resolved = await asyncio.to_thread(_audio_cpp_switch_target, requested_model)+ if resolved is None:+ # Use trusted hits immediately. The switch resolver refreshes stale hits+ # and unconfirmed misses, keeping removed scan roots out of switches.+ resolved = resolve_trusted_cached_local_gguf(+ requested_model,+ include_companion_scope = True,+ )if resolved is not None:warm_index_soon()else:@@ -10755,8 +10801,13 @@ async def _maybe_auto_switch_model(requested_base,(override_id, public_model_id(override_id)),)- # Not inferred from the quant: a GGUF loaded from a local directory carries none.- target_is_gguf = await asyncio.to_thread(local_target_is_gguf, target_id, override_id)+ # Not inferred from the quant: a GGUF loaded from a local directory carries none. An+ # audio.cpp GGUF is a GGUF too, but one only audiocpp_server reads, never llama.cpp.+ from core.inference.audio_cpp_models import looks_like_audio_cpp++ target_is_gguf = not looks_like_audio_cpp(target_id) and await asyncio.to_thread(+ local_target_is_gguf, target_id, override_id+ )gguf_companion_roots: tuple[str, ...] = ()if target_is_gguf:if resolved is None:@@ -15279,6 +15330,56 @@ async def _prepare_load_placement(return _LoadPlacement(requested, resolved, is_vulkan, diffusion_kind)+def _audio_intent_gguf_refusal(config, request) -> Optional[str]:+ """Why a GGUF the Audio page asked for cannot be its audio model, or None.++ The Audio page (and only it) sends ``audio_device``. An audio.cpp GGUF never reaches here (it+ resolves to the audio worker), so a GGUF that does is a llama.cpp file: fine when it is a+ speech-codec model the page runs through llama-server (Orpheus/SNAC, BiCodec, DAC, by vocab or+ name), refused when it is anything else, rather than silently loading a chat model. Answered+ from the downloaded file's header; a file not on disk yet is left to the load's own checks.+ """+ if getattr(request, "audio_device", None) is None:+ return None+ path = getattr(config, "gguf_file", None)+ verified = getattr(config, "gguf_verified", None)+ if not path and verified:+ path = verified[2]+ repo = getattr(config, "gguf_hf_repo", None)+ variant = getattr(config, "gguf_variant", None)+ if not path and repo and variant:+ try:+ from hub.utils.gguf import resolve_local_gguf_path+ path = resolve_local_gguf_path(repo, variant)+ except Exception: # noqa: BLE001 - unresolvable locally: nothing to judge yet+ path = None+ if not path or not Path(path).is_file():+ return None+ from hub.services.models.catalog_classification import _arch_to_audio_type+ from utils.gguf_archs import is_audio_cpp_gguf_architecture, is_speech_gguf_architecture+ from utils.models.gguf_metadata import read_gguf_architecture, read_gguf_tts_audio_type++ arch = read_gguf_architecture(str(path))+ if arch is None or is_speech_gguf_architecture(arch) or is_audio_cpp_gguf_architecture(arch):+ # Unreadable, or a speech arch the chat gate already refuses with its own message.+ return None+ if read_gguf_tts_audio_type(str(path)) or _arch_to_audio_type(+ arch, (config.identifier, Path(path).name)+ ):+ return None+ return (+ f"This GGUF is not an audio model (architecture '{arch}'), so the Audio page cannot run it. "+ "Load it from Chat instead."+ )+++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)++def _native_audio_cpu_load(config, request) -> bool:"""True when this load is a native audio model the user placed in CPU RAM.@@ -15286,11 +15387,12 @@ def _native_audio_cpu_load(config, request) -> bool:for everything else, so a chat model cannot send it to skip the VRAM guardsthat read this."""- from core.inference.audio_device import audio_device_forces_cpu+ from core.inference.audio_device import audio_load_runs_on_cpufrom core.inference.native_audio import NATIVE_AUDIO_TYPES- return getattr(config, "audio_type", None) in NATIVE_AUDIO_TYPES and audio_device_forces_cpu(- getattr(request, "audio_device", None)+ audio_type = getattr(config, "audio_type", None)+ return audio_type in NATIVE_AUDIO_TYPES and audio_load_runs_on_cpu(+ audio_type, getattr(request, "audio_device", None))@@ -15303,14 +15405,15 @@ def _resident_audio_placement_matches(backend, request) -> bool:from before this existed has no key and is read as GPU, which is what thoseloads did."""- from core.inference.audio_device import audio_device_forces_cpu+ from core.inference.audio_device import audio_load_runs_on_cpufrom core.inference.native_audio import NATIVE_AUDIO_TYPESresident = backend.models.get(backend.active_model_name, {})- if resident.get("audio_type") not in NATIVE_AUDIO_TYPES:+ audio_type = resident.get("audio_type")+ if audio_type not in NATIVE_AUDIO_TYPES:return True- return bool(resident.get("audio_cpu", False)) == audio_device_forces_cpu(- getattr(request, "audio_device", None)+ return bool(resident.get("audio_cpu", False)) == audio_load_runs_on_cpu(+ audio_type, getattr(request, "audio_device", None))@@ -15337,6 +15440,20 @@ async def _preflight_native_audio_placement(audio_type = getattr(config, "audio_type", None)if audio_type not in NATIVE_AUDIO_TYPES:return placement+ from core.inference.audio_cpp_models import AUDIO_CPP_AUDIO_TYPES++ if audio_type in AUDIO_CPP_AUDIO_TYPES:+ from core.inference.audio_cpp_server import model_runtime_problem++ audio_cpp_model = getattr(config, "audio_cpp", None)+ problem = (+ await asyncio.to_thread(model_runtime_problem, audio_cpp_model)+ if audio_cpp_model is not None+ else None+ )+ if problem:+ # Refused here, before the orchestrator evicts the resident model for a load that cannot start.+ raise HTTPException(status_code = 501, detail = problem)if getattr(config, "is_lora", False):raise HTTPException(status_code = 400,@@ -15407,7 +15524,15 @@ async def _preflight_native_audio_placement(# here makes auto-placement select several GPUs and the single-device# native backend then rejects a model that fits one supported card.required_gb = _MINIMAX_MUSIC3_RESIDENT_GB if audio_type == "minimax_music3" else None- if len(targets) > 1:+ from core.inference.audio_cpp_models import AUDIO_CPP_AUDIO_TYPES++ if audio_type in AUDIO_CPP_AUDIO_TYPES:+ # An umbrella id names a subfolder of a repo holding many models, and a repo holds+ # every quant, so repository bytes say nothing here. Size from the one variant it loads.+ audio_cpp_model = getattr(config, "audio_cpp", None)+ if audio_cpp_model is not None:+ required_gb = audio_cpp_resident_gb(audio_cpp_model.size_bytes)+ elif len(targets) > 1:required_gb = 0.0for target in targets:target_required_gb, _metadata = hardware.estimate_required_model_memory_gb(@@ -17904,6 +18029,11 @@ async def _load_model_impl(# Ahead of the arbiter: acquire_for evicts a resident Images/Video pipeline and the# confirmation below cancels the running generations, both before load_model's own# copy of this check runs. A header-sized read spares them. Fails open into that copy.+ if config.is_gguf:+ _not_audio = await asyncio.to_thread(_audio_intent_gguf_refusal, config, request)+ if _not_audio:+ logger.error("Refusing a non-audio GGUF loaded for audio: %s", _not_audio)+ raise HTTPException(status_code = 400, detail = _not_audio)if config.is_gguf and gguf_intent is not None:_non_chat = await asyncio.to_thread(llama_backend.non_chat_gguf_refusal_for_intent, gguf_intent@@ -18438,6 +18568,8 @@ async def _load_model_impl(audio_type = _model_info.get("audio_type", config.audio_type),has_audio_input = _model_info.get("has_audio_input", config.has_audio_input),has_video_input = _model_info.get("has_video_input", False),+ audio_family = _model_info.get("audio_family"),+ audio_options = _model_info.get("audio_options"),is_mlx = bool(_model_info.get("is_mlx", False)),mlx_kv_quant = _model_info.get("mlx_kv_quant"),mlx_kv_quant_requested = _model_info.get("mlx_kv_quant_requested"),@@ -19833,7 +19965,9 @@ async def estimate_memory(return EstimateMemoryResponse(available = False, reason = "not_gguf")from core.inference.native_audio import is_native_audio_model- if is_native_audio_model(model_identifier):+ if getattr(config, "audio_cpp", None) is not None or is_native_audio_model(+ model_identifier+ ):return EstimateMemoryResponse(available = False, reason = "not_gguf")if getattr(config, "is_lora", False):return EstimateMemoryResponse(available = False, reason = "unsizable")@@ -20993,6 +21127,9 @@ async def get_status(current_subject: str):audio_type = audio_type,has_audio_input = has_audio_input,has_video_input = has_video_input,+ audio_family = model_info.get("audio_family"),+ audio_options = model_info.get("audio_options"),+ gguf_variant = model_info.get("gguf_variant"),is_mlx = bool(model_info.get("is_mlx", False)),mlx_kv_quant = model_info.get("mlx_kv_quant"),mlx_kv_quant_requested = model_info.get("mlx_kv_quant_requested"),@@ -21118,6 +21255,8 @@ _TRANSFORMERS_TTS_AUDIO_TYPES = frozenset("moss_tts_nano","higgs_tts3","minimax_music3",+ "audiocpp_tts",+ "audiocpp_music",))# NativeAudioBackend._context_length ignores the requested window for these.@@ -21127,6 +21266,20 @@ _STANDARD_LOAD_DEFAULT_CONTEXT = 2048_MINIMAX_NEEDS_DESCRIPTION = "MiniMax Music 3 requires a music description in addition to lyrics."+def _audio_cpp_music_request_problem(+ family: Optional[str], lyrics: Optional[str], description: Optional[str]+) -> Optional[str]:+ """Why an audio.cpp music request is missing a field its family requires, or None.++ Checked on the route so the caller gets a 400 naming the field, not a 500 from the worker.+ """+ if family == "minimax_music3" and not str(lyrics or "").strip():+ return "MiniMax Music 3 needs lyrics."+ if family == "yue2" and not str(description or "").strip():+ return "YuE2 needs a style description."+ return None++async def _generate_tts_wav(text: str,payload: ChatCompletionRequest,@@ -21169,6 +21322,7 @@ async def _generate_tts_wav(prompt_for_budget = text# Pick backend - both return (wav_bytes, sample_rate)+ audio_family = Nonellama_backend = get_llama_cpp_backend()# GGUF TTS goes straight to llama-server /completion, holding a slot with no# admission lease, so only the direct counter can show it in the slot readout.@@ -21205,6 +21359,7 @@ async def _generate_tts_wav(raise HTTPException(status_code = 400, detail = "Active model is not an audio model.")model_name = _orchestrator_public_model_id(backend)audio_type = model_info.get("audio_type")+ audio_family = model_info.get("audio_family")supported_audio_types = _TRANSFORMERS_TTS_AUDIO_TYPES_audio_model_id = getattr(backend, "active_model_name", None) or model_namegen = lambda: backend.generate_audio_response(@@ -21225,6 +21380,7 @@ async def _generate_tts_wav(instructions = payload.audio_instructions,language = payload.audio_language,seed = payload.seed,+ **({"audio_options": payload.audio_options} if payload.audio_options else {}),)if audio_type not in supported_audio_types:@@ -21234,6 +21390,12 @@ async def _generate_tts_wav()if audio_type == "minimax_music3" and not str(payload.audio_instructions or "").strip():raise HTTPException(status_code = 400, detail = _MINIMAX_NEEDS_DESCRIPTION)+ if audio_type == "audiocpp_music":+ _music_request_problem = _audio_cpp_music_request_problem(+ audio_family, text, payload.audio_instructions+ )+ if _music_request_problem:+ raise HTTPException(status_code = 400, detail = _music_request_problem)if audio_type in _EXTRA_PROMPT_FIELD_AUDIO_TYPES:prompt_for_budget = _native_tts_prompt_for_budget(text,@@ -21604,6 +21766,7 @@ async def openai_audio_speech(max_tokens = body.max_new_tokens or AUDIO_GENERATION_MAX_TOKENS,audio_instructions = body.instructions,audio_language = body.language,+ audio_options = body.audio_options,seed = body.seed,)# model is informational and is echoed verbatim into the row, so a failure before the@@ -21873,11 +22036,23 @@ def _stt_engine_for_model(model: Optional[str]) -> Optional[str]:"""if not model:return None+ from core.inference.audio_cpp_models import looks_like_audio_cpp, resolvefrom core.inference.stt_mtmd_sidecar import is_mtmd_model- # Only the mtmd ids are forced. Whisper ids are shared with the Transformers- # sidecar and work there, so leaving them alone keeps the default behaviour.- return "mtmd" if is_mtmd_model(model.strip()) else None+ # Only the mtmd and audio.cpp ids are forced. Whisper ids are shared with the Transformers+ # sidecar and work there, so leaving them alone keeps the default behaviour. An audio.cpp id+ # is an umbrella folder, a legacy key, or a repo whose cached GGUF says audiocpp.+ if is_mtmd_model(model.strip()):+ return "mtmd"+ if looks_like_audio_cpp(model.strip()):+ return "audiocpp"+ try:+ audio_cpp_model = resolve(model.strip(), network = False)+ except Exception: # noqa: BLE001 - unreadable from the cache: leave the default+ audio_cpp_model = None+ if audio_cpp_model is not None and audio_cpp_model.task == "asr":+ return "audiocpp"+ return Nonedef _resolve_stt_engine(engine: Optional[str]) -> str:@@ -21889,9 +22064,13 @@ def _resolve_stt_engine(engine: Optional[str]) -> str:return "gguf"if normalized in ("mtmd", "llama_cpp", "llama.cpp"):return "mtmd"+ if normalized in ("audiocpp", "audio_cpp", "audio.cpp"):+ return "audiocpp"raise HTTPException(status_code = 422,- detail = f"Unknown STT engine '{engine}'. Use 'transformers', 'gguf', or 'mtmd'.",+ detail = (+ f"Unknown STT engine '{engine}'. Use 'transformers', 'gguf', 'mtmd', or 'audiocpp'."+ ),)@@ -21962,6 +22141,9 @@ def _stt_download_module(engine: str):if engine == "gguf":from core.inference import stt_ggml_sidecarreturn stt_ggml_sidecar+ if engine == "audiocpp":+ from core.inference import stt_audiocpp_sidecar+ return stt_audiocpp_sidecarfrom core.inference import stt_sidecarreturn stt_sidecar@@ -22110,6 +22292,9 @@ def _stt_repo_reference(model, engine):if selected == "mtmd":spec = stt_mtmd_sidecar.MTMD_STT_MODELS.get(model)return spec.repo if spec else model+ if selected == "audiocpp":+ from core.inference.audio_cpp_models import DEFAULT_AUDIO_CPP_STT_MODEL, repo_of+ return repo_of(model or DEFAULT_AUDIO_CPP_STT_MODEL) or modelreturn stt_sidecar.resolve_model_repo(model)@@ -22121,13 +22306,16 @@ def _stt_resolved_model_id(model, engine):return stt_ggml_sidecar.resolve_ggml_model_id(model)if engine == "mtmd":return stt_mtmd_sidecar.resolve_mtmd_model_id(model)+ if engine == "audiocpp":+ from core.inference import stt_audiocpp_sidecar+ return stt_audiocpp_sidecar.resolve_audio_cpp_stt_model_id(model)return stt_sidecar.resolve_model_id(model)except Exception: # noqa: BLE001 - an id the loader would refuse is not what it loadedreturn Nonedef _account_stt_status(status):- for engine in ("transformers", "gguf", "mtmd"):+ for engine in ("transformers", "gguf", "mtmd", "audiocpp"):section = status[engine]loaded = section.get("loaded_model")if account_access.resident_hidden(f"stt:{engine}", loaded):@@ -22145,6 +22333,28 @@ def _account_stt_status(status):return status+def _audio_cpp_runtime_status() -> dict:+ """What the installed audio.cpp runtime can run, so the Audio page can mark rows before a load."""+ try:+ from core.inference import audio_cpp_server++ binary = audio_cpp_server.find_audio_cpp_server_binary()+ if binary is None:+ return {"available": False, "espeak": False, "backend": None, "release_tag": None}+ record = audio_cpp_server.read_install_record(binary)+ backend = record.get("backend")+ release_tag = record.get("release_tag")+ return {+ "available": True,+ "espeak": audio_cpp_server.binary_has_espeak(binary),+ "backend": backend if isinstance(backend, str) else None,+ "release_tag": release_tag if isinstance(release_tag, str) else None,+ }+ except Exception as exc: # noqa: BLE001 - a status poll must not fail on a probe+ logger.debug("audio.cpp runtime probe failed: %s", exc)+ return {"available": False, "espeak": False, "backend": None, "release_tag": None}++@studio_router.get("/audio/stt/status")async def stt_status(model: Optional[str] = None, current_subject: str = Depends(get_current_subject)@@ -22155,10 +22365,20 @@ async def stt_status(custom Hugging Face repository beyond the curated defaults."""if account_access.managed_account() and model:- await asyncio.to_thread(- account_access.require_model_access, _stt_repo_reference(model, "transformers")- )- from core.inference import stt_ggml_sidecar, stt_mtmd_sidecar, stt_sidecar+ # The engine that owns the id: the Transformers resolver refuses mtmd and audio.cpp keys,+ # which would turn a status poll into a 500.+ engine = _stt_engine_for_model(model) or "transformers"+ try:+ repo = _stt_repo_reference(model, engine)+ except Exception as exc: # noqa: BLE001 - an id no engine accepts is not a server error+ raise HTTPException(status_code = 422, detail = str(exc)) from exc+ await asyncio.to_thread(account_access.require_model_access, repo)+ from core.inference import (+ stt_audiocpp_sidecar,+ stt_ggml_sidecar,+ stt_mtmd_sidecar,+ stt_sidecar,+ )from core.inference.stt_sidecar import (DEFAULT_STT_MODEL,STT_MODELS,@@ -22169,6 +22389,8 @@ async def stt_status(sidecar = get_stt_sidecar()ggml = stt_ggml_sidecar.get_ggml_stt_sidecar()mtmd = stt_mtmd_sidecar.get_mtmd_stt_sidecar()+ audiocpp = stt_audiocpp_sidecar.get_audio_cpp_stt_sidecar()+ audiocpp_downloaded = await asyncio.to_thread(stt_audiocpp_sidecar.downloaded_model_ids)transformers_downloaded = [model_id for model_id in STT_MODELS if stt_sidecar.is_model_downloaded(model_id)]@@ -22228,6 +22450,26 @@ async def stt_status(],"download": stt_ggml_sidecar.download_status(),},+ # audio.cpp engine: any audio.cpp ASR GGUF. ``models`` is the recommended list plus+ # whatever is downloaded; ``downloaded_models`` is found by GGUF header in the HF cache.+ "audiocpp": {+ "available": stt_audiocpp_sidecar.is_available(),+ "loaded_model": audiocpp.loaded_model,+ "loaded_variant": audiocpp.loaded_variant,+ "loading": audiocpp.is_loading(),+ "device": audiocpp.device,+ "keep_alive_seconds": audiocpp.keep_alive_seconds,+ "default_model": None,+ "models": list(+ dict.fromkeys(+ [*stt_audiocpp_sidecar.AUDIO_CPP_STT_MODELS, *audiocpp_downloaded]+ )+ ),+ "downloaded_models": audiocpp_downloaded,+ "download": stt_audiocpp_sidecar.download_status(),+ },+ # The audio.cpp runtime itself, for the Audio page's TTS and music rows.+ "audio_cpp_runtime": _audio_cpp_runtime_status(),})if account_access.managed_account():@@ -22420,7 +22662,7 @@ async def stt_unload(if account_access.managed_account():engines = [candidate- for candidate in (engines or ["transformers", "gguf", "mtmd"])+ for candidate in (engines or ["transformers", "gguf", "mtmd", "audiocpp"])if not account_access.resident_hidden(f"stt:{candidate}", _stt_sidecar_for(candidate).loaded_model)@@ -32415,16 +32657,25 @@ def _stt_model_objects(created: int, catalog_at: Optional[float] = None) -> listfrom the engines this route can select."""try:- from core.inference import stt_mtmd_sidecar, stt_sidecar+ from core.inference import stt_audiocpp_sidecar, stt_mtmd_sidecar, stt_sidecarwhisper_ready = stt_sidecar.is_available()mtmd_ready = stt_mtmd_sidecar.is_available()+ audiocpp_ready = stt_audiocpp_sidecar.is_available()loaded = set()if whisper_ready:whisper_loaded = stt_sidecar.get_stt_sidecar().loaded_modelloaded.add(stt_sidecar.STT_MODELS.get(whisper_loaded, whisper_loaded))if mtmd_ready:loaded.add(stt_mtmd_sidecar.get_mtmd_stt_sidecar().loaded_model)+ if audiocpp_ready:+ # Status may name it by a legacy key; the listing names rows.+ loaded.add(+ stt_audiocpp_sidecar.acm_row_id(+ stt_audiocpp_sidecar.get_audio_cpp_stt_sidecar().loaded_model+ )+ or None+ )loaded -= {None}ids: list[str] = []@@ -32445,6 +32696,10 @@ def _stt_model_objects(created: int, catalog_at: Optional[float] = None) -> listfor model_id in stt_mtmd_sidecar.MTMD_STT_MODELSif stt_mtmd_sidecar.is_model_downloaded(model_id))+ audiocpp_ids: set[str] = set()+ if audiocpp_ready:+ audiocpp_ids = set(stt_audiocpp_sidecar.downloaded_model_ids())+ ids.extend(model_id for model_id in sorted(audiocpp_ids) if model_id not in ids)# A custom Whisper repo the route can still reload by name while it is resident.ids.extend(sorted(model_id for model_id in loaded if model_id not in ids))except Exception as exc: # noqa: BLE001@@ -32466,11 +32721,18 @@ def _stt_model_objects(created: int, catalog_at: Optional[float] = None) -> listquant = extract_quant_token(spec.model_file)if quant:obj["quant"] = quant+ is_audio_cpp = model_id in audiocpp_idsif account_access.managed_account():- repo = spec.repo if spec is not None else model_id+ if is_audio_cpp:+ from core.inference.audio_cpp_models import repo_of+ repo = repo_of(model_id) or model_id+ else:+ repo = spec.repo if spec is not None else model_idif not account_access.model_visible(repo):continue- engine = "mtmd" if spec is not None else "transformers"+ engine = (+ "audiocpp" if is_audio_cpp else ("mtmd" if spec is not None else "transformers")+ )if account_access.resident_hidden(f"stt:{engine}", model_id):obj["loaded"] = Falseobjects.append(obj)@@ -32684,6 +32946,45 @@ def _servable_catalog_rows(]+def _audio_cpp_speech_model_objects(created: int) -> list[dict]:+ """Downloaded audio.cpp speech and music GGUFs, found by header in the HF cache. The cache scan+ lists a dedicated repo as a GGUF but cannot key an umbrella folder, and neither loads in+ llama.cpp. /v1/audio/speech serves both kinds, loading one by name when auto-switch is on."""+ try:+ from core.inference import audio_cpp_server+ from core.inference.audio_cpp_models import downloaded_models++ binary = audio_cpp_server.find_audio_cpp_server_binary()+ if binary is None:+ return []+ objects = []+ for model in downloaded_models():+ if model.audio_type is None:+ continue+ if account_access.managed_account() and not account_access.model_visible(+ model.repo_id or model.id+ ):+ continue+ # An eSpeak model on a build without eSpeak would only 501.+ if audio_cpp_server.model_runtime_problem(model, binary) is not None:+ continue+ objects.append(+ {+ "id": model.id,+ "object": "model",+ "created": created,+ "owned_by": _OWNED_BY,+ "task": _TTS_MODEL_TASK,+ "display_name": model.display_name,+ "loaded": False,+ }+ )+ return objects+ except Exception as exc: # noqa: BLE001 - a listing never fails for one engine+ logger.debug("audio.cpp models unavailable for /v1/models: %s", exc)+ return []++async def _openai_catalog_objects() -> list[dict]:"""Every model the server knows about for ``GET /v1/models``: the loadedmodel(s) plus locally available (downloaded/cached) models discovered by@@ -32740,6 +33041,7 @@ async def _openai_catalog_objects() -> list[dict]:lambda: (_media_model_objects(catalog, _created, _account_catalog_cache()["at"])+ _stt_model_objects(_created, _account_catalog_cache()["at"])+ + _audio_cpp_speech_model_objects(_created)))for obj in media:diff --git a/studio/backend/routes/training_vram.py b/studio/backend/routes/training_vram.pyindex 63252738acf..977b17e1ac6 100644--- a/studio/backend/routes/training_vram.py+++ b/studio/backend/routes/training_vram.py@@ -111,6 +111,17 @@ def summarize_resident_stt() -> Dict[str, Any]:except Exception as e:logger.warning("Could not inspect mtmd STT sidecar: %s", e)+ try:+ from core.inference.stt_audiocpp_sidecar import get_audio_cpp_stt_sidecar++ audiocpp = get_audio_cpp_stt_sidecar()+ if not model:+ model = audiocpp.loaded_model+ device = device or audiocpp.device+ loading = loading or audiocpp.is_loading()+ except Exception as e:+ logger.warning("Could not inspect audio.cpp STT sidecar: %s", e)+return {"model": model,"device": device,@@ -579,6 +590,34 @@ def free_stt_model_for_training(reason: str) -> List[str]:except Exception as e:logger.warning("Could not unload mtmd STT model: %s", e)+ try:+ from core.inference.stt_audiocpp_sidecar import get_audio_cpp_stt_sidecar+ audiocpp = get_audio_cpp_stt_sidecar()+ if audiocpp.is_loading() and audiocpp.cancel_pending_load():+ logger.info("Cancelling audio.cpp STT model load for training (%s)", reason)+ # audiocpp_server loads the model before it answers, so the cancelled startup is killed and reaped+ # under the sidecar lock; wait for that before training claims the memory.+ audiocpp.wait_for_load_to_settle()+ if audiocpp.loaded_model:+ audiocpp.unload()+ freed.append("stt:audiocpp-loading")+ else:+ audiocpp_model = audiocpp.loaded_model+ if audiocpp_model and _stt_sidecar_holds_no_vram(audiocpp):+ logger.info(+ "Keeping CPU-placed audio.cpp STT model '%s' through training (%s)",+ audiocpp_model,+ reason,+ )+ elif audiocpp_model:+ logger.info(+ "Unloading audio.cpp STT model '%s' for training (%s)", audiocpp_model, reason+ )+ audiocpp.unload()+ freed.append(f"stt:{audiocpp_model}")+ except Exception as e:+ logger.warning("Could not unload audio.cpp STT model: %s", e)+return freeddiff --git a/studio/backend/tests/test_account_inference_isolation.py b/studio/backend/tests/test_account_inference_isolation.pyindex f9e6b1fd8bf..e933d7d3724 100644--- a/studio/backend/tests/test_account_inference_isolation.py+++ b/studio/backend/tests/test_account_inference_isolation.py@@ -342,7 +342,7 @@ def test_stt_private_status_and_download_state_are_filtered(monkeypatch):monkeypatch.setattr(inference, "_stt_repo_reference", lambda model, engine: model)run_as(ALICE, access.note_resident_account, "stt:transformers", "org/private")status = {"loaded_model": "org/private"}- for engine in ["transformers", "gguf", "mtmd"]:+ for engine in ["transformers", "gguf", "mtmd", "audiocpp"]:status[engine] = {"loaded_model": "org/private","downloaded_models": ["org/private"],diff --git a/studio/backend/tests/test_audio_cpp_models.py b/studio/backend/tests/test_audio_cpp_models.pynew file mode 100644index 00000000000..d04f799a335--- /dev/null+++ b/studio/backend/tests/test_audio_cpp_models.py@@ -0,0 +1,1858 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""audio.cpp GGUFs: recognising them by header, resolving ids and variants, their files in the HF+cache, and the worker backend's request shaping."""++import base64+import io+import json+import os+import struct+import sys+import wave+from pathlib import Path+from types import SimpleNamespace++import pytest++from core.inference import audio_cpp_backend, audio_cpp_files+from core.inference import audio_cpp_models as acm+from core.inference.audio_cpp_models import (+ AUDIO_CPP_REPO,+ AudioCppModel,+ AudioCppVariant,+ RepoFile,+)++# ---------------------------------------------------------------------------+# Fixtures: GGUF headers and a fake HF cache+++def _gguf_bytes(+ arch = "audiocpp",+ family = None,+ spec = None,+ *,+ blob_before_spec = 0,+ extra = (),+) -> bytes:+ kv = [("general.architecture", 8, arch)]+ kv.append(("general.name", 8, "test"))+ if blob_before_spec:+ # audiocpp.embedded_files.data: a u8 array some writers place before the spec keys.+ kv.append(("audiocpp.embedded_files.data", 9, blob_before_spec))+ if family is not None:+ kv.append(("audiocpp.model_spec.version", 4, 1))+ kv.append(("audiocpp.model_spec.family", 8, family))+ if spec is not None:+ kv.append(("audiocpp.model_spec.json", 8, json.dumps(spec)))+ kv.extend(extra)+ out = bytearray(struct.pack("<IIQQ", 0x46554747, 3, 0, len(kv)))+ for key, vtype, value in kv:+ k = key.encode()+ out += struct.pack("<Q", len(k)) + k + struct.pack("<I", vtype)+ if vtype == 8:+ v = value.encode()+ out += struct.pack("<Q", len(v)) + v+ elif vtype == 4:+ out += struct.pack("<I", value)+ elif vtype == 9:+ out += struct.pack("<IQ", 0, value) + b"\0" * value+ return bytes(out) + b"\0" * 64+++def hub(tmp_path, monkeypatch):+ """An empty HF hub cache every audio.cpp lookup reads, with the Hub and runtime specs out of reach."""+ root = tmp_path / "hub"+ root.mkdir()+ monkeypatch.setattr(acm, "_hub_cache", lambda: root)+ monkeypatch.setattr(audio_cpp_files, "_hub_cache", lambda: root)+ monkeypatch.setattr(acm, "runtime_spec", lambda family: None)+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")+ acm.forget()+ with acm._resolve_lock:+ acm._downloaded_cache.clear()+ yield root+ acm.forget()+++def _snapshot(+ root,+ repo = AUDIO_CPP_REPO,+ sha = "a" * 40,+ main = True,+):+ repo_dir = root / ("models--" + repo.replace("/", "--"))+ snap = repo_dir / "snapshots" / sha+ snap.mkdir(parents = True, exist_ok = True)+ if main:+ (repo_dir / "refs").mkdir(exist_ok = True)+ (repo_dir / "refs" / "main").write_text(sha)+ return snap+++def _put(+ snap,+ rel,+ data = b"x",+):+ path = snap / rel+ path.parent.mkdir(parents = True, exist_ok = True)+ path.write_bytes(data)+ return path+++KOKORO_SPEC = {+ "family": "kokoro_tts",+ "tasks": ["tts"],+ "ui": {"default_voice": "af_heart", "builtin_voices": ["af_heart", "am_adam"]},+ "options": {+ "request": [+ {"name": "language", "type": "string"},+ {"name": "seed", "type": "int"},+ {"name": "speed", "type": "float", "default": 1, "min": 0.5, "max": 2},+ {"name": "phonemes", "type": "string_list"},+ {"name": "text_chunk_size", "type": "int", "default": 240, "min": 1},+ {"name": "mode", "type": "enum", "values": ["a", "b"], "default": "a"},+ {"name": "voice_dir", "type": "path"},+ ]+ },+}+++def _kokoro(root):+ snap = _snapshot(root)+ _put(+ snap,+ "Kokoro-82M-GGUF/kokoro-82m-q8_0.gguf",+ _gguf_bytes(family = "kokoro_tts", spec = KOKORO_SPEC),+ )+ _put(snap, "Kokoro-82M-GGUF/README.md", b"readme")+ return snap+++def _model(+ folder,+ family,+ task,+ *,+ files = None,+ primary = None,+ key = "Q8_0",+ **kw,+):+ files = files or (RepoFile(f"{folder}/{folder.lower()}-q8_0.gguf", 4),)+ primary = files[0].path if primary is None else primary+ variant = AudioCppVariant(key, tuple(files), primary)+ fields = dict(+ id = f"{AUDIO_CPP_REPO}/{folder}",+ repo_id = AUDIO_CPP_REPO,+ folder = folder,+ display_name = folder,+ family = family,+ task = task,+ server_task = "gen" if task == "music" else task,+ variant = variant,+ variants = (variant,),+ default_variant = key,+ )+ fields.update(kw)+ return AudioCppModel(**fields)+++CANARY = _model("Canary-180M-Flash-GGUF", "canary_asr", "asr")+++# ---------------------------------------------------------------------------+# Ids+++def test_ids_legacy_keys_and_subfolders_parse_without_io():+ ref = acm.parse_identifier("audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF")+ assert (ref.repo_id, ref.folder, ref.variant_hint) == (AUDIO_CPP_REPO, "Kokoro-82M-GGUF", None)+ assert ref.display_name == "Kokoro-82M-GGUF"+ legacy = acm.parse_identifier("audiocpp-ace-step-1.5-turbo")+ assert legacy.id == f"{AUDIO_CPP_REPO}/ACE-Step1.5-GGUF" and legacy.variant_hint == "turbo/Q8_0"+ # The sub-folder ids of earlier builds name the folder row and a variant.+ old = acm.parse_identifier("audio-cpp/audio.cpp-gguf/PocketTTS-GGUF/english")+ assert old.id == f"{AUDIO_CPP_REPO}/PocketTTS-GGUF" and old.variant_hint == "english"+ moon = acm.parse_identifier("Audio-CPP/audio.cpp-gguf/Moonshine-Streaming-GGUF/tiny")+ assert moon.variant_hint == "tiny/Q8_0"+ dedicated = acm.parse_identifier("audio-cpp/MiniMax-Music3-GGUF")+ assert (dedicated.repo_id, dedicated.folder) == ("audio-cpp/MiniMax-Music3-GGUF", "")+ assert dedicated.display_name == "MiniMax-Music3-GGUF"+ for junk in (None, "", "no-slash", "audio-cpp/audio.cpp-gguf/../x", "a/b/c"):+ assert acm.parse_identifier(junk) is None+ assert acm.split_variant_ref("audio-cpp/Yue2-3B-GGUF:BF16") == (+ "audio-cpp/Yue2-3B-GGUF",+ "BF16",+ )+ assert acm.split_variant_ref(r"C:\models\x.gguf") == (r"C:\models\x.gguf", None)+ assert acm.is_umbrella_id("audiocpp-qwen3-asr-0.6b")+ assert not acm.is_umbrella_id("unsloth/Qwen3-0.6B-GGUF")+ assert acm.repo_of("audiocpp-kokoro-82m") == AUDIO_CPP_REPO+ assert acm.repo_of("audio-cpp/Yue2-3B-GGUF:Q8_0") == "audio-cpp/Yue2-3B-GGUF"+++# ---------------------------------------------------------------------------+# Headers+++def test_header_reads_family_and_spec_past_embedded_data():+ data = _gguf_bytes(family = "moonshine_asr", spec = {"tasks": ["asr"]}, blob_before_spec = 5000)+ header = acm.parse_header(io.BytesIO(data))+ assert (+ header.is_audio_cpp+ and header.family == "moonshine_asr"+ and header.spec == {"tasks": ["asr"]}+ )+ # A prefix that stops inside the embedded data still answers "audio.cpp", without a family.+ short = acm.parse_header(io.BytesIO(data[:2000]))+ assert short.is_audio_cpp and short.family is None and not short.complete+ llama = acm.parse_header(io.BytesIO(_gguf_bytes(arch = "llama")))+ assert llama is not None and not llama.is_audio_cpp+ assert acm.parse_header(io.BytesIO(b"not a gguf at all, just bytes...")) is None+++def test_quant_labels():+ assert acm.quant_label("kokoro-82m-q8_0.gguf") == "Q8_0"+ assert acm.quant_label("kitten-tts-mini-0.8-orig.gguf") == "orig"+ assert acm.quant_label("x/pocket-tts-english-bf16.gguf") == "BF16"+ assert acm.quant_label("voxtral-mini-4b-realtime-2602-q4_k.gguf") == "Q4_K"+++# ---------------------------------------------------------------------------+# Resolution, from the cache alone+++def test_umbrella_folder_resolves_from_its_cached_header(hub):+ _kokoro(hub)+ model = acm.resolve(f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF", network = False)+ assert model.family == "kokoro_tts" and model.task == "tts" and model.server_task == "tts"+ assert model.audio_type == "audiocpp_tts" and model.needs_espeak+ assert model.display_name == "Kokoro-82M-GGUF" and model.variant.key == "Q8_0"+ assert model.files == (+ "Kokoro-82M-GGUF/kokoro-82m-q8_0.gguf",+ ) # the README is not a model file+ assert model.unsupported is None+ # The same model through its legacy key and a quant spelled any way.+ assert acm.resolve("audiocpp-kokoro-82m", network = False).id == model.id+ assert acm.resolve(model.id, "q8_0", network = False).variant.key == "Q8_0"+ missing = acm.resolve(model.id, "Q2_K", network = False)+ assert "not found" in missing.unsupported and "Q8_0" in missing.unsupported+ assert acm.looks_like_audio_cpp(model.id)+++def test_options_come_from_the_spec_minus_what_studio_drives(hub):+ _kokoro(hub)+ model = acm.resolve(f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF", network = False)+ by_name = {o["name"]: o for o in model.options}+ # Language and seed have their own controls; lists and paths cannot be rendered.+ assert list(by_name) == ["voice", "speed", "text_chunk_size", "mode"]+ assert by_name["voice"] == {+ "name": "voice",+ "type": "enum",+ "description": "Built-in speaker.",+ "required": False,+ "default": "af_heart",+ "min": None,+ "max": None,+ "values": ["af_heart", "am_adam"],+ }+ assert by_name["speed"]["default"] == 1 and by_name["speed"]["max"] == 2+ assert by_name["mode"]["values"] == ["a", "b"]+++def test_validate_options_drops_unknowns_and_clamps():+ schema = acm.option_schema(acm.FAMILIES["kokoro_tts"], KOKORO_SPEC, None)+ assert acm.validate_options(+ schema,+ {+ "speed": 9,+ "text_chunk_size": "12.6",+ "mode": "c",+ "voice": "am_adam",+ "seed": 4,+ "rm -rf": 1,+ },+ ) == {"speed": 2.0, "text_chunk_size": 13, "voice": "am_adam"}+ assert acm.validate_options(schema, None) == {}+++def test_a_llama_gguf_is_not_audio_cpp(hub):+ snap = _snapshot(hub, "unsloth/Qwen3-0.6B-GGUF")+ _put(snap, "Qwen3-0.6B-Q4_K_M.gguf", _gguf_bytes(arch = "qwen3"))+ assert acm.resolve("unsloth/Qwen3-0.6B-GGUF", network = False) is None+ assert (+ acm.resolve("unsloth/Qwen3-0.6B-GGUF", network = False, gguf_hint = "Qwen3-0.6B-Q4_K_M.gguf")+ is None+ )+ assert not acm.looks_like_audio_cpp("unsloth/Qwen3-0.6B-GGUF")+++def test_a_dedicated_repo_resolves_by_header_with_its_quants(hub):+ repo = "someone/AudioCPP-Voxtral-GGUF"+ snap = _snapshot(hub, repo)+ header = _gguf_bytes(family = "voxtral_realtime")+ _put(snap, "voxtral-q8_0.gguf", header)+ _put(snap, "voxtral-q4_k.gguf", header)+ model = acm.resolve(repo, network = False)+ assert (+ model.task == "asr"+ and model.audio_type is None+ and model.display_name == "AudioCPP-Voxtral-GGUF"+ )+ assert [v.key for v in model.variants] == ["Q8_0", "Q4_K"]+ with pytest.raises(acm.AudioCppModelError, match = "speech-to-text"):+ acm.require_runnable(model, "tts")+ acm.require_runnable(model, "asr")+++def test_an_unknown_family_follows_its_spec_tasks_or_is_refused(hub):+ for family, tasks, task, server in (+ ("new_tts", ["tts", "clone"], "tts", "tts"),+ ("new_music", ["music"], "music", "gen"),+ ("new_sep", ["sep"], "", ""),+ ):+ repo = f"someone/{family}-GGUF"+ _put(_snapshot(hub, repo), "m-q8_0.gguf", _gguf_bytes(family = family, spec = {"tasks": tasks}))+ model = acm.resolve(repo, network = False)+ assert (model.task, model.server_task) == (task, server)+ assert (model.unsupported is None) == bool(task)+ sep = acm.resolve("someone/new_sep-GGUF", network = False)+ assert "Source separation" in sep.unsupported+++def test_known_task_families_are_refused_with_a_reason(hub):+ _put(_snapshot(hub), "HTDemucs-GGUF/htdemucs-q8_0.gguf", _gguf_bytes(family = "htdemucs"))+ model = acm.resolve(f"{AUDIO_CPP_REPO}/HTDemucs-GGUF", network = False)+ assert "Source separation" in model.unsupported+ with pytest.raises(acm.AudioCppModelError):+ acm.require_runnable(model, "tts")+++def test_qwen3_tts_package_kind_comes_from_its_name(hub):+ snap = _snapshot(hub)+ for folder in (+ "Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF",+ "Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF",+ "Qwen3-TTS-12Hz-0.6B-Base-GGUF",+ ):+ _put(snap, f"{folder}/{folder.lower()}-q8_0.gguf", _gguf_bytes(family = "qwen3_tts"))+ design = acm.resolve(f"{AUDIO_CPP_REPO}/Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF", network = False)+ custom = acm.resolve(f"{AUDIO_CPP_REPO}/Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF", network = False)+ base = acm.resolve(f"{AUDIO_CPP_REPO}/Qwen3-TTS-12Hz-0.6B-Base-GGUF", network = False)+ assert design.server_task == "vdes" and design.request_defaults["options"]["instruct"]+ assert custom.server_task == "tts" and custom.request_defaults["voice"] == "vivian"+ # The published GGUF embeds no speaker list, so the picker offers the package's own nine.+ voice = next(o for o in custom.options if o["name"] == "voice")+ assert (+ voice["default"] == "vivian" and len(voice["values"]) == 9 and "uncle_fu" in voice["values"]+ )+ assert not any(o["name"] == "voice" for o in design.options)+ assert "reference voice" in base.unsupported+++def test_sub_folders_and_same_quant_files_become_named_variants(hub):+ snap = _snapshot(hub)+ ace = _gguf_bytes(family = "ace_step")+ _put(snap, "ACE-Step1.5-GGUF/turbo/ace-step-1.5-turbo-q8_0.gguf", ace)+ _put(snap, "ACE-Step1.5-GGUF/base/ace-step-1.5-base-q8_0.gguf", ace)+ moon = _gguf_bytes(family = "moonshine_asr")+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0.gguf", moon)+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0.gguf", moon)+ model = acm.resolve(f"{AUDIO_CPP_REPO}/ACE-Step1.5-GGUF", network = False)+ assert [v.key for v in model.variants] == ["turbo/Q8_0", "base/Q8_0"]+ assert model.variant.key == "turbo/Q8_0" and model.variants[0].label == "Q8_0 · turbo"+ # A bare quant shared by both picks the default; the legacy id names its sub-folder.+ assert acm.resolve(model.id, "Q8_0", network = False).variant.key == "turbo/Q8_0"+ assert acm.resolve("audiocpp-ace-step-1.5-base", network = False).variant.key == "base/Q8_0"+ moonshine = acm.resolve("audiocpp-moonshine-small", network = False)+ assert moonshine.variant.key == "small/Q8_0" and moonshine.variant.label == "Q8_0 · small"+ assert moonshine.default_variant == "tiny/Q8_0"+ assert acm.resolve(+ f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF/tiny", network = False+ ).variant.key == ("tiny/Q8_0")+++def _minimax(root, *, quant = "q4_0"):+ snap = _snapshot(root, "audio-cpp/MiniMax-Music3-GGUF")+ header = _gguf_bytes(family = "minimax_music3")+ for rel in (+ "config.json",+ "config/language_model.json",+ "config/rvq_depth_decoder.json",+ "config/condition_encoder.json",+ "config/transformer.json",+ "config/vocoder.json",+ "tokenizer/tokenizer.json",+ "tokenizer/tokenizer_config.json",+ ):+ _put(snap, rel, b"{}")+ for rel in (+ f"language_model_{quant}.gguf",+ "rvq_depth_decoder_q8_0.gguf",+ f"transformer_{quant}.gguf",+ "condition_encoder.gguf",+ "vocoder.gguf",+ ):+ _put(snap, rel, header)+ return snap+++def test_a_package_repo_lists_its_mixes_and_picks_its_components(hub):+ _minimax(hub)+ model = acm.resolve("audio-cpp/MiniMax-Music3-GGUF", network = False)+ assert model.family == "minimax_music3" and model.task == "music" and model.server_task == "gen"+ assert model.is_package and [v.key for v in model.variants] == ["Q4_0"] # only Q4_0 is complete+ assert len(model.files) == 13 and model.gguf_file == "language_model_q4_0.gguf"+ assert model.model_options["session_options"] == {+ "minimax_music3.language_model_gguf": "language_model_q4_0.gguf",+ "minimax_music3.rvq_depth_decoder_gguf": "rvq_depth_decoder_q8_0.gguf",+ "minimax_music3.flow_transformer_gguf": "transformer_q4_0.gguf",+ }+ # The Studio-side list stands in for the runtime's spec; lyrics and duration have their own fields.+ assert [o["name"] for o in model.options] == [+ "num_inference_steps",+ "guidance_scale",+ "ar_guidance_scale",+ "top_k",+ ]+ assert audio_cpp_files.cached_files(model) is not None+++def test_package_layouts_plan_whole_mixes(hub):+ from hub.utils.gguf_plan import build_gguf_variant_plans, plan_for_variant++ def sib(name, size = 10):+ return SimpleNamespace(rfilename = name, size = size, lfs = {"sha256": name})++ names = [+ "sidecars/yue2-model-config.json",+ "sidecars/yue2-generation-config.json",+ "sidecars/yue2-qwen.tiktoken",+ "sidecars/yue2-vae-config.json",+ "yue2-3b-q8_0.gguf",+ "yue2-3b-bf16.gguf",+ "yue2-vae-f16.gguf",+ "yue2-vae-f32.gguf",+ "README.md",+ ]+ plans = build_gguf_variant_plans([sib(n) for n in names])+ assert sorted(plans) == ["bf16", "q8_0"]+ plan = plan_for_variant(plans, "BF16")+ assert set(plan.target_filenames) == set(names[:4]) | {"yue2-3b-bf16.gguf", "yue2-vae-f16.gguf"}+ # Files every mix shares are companions, never one mix's own weights.+ assert plan.main_filenames == frozenset({"yue2-3b-bf16.gguf"})+ assert "yue2-vae-f16.gguf" in plan.companion_hashes+++def test_voice_embeddings_ride_with_the_gguf_they_sit_beside():+ from hub.utils.gguf_plan import build_gguf_variant_plans, plan_for_variant++ def sib(name):+ return SimpleNamespace(rfilename = name, size = 5, lfs = {"sha256": name})++ names = [+ "PocketTTS-GGUF/english/pocket-tts-english-q8_0.gguf",+ "PocketTTS-GGUF/english/embeddings/alba.safetensors",+ "PocketTTS-GGUF/english/embeddings/anna.safetensors",+ "PocketTTS-GGUF/german/pocket-tts-german-q8_0.gguf",+ "PocketTTS-GGUF/german/embeddings/karl.safetensors",+ ]+ plans = build_gguf_variant_plans([sib(n) for n in names])+ english = plan_for_variant(plans, "PocketTTS-GGUF/english/pocket-tts-english-q8_0")+ assert set(english.target_filenames) == set(names[:3])+ assert english.download_size_bytes == 15+++def test_download_target_maps_a_folder_row_onto_the_planner_key(hub):+ _kokoro(hub)+ assert acm.download_target(f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF", "Q8_0") == (+ AUDIO_CPP_REPO,+ "Kokoro-82M-GGUF/kokoro-82m-q8_0",+ )+ assert acm.download_target("audio-cpp/MiniMax-Music3-GGUF", "Q4_0") is None+++# ---------------------------------------------------------------------------+# Files in the cache+++def test_cached_files_require_every_file_of_the_variant(hub):+ snap = _snapshot(hub)+ gguf = RepoFile("PocketTTS-GGUF/english/pocket-tts-english-q8_0.gguf", 4)+ voice = RepoFile("PocketTTS-GGUF/english/embeddings/alba.safetensors", 1)+ m = _model("PocketTTS-GGUF", "pocket_tts", "tts", files = (gguf, voice), key = "english/Q8_0")+ _put(snap, gguf.path, b"GGUF")+ # An interrupted download missing a voice is not a complete model.+ assert audio_cpp_files.cached_files(m) is None+ assert audio_cpp_files.missing_files(m) == [(voice.path, 1)]+ _put(snap, voice.path, b"x")+ assert len(audio_cpp_files.cached_files(m)) == 2+ # A truncated file is not complete either.+ _put(snap, gguf.path, b"GG")+ assert audio_cpp_files.cached_files(m) is None+++def test_farm_layout_keeps_the_voice_folder_beside_the_gguf(hub, monkeypatch):+ snap = _snapshot(hub)+ gguf = RepoFile("PocketTTS-GGUF/english/pocket-tts-english-q8_0.gguf", 4)+ voice = RepoFile("PocketTTS-GGUF/english/embeddings/alba.safetensors", 1)+ m = _model("PocketTTS-GGUF", "pocket_tts", "tts", files = (gguf, voice), key = "english/Q8_0")+ _put(snap, gguf.path, b"GGUF")+ _put(snap, voice.path, b"x")+ monkeypatch.setattr(audio_cpp_files.sys, "platform", "win32")+ served = audio_cpp_files.materialize(m, hub_cache = hub)+ farm = audio_cpp_files._link_farm_root(hub) / m.key+ assert served == str(farm / "english" / "pocket-tts-english-q8_0.gguf")+ assert (farm / "english" / "embeddings" / "alba.safetensors").is_file()+ marker = json.loads((farm / audio_cpp_files._SOURCE_MARKER).read_text(encoding = "utf-8"))+ assert marker["repo_id"] == AUDIO_CPP_REPO and len(marker["files"]) == 2+++def test_a_package_is_served_as_its_directory(hub, monkeypatch):+ _minimax(hub)+ model = acm.resolve("audio-cpp/MiniMax-Music3-GGUF", network = False)+ monkeypatch.setattr(audio_cpp_files.sys, "platform", "win32")+ served = Path(audio_cpp_files.materialize(model, hub_cache = hub))+ assert served == audio_cpp_files._link_farm_root(hub) / model.key+ assert (served / "tokenizer" / "tokenizer.json").is_file() and (+ served / "vocoder.gguf"+ ).is_file()+++def test_windows_refuses_a_model_path_the_server_cannot_open(hub, monkeypatch):+ from core.inference import audio_cpp_server as srv+ from core.inference.audio_cpp_server import AudioCppUnavailableError++ _put(_snapshot(hub), CANARY.gguf_file, b"GGUF")+ binary = str(hub / srv.BINARY_NAME)+ monkeypatch.setattr(audio_cpp_files.sys, "platform", "win32")+ assert srv.model_runtime_problem(CANARY, binary) is None+ monkeypatch.setattr(audio_cpp_files, "_WINDOWS_MAX_MODEL_PATH", 10)+ # Refused before download or eviction, not first at materialize.+ assert "shorter" in srv.model_runtime_problem(CANARY, binary)+ with pytest.raises(AudioCppUnavailableError, match = "shorter"):+ audio_cpp_files.materialize(CANARY, hub_cache = hub)+ monkeypatch.setattr(audio_cpp_files.sys, "platform", "linux")+ assert srv.model_runtime_problem(CANARY, binary) is None+++def test_an_unsupported_model_is_a_runtime_problem(hub):+ from core.inference import audio_cpp_server as srv+ refused = _model(+ "HTDemucs-GGUF",+ "htdemucs",+ "",+ unsupported = "Source separation models are not supported in Studio yet.",+ )+ assert "Source separation" in srv.model_runtime_problem(refused, "x")+++def test_files_split_across_snapshots_are_found_in_the_one_that_holds_them(hub):+ _snapshot(hub, sha = "a" * 40)+ other = _snapshot(hub, sha = "b" * 40, main = False)+ _put(other, CANARY.gguf_file, b"GGUF")+ assert audio_cpp_files.cached_files(CANARY) == [other / CANARY.gguf_file]+++def test_materialize_of_a_missing_model_raises(hub):+ _snapshot(hub)+ with pytest.raises(FileNotFoundError):+ audio_cpp_files.materialize(CANARY, hub_cache = hub)+++def _symlinked(+ hub,+ model = CANARY,+ data = b"GGUF-weights",+):+ snap = _snapshot(hub)+ blobs = snap.parent.parent / "blobs"+ blobs.mkdir(exist_ok = True)+ blob = blobs / "deadbeef"+ blob.write_bytes(data)+ link = snap / model.gguf_file+ link.parent.mkdir(parents = True, exist_ok = True)+ try:+ link.symlink_to(os.path.relpath(blob, link.parent))+ except OSError:+ pytest.skip("this filesystem or account cannot create symlinks")+ return link, blob+++def test_symlinked_cache_entries_are_hardlinked_under_their_real_names(hub):+ model = _model(+ "Canary-180M-Flash-GGUF", "canary_asr", "asr", files = (RepoFile(CANARY.gguf_file, 12),)+ )+ _link, blob = _symlinked(hub, model)+ path = audio_cpp_files.materialize(model, hub_cache = hub)+ assert path.endswith(".gguf") and not os.path.islink(path)+ assert os.path.samefile(path, blob)+ assert audio_cpp_files.materialize(model, hub_cache = hub) == path+++def test_prune_drops_farm_entries_whose_files_were_deleted(hub):+ model = _model(+ "Canary-180M-Flash-GGUF", "canary_asr", "asr", files = (RepoFile(CANARY.gguf_file, 4),)+ )+ link, blob = _symlinked(hub, model, b"GGUF")+ path = audio_cpp_files.materialize(model, hub_cache = hub)+ assert audio_cpp_files.prune_link_farm(hub) == 0 # still referenced+ link.unlink()+ blob.unlink()+ assert audio_cpp_files.prune_link_farm(hub) == 2 # the file and its source record+ assert not os.path.exists(path)+++def test_prune_removes_old_unrecorded_farm_dirs(hub):+ farm = audio_cpp_files._link_farm_root(hub)+ legacy = farm / "audiocpp-canary-180m-flash"+ legacy.mkdir(parents = True)+ (legacy / "canary.gguf").write_bytes(b"x")+ # A young unrecorded folder may be a materialize in flight.+ assert audio_cpp_files.prune_link_farm(hub) == 0+ os.utime(legacy, (1, 1))+ assert audio_cpp_files.prune_link_farm(hub) == 1+ assert not legacy.exists()+++def test_a_copied_file_is_not_recopied(hub, monkeypatch):+ model = _model(+ "Canary-180M-Flash-GGUF", "canary_asr", "asr", files = (RepoFile(CANARY.gguf_file, 4),)+ )+ _symlinked(hub, model, b"GGUF")++ def no_link(*_a, **_k):+ raise OSError("cross-device link")++ copies = []+ real_copy = audio_cpp_files.shutil.copyfile+ monkeypatch.setattr(audio_cpp_files.os, "link", no_link)+ monkeypatch.setattr(+ audio_cpp_files.shutil, "copyfile", lambda a, b: copies.append(a) or real_copy(a, b)+ )+ for _ in range(3):+ audio_cpp_files.materialize(model, hub_cache = hub)+ assert len(copies) == 1+++def test_an_unwritable_farm_location_is_an_unavailable_error(hub, monkeypatch):+ from core.inference.audio_cpp_server import AudioCppUnavailableError++ model = _model(+ "Canary-180M-Flash-GGUF", "canary_asr", "asr", files = (RepoFile(CANARY.gguf_file, 12),)+ )+ _symlinked(hub, model)+ farm_root = audio_cpp_files._link_farm_root(hub)+ real_mkdir = Path.mkdir++ def mkdir(self, *a, **kw):+ if farm_root in (self, *self.parents):+ raise PermissionError(13, "Permission denied", str(self))+ return real_mkdir(self, *a, **kw)++ monkeypatch.setattr(Path, "mkdir", mkdir)+ with pytest.raises(AudioCppUnavailableError, match = "writable folder"):+ audio_cpp_files.materialize(model, hub_cache = hub)+++def _dir_link(link, target):+ """A directory symlink, or a Windows junction when this account cannot create symlinks."""+ try:+ os.symlink(target, link, target_is_directory = True)+ except OSError:+ if sys.platform != "win32":+ pytest.skip("this filesystem or account cannot create symlinks")+ import _winapi+ _winapi.CreateJunction(str(target), str(link))+++def test_prune_never_follows_a_link_planted_in_the_farm(hub, tmp_path):+ farm = audio_cpp_files._link_farm_root(hub)+ victim = tmp_path / "victim"+ victim.mkdir()+ (victim / "notes.txt").write_text("keep", encoding = "utf-8")+ farm.mkdir(parents = True)+ _dir_link(farm / "not-a-model", victim)+ (farm / "some-model").mkdir()+ _dir_link(farm / "some-model" / "sub", victim)+ os.utime(farm / "some-model", (1, 1))+ audio_cpp_files.prune_link_farm(hub)+ assert (victim / "notes.txt").read_text(encoding = "utf-8") == "keep"+ assert not (farm / "not-a-model").exists()+++def test_materialize_does_not_write_through_a_planted_model_folder_link(hub, tmp_path, monkeypatch):+ snap = _snapshot(hub)+ _put(snap, CANARY.gguf_file, b"GGUF")+ farm = audio_cpp_files._link_farm_root(hub)+ farm.mkdir(parents = True)+ elsewhere = tmp_path / "elsewhere"+ elsewhere.mkdir()+ _dir_link(farm / CANARY.key, elsewhere)+ monkeypatch.setattr(audio_cpp_files.sys, "platform", "win32") # always goes through the farm+ served = audio_cpp_files.materialize(CANARY, hub_cache = hub)+ assert list(elsewhere.iterdir()) == []+ assert os.path.samefile(served, snap / CANARY.gguf_file)+++def test_materialize_refuses_a_repo_file_name_that_climbs_out_of_the_farm(+ hub, tmp_path, monkeypatch+):+ from dataclasses import replace++ from core.inference.audio_cpp_server import AudioCppUnavailableError++ snap = _snapshot(hub)+ _put(snap, CANARY.gguf_file, b"GGUF")+ evil = acm.RepoFile("Canary-180M-Flash-GGUF/embeddings/..\\..\\..\\victim", 4)+ _put(snap, evil.path, b"EVIL")+ victim = audio_cpp_files._link_farm_root(hub).parent / "victim"+ variant = replace(CANARY.variant, files = (*CANARY.variant.files, evil))+ model = replace(CANARY, variant = variant, variants = (variant,))+ monkeypatch.setattr(audio_cpp_files.sys, "platform", "win32") # always goes through the farm+ with pytest.raises(AudioCppUnavailableError, match = "Refusing"):+ audio_cpp_files.materialize(model, hub_cache = hub)+ assert not victim.exists()+++def test_downloaded_models_are_found_by_header(hub):+ _kokoro(hub)+ snap = _snapshot(hub)+ _put(snap, "Qwen3-ASR-0.6B-GGUF/qwen3-asr-0.6b-q8_0.gguf", _gguf_bytes(family = "qwen3_asr"))+ _put(_snapshot(hub, "someone/llama-GGUF"), "llama-q4_k_m.gguf", _gguf_bytes(arch = "llama"))+ _put(+ _snapshot(hub, "someone/Parakeet-GGUF"),+ "parakeet-q8_0.gguf",+ _gguf_bytes(family = "parakeet_tdt"),+ )+ found = {m.id: m.task for m in acm.downloaded_models()}+ assert found == {+ f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF": "tts",+ f"{AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF": "asr",+ "someone/Parakeet-GGUF": "asr",+ }+ from core.inference import stt_audiocpp_sidecar as s++ assert sorted(s.downloaded_model_ids()) == [+ f"{AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF",+ # The legacy key of that downloaded folder, which Settings > Voice compares against.+ "audiocpp-qwen3-asr-0.6b",+ "someone/Parakeet-GGUF",+ ]+++# ---------------------------------------------------------------------------+# Worker backend request shaping, against a recording fake server+++def _wav(seconds = 0.1, rate = 24000):+ buf = io.BytesIO()+ with wave.open(buf, "wb") as w:+ w.setnchannels(1)+ w.setsampwidth(2)+ w.setframerate(rate)+ w.writeframes(b"\0\0" * int(seconds * rate))+ return buf.getvalue()+++class _FakeServer:+ def __init__(self, model, reply):+ self.model = model+ self.model_id = "studio-test"+ self.backend = "cuda"+ self.reply = reply+ self.calls = []++ def alive(self):+ return True++ def post_json(self, path, payload, **kwargs):+ self.calls.append((path, payload))+ return self.reply++ def stop(self):+ pass+++def _backend_with(model, reply):+ b = audio_cpp_backend.AudioCppBackend()+ b._server = _FakeServer(model, reply)+ b._model = model+ b.models = {model.id: {"is_audio": True, "audio_type": model.audio_type}}+ b.active_model_name = model.id+ return b, b._server+++def _speech_model(family, **kw):+ policy = acm.family_policy(family, None, (kw.pop("name", family),))+ return _model(+ f"{family}-GGUF",+ family,+ policy.task,+ server_task = policy.default_server_task,+ request_defaults = dict(policy.request_defaults),+ **kw,+ )+++SPEECH_WAV = ("audio/wav", _wav())+MUSIC_REPLY = (+ "application/json",+ json.dumps({"audio": base64.b64encode(_wav()).decode()}).encode(),+)+++def test_speech_never_forwards_generic_sampling():+ b, srv = _backend_with(_speech_model("moss_tts_nano"), SPEECH_WAV)+ wav, rate = b.generate_audio_response("hello", temperature = 0.6, top_p = 0.9, seed = 7)+ path, body = srv.calls[0]+ assert path == "/v1/audio/speech" and rate == 24000 and wav[:4] == b"RIFF"+ assert body == {"model": "studio-test", "input": "hello", "seed": "7"}+++def test_speech_passes_instruction_language_and_default_voice():+ b, srv = _backend_with(_speech_model("pocket_tts"), SPEECH_WAV)+ b.generate_audio_response("hi", instructions = " warm ", language = "en")+ body = srv.calls[0][1]+ assert body["voice"] == "alba"+ assert body["options"] == {"instruct": "warm", "language": "en"}+++def test_audio_options_reach_the_request_validated():+ schema = acm.option_schema(acm.FAMILIES["kokoro_tts"], KOKORO_SPEC, None)+ b, srv = _backend_with(_speech_model("kokoro_tts", options = schema), SPEECH_WAV)+ b.generate_audio_response(+ "hi", audio_options = {"voice": "am_adam", "speed": 1.5, "bogus": 1, "mode": "zzz"}+ )+ body = srv.calls[0][1]+ assert body["voice"] == "am_adam" and body["options"] == {"speed": 1.5}+++def test_speech_retry_keeps_package_defaults_and_user_options_and_covers_500():+ from core.inference.audio_cpp_server import AudioCppRequestError++ design = _speech_model("qwen3_tts", name = "Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF")+ b, srv = _backend_with(design, SPEECH_WAV)+ calls = []++ def post_json(path, payload, **kwargs):+ calls.append(json.loads(json.dumps(payload)))+ if len(calls) == 1:+ raise AudioCppRequestError(500, "unknown option: language")+ return SPEECH_WAV++ srv.post_json = post_json+ b.generate_audio_response("hi", language = "en")+ assert calls[0]["options"]["language"] == "en" and calls[0]["options"]["instruct"]+ # The retry drops the request's hints, never the package's own instruction.+ assert calls[1]["options"] == design.request_defaults["options"]+++def test_a_busy_server_is_not_retried():+ from core.inference.audio_cpp_server import AudioCppRequestError++ b, srv = _backend_with(_speech_model("kokoro_tts"), SPEECH_WAV)++ def post_json(path, payload, **kwargs):+ raise AudioCppRequestError(503, "server_busy")++ srv.post_json = post_json+ with pytest.raises(RuntimeError, match = "server_busy"):+ b.generate_audio_response("hi", instructions = "warm")+++def test_music_maps_description_lyrics_and_duration():+ b, srv = _backend_with(_speech_model("ace_step"), MUSIC_REPLY)+ wav, _ = b.generate_audio_response(+ "[verse] la la", instructions = "synth pop", max_new_tokens = 1500+ )+ path, body = srv.calls[0]+ assert path == "/v1/tasks/run" and wav[:4] == b"RIFF"+ assert body["request"] == {+ "text": "synth pop",+ "duration_seconds": 60.0,+ "lyrics": "[verse] la la",+ }+++def test_music_without_a_description_uses_the_prompt_and_stable_audio_drops_lyrics():+ b, srv = _backend_with(_speech_model("stable_audio"), MUSIC_REPLY)+ b.generate_audio_response("uplifting house", max_new_tokens = 0)+ assert srv.calls[0][1]["request"] == {"text": "uplifting house", "duration_seconds": 30.0}+++def test_minimax_takes_the_caption_as_input_and_lyrics_and_duration_as_options():+ minimax = _speech_model("minimax_music3", options = acm.FAMILIES["minimax_music3"].options)+ b, srv = _backend_with(minimax, MUSIC_REPLY)+ b.generate_audio_response(+ "[verse] hi", instructions = "lofi", max_new_tokens = 500, seed = 3, audio_options = {"top_k": 9}+ )+ request = srv.calls[0][1]["request"]+ assert request["text"] == "lofi" and request["seed"] == "3"+ # The runtime rejects duration_sec beside duration_seconds ("conflicting option values").+ assert request["options"] == {"top_k": 9, "lyrics": "[verse] hi"}+ assert request["duration_seconds"] == 20.0+ with pytest.raises(RuntimeError, match = "needs lyrics"):+ b.generate_audio_response("", instructions = "lofi")+++def test_yue2_takes_the_description_as_its_required_style():+ b, srv = _backend_with(_speech_model("yue2"), MUSIC_REPLY)+ b.generate_audio_response("[chorus] oh", instructions = "rock, male vocal")+ request = srv.calls[0][1]["request"]+ assert request["text"] == "[chorus] oh"+ assert request["options"] == {+ "style": "rock, male vocal",+ "lyrics": "[chorus] oh",+ "semantic_max_tokens": 2048,+ "semantic_min_tokens": 200,+ }+ with pytest.raises(RuntimeError, match = "style"):+ b.generate_audio_response("[chorus] oh")+++def test_task_response_without_audio_is_an_error():+ with pytest.raises(RuntimeError, match = "no audio"):+ audio_cpp_backend._audio_from_task_response("application/json", b'{"text": "x"}')+++def test_generation_needs_an_active_model():+ b = audio_cpp_backend.AudioCppBackend()+ with pytest.raises(RuntimeError, match = "No active audio model"):+ b.generate_audio_response("x")+++def test_load_rejects_speech_to_text_models():+ b = audio_cpp_backend.AudioCppBackend()+ with pytest.raises(RuntimeError, match = "speech-to-text"):+ b.load_model(SimpleNamespace(identifier = CANARY.id, audio_cpp = CANARY))+++def test_status_fields_of_a_loaded_model():+ schema = acm.option_schema(acm.FAMILIES["kokoro_tts"], KOKORO_SPEC, None)+ fields = audio_cpp_backend.model_info_fields(_speech_model("kokoro_tts", options = schema))+ assert fields["audio_family"] == "kokoro_tts" and fields["gguf_variant"] == "Q8_0"+ assert [o["name"] for o in fields["audio_options"]] == [+ "voice",+ "speed",+ "text_chunk_size",+ "mode",+ ]+++# ---------------------------------------------------------------------------+# Routing, config and classification+++def test_stt_routing_forces_the_audiocpp_engine_for_its_models(hub):+ import routes.inference as ri++ _put(_snapshot(hub), CANARY.gguf_file, _gguf_bytes(family = "canary_asr"))+ assert ri._stt_engine_for_model("audiocpp-canary-180m-flash") == "audiocpp"+ assert ri._stt_engine_for_model(CANARY.id) == "audiocpp"+ for alias in ("audiocpp", "audio_cpp", "audio.cpp", " AudioCpp "):+ assert ri._resolve_stt_engine(alias) == "audiocpp"+ assert ri._stt_repo_reference("audiocpp-canary-180m-flash", "audiocpp") == AUDIO_CPP_REPO+ # Saved legacy keys report as themselves (Settings compares against them); folder ids as rows.+ assert ri._stt_resolved_model_id("audiocpp-canary-180m-flash", "audiocpp") == (+ "audiocpp-canary-180m-flash"+ )+ assert ri._stt_resolved_model_id(CANARY.id, "audiocpp") == CANARY.id+++def test_stt_sidecar_resolves_any_cached_asr_and_rejects_the_rest(hub):+ from core.inference import stt_audiocpp_sidecar as s+ from core.inference.stt_sidecar import SttModelIdError, SttModelNotDownloadedError++ _kokoro(hub)+ _put(_snapshot(hub), CANARY.gguf_file, _gguf_bytes(family = "canary_asr"))+ assert s.resolve_audio_cpp_stt_model_id(None) == f"{AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF"+ assert s.resolve_audio_cpp_stt_model("audiocpp-canary-180m-flash").family == "canary_asr"+ assert s.is_model_downloaded(CANARY.id)+ with pytest.raises(SttModelIdError, match = "not a speech-to-text"):+ s.resolve_audio_cpp_stt_model(f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF")+ with pytest.raises(SttModelIdError):+ s.resolve_audio_cpp_stt_model("small")+ with pytest.raises(SttModelNotDownloadedError):+ s.resolve_audio_cpp_stt_model(f"{AUDIO_CPP_REPO}/Parakeet-TDT-0.6B-v3-GGUF")+++def test_registry_keeps_the_resident_engine_when_audiocpp_runtime_is_missing(monkeypatch):+ from core.inference import stt_audiocpp_sidecar, stt_registry++ monkeypatch.setattr(stt_audiocpp_sidecar, "is_available", lambda: False)+ monkeypatch.setattr(stt_audiocpp_sidecar, "is_model_downloaded", lambda model: True)+ assert stt_registry._model_is_downloaded("audiocpp", "audiocpp-canary-180m-flash") is False+++def test_model_config_answers_umbrella_ids_without_the_hub(hub, monkeypatch):+ from utils.models import model_config++ snap = _snapshot(hub)+ _put(snap, "Supertonic-3-GGUF/supertonic-3-f16.gguf", _gguf_bytes(family = "supertonic"))+ _put(snap, CANARY.gguf_file, _gguf_bytes(family = "canary_asr"))++ def refuse(*args, **kwargs):+ raise AssertionError("an umbrella id must not reach a Hub probe")++ monkeypatch.setattr(model_config, "detect_gguf_model_remote", refuse)+ monkeypatch.setattr(model_config, "is_vision_model", refuse)+ config = model_config.ModelConfig.from_identifier(f"{AUDIO_CPP_REPO}/Supertonic-3-GGUF")+ assert config.identifier == f"{AUDIO_CPP_REPO}/Supertonic-3-GGUF"+ assert config.is_audio and config.audio_type == "audiocpp_tts" and config.gguf_variant == "F16"+ assert not config.is_gguf and not config.is_lora and not config.is_vision+ assert config.audio_cpp.family == "supertonic" and config.is_cached+ # A dictation model is not a main-slot model.+ with pytest.raises(ValueError, match = "speech-to-text"):+ model_config.ModelConfig.from_identifier("audiocpp-canary-180m-flash")+++def test_model_config_routes_a_hub_repo_by_its_gguf_header(hub, monkeypatch):+ from utils.models import model_config++ repo = "audio-cpp/Yue2-3B-GGUF"+ snap = _snapshot(hub, repo)+ for rel in (+ "sidecars/yue2-model-config.json",+ "sidecars/yue2-generation-config.json",+ "sidecars/yue2-qwen.tiktoken",+ "sidecars/yue2-vae-config.json",+ ):+ _put(snap, rel, b"{}")+ _put(snap, "yue2-3b-q8_0.gguf", _gguf_bytes(family = "yue2"))+ _put(snap, "yue2-vae-f16.gguf", _gguf_bytes()) # the VAE carries no spec+ monkeypatch.setattr(+ model_config, "detect_gguf_model_remote", lambda *a, **k: "yue2-3b-q8_0.gguf"+ )++ def no_llama(*a, **k):+ raise AssertionError("an audio.cpp GGUF must not reach the llama.cpp preflight")++ monkeypatch.setattr(model_config, "list_gguf_variants", no_llama)+ config = model_config.ModelConfig.from_identifier(repo)+ assert config.audio_type == "audiocpp_music" and not config.is_gguf+ assert config.gguf_variant == "Q8_0" and config.audio_cpp.is_package+ assert config.audio_cpp.model_options["session_options"]["yue2.vae_gguf"] == "yue2-vae-f16.gguf"+++def test_native_audio_helpers_point_at_the_holding_repo(hub):+ from core.inference import native_audio++ _put(+ _snapshot(hub),+ "ACE-Step1.5-GGUF/turbo/ace-step-1.5-turbo-q8_0.gguf",+ _gguf_bytes(family = "ace_step"),+ )+ music = f"{AUDIO_CPP_REPO}/ACE-Step1.5-GGUF"+ assert native_audio.is_native_audio_model(music)+ assert native_audio.audio_cpp_audio_type(music) == "audiocpp_music"+ assert native_audio.native_audio_security_targets(music) == [AUDIO_CPP_REPO]+ assert native_audio.native_audio_security_targets(+ "audio-cpp/Yue2-3B-GGUF", "audiocpp_music"+ ) == ["audio-cpp/Yue2-3B-GGUF"]+ assert "audiocpp_tts" in native_audio.NATIVE_AUDIO_TYPES+ with pytest.raises(ValueError, match = "GGUF variant"):+ native_audio.native_audio_download_plan(music)+++def test_audio_cpp_ggufs_are_classified_off_chat(hub):+ from hub.services.models import catalog_classification as cc+ from utils.gguf_archs import is_audio_cpp_gguf_architecture++ assert is_audio_cpp_gguf_architecture(" AudioCPP ") and not is_audio_cpp_gguf_architecture(+ "llama"+ )+ snap = _kokoro(hub)+ kokoro = snap / "Kokoro-82M-GGUF" / "kokoro-82m-q8_0.gguf"+ asr = _put(snap, CANARY.gguf_file, _gguf_bytes(family = "canary_asr"))+ sep = _put(snap, "HTDemucs-GGUF/htdemucs-q8_0.gguf", _gguf_bytes(family = "htdemucs"))+ music = _put(snap, "Yue2/yue2-3b-q8_0.gguf", _gguf_bytes(family = "yue2"))+ assert cc._gguf_path_task(kokoro) == "text-to-speech"+ assert cc._gguf_path_audio_type(kokoro) == "audiocpp_tts"+ assert cc._gguf_path_task(music) == "text-to-audio"+ assert cc._gguf_path_audio_type(music) == "audiocpp_music"+ assert cc._gguf_path_task(asr) == "automatic-speech-recognition"+ assert cc._gguf_path_task(sep) == "audio-to-audio"+ # Architecture alone (a remote prefix): the family comes from the names.+ assert cc._arch_to_task("audiocpp", ("audio-cpp/MiniMax-Music3-GGUF",)) == "text-to-audio"+ assert cc._arch_to_audio_type("audiocpp", ("Kokoro-82M-GGUF",)) == "audiocpp_tts"+++def test_llama_refuses_an_audio_cpp_gguf_with_a_pointer_to_the_audio_page():+ from core.inference.llama_cpp import LlamaCppBackend++ probe = object.__new__(LlamaCppBackend)+ probe._architecture = "audiocpp"+ probe._gguf_header_parsed = True+ probe._model_identifier = "someone/x-GGUF"+ assert "Audio page" in probe._non_chat_gguf_refusal("x.gguf")+++def test_speech_api_music_default_is_thirty_seconds():+ import routes.inference as ri+ from models.inference import ChatCompletionRequest++ payload = ChatCompletionRequest(messages = [{"role": "user", "content": "x"}], max_tokens = 8192)+ assert (+ ri._tts_max_new_tokens(+ payload, None, audio_type = "audiocpp_music", speech_api_default_max_tokens = True+ )+ == 750+ )+ assert ri._tts_max_new_tokens(payload, None, audio_type = "audiocpp_music") == 240 * 25+++def test_public_id_of_an_audio_cpp_model_is_the_id_itself():+ from core.inference.model_ids import public_model_id+ for mid in (f"{AUDIO_CPP_REPO}/ACE-Step1.5-GGUF/turbo", f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"):+ assert public_model_id(mid) == mid+ # Unrelated three-segment paths are still paths.+ assert public_model_id("some/local/dir") != "some/local/dir"+++def test_umbrella_repo_is_hidden_from_chat():+ from utils.hidden_models import is_hidden_model+ assert is_hidden_model(AUDIO_CPP_REPO)+ assert is_hidden_model("Audio-CPP/audio.cpp-GGUF")+++def test_resident_estimate_scales_with_the_variant():+ import routes.inference as ri++ small = ri.audio_cpp_resident_gb(237 * 1024**2)+ big = ri.audio_cpp_resident_gb(5899 * 1024**2)+ assert 1.5 < small < 3 and 15 < big < 18+++def test_one_failed_transcription_does_not_hide_the_engine(monkeypatch):+ from core.inference import stt_audiocpp_sidecar as s++ monkeypatch.setattr(s.audio_cpp_server, "is_available", lambda: True)+ s.note_runtime_inference_failure("HTTP 500 on a bad clip")+ try:+ assert s.is_available() is True+ finally:+ s.clear_runtime_inference_failure()+++def test_child_home_is_private_and_per_user(tmp_path, monkeypatch):+ from core.inference import audio_cpp_server as srv+ import utils.paths.storage_roots as roots++ monkeypatch.setattr(roots, "studio_root", lambda: tmp_path / "studio")+ monkeypatch.setattr(srv, "_MAX_CHILD_HOME_LEN", len(str(tmp_path)) + 40)+ assert srv._child_home_dir() == tmp_path / "studio" / "cache" / "audiocpp-home"+ monkeypatch.setattr(srv.tempfile, "gettempdir", lambda: str(tmp_path / "tmp"))+ # Too long for eSpeak-ng's data-dir buffer: the short per-user temp home instead.+ monkeypatch.setattr(roots, "studio_root", lambda: tmp_path / ("x" * 60) / "studio")+ assert srv._child_home_dir().parent == tmp_path / "tmp"++ def broken():+ raise OSError("no studio root")++ monkeypatch.setattr(roots, "studio_root", broken)+ home = srv._child_home_dir()+ assert home.parent == tmp_path / "tmp" and home.name.startswith("unsloth-audiocpp-home-")+++def test_espeak_models_need_an_espeak_build(tmp_path, monkeypatch):+ from core.inference import audio_cpp_server as srv++ binary = tmp_path / srv.BINARY_NAME+ binary.write_bytes(b"x")+ kokoro = _speech_model("kokoro_tts", needs_espeak = True)+ assert "eSpeak-ng" in srv.model_runtime_problem(kokoro, str(binary))+ assert srv.model_runtime_problem(CANARY, str(binary)) is None+ (tmp_path / "espeak-ng-data.bin").write_bytes(b"x")+ assert srv.model_runtime_problem(kokoro, str(binary)) is None+ # A record that says eSpeak is not enough once the data was removed or quarantined.+ monkeypatch.setattr(srv, "read_install_record", lambda _binary: {"espeak": True})+ (tmp_path / "espeak-ng-data.bin").unlink()+ assert "eSpeak-ng" in srv.model_runtime_problem(kokoro, str(binary))+ monkeypatch.setattr(srv, "find_audio_cpp_server_binary", lambda: None)+ assert "not installed" in srv.model_runtime_problem(kokoro)+++def test_child_home_is_outside_the_managed_install(monkeypatch, tmp_path):+ from core.inference import audio_cpp_server as srv++ monkeypatch.setattr(srv, "managed_audio_cpp_dir", lambda: tmp_path / "audio.cpp")+ env = srv.child_env(str(tmp_path / srv.BINARY_NAME))+ homes = {v for k, v in env.items() if k in ("HOME", "USERPROFILE", "LOCALAPPDATA", "APPDATA")}+ assert homes and not any(str(tmp_path / "audio.cpp") in h for h in homes)+++def test_a_binary_that_cannot_spawn_is_a_typed_error_and_leaks_nothing(monkeypatch, tmp_path):+ import tempfile as _tempfile++ from core.inference import audio_cpp_server as srv++ made = []+ real_mkdtemp = _tempfile.mkdtemp+ monkeypatch.setattr(+ srv.tempfile,+ "mkdtemp",+ lambda **kw: made.append(real_mkdtemp(dir = tmp_path, **kw)) or made[-1],+ )+ monkeypatch.setattr(srv, "ensure_binary", lambda: str(tmp_path / "missing" / srv.BINARY_NAME))+ monkeypatch.setattr(srv, "model_runtime_problem", lambda model, binary = None: None)+ with pytest.raises(srv.AudioCppUnavailableError):+ srv.AudioCppServer.start(CANARY, str(tmp_path / "m.gguf"))+ assert made and not os.path.exists(made[0])+++def test_a_package_config_carries_its_session_options(tmp_path, monkeypatch):+ from core.inference import audio_cpp_server as srv++ written = {}++ class Stop(Exception):+ pass++ def fake_popen(command, *a, **k):+ config = command[command.index("--config") + 1]+ written.update(json.loads(Path(config).read_text(encoding = "utf-8")))+ raise Stop()++ monkeypatch.setattr(srv, "ensure_binary", lambda: str(tmp_path / srv.BINARY_NAME))+ monkeypatch.setattr(srv, "model_runtime_problem", lambda model, binary = None: None)+ monkeypatch.setattr(srv, "select_backend", lambda binary, force_cpu: "cpu")+ monkeypatch.setattr(srv.subprocess, "Popen", fake_popen)+ yue2 = _model(+ "Yue2-3B-GGUF",+ "yue2",+ "music",+ primary = "",+ model_options = {"session_options": {"yue2.model_gguf": "yue2-3b-bf16.gguf"}},+ )+ with pytest.raises(Stop):+ srv.AudioCppServer.start(yue2, str(tmp_path / "pkg"))+ entry = written["models"][0]+ assert (+ entry["family"] == "yue2"+ and entry["task"] == "gen"+ and entry["path"] == str(tmp_path / "pkg")+ )+ assert entry["session_options"] == {"yue2.model_gguf": "yue2-3b-bf16.gguf"}+++# ---------------------------------------------------------------------------+# Hub deletion+++def test_clearing_the_hub_cache_prunes_the_link_farm(hub, monkeypatch):+ from utils import cache_inventory++ snap = _snapshot(hub)+ _put(snap, CANARY.gguf_file, b"GGUF")+ monkeypatch.setattr(audio_cpp_files.sys, "platform", "win32")+ served = audio_cpp_files.materialize(CANARY, hub_cache = hub)+ pruned = []+ real = audio_cpp_files.prune_link_farm+ monkeypatch.setattr(+ audio_cpp_files, "prune_link_farm", lambda root = None: pruned.append(root) or real(root)+ )+ monkeypatch.setattr(cache_inventory, "_training_refusal", lambda key: None)+ monkeypatch.setattr(cache_inventory, "_inference_refusal", lambda key: None)+ monkeypatch.setattr(cache_inventory, "_link_mode_refusal", lambda key: None)+ monkeypatch.setattr(cache_inventory, "_reserve_downloads", lambda key: ([], None))+ monkeypatch.setattr(cache_inventory, "_release_downloads", lambda reserved: None)+ monkeypatch.setattr(cache_inventory, "_resolve_roots", lambda definition: [hub])++ def empty(root, **_kwargs):+ import shutil+ shutil.rmtree(root / ("models--" + AUDIO_CPP_REPO.replace("/", "--")))+ return cache_inventory.PurgeOutcome()++ monkeypatch.setattr(cache_inventory, "empty_cache_root", empty)+ cache_inventory.purge_cache("hf_hub")+ assert pruned == [hub]+ assert not os.path.exists(served)+++def test_deleting_any_repo_prunes_the_farm_of_the_cache_it_was_in(tmp_path, monkeypatch):+ import asyncio++ from hub.services.models import deletion+ from hub.utils import hf_cache_state++ other_root = tmp_path / "old" / "hub"+ repo = "audio-cpp/Yue2-3B-GGUF"+ repo_folder = other_root / ("models--" + repo.replace("/", "--"))+ (repo_folder / "snapshots" / ("a" * 40)).mkdir(parents = True)+ monkeypatch.setattr(hf_cache_state, "hf_cache_roots", lambda: [other_root])+ monkeypatch.setattr(deletion.account_access, "require_installation_owner", lambda: None)+ for guard in (+ "_llama_cpp_blocks_delete",+ "_inference_backend_blocks_delete",+ "_audio_cpp_blocks_delete",+ ):+ monkeypatch.setattr(deletion, guard, lambda *a: False)+ for guard in ("_diffusion_blocks_delete", "_video_blocks_delete"):+ monkeypatch.setattr(deletion, guard, lambda *a: None)+ monkeypatch.setattr(deletion, "resolve_cached_repo_id_case", lambda repo_id, repo_type: repo_id)+ monkeypatch.setattr(deletion.downloads.registry, "begin_delete", lambda *a: True)+ monkeypatch.setattr(deletion.downloads.registry, "end_delete", lambda *a: None)+ monkeypatch.setattr(+ deletion, "_delete_cached_model_blocking", lambda *a, **k: {"deleted": True}+ )+ monkeypatch.setattr(deletion.cache_inventory, "invalidate_hf_cache_scans", lambda: None)+ pruned = []+ monkeypatch.setattr(audio_cpp_files, "prune_link_farm", lambda root = None: pruned.append(root))+ asyncio.run(deletion.delete_cached_model_response(repo, cache_path = str(repo_folder)))+ # The Hub row sends the repo folder; the farm sits beside that folder's hub root.+ assert pruned == [other_root.resolve()]+++ "state", ["idle", "stt_loading", "stt_loaded", "speech_loading", "speech_active"]+)+def test_delete_guard_covers_resident_and_loading_audio_models(monkeypatch, state):+ from core.inference import orchestrator, stt_audiocpp_sidecar+ from hub.services.models import deletion++ side = stt_audiocpp_sidecar.AudioCppSttSidecar()+ if state == "stt_loading":+ side._loading, side._loading_model = True, f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"+ if state == "stt_loaded":+ side._model_id = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"+ side._server = SimpleNamespace(alive = lambda: True)+ speech = "audiocpp-kokoro-82m"+ backend = SimpleNamespace(+ active_model_name = speech if state == "speech_active" else None,+ loading_models = {speech} if state == "speech_loading" else set(),+ )+ monkeypatch.setattr(stt_audiocpp_sidecar, "get_audio_cpp_stt_sidecar", lambda: side)+ monkeypatch.setattr(orchestrator, "peek_inference_backend", lambda: backend)+ assert deletion._audio_cpp_blocks_delete(AUDIO_CPP_REPO) is (state != "idle")+ assert deletion._audio_cpp_blocks_delete("someone/other-repo") is False+++def test_umbrella_download_jobs_report_under_their_folder_row(hub):+ snap = _snapshot(hub)+ moon = _gguf_bytes(family = "moonshine_asr")+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0.gguf", moon)+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0.gguf", moon)+ assert acm.folder_row_for_download(+ AUDIO_CPP_REPO, "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0"+ ) == (f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF", "small/Q8_0")+ # Not cached yet: the planner key's own path still names the row and quant.+ assert acm.folder_row_for_download(+ AUDIO_CPP_REPO, "PocketTTS-GGUF/english/pocket-tts-english-q8_0"+ ) == (f"{AUDIO_CPP_REPO}/PocketTTS-GGUF", "english/Q8_0")+ assert acm.folder_row_for_download("audio-cpp/Yue2-3B-GGUF", "q8_0") is None+++def test_active_downloads_name_umbrella_jobs_by_row(hub, monkeypatch):+ import asyncio++ from hub.schemas.downloads import ActiveDownload+ from hub.services.models import downloads++ job = ActiveDownload.model_construct(+ repo_id = AUDIO_CPP_REPO, variant = "Kokoro-82M-GGUF/kokoro-82m-q8_0", state = "downloading"+ )+ other = ActiveDownload.model_construct(repo_id = "a/b", variant = "Q4_K_M", state = "downloading")+ monkeypatch.setattr(+ downloads.download_lifecycle, "active_download_refs", lambda *a, **k: [job, other]+ )+ monkeypatch.setattr(+ downloads, "resolve_cached_repo_id_case", lambda repo_id, repo_type: repo_id+ )+ rows = asyncio.run(downloads.get_active_downloads_response()).downloads+ assert [(r.repo_id, r.variant) for r in rows] == [+ (f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF", "Q8_0"),+ ("a/b", "Q4_K_M"),+ ]+ only = asyncio.run(downloads.get_active_downloads_response(f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"))+ assert [r.repo_id for r in only.downloads] == [f"{AUDIO_CPP_REPO}/Kokoro-82M-GGUF"]+++def test_stt_requests_carry_their_variant_in_the_model_id():+ from models.inference import SttLoadRequest++ folder = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"+ assert (+ SttLoadRequest(model = folder, engine = "audiocpp", gguf_variant = "tiny").model+ == f"{folder}:tiny"+ )+ assert SttLoadRequest(model = "audiocpp-moonshine-small", gguf_variant = "Q8_0").model == (+ "audiocpp-moonshine-small:Q8_0"+ )+ assert SttLoadRequest(model = folder, engine = "audiocpp").model == folder+ # Other engines keep their own ids untouched.+ assert SttLoadRequest(+ model = "openai/whisper-small", engine = "transformers", gguf_variant = "x"+ ).model == ("openai/whisper-small")+++def test_stt_sidecar_picks_a_named_sub_variant(hub):+ from core.inference import stt_audiocpp_sidecar as s++ snap = _snapshot(hub)+ moon = _gguf_bytes(family = "moonshine_asr")+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0.gguf", moon)+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0.gguf", moon)+ folder = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"+ assert s.resolve_audio_cpp_stt_model(f"{folder}:small").variant.key == "small/Q8_0"+ assert s.resolve_audio_cpp_stt_model(folder).variant.key == "tiny/Q8_0"+ assert s.resolve_audio_cpp_stt_model_id(f"{folder}:small") == folder+++def _fake_cache_repo(snap):+ files = [+ SimpleNamespace(file_name = path.name, file_path = str(path), blob_path = None)+ for path in sorted(snap.rglob("*"))+ if path.is_file()+ ]+ return SimpleNamespace(+ repo_path = str(snap.parent.parent),+ revisions = [SimpleNamespace(snapshot_path = str(snap), files = files)],+ )+++def _files_under(snap):+ return {p.relative_to(snap).as_posix() for p in snap.rglob("*") if p.is_file()}+++def test_deleting_a_package_mix_keeps_what_another_downloaded_mix_loads(hub, monkeypatch):+ from hub.services.models import deletion++ snap = _minimax(hub, quant = "q4_0")+ header = _gguf_bytes(family = "minimax_music3")+ for rel in ("language_model_q8_0.gguf", "transformer_q8_0.gguf"):+ _put(snap, rel, header) # Q8_0 is complete too, sharing rvq_depth_decoder_q8_0 with Q4_0+ monkeypatch.setattr(+ deletion.gguf_variants,+ "delete_variant_incomplete_blobs_result",+ lambda *a, **k: SimpleNamespace(unresolved = False, deleted = 0, deleted_bytes = 0),+ )+ deletion._delete_gguf_variant_from_repos(+ "audio-cpp/MiniMax-Music3-GGUF", "Q8_0", [_fake_cache_repo(snap)], None, root = hub+ )+ left = _files_under(snap)+ # Q8_0's own weights are gone; every file the Q4_0 mix loads is still there.+ assert "language_model_q8_0.gguf" not in left and "transformer_q8_0.gguf" not in left+ assert set(acm.package_variant_files(left)["Q4_0"]) <= left+ assert "rvq_depth_decoder_q8_0.gguf" in left+ # The last mix takes its shared files with it.+ deletion._delete_gguf_variant_from_repos(+ "audio-cpp/MiniMax-Music3-GGUF", "Q4_0", [_fake_cache_repo(snap)], None, root = hub+ )+ assert not snap.exists() or not [p for p in snap.rglob("*.gguf")]+++def test_package_mixes_show_only_the_studio_option_list():+ runtime = {+ "options": {+ "request": [+ {"name": "cot", "type": "enum", "values": ["off", "full"], "default": "full"},+ {"name": "abc_temperature", "type": "float"},+ {"name": "semantic_penalty_window", "type": "int"},+ ]+ }+ }+ names = [o["name"] for o in acm.option_schema(acm.FAMILIES["yue2"], runtime, None)]+ assert names == [+ "cot",+ "num_inference_steps",+ "guidance_scale",+ "semantic_temperature",+ "semantic_top_p",+ "semantic_top_k",+ ]+ # Other families still follow the runtime's spec.+ assert [o["name"] for o in acm.option_schema(acm.FAMILIES["ace_step"], runtime, None)] == [+ "cot",+ "abc_temperature",+ "semantic_penalty_window",+ ]+++def test_yue2_lists_only_its_package_mixes(hub):+ snap = _snapshot(hub, "audio-cpp/Yue2-3B-GGUF")+ for rel in (+ "sidecars/yue2-model-config.json",+ "sidecars/yue2-generation-config.json",+ "sidecars/yue2-qwen.tiktoken",+ "sidecars/yue2-vae-config.json",+ ):+ _put(snap, rel, b"{}")+ for quant in ("q8_0", "bf16", "q4_0", "ios-q4_0"):+ _put(snap, f"yue2-3b-{quant}.gguf", _gguf_bytes(family = "yue2"))+ for vae in ("f16", "f32"):+ _put(snap, f"yue2-vae-{vae}.gguf", _gguf_bytes())+ model = acm.resolve("audio-cpp/Yue2-3B-GGUF", network = False)+ assert [v.key for v in model.variants] == ["Q8_0", "BF16", "Q4_0"]+ assert all("yue2-vae-f16.gguf" in [f.path for f in v.files] for v in model.variants)+++def _audio_load(+ tmp_path,+ arch,+ name = "model-Q4_K_M.gguf",+):+ path = tmp_path / name+ path.write_bytes(_gguf_bytes(arch = arch))+ config = SimpleNamespace(+ identifier = "someone/model-GGUF",+ gguf_file = str(path),+ gguf_verified = None,+ gguf_hf_repo = None,+ gguf_variant = None,+ )+ return config, SimpleNamespace(audio_device = "auto")+++def test_an_audio_page_load_of_a_chat_gguf_is_refused(tmp_path, monkeypatch):+ import routes.inference as ri+ from utils.models import gguf_metadata++ config, request = _audio_load(tmp_path, "qwen3")+ monkeypatch.setattr(gguf_metadata, "read_gguf_tts_audio_type", lambda path: None)+ assert "not an audio model" in ri._audio_intent_gguf_refusal(config, request)+ # Chat loads (no audio_device) are not this check's business.+ assert ri._audio_intent_gguf_refusal(config, SimpleNamespace(audio_device = None)) is None+ # A speech-codec GGUF the page runs through llama-server passes, by vocab or by name.+ monkeypatch.setattr(gguf_metadata, "read_gguf_tts_audio_type", lambda path: "snac")+ assert ri._audio_intent_gguf_refusal(config, request) is None+ monkeypatch.setattr(gguf_metadata, "read_gguf_tts_audio_type", lambda path: None)+ orpheus, _ = _audio_load(tmp_path, "llama", name = "orpheus-3b-0.1-ft-Q4_K_M.gguf")+ assert ri._audio_intent_gguf_refusal(orpheus, request) is None+ # A file not on disk yet is left to the load's own checks.+ config.gguf_file = str(tmp_path / "absent.gguf")+ assert ri._audio_intent_gguf_refusal(config, request) is None+++def test_stt_takes_the_variant_keys_gguf_variants_lists_even_from_a_partial_cache(hub):+ from core.inference import stt_audiocpp_sidecar as s+ from models.inference import SttLoadRequest++ folder = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"+ assert acm.split_variant_ref(f"{folder}:small/Q8_0") == (folder, "small/Q8_0")+ request = SttLoadRequest(model = folder, engine = "audiocpp", gguf_variant = "small/Q8_0")+ assert request.model == f"{folder}:small/Q8_0"+ # Only small is downloaded, so the cache alone would call it plain Q8_0.+ _put(+ _snapshot(hub),+ "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0.gguf",+ _gguf_bytes(family = "moonshine_asr"),+ )+ for wanted in ("small/Q8_0", "small", "Q8_0"):+ model = s.resolve_audio_cpp_stt_model(f"{folder}:{wanted}")+ assert model.unsupported is None+ assert model.gguf_file.endswith("moonshine-streaming-small-q8_0.gguf")+ assert s.resolve_audio_cpp_stt_model(f"{folder}:small/Q8_0").variant.key == "small/Q8_0"+ assert s.resolve_audio_cpp_stt_model(f"{folder}:small").variant.key == "small/Q8_0"+ assert s.is_model_downloaded(f"{folder}:small/Q8_0")+ # A variant that is not on disk is still refused rather than swapped for another.+ tiny = acm.resolve(folder, "tiny/Q8_0", network = False)+ assert "not found" in tiny.unsupported+ # A file stem is a spelling of its own row, not a new scope.+ stem = acm.resolve(folder, "moonshine-streaming-small-q8_0", network = False)+ assert stem.variant.key == "Q8_0" and stem.unsupported is None+++def test_yue2_length_follows_the_requested_duration():+ b, srv = _backend_with(_speech_model("yue2"), MUSIC_REPLY)+ b.generate_audio_response("[chorus] oh", instructions = "rock", max_new_tokens = 125)+ options = srv.calls[0][1]["request"]["options"]+ # 5 s at 25 frames per second, with the default 200-frame floor lowered to fit.+ assert options["semantic_max_tokens"] == 125 and options["semantic_min_tokens"] == 125+ b.generate_audio_response("[chorus] oh", instructions = "rock", max_new_tokens = 1500)+ options = srv.calls[1][1]["request"]["options"]+ assert options["semantic_max_tokens"] == 1500 and options["semantic_min_tokens"] == 200+++def test_music_requests_missing_a_required_field_are_a_400_message():+ import routes.inference as ri++ assert ri._audio_cpp_music_request_problem("yue2", "[verse] la", "") == (+ "YuE2 needs a style description."+ )+ assert ri._audio_cpp_music_request_problem("minimax_music3", " ", "lofi") == (+ "MiniMax Music 3 needs lyrics."+ )+ assert ri._audio_cpp_music_request_problem("yue2", "", "rock") is None+ assert ri._audio_cpp_music_request_problem("ace_step", "", "") is None+++def test_a_variantless_stt_id_keeps_the_loaded_variant_and_an_explicit_one_switches(+ hub, monkeypatch+):+ from core.inference import stt_audiocpp_sidecar as s++ snap = _snapshot(hub)+ moon = _gguf_bytes(family = "moonshine_asr")+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0.gguf", moon)+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0.gguf", moon)+ folder = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"+ small = s.resolve_audio_cpp_stt_model(f"{folder}:small/Q8_0")++ started = []++ class _Server:+ def __init__(self, model):+ self.model, self.backend = model, "cpu"++ def alive(self):+ return True++ def stop(self):+ pass++ def start(model, path, **kwargs):+ started.append(model.variant.key)+ return _Server(model)++ monkeypatch.setattr(s, "ensure_engine_available", lambda: "audiocpp_server")+ monkeypatch.setattr(s.AudioCppServer, "start", start)+ side = s.AudioCppSttSidecar()+ try:+ side.load(f"{folder}:small/Q8_0")+ assert started == ["small/Q8_0"]+ # Settings and dictation send the bare row id: that is the loaded small, not the default tiny.+ assert side.keep_loaded_variant(folder) == small.canonical_id+ assert side.keep_loaded_variant("audiocpp-moonshine-tiny") != small.canonical_id+ side.load(folder)+ assert started == ["small/Q8_0"] and side.loaded_variant == "small/Q8_0"+ # An explicit variant still switches.+ side.load(f"{folder}:tiny/Q8_0")+ assert started == ["small/Q8_0", "tiny/Q8_0"] and side.loaded_variant == "tiny/Q8_0"+ finally:+ side.unload()+ # Nothing loaded: the bare row id means the row's default.+ assert side.keep_loaded_variant(folder) == folder+++def test_stt_status_speaks_legacy_keys_to_the_clients_that_saved_them(hub, monkeypatch):+ from core.inference import stt_audiocpp_sidecar as s++ snap = _snapshot(hub)+ moon = _gguf_bytes(family = "moonshine_asr")+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-tiny-q8_0.gguf", moon)+ _put(snap, "Moonshine-Streaming-GGUF/moonshine-streaming-small-q8_0.gguf", moon)+ _put(snap, CANARY.gguf_file, _gguf_bytes(family = "canary_asr"))+ downloaded = s.downloaded_model_ids()+ folder = f"{AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF"+ # Folder ids for the Audio page, and each key whose own folder and variant is on disk.+ for name in (+ folder,+ CANARY.id,+ "audiocpp-canary-180m-flash",+ "audiocpp-moonshine-tiny",+ "audiocpp-moonshine-small",+ ):+ assert name in downloaded+ assert "audiocpp-parakeet-tdt-0.6b-v3" not in downloaded++ class _Server:+ def __init__(self, model):+ self.model, self.backend = model, "cpu"++ def alive(self):+ return True++ def stop(self):+ pass++ monkeypatch.setattr(s, "ensure_engine_available", lambda: "audiocpp_server")+ monkeypatch.setattr(s.AudioCppServer, "start", lambda model, path, **kw: _Server(model))+ side = s.AudioCppSttSidecar()+ try:+ side.load("audiocpp-moonshine-small")+ assert (+ side.loaded_model == "audiocpp-moonshine-small" and side.loaded_variant == "small/Q8_0"+ )+ # The same model named by its folder row reports the row, without a restart.+ side.load(f"{folder}:small/Q8_0")+ assert side.loaded_model == folder+ side.load("audiocpp-moonshine-small")+ assert side.loaded_model == "audiocpp-moonshine-small"+ # Unloading by either name finds it.+ side.unload(expected_model = folder)+ assert side.loaded_model is None+ finally:+ side.unload()+++def test_stt_errors_do_not_name_the_engine(hub):+ from core.inference import stt_audiocpp_sidecar as s+ from core.inference.stt_sidecar import SttModelIdError++ with pytest.raises(SttModelIdError) as refused:+ s.resolve_audio_cpp_stt_model("small")+ assert "audio.cpp" not in str(refused.value) and "audio runtime" in str(refused.value)+ unknown = acm.family_policy("brand_new_family", None)+ assert "audio.cpp" not in unknown.unsupported+++def test_standalone_music_gguf_rows_are_not_offered_to_chat(hub):+ from huggingface_hub import scan_cache_dir++ from hub.services.models import cache_inventory++ _put(_snapshot(hub, "audio-cpp/Yue2-3B-GGUF"), "yue2-3b-q8_0.gguf", _gguf_bytes(family = "yue2"))+ # The fixture cache passed in: left to itself the scanner walks the machine's own caches.+ scans = [scan_cache_dir(hub)]+ rows = {+ r["repo_id"]: r+ for r in cache_inventory._scan_cached_gguf(cache_scans = scans, active_hub_cache = hub)+ }+ assert rows["audio-cpp/Yue2-3B-GGUF"]["task"] == "text-to-audio"+ assert rows["audio-cpp/Yue2-3B-GGUF"]["capabilities"]["can_chat"] is False+++def test_a_miss_without_a_token_is_not_served_to_a_caller_with_one(monkeypatch):+ seen = []++ def fake(ref, wanted, hf_token, network, tags):+ seen.append(hf_token)+ return CANARY if hf_token else None++ monkeypatch.setattr(acm, "_resolve_uncached", fake)+ acm._resolve_cache.clear()+ assert acm.resolve("someone/Gated-ASR-GGUF") is None+ assert acm.resolve("someone/Gated-ASR-GGUF", hf_token = "hf_secret") is CANARY+ assert acm.resolve("someone/Gated-ASR-GGUF", hf_token = "hf_secret") is CANARY+ assert seen == [None, "hf_secret"]+++def test_deleting_from_an_inactive_cache_prunes_that_caches_farm(monkeypatch, tmp_path):+ import asyncio++ from hub.services.models import deletion+ from hub.utils import hf_cache_state++ active, old = tmp_path / "active" / "hub", tmp_path / "old" / "hub"+ pruned = []+ monkeypatch.setattr(deletion.account_access, "require_installation_owner", lambda: None)+ for name in (+ "_llama_cpp_blocks_delete",+ "_inference_backend_blocks_delete",+ "_audio_cpp_blocks_delete",+ ):+ monkeypatch.setattr(deletion, name, lambda *a: False)+ monkeypatch.setattr(deletion, "_diffusion_blocks_delete", lambda *a: None)+ monkeypatch.setattr(deletion, "_video_blocks_delete", lambda *a: None)+ monkeypatch.setattr(deletion, "resolve_cached_repo_id_case", lambda r, **k: r)+ # The repo lives only in the remembered, inactive cache; cache_path is omitted.+ monkeypatch.setattr(+ deletion, "_delete_cached_model_blocking", lambda *a, **k: {"status": "deleted"}+ )+ monkeypatch.setattr(hf_cache_state, "hf_cache_roots", lambda *a: [active, old])+ monkeypatch.setattr(+ audio_cpp_files, "prune_link_farm", lambda root = None: pruned.append(root) or 0+ )+ asyncio.run(deletion.delete_cached_model_response("audio-cpp/Yue2-3B-GGUF"))+ assert old in pruned+++def test_a_dictation_server_training_moved_to_cpu_returns_to_the_gpu_after(hub, monkeypatch):+ from core.inference import stt_audiocpp_sidecar as s++ _put(_snapshot(hub), CANARY.gguf_file, _gguf_bytes(family = "canary_asr"))+ started = []++ class _Server:+ def __init__(self, cpu):+ self.backend = "cpu" if cpu else "cuda"++ def alive(self):+ return True++ def stop(self):+ pass++ def start(+ model,+ path,+ force_cpu = False,+ **kwargs,+ ):+ started.append(force_cpu)+ return _Server(force_cpu)++ training = [True]+ monkeypatch.setattr(s, "ensure_engine_available", lambda: "audiocpp_server")+ monkeypatch.setattr(s, "_training_active", lambda: training[0])+ monkeypatch.setattr(s.AudioCppServer, "start", start)+ side = s.AudioCppSttSidecar()+ model = f"{AUDIO_CPP_REPO}/Canary-180M-Flash-GGUF"+ try:+ side.load(model, device = "gpu")+ side.load(model, device = "gpu") # still training: kept on the CPU, no restart+ assert started == [True]+ training[0] = False+ side.load(model, device = "gpu")+ assert started == [True, False] and side.device == "cuda"+ finally:+ side.unload()+++def test_a_remote_header_miss_without_a_token_is_not_served_to_one_with_it(monkeypatch):+ from core.inference import diffusion_compat++ seen = []++ def read(repo, filename, token, **kw):+ seen.append(token)+ return _gguf_bytes(family = "canary_asr") if token else None++ monkeypatch.setattr(diffusion_compat, "_read_gguf_header", read)+ assert acm.read_remote_header("someone/Gated-GGUF", "a.gguf", None, size = 64) is None+ header = acm.read_remote_header("someone/Gated-GGUF", "a.gguf", "hf_secret", size = 64)+ assert header is not None and header.family == "canary_asr" and seen == [None, "hf_secret"]+++def test_a_finished_download_is_listed_on_the_next_status_poll(hub):+ """Status polls during the download cache a listing without the model; the download's own+ forget() must drop it, or the first poll after completion reads as a failed download."""+ assert acm.downloaded_models("asr") == []+ _put(+ _snapshot(hub),+ "Qwen3-ASR-0.6B-GGUF/qwen3-asr-0.6b-q8_0.gguf",+ _gguf_bytes(family = "qwen3_asr"),+ )+ acm.forget(f"{AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF")+ assert [m.id for m in acm.downloaded_models("asr")] == [f"{AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF"]+++def test_a_variant_download_reports_the_row_the_caller_tracks():+ """The Audio page tracks the bare row; a variant pick reaches the worker as ``row:variant``."""+ import threading++ from core.inference.stt_audiocpp_sidecar import _AudioCppDownloadState++ state = _AudioCppDownloadState()+ release = threading.Event()+ state._model_id = f"{AUDIO_CPP_REPO}/Moonshine-GGUF:tiny/Q8_0"+ state._thread = threading.Thread(target = release.wait, daemon = True)+ state._thread.start()+ try:+ assert state.status()["model"] == f"{AUDIO_CPP_REPO}/Moonshine-GGUF"+ finally:+ release.set()+++def test_missing_files_are_counted_in_the_snapshot_downloads_land_in(hub):+ from dataclasses import replace++ old = _snapshot(hub, sha = "b" * 40, main = False)+ main = _snapshot(hub) # refs/main+ gguf = RepoFile("PocketTTS-GGUF/english/pocket-tts-english-q8_0.gguf", 4)+ voice = RepoFile("PocketTTS-GGUF/english/embeddings/alba.safetensors", 1)+ _put(old, gguf.path, b"GGUF") # an older revision holds more of the files+ variant = acm.AudioCppVariant("english/Q8_0", (gguf, voice), gguf.path)+ model = replace(CANARY, folder = "PocketTTS-GGUF", variant = variant, variants = (variant,))+ # Downloads go to refs/main, so that is where the gap is measured; the old snapshot would+ # report only the voice missing and never become complete.+ assert audio_cpp_files.missing_files(model, hub_cache = hub) == [(gguf.path, 4), (voice.path, 1)]+ _put(main, gguf.path, b"GGUF")+ _put(main, voice.path, b"v")+ assert audio_cpp_files.missing_files(model, hub_cache = hub) == []diff --git a/studio/backend/tests/test_audio_cpp_runtime_status.py b/studio/backend/tests/test_audio_cpp_runtime_status.pynew file mode 100644index 00000000000..1c7009903e0--- /dev/null+++ b/studio/backend/tests/test_audio_cpp_runtime_status.py@@ -0,0 +1,95 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The ``audio_cpp_runtime`` block of /audio/stt/status the Audio page reads before a load."""++import asyncio+import json++from core.inference import audio_cpp_server+from routes import inference+++def _patch(+ monkeypatch,+ *,+ binary,+ record = None,+ espeak = False,+):+ monkeypatch.setattr(audio_cpp_server, "find_audio_cpp_server_binary", lambda: binary)+ monkeypatch.setattr(audio_cpp_server, "read_install_record", lambda _binary: record or {})+ monkeypatch.setattr(audio_cpp_server, "binary_has_espeak", lambda _binary: espeak)+++def test_runtime_available_with_espeak(monkeypatch):+ _patch(+ monkeypatch,+ binary = "/opt/audio.cpp/audiocpp_server",+ record = {"backend": "cuda", "release_tag": "v0.4.0"},+ espeak = True,+ )+ assert inference._audio_cpp_runtime_status() == {+ "available": True,+ "espeak": True,+ "backend": "cuda",+ "release_tag": "v0.4.0",+ }+++def test_runtime_available_without_espeak(monkeypatch):+ # A custom or upstream build: no install record, no eSpeak data beside the server.+ _patch(monkeypatch, binary = "/usr/local/bin/audiocpp_server", record = {}, espeak = False)+ assert inference._audio_cpp_runtime_status() == {+ "available": True,+ "espeak": False,+ "backend": None,+ "release_tag": None,+ }+++def test_runtime_missing(monkeypatch):+ _patch(monkeypatch, binary = None, espeak = True)+ assert inference._audio_cpp_runtime_status() == {+ "available": False,+ "espeak": False,+ "backend": None,+ "release_tag": None,+ }+++def test_runtime_probe_error_reports_unavailable(monkeypatch):+ def boom():+ raise OSError("permission denied")++ monkeypatch.setattr(audio_cpp_server, "find_audio_cpp_server_binary", boom)+ assert inference._audio_cpp_runtime_status()["available"] is False+++def test_malformed_record_fields_are_dropped(monkeypatch):+ _patch(+ monkeypatch,+ binary = "/opt/audio.cpp/audiocpp_server",+ record = {"backend": ["cuda"], "release_tag": 7},+ espeak = False,+ )+ status = inference._audio_cpp_runtime_status()+ assert status["backend"] is None and status["release_tag"] is None+++def test_stt_status_payload_includes_runtime_block(monkeypatch):+ _patch(+ monkeypatch,+ binary = "/opt/audio.cpp/audiocpp_server",+ record = {"backend": "vulkan", "release_tag": "v0.4.0"},+ espeak = False,+ )+ monkeypatch.setattr(inference.account_access, "managed_account", lambda: False)+ response = asyncio.run(inference.stt_status(model = None, current_subject = "owner"))+ body = json.loads(response.body)+ assert body["audio_cpp_runtime"] == {+ "available": True,+ "espeak": False,+ "backend": "vulkan",+ "release_tag": "v0.4.0",+ }diff --git a/studio/backend/tests/test_audio_cpp_server_http.py b/studio/backend/tests/test_audio_cpp_server_http.pynew file mode 100644index 00000000000..cd48be382b2--- /dev/null+++ b/studio/backend/tests/test_audio_cpp_server_http.py@@ -0,0 +1,274 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""AudioCppServer against a real child process: a small fake ``audiocpp_server`` speaking the HTTP contract."""++import io+import json+import sys+import textwrap+import threading+import time+import wave++import pytest++from core.inference import audio_cpp_server as srv+from core.inference.audio_cpp_models import AudioCppModel, AudioCppVariant, RepoFile+++def _model(folder: str, family: str, task: str) -> AudioCppModel:+ main = RepoFile(f"{folder}/{folder.lower()}-q8_0.gguf", 1)+ variant = AudioCppVariant("Q8_0", (main,), main.path)+ return AudioCppModel(+ id = f"audio-cpp/audio.cpp-gguf/{folder}",+ repo_id = "audio-cpp/audio.cpp-gguf",+ folder = folder,+ display_name = folder,+ family = family,+ task = task,+ server_task = task,+ variant = variant,+ variants = (variant,),+ default_variant = "Q8_0",+ )+++CANARY = _model("Canary-180M-Flash-GGUF", "canary_asr", "asr")+KOKORO = _model("Kokoro-82M-GGUF", "kokoro_tts", "tts")++FAKE_SERVER = textwrap.dedent(+ r"""+ import email, io, json, sys, time, wave+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer++ cfg = json.load(open(sys.argv[sys.argv.index("--config") + 1], encoding="utf-8"))+ model_id = cfg["models"][0]["id"]+ listed = "wrong-id" if cfg["models"][0]["path"].endswith("wrong-id.gguf") else model_id++ def wav():+ buf = io.BytesIO()+ with wave.open(buf, "wb") as w:+ w.setnchannels(1); w.setsampwidth(2); w.setframerate(16000); w.writeframes(b"\0\0" * 1600)+ return buf.getvalue()++ class H(BaseHTTPRequestHandler):+ def log_message(self, *a): pass+ def reply(self, code, body, ctype="application/json"):+ self.send_response(code); self.send_header("Content-Type", ctype)+ self.send_header("Content-Length", str(len(body))); self.end_headers(); self.wfile.write(body)+ def do_GET(self):+ if self.path == "/health":+ return self.reply(200, json.dumps({"status": "ok", "backend": cfg["backend"]}).encode())+ if self.path == "/v1/models":+ return self.reply(200, json.dumps({"data": [{"id": listed}]}).encode())+ self.reply(404, b"{}")+ def do_POST(self):+ body = self.rfile.read(int(self.headers.get("Content-Length") or 0))+ if self.path == "/v1/audio/speech":+ req = json.loads(body)+ if req.get("input") == "slow":+ time.sleep(30)+ return self.reply(200, wav(), "audio/wav")+ if self.path == "/v1/audio/transcriptions":+ msg = email.message_from_bytes(b"Content-Type: " + self.headers["Content-Type"].encode() + b"\r\n\r\n" + body)+ fields = {}+ for part in msg.get_payload():+ name = part.get_param("name", header="content-disposition")+ fields[name] = part.get_filename() or part.get_payload(decode=True).decode()+ if fields.get("language") == "slow":+ time.sleep(30)+ return self.reply(200, json.dumps({"text": json.dumps(fields, sort_keys=True)}).encode())+ self.reply(404, b"{}")++ ThreadingHTTPServer(("127.0.0.1", cfg["port"]), H).serve_forever()+ """+)+++def fake_binary(tmp_path, monkeypatch):+ script = tmp_path / "fake_server.py"+ script.write_text(FAKE_SERVER, encoding = "utf-8")+ binary = tmp_path / srv.BINARY_NAME+ binary.write_bytes(b"")+ real_popen = srv.subprocess.Popen++ def launch(command, *args, **kwargs):+ # The fake runs as the direct child (no shell wrapper), so stop() terminates the server itself.+ if command and command[0] == str(binary):+ command = [sys.executable, str(script), *command[1:]]+ return real_popen(command, *args, **kwargs)++ monkeypatch.setattr(srv.subprocess, "Popen", launch)+ monkeypatch.setattr(srv, "ensure_binary", lambda: str(binary))+ monkeypatch.setattr(srv, "model_runtime_problem", lambda model, binary = None: None)+ monkeypatch.setattr(srv, "select_backend", lambda binary, force_cpu: "cpu")+ return binary+++def test_ready_only_when_our_model_id_is_listed(fake_binary, tmp_path, monkeypatch):+ monkeypatch.setattr(srv, "_SERVER_START_TIMEOUT_SECONDS", 4.0)+ model = CANARY+ server = srv.AudioCppServer.start(model, str(tmp_path / "m.gguf"))+ try:+ assert server.alive() and server._probe()+ finally:+ server.stop()+ assert not server.alive()+ assert not server._config_dir.exists()+ # A responder that does not list this launch's id is not our child: never treated as ready.+ with pytest.raises(srv.AudioCppUnavailableError, match = "did not start in time"):+ srv.AudioCppServer.start(model, str(tmp_path / "wrong-id.gguf"))+++def test_readiness_ignores_an_ambient_http_proxy(fake_binary, tmp_path, monkeypatch):+ monkeypatch.setattr(srv, "_SERVER_START_TIMEOUT_SECONDS", 6.0)+ for name in ("HTTP_PROXY", "http_proxy"):+ monkeypatch.setenv(name, "http://127.0.0.1:9")+ for name in ("NO_PROXY", "no_proxy"):+ monkeypatch.delenv(name, raising = False)+ server = srv.AudioCppServer.start(KOKORO, str(tmp_path / "m.gguf"))+ try:+ assert server._probe()+ finally:+ server.stop()+++def test_cancel_closes_the_socket_mid_request(fake_binary, tmp_path):+ server = srv.AudioCppServer.start(KOKORO, str(tmp_path / "m.gguf"))+ try:+ cancel = threading.Event()+ threading.Timer(0.3, cancel.set).start()+ started = time.monotonic()+ with pytest.raises(srv.AudioCppRequestCancelledError):+ server.post_json(+ "/v1/audio/speech",+ {"model": server.model_id, "input": "slow"},+ timeout = 20,+ cancel_event = cancel,+ )+ # Returns on the cancel, not on the server's reply or the timeout (Windows never woke the recv).+ assert time.monotonic() - started < 5+ # The server is untouched by the client-side cancel and still serves.+ _ctype, data = server.post_json(+ "/v1/audio/speech", {"model": server.model_id, "input": "hi"}+ )+ with wave.open(io.BytesIO(data)) as w:+ assert w.getframerate() == 16000+ finally:+ server.stop()+++def test_transcription_multipart_carries_model_language_and_file(fake_binary, tmp_path):+ from core.inference.stt_audiocpp_sidecar import AudioCppSttSidecar++ model = CANARY+ server = srv.AudioCppServer.start(model, str(tmp_path / "m.gguf"))+ try:+ side = AudioCppSttSidecar()+ side._server = server+ fields = json.loads(side._post_transcription(b"RIFF....WAVE", "en", None))+ assert fields == {"file": "dictation.wav", "language": "en", "model": server.model_id}+ finally:+ server.stop()+++def test_cancelled_transcription_stops_the_busy_server(fake_binary, tmp_path):+ from core.inference.stt_audiocpp_sidecar import (+ AudioCppSttSidecar,+ SttTranscriptionCancelledError,+ )+ server = srv.AudioCppServer.start(CANARY, str(tmp_path / "m.gguf"))+ try:+ side = AudioCppSttSidecar()+ side._server = server+ cancel = threading.Event()+ threading.Timer(0.3, cancel.set).start()+ with side._lock, pytest.raises(SttTranscriptionCancelledError):+ side._post_transcription(b"RIFF....WAVE", "slow", cancel)+ # The child still decoding the abandoned clip is gone, so the next load starts a fresh one.+ assert side._server is None and not server.alive()+ finally:+ server.stop()+++def test_threads_budget_reaches_the_command_line(fake_binary, tmp_path, monkeypatch):+ seen = {}+ launch = srv.subprocess.Popen # the fixture's launcher++ def spy(command, *args, **kwargs):+ seen["command"] = command+ return launch(command, *args, **kwargs)++ monkeypatch.setattr(srv.subprocess, "Popen", spy)+ monkeypatch.setenv("UNSLOTH_CPU_THREADS", "3")+ server = srv.AudioCppServer.start(KOKORO, str(tmp_path / "m.gguf"))+ server.stop()+ assert seen["command"][-2:] == ["--threads", "3"]+ monkeypatch.setenv("UNSLOTH_CPU_THREADS", "zero")+ assert srv._cpu_threads() is None+++def test_cuda_graphs_are_off_only_for_families_that_wedge_with_them(+ fake_binary, tmp_path, monkeypatch+):+ seen = []+ launch = srv.subprocess.Popen # the fixture's launcher++ def spy(command, *args, **kwargs):+ seen.append(kwargs["env"])+ return launch(command, *args, **kwargs)++ monkeypatch.setattr(srv.subprocess, "Popen", spy)+ monkeypatch.delenv("GGML_CUDA_DISABLE_GRAPHS", raising = False)+ for model in (_model("Nemotron-3.5-ASR-Streaming-0.6B-GGUF", "nemotron_asr", "asr"), CANARY):+ srv.AudioCppServer.start(model, str(tmp_path / "m.gguf")).stop()+ assert seen[0].get("GGML_CUDA_DISABLE_GRAPHS") == "1"+ assert "GGML_CUDA_DISABLE_GRAPHS" not in seen[1]+++def test_gpu_runs_cap_host_threads_unless_the_user_set_a_budget(fake_binary, tmp_path, monkeypatch):+ seen = []+ launch = srv.subprocess.Popen # the fixture's launcher++ def spy(command, *args, **kwargs):+ seen.append(command)+ return launch(command, *args, **kwargs)++ monkeypatch.setattr(srv.subprocess, "Popen", spy)+ monkeypatch.delenv("UNSLOTH_CPU_THREADS", raising = False)+ monkeypatch.setattr(srv.os, "cpu_count", lambda: 192)+ srv.AudioCppServer.start(KOKORO, str(tmp_path / "m.gguf")).stop() # the fixture's CPU backend+ monkeypatch.setattr(srv, "select_backend", lambda binary, force_cpu: "cuda")+ srv.AudioCppServer.start(KOKORO, str(tmp_path / "m.gguf")).stop()+ monkeypatch.setenv("UNSLOTH_CPU_THREADS", "32")+ srv.AudioCppServer.start(KOKORO, str(tmp_path / "m.gguf")).stop()+ assert "--threads" not in seen[0]+ assert seen[1][-2:] == ["--threads", "8"] and seen[2][-2:] == ["--threads", "32"]+++def test_a_custom_build_launches_on_a_backend_it_was_compiled_with(tmp_path, monkeypatch):+ """No install record: a CPU or Vulkan build on an NVIDIA host must not be asked for CUDA."""+ if sys.platform == "win32":+ pytest.skip("shell-script stand-in for the binary")+ from core.inference import audio_cpp_server as srv++ monkeypatch.delenv("UNSLOTH_AUDIO_CPP_BACKEND", raising = False)+ monkeypatch.setattr(srv.sys, "platform", "linux")+ monkeypatch.setattr(+ srv.shutil, "which", lambda name: "/usr/bin/nvidia-smi" if name == "nvidia-smi" else None+ )++ def build(name, backends):+ binary = tmp_path / name / "audiocpp_server"+ binary.parent.mkdir()+ binary.write_text(f"#!/bin/sh\necho 'audio.cpp custom'\necho 'backends: {backends}'\n")+ binary.chmod(0o755)+ return str(binary)++ assert srv.select_backend(build("cpu", "cpu"), False) == "cpu"+ assert srv.select_backend(build("vulkan", "cpu,vulkan"), False) == "vulkan"+ assert srv.select_backend(build("cuda", "cpu,cuda"), False) == "cuda"+ # A build too old to report keeps the host guess.+ assert srv.select_backend(build("silent", ""), False) == "cuda"diff --git a/studio/backend/tests/test_audio_device_guards.py b/studio/backend/tests/test_audio_device_guards.pyindex 7909afb7065..23471905e49 100644--- a/studio/backend/tests/test_audio_device_guards.py+++ b/studio/backend/tests/test_audio_device_guards.py@@ -48,6 +48,18 @@ def test_only_a_native_audio_model_counts_as_a_cpu_audio_load():assert not ri._native_audio_cpu_load(_audio(), _request(None))+def test_an_auto_gguf_audio_load_on_a_cpu_only_runtime_counts_as_cpu(monkeypatch):+ from core.inference import audio_cpp_server++ gguf_tts = _audio(audio_type = "audiocpp_tts")+ monkeypatch.setattr(audio_cpp_server, "runtime_runs_on_cpu", lambda: True)+ assert ri._native_audio_cpu_load(gguf_tts, _request("auto"))+ # Only the GGUF runtime's own backend decides this; other native audio still needs "cpu".+ assert not ri._native_audio_cpu_load(_audio(), _request("auto"))+ monkeypatch.setattr(audio_cpp_server, "runtime_runs_on_cpu", lambda: False)+ assert not ri._native_audio_cpu_load(gguf_tts, _request("auto"))++def test_a_chat_model_cannot_skip_the_guards_by_sending_audio_device():"""audio_device is documented as ignored off the audio path. If it were notgated here, any load could set it and walk past the training guard."""@@ -153,6 +165,72 @@ def test_a_model_loaded_before_this_existed_is_read_as_gpu():assert not ri._resident_audio_placement_matches(_backend(audio_cpu = None), _request("cpu"))+def test_a_gguf_audio_model_on_a_cpu_only_runtime_is_resident_in_cpu_ram(monkeypatch):+ """Auto on a CPU-only runtime lands in CPU RAM: the orchestrator must record that, and a repeat+ Auto load must neither reload it nor take the GPU from a running Images/Video pipeline."""+ import inspect++ from core.inference import audio_cpp_server, orchestrator++ monkeypatch.setattr(audio_cpp_server, "runtime_runs_on_cpu", lambda: True)+ resident = _backend(audio_cpu = True, audio_type = "audiocpp_tts")+ assert ri._resident_audio_placement_matches(resident, _request("auto"))+ assert ri._resident_audio_holds_no_gpu(resident)+ assert "audio_load_runs_on_cpu(_audio_type, audio_device)" in inspect.getsource(orchestrator)+ monkeypatch.setattr(audio_cpp_server, "runtime_runs_on_cpu", lambda: False)+ assert not ri._resident_audio_placement_matches(resident, _request("auto"))+++def test_an_auto_load_on_a_cpu_only_runtime_reaches_the_worker_as_cpu(monkeypatch):+ """The worker hides the accelerators and no card is sized only for an explicit CPU load, so the+ orchestrator must turn Auto into CPU when the runtime can only run there."""+ import threading++ from core.inference import audio_cpp_server+ from core.inference import orchestrator as orch_mod++ seen = {}++ class _StopAfterSelection(threading.Event):+ def is_set(self):+ return "selection" in seen++ def _gpu_selection(*args, **kwargs):+ seen["selection"] = "gpu"+ return [0], {"selection_mode": "auto"}++ monkeypatch.setattr(orch_mod, "prepare_gpu_selection", _gpu_selection)+ orch = orch_mod.InferenceOrchestrator.__new__(orch_mod.InferenceOrchestrator)+ orch.loading_models = set()+ config = types.SimpleNamespace(+ identifier = "unsloth/Kokoro-82M-GGUF",+ audio_type = "audiocpp_tts",+ audio_cpp = object(),+ gguf_variant = None,+ )++ def _load():+ seen.clear()+ orig = orch_mod.audio_device_forces_cpu++ def _forces(value):+ if "selection" not in seen and orig(value):+ seen["selection"] = "cpu"+ return orig(value)++ monkeypatch.setattr(orch_mod, "audio_device_forces_cpu", _forces)+ assert (+ orch.load_model(config, audio_device = "auto", load_cancel_event = _StopAfterSelection())+ is False+ )+ return seen["selection"]++ monkeypatch.setattr(audio_cpp_server, "runtime_runs_on_cpu", lambda: True)+ assert _load() == "cpu"+ monkeypatch.setattr(audio_cpp_server, "runtime_runs_on_cpu", lambda: False)+ assert _load() == "gpu"++def test_a_non_audio_model_keeps_the_shortcut():assert ri._resident_audio_placement_matches(_backend(audio_cpu = None, audio_type = None), _request("cpu")diff --git a/studio/backend/tests/test_gguf_load_cache_reuse.py b/studio/backend/tests/test_gguf_load_cache_reuse.pyindex 3f861e1c15a..7cd85e1bc74 100644--- a/studio/backend/tests/test_gguf_load_cache_reuse.py+++ b/studio/backend/tests/test_gguf_load_cache_reuse.py@@ -1073,6 +1073,9 @@ class TestLoadHubDownloadExclusion:# Read from requested_extra_args, which is what the load was invoked# with rather than the rewritten launch list."requested_llama_extra_args",+ # Constant None: llama-server never serves an audio GGUF.+ "audio_family",+ "audio_options",}unresolved = sorted(namediff --git a/studio/backend/tests/test_orchestrator_unload_cancel.py b/studio/backend/tests/test_orchestrator_unload_cancel.pyindex 1772ec9e52a..2bf4d2ebd9a 100644--- a/studio/backend/tests/test_orchestrator_unload_cancel.py+++ b/studio/backend/tests/test_orchestrator_unload_cancel.py@@ -3868,6 +3868,7 @@ def test_every_long_lived_spawner_consults_the_shutdown_latch():backend = Path(__file__).resolve().parent.parentguarded = {"core/export/orchestrator.py",+ "core/inference/audio_cpp_server.py","core/inference/engine_install.py","core/inference/lemonade_server.py","core/inference/llama_cpp.py",diff --git a/studio/backend/tests/test_presence_penalty.py b/studio/backend/tests/test_presence_penalty.pyindex fe5cb3a255e..52aa4e79619 100644--- a/studio/backend/tests/test_presence_penalty.py+++ b/studio/backend/tests/test_presence_penalty.py@@ -434,7 +434,12 @@ def test_a_video_clip_crosses_the_worker_boundary_only_to_a_backend_that_takes_iworker_source = (Path(__file__).resolve().parents[1] / "core" / "inference" / "worker.py").read_text(encoding = "utf-8")- assert '("is_audio", "audio_type", "has_audio_input", "has_video_input")' in worker_source+ import re++ mirrored = re.search(r'for k in \(\s*("is_audio",[^)]*)\)', worker_source)+ assert mirrored, "the worker's mirrored classification keys moved"+ for key in ("is_audio", "audio_type", "has_audio_input", "has_video_input"):+ assert f'"{key}"' in mirrored.group(1)def test_both_orchestrator_entry_points_forward_the_clip_into_the_command():diff --git a/studio/backend/tests/test_stt_ggml_sidecar.py b/studio/backend/tests/test_stt_ggml_sidecar.pyindex 9595914ed87..da5a07ad4c2 100644--- a/studio/backend/tests/test_stt_ggml_sidecar.py+++ b/studio/backend/tests/test_stt_ggml_sidecar.py@@ -1251,9 +1251,9 @@ def test_unload_all_attempts_every_backend_even_when_one_fails(monkeypatch):asyncio.run(ri.stt_unload(engine = None, current_subject = "tester"))assert excinfo.value.status_code == 500- # The later engines are still attempted after transformers raised. mtmd is- # included so an Unload with no engine frees a resident llama-server too.- assert attempted == ["transformers", "gguf", "mtmd"]+ # The later engines are still attempted after transformers raised. mtmd and audiocpp are+ # included so an Unload with no engine frees a resident llama-server or audiocpp_server too.+ assert attempted == ["transformers", "gguf", "mtmd", "audiocpp"]# 4. free_stt_model_for_training isolates the two backends -----------------------diff --git a/studio/backend/tests/test_stt_registry.py b/studio/backend/tests/test_stt_registry.pyindex 7d3b3e4a983..dabd5714ff4 100644--- a/studio/backend/tests/test_stt_registry.py+++ b/studio/backend/tests/test_stt_registry.py@@ -95,7 +95,7 @@ def test_load_releases_the_other_engines_after_the_target_loads(monkeypatch):# Two engines resident at once doubles VRAM for the whole keep-alive window, but the# release follows the load: a 409 must not cost the user the engine they were using.- assert order == ["load:mtmd", "unload:transformers", "unload:gguf"]+ assert order == ["load:mtmd", "unload:transformers", "unload:gguf", "unload:audiocpp"]def test_load_still_succeeds_when_another_engine_refuses_to_release(monkeypatch):diff --git a/studio/backend/tests/test_stt_sidecar.py b/studio/backend/tests/test_stt_sidecar.pyindex f57d73d1989..9f1098722a9 100644--- a/studio/backend/tests/test_stt_sidecar.py+++ b/studio/backend/tests/test_stt_sidecar.py@@ -1927,3 +1927,14 @@ def test_decoding_stops_as_soon_as_the_request_is_cancelled(monkeypatch):cancelled.set()with pytest.raises(stt_sidecar_module.SttTranscriptionCancelledError):stt_sidecar_module._decode_audio_bounded(buf.getvalue(), cancelled)+++def test_unloading_an_empty_sidecar_skips_the_collection(monkeypatch):+ # The registry releases idle engines on every other engine's transcription; a full+ # gc.collect there cost each audio.cpp / GGUF dictation request ~130 ms.+ collected = []+ monkeypatch.setattr(stt_sidecar_module.gc, "collect", lambda *a: collected.append(1))+ sidecar = stt_sidecar_module.WhisperSttSidecar()+ sidecar.unload(wait = False)+ sidecar.unload()+ assert collected == []diff --git a/studio/backend/utils/cache_inventory.py b/studio/backend/utils/cache_inventory.pyindex 854fadc0e6e..bf8c0394add 100644--- a/studio/backend/utils/cache_inventory.py+++ b/studio/backend/utils/cache_inventory.py@@ -1343,6 +1343,10 @@ def purge_cache(key: str) -> dict:outcome.freed_bytes += root_outcome.freed_bytesoutcome.removed_entries += root_outcome.removed_entriesoutcome.errors.extend(root_outcome.errors)+ if definition.key == "hf_hub":+ # audio.cpp's link farm beside the hub hardlinks its blobs, so they would stay on disk.+ from core.inference.audio_cpp_files import prune_link_farm+ prune_link_farm(root)return _purge_result(definition, outcome)finally:_release_downloads(reserved)diff --git a/studio/backend/utils/gguf_archs.py b/studio/backend/utils/gguf_archs.pyindex e9bc54f2106..d5e85b833b0 100644--- a/studio/backend/utils/gguf_archs.py+++ b/studio/backend/utils/gguf_archs.py@@ -40,3 +40,13 @@ def is_speech_gguf_architecture(architecture: Optional[str]) -> bool:if normalized in SPEECH_GGUF_ARCHS:return Truereturn any(marker in normalized for marker in _VOCODER_MARKERS)+++# ``general.architecture`` of every GGUF audio.cpp writes. Only audiocpp_server reads these (speech,+# music, transcription); llama.cpp has no such architecture.+AUDIO_CPP_GGUF_ARCHITECTURE = "audiocpp"+++def is_audio_cpp_gguf_architecture(architecture: Optional[str]) -> bool:+ """Whether ``general.architecture`` names a GGUF only audio.cpp runs. Case- and space-insensitive."""+ return bool(architecture) and architecture.strip().lower() == AUDIO_CPP_GGUF_ARCHITECTUREdiff --git a/studio/backend/utils/hidden_models.py b/studio/backend/utils/hidden_models.pyindex 351557f2538..3869f2227f1 100644--- a/studio/backend/utils/hidden_models.py+++ b/studio/backend/utils/hidden_models.py@@ -43,6 +43,11 @@ _HIDDEN_STT_REPO_IDS = frozenset()_HIDDEN_STT_REPO_IDS_LOWER = frozenset(repo_id.lower() for repo_id in _HIDDEN_STT_REPO_IDS)+# audio.cpp's umbrella repo: every speech, music and ASR package lives in one of its subfolders, so+# the cache holds GGUFs the chat index would otherwise offer as a chat model. The Audio page and+# Voice settings reach them through the audio.cpp catalog instead.+_HIDDEN_AUDIO_CPP_REPO_IDS_LOWER = frozenset({"audio-cpp/audio.cpp-gguf"})+# Curated Audio-page TTS checkpoints, which stay VISIBLE but must not be chat-loadable: a chat turn on one comes back as synthesized speech. Listed by id because config sniffing cannot catch them (Orpheus/OuteTTS are LlamaForCausalLM, Spark is Qwen2ForCausalLM) and a GGUF companion carries no tokenizer_config for the codec probe._CURATED_TTS_REPO_IDS = frozenset({@@ -65,6 +70,12 @@ def is_curated_tts_repo_id(value: str | None) -> bool:return bool(value and value.strip().lower() in _CURATED_TTS_REPO_IDS_LOWER)+def is_audio_cpp_repo_id(value: str | None) -> bool:+ """True for audio.cpp's umbrella repo. Hidden from chat like a curated STT repo, and like one still+ emitted as a Model Hub management row, since that row is where its downloaded packages are deleted."""+ return bool(value and value.strip().lower() in _HIDDEN_AUDIO_CPP_REPO_IDS_LOWER)++def is_curated_stt_repo_id(value: str | None) -> bool:"""True only for Unsloth's exact curated STT Hub repositories. Still hidden from chat, but task-scoped inventory consumers need the real cache rows so the Audio page need not reimplement size, format, variants and lifecycle."""return bool(value and value.strip().lower() in _HIDDEN_STT_REPO_IDS_LOWER)@@ -161,6 +172,7 @@ def is_hidden_model(*values: str | None) -> bool:_PROBE_REPO_ID.lower(),*(repo_id.lower() for repo_id in _DEFAULT_EMBEDDING_REPO_IDS),*_HIDDEN_STT_REPO_IDS_LOWER,+ *_HIDDEN_AUDIO_CPP_REPO_IDS_LOWER,}exact_paths: list[str] = []for model in {diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.pyindex 33747fe8ca7..14a5aa0f51f 100644--- a/studio/backend/utils/models/model_config.py+++ b/studio/backend/utils/models/model_config.py@@ -1520,6 +1520,40 @@ def detect_audio_type()[0]+def _audio_cpp_repo_audio_type(+ model_name: str, hf_token: Optional[str], offline: bool+) -> Optional[str]:+ """``audiocpp_tts`` / ``audiocpp_music`` for an audio.cpp GGUF repo, ``""`` for one that is+ audio.cpp but neither (speech-to-text), None when it is not audio.cpp or was not looked at.++ Only names that can be a GGUF repo are looked at (an umbrella folder, an ``audio-cpp`` repo,+ a ``*-GGUF`` or audio.cpp-named repo), so this costs an ordinary model nothing.+ """+ try:+ from core.inference import audio_cpp_models+ except Exception: # noqa: BLE001 - no audio.cpp support+ return None+ name = model_name.strip()+ lowered = name.lower()+ if not (+ audio_cpp_models.is_umbrella_id(name)+ or lowered.startswith("audio-cpp/")+ or "gguf" in lowered.rsplit("/", 1)[-1]+ or "audiocpp" in lowered+ or "audio.cpp" in lowered+ ):+ return None+ if audio_cpp_models.parse_identifier(name) is None:+ return None+ try:+ model = audio_cpp_models.resolve(name, None, hf_token, network = not offline)+ except Exception: # noqa: BLE001 - unknown, not "not audio.cpp"+ return None+ if model is None:+ return None+ return model.audio_type or ""++def detect_audio_type_checked(model_name: str,hf_token: Optional[str] = None,@@ -1538,8 +1572,10 @@ def detect_audio_type_checked(return None, Truetry:- from core.inference.native_audio import NATIVE_AUDIO_MODEL_IDS- curated_type = NATIVE_AUDIO_MODEL_IDS.get(str(model_name).strip().lower())+ from core.inference.native_audio import NATIVE_AUDIO_MODEL_IDS, audio_cpp_audio_type+ curated_type = NATIVE_AUDIO_MODEL_IDS.get(+ str(model_name).strip().lower()+ ) or audio_cpp_audio_type(str(model_name))except Exception:curated_type = Noneif curated_type:@@ -1547,6 +1583,9 @@ def detect_audio_type_checked(# Key on effective offline (kwarg OR env) so an offline negative can't poison a later probe.effective_offline = bool(local_files_only or _env_offline())+ audio_cpp_type = _audio_cpp_repo_audio_type(str(model_name), hf_token, effective_offline)+ if audio_cpp_type is not None:+ return audio_cpp_type or None, Trueif _offline_cache_read_refused(hf_token, model_name, model_name, effective_offline):return None, Falselocal_fingerprint = (@@ -4212,6 +4251,9 @@ class ModelConfig:gguf_cache_repo: Optional[str] = Nonegguf_variant: Optional[str] = None # Quantization variant (e.g. "Q4_K_M")base_model: Optional[str] = None # Base model (for LoRAs)+ # The resolved audio.cpp model (core.inference.audio_cpp_models.AudioCppModel) for a GGUF only+ # audiocpp_server runs. Such a config loads through the native-audio worker, never llama-server.+ audio_cpp: Optional[Any] = None@classmethoddef from_lora_path(@@ -4308,6 +4350,9 @@ class ModelConfig:return Noneidentifier = model_id.strip()+ audio_cpp_config = cls._from_audio_cpp_identifier(identifier, gguf_variant, hf_token)+ if audio_cpp_config is not None:+ return audio_cpp_configis_local = is_local_path(identifier)path = normalize_path(identifier) if is_local else identifier@@ -4341,6 +4386,11 @@ class ModelConfig:else:gguf_file = detect_gguf_model(path)if gguf_file:+ audio_cpp_config = cls._from_audio_cpp_identifier(+ identifier, gguf_variant, hf_token, gguf_file = gguf_file+ )+ if audio_cpp_config is not None:+ return audio_cpp_configdisplay_name = Path(gguf_file).stemlogger.info(f"Detected local GGUF model: {gguf_file}")@@ -4520,6 +4570,13 @@ class ModelConfig:if _env_offline():raise GgufRepoUnreadableError(_gguf_repo_unreadable_message(identifier, None))if gguf_filename:+ # A GGUF only audio.cpp reads never reaches llama-server: its header says so before+ # anything is downloaded.+ audio_cpp_config = cls._from_audio_cpp_identifier(+ identifier, gguf_variant, hf_token, gguf_hint = gguf_filename+ )+ if audio_cpp_config is not None:+ return audio_cpp_config# Preflight: verify the llama-server binary exists before a multi-GB download.# include_denied: a transiently locked binary still exists and the lock clears in time.from core.inference.llama_cpp import (@@ -4711,6 +4768,65 @@ class ModelConfig:base_model = base_model,)+ @classmethod+ def _from_audio_cpp_identifier(+ cls,+ identifier: str,+ gguf_variant: Optional[str],+ hf_token: Optional[str],+ *,+ gguf_hint: Optional[str] = None,+ gguf_file: Optional[str] = None,+ ) -> Optional["ModelConfig"]:+ """A GGUF only audio.cpp runs, as a speech or music config for the native-audio worker.++ Called three ways: up front for an umbrella folder id (``audio-cpp/audio.cpp-gguf/<Folder>``,+ which no repo probe below can read), for a local GGUF once found, and for a Hub repo once+ its GGUF is known. The last two read the file's header, so an ordinary llama.cpp GGUF+ returns None here at the cost of one header read. Raises ``ValueError`` for an audio.cpp+ model Studio cannot run in this slot (speech-to-text, an unsupported task or variant).+ """+ try:+ from core.inference import audio_cpp_models+ except Exception: # noqa: BLE001 - no audio.cpp support, no audio.cpp id+ return None+ if gguf_file is not None:+ header = audio_cpp_models.read_local_header(gguf_file)+ if header is None or not header.is_audio_cpp:+ return None+ target = gguf_file+ elif gguf_hint is None and not audio_cpp_models.is_umbrella_id(identifier):+ return None+ else:+ target = identifier+ model = audio_cpp_models.resolve(+ target,+ gguf_variant,+ hf_token,+ network = not _env_offline(),+ gguf_hint = gguf_hint,+ )+ if model is None:+ return None+ audio_cpp_models.require_runnable(model, "tts")+ from core.inference import audio_cpp_files++ return cls(+ identifier = model.id,+ display_name = model.display_name,+ path = model.local_path or model.id,+ is_local = bool(model.local_path),+ is_cached = audio_cpp_files.is_downloaded(model),+ is_vision = False,+ is_lora = False,+ is_audio = True,+ audio_type = model.audio_type,+ has_audio_input = False,+ gguf_variant = model.variant.key,+ base_model = None,+ audio_cpp = model,+ )+@classmethoddef from_ui_selection(cls,diff --git a/studio/frontend/src/app/routes/audio.tsx b/studio/frontend/src/app/routes/audio.tsxindex 01b8c8e0251..66a8eab9887 100644--- a/studio/frontend/src/app/routes/audio.tsx+++ b/studio/frontend/src/app/routes/audio.tsx@@ -2,6 +2,7 @@// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0import { createRoute } from "@tanstack/react-router";+import { AUDIO_CPP_AUDIO_TYPES } from "../../features/audio/audio-cpp-catalog.ts";import { requireAuth } from "../auth-guards";import { Route as rootRoute } from "./__root";@@ -11,6 +12,7 @@ const NATIVE_AUDIO_TYPES = new Set(["moss_tts_nano","higgs_tts3","minimax_music3",+ ...AUDIO_CPP_AUDIO_TYPES,]);// RootLayout renders AudioPage persistently (so an in-flight generation is not cancelled when leaving the tab); this route only owns the URL + auth gate.diff --git a/studio/frontend/src/features/audio/api.ts b/studio/frontend/src/features/audio/api.tsindex 18ef188d24d..5064df6ab1e 100644--- a/studio/frontend/src/features/audio/api.ts+++ b/studio/frontend/src/features/audio/api.ts@@ -30,6 +30,8 @@ export interface GenerateAudioOptions {audio_instructions?: string;audio_language?: string;seed?: number;+ /** A GGUF audio model's own options by name, from its status `audio_options` schema. */+ audio_options?: Record<string, boolean | number | string>;signal?: AbortSignal;}diff --git a/studio/frontend/src/features/audio/audio-cpp-catalog.ts b/studio/frontend/src/features/audio/audio-cpp-catalog.tsnew file mode 100644index 00000000000..d53e8834796--- /dev/null+++ b/studio/frontend/src/features/audio/audio-cpp-catalog.ts@@ -0,0 +1,167 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++// Seeds the Audio pickers and dictation settings; any GGUF the backend recognises works too.+// Free of app imports so the node test runner can load it directly.++export const AUDIO_CPP_REPO = "audio-cpp/audio.cpp-gguf";++export const AUDIO_CPP_TTS_AUDIO_TYPE = "audiocpp_tts";+export const AUDIO_CPP_MUSIC_AUDIO_TYPE = "audiocpp_music";+export const AUDIO_CPP_AUDIO_TYPES: ReadonlySet<string> = new Set([+ AUDIO_CPP_TTS_AUDIO_TYPE,+ AUDIO_CPP_MUSIC_AUDIO_TYPE,+]);++export type AudioCppTask = "tts" | "music" | "asr";++export interface AudioCppModel {+ /** Hub repo id, or `${AUDIO_CPP_REPO}/<folder>` for a package in the shared repo. */+ id: string;+ task: AudioCppTask;+ /** ASR only: the primary language codes the model transcribes. Absent = multilingual. */+ languages?: readonly string[];+ /** Phonemizes with eSpeak-ng, which upstream runtime bundles lack (backend needs_espeak). */+ needsEspeak?: boolean;+}++/** The `audio_cpp_runtime` block of /api/inference/audio/stt/status. */+export interface AudioCppRuntimeStatus {+ available: boolean;+ espeak: boolean;+ backend: string | null;+ release_tag: string | null;+}++const MB = 1024 * 1024;++const folder = (name: string) => `${AUDIO_CPP_REPO}/${name}`;+const ENGLISH = ["en"] as const;++export const AUDIO_CPP_MODELS: readonly AudioCppModel[] = [+ { id: folder("Kokoro-82M-GGUF"), task: "tts", needsEspeak: true },+ { id: folder("KittenTTS-GGUF"), task: "tts", needsEspeak: true },+ { id: folder("Piper-TTS-GGUF"), task: "tts", needsEspeak: true },+ { id: folder("Inflect-Micro-v2-GGUF"), task: "tts", needsEspeak: true },+ { id: folder("PocketTTS-GGUF"), task: "tts" },+ { id: folder("MOSS-TTS-Nano-100M-GGUF"), task: "tts" },+ { id: folder("Supertonic-3-GGUF"), task: "tts" },+ { id: folder("Chatterbox-Turbo-GGUF"), task: "tts" },+ { id: folder("VoxCPM2-GGUF"), task: "tts" },+ { id: folder("Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF"), task: "tts" },+ { id: folder("Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF"), task: "tts" },+ { id: "audio-cpp/MiniMax-Music3-GGUF", task: "music" },+ { id: "audio-cpp/Yue2-3B-GGUF", task: "music" },+ { id: folder("ACE-Step1.5-GGUF"), task: "music" },+ { id: folder("Stable-Audio-3-Small-Music-GGUF"), task: "music" },+ { id: folder("Qwen3-ASR-0.6B-GGUF"), task: "asr" },+ { id: folder("Qwen3-ASR-1.7B-GGUF"), task: "asr" },+ { id: folder("Parakeet-TDT-0.6B-v3-GGUF"), task: "asr" },+ { id: folder("Canary-180M-Flash-GGUF"), task: "asr", languages: ["en", "de", "es", "fr"] },+ { id: folder("Moonshine-Streaming-GGUF"), task: "asr", languages: ENGLISH },+ { id: folder("Nemotron-3.5-ASR-Streaming-0.6B-GGUF"), task: "asr", languages: ENGLISH },+];++/** Legacy Settings > Voice keys; the backend still maps each to its folder id (and variant). */+export interface AudioCppDictationModel {+ key: string;+ id: string;+ /** The folder's sub-package when it ships several (Moonshine sizes). */+ variant?: string;+ sizeBytes: number;+}++const dictation = <const K extends string>(+ key: K,+ name: string,+ sizeMb: number,+ variant?: string,+): AudioCppDictationModel & { key: K } => ({+ key,+ id: folder(name),+ sizeBytes: Math.trunc(sizeMb * MB),+ ...(variant ? { variant } : {}),+});++export const AUDIO_CPP_DICTATION_MODELS = [+ dictation("audiocpp-qwen3-asr-0.6b", "Qwen3-ASR-0.6B-GGUF", 1097.9),+ dictation("audiocpp-qwen3-asr-1.7b", "Qwen3-ASR-1.7B-GGUF", 2358.4),+ dictation("audiocpp-parakeet-tdt-0.6b-v3", "Parakeet-TDT-0.6B-v3-GGUF", 873.3),+ dictation("audiocpp-canary-180m-flash", "Canary-180M-Flash-GGUF", 237.9),+ dictation("audiocpp-moonshine-tiny", "Moonshine-Streaming-GGUF", 57.6, "tiny"),+ dictation("audiocpp-moonshine-small", "Moonshine-Streaming-GGUF", 286.7, "small"),+ dictation(+ "audiocpp-nemotron-3.5-asr-0.6b",+ "Nemotron-3.5-ASR-Streaming-0.6B-GGUF",+ 887.5,+ ),+] as const satisfies readonly AudioCppDictationModel[];++export type AudioCppSttKey = (typeof AUDIO_CPP_DICTATION_MODELS)[number]["key"];++export const AUDIO_CPP_STT_KEYS: readonly AudioCppSttKey[] = AUDIO_CPP_DICTATION_MODELS.map(+ (model) => model.key,+);++function normalizedId(id: string | null | undefined): string {+ return id?.trim().toLowerCase().replace(/\/+$/, "") ?? "";+}++const BY_ID = new Map<string, AudioCppModel>(+ AUDIO_CPP_MODELS.map((model) => [model.id.toLowerCase(), model]),+);+const DICTATION_BY_KEY = new Map<string, AudioCppDictationModel>(+ AUDIO_CPP_DICTATION_MODELS.map((model) => [model.key, model]),+);++export function isAudioCppFolderId(id: string | null | undefined): boolean {+ const text = normalizedId(id);+ return (+ text.startsWith(`${AUDIO_CPP_REPO.toLowerCase()}/`) &&+ text.length > AUDIO_CPP_REPO.length + 1+ );+}++export function audioCppDisplayName(id: string): string {+ const trimmed = id.trim().replace(/\/+$/, "");+ if (isAudioCppFolderId(trimmed)) {+ return trimmed.slice(AUDIO_CPP_REPO.length + 1).split("/")[0] || trimmed;+ }+ return trimmed.split("/").pop() || trimmed;+}++export function audioCppModelFor(id: string | null | undefined): AudioCppModel | null {+ return BY_ID.get(normalizedId(id)) ?? null;+}++export function audioCppDictationModelFor(+ key: string | null | undefined,+): AudioCppDictationModel | null {+ const text = key?.trim();+ return text ? (DICTATION_BY_KEY.get(text) ?? null) : null;+}++/** Served by the audio runtime rather than llama-server, as far as the picker can tell. */+export function isAudioRuntimeGguf(+ id: string | null | undefined,+ audioType?: string | null,+): boolean {+ return (+ AUDIO_CPP_AUDIO_TYPES.has(audioType ?? "") ||+ audioCppModelFor(id) !== null ||+ isAudioCppFolderId(id)+ );+}++export function audioCppModelsForTask(task: AudioCppTask): AudioCppModel[] {+ return AUDIO_CPP_MODELS.filter((model) => model.task === task);+}++/** Music length the backend clamps to, whatever max_tokens asks for. */+export const AUDIO_CPP_MUSIC_MIN_SECONDS = 5;+export const AUDIO_CPP_MUSIC_MAX_SECONDS = 240;++export function audioCppSizeLabel(sizeBytes: number): string {+ const mb = sizeBytes / MB;+ return mb < 1000 ? `${Math.round(mb)} MB` : `${(mb / 1024).toFixed(1)} GB`;+}diff --git a/studio/frontend/src/features/audio/audio-options-fields.tsx b/studio/frontend/src/features/audio/audio-options-fields.tsxnew file mode 100644index 00000000000..bf952dd7fe3--- /dev/null+++ b/studio/frontend/src/features/audio/audio-options-fields.tsx@@ -0,0 +1,161 @@+// 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 { Input } from "@/components/ui/input";+import {+ Select,+ SelectContent,+ SelectItem,+ SelectTrigger,+ SelectValue,+} from "@/components/ui/select";+import { Switch } from "@/components/ui/switch";+import { ParamSlider } from "@/features/chat";+import {+ type AudioOptionSpec,+ type AudioOptionValue,+ type AudioOptionValues,+ audioOptionDisplayValue,+ audioOptionFloatStep,+ audioOptionLabel,+ audioVoiceLabel,+ coerceAudioOptionValue,+} from "./audio-options";++function OptionHint({ text }: { text?: string | null }) {+ return text ? (+ <p className="text-ui-11p5 leading-snug text-muted-foreground">{text}</p>+ ) : null;+}++/** One control per declared option, drawn from the type alone: a switch, a slider when the+ * range is bounded (else a number box), a select, or a text box. */+export function AudioOptionFields({+ specs,+ values,+ onChange,+ disabled,+ family,+}: {+ specs: readonly AudioOptionSpec[];+ values: AudioOptionValues;+ /** `undefined` clears the option back to the model's default. */+ onChange: (name: string, value: AudioOptionValue | undefined) => void;+ disabled?: boolean;+ /** The loaded model's runtime family, for readable voice names. */+ family?: string | null;+}) {+ return (+ <>+ {specs.map((spec) => {+ const id = `audio-option-${spec.name.replace(/[^a-zA-Z0-9_-]/g, "-")}`;+ const label = `${audioOptionLabel(spec.name)}${spec.required ? " *" : ""}`;+ const value = audioOptionDisplayValue(spec, values);+ if (spec.type === "bool") {+ return (+ <div key={spec.name} className="grid gap-1.5">+ <label+ htmlFor={id}+ className="flex items-center justify-between gap-3 text-ui-13 font-medium text-foreground"+ >+ {label}+ <Switch+ id={id}+ checked={value === true}+ disabled={disabled}+ onCheckedChange={(checked) => onChange(spec.name, checked)}+ />+ </label>+ <OptionHint text={spec.description} />+ </div>+ );+ }+ if (+ (spec.type === "int" || spec.type === "float") &&+ spec.min != null &&+ spec.max != null &&+ spec.max > spec.min+ ) {+ const step = spec.type === "int" ? 1 : audioOptionFloatStep(spec.min, spec.max);+ return (+ <ParamSlider+ key={spec.name}+ label={label}+ value={typeof value === "number" ? value : spec.min}+ min={spec.min}+ max={spec.max}+ step={step}+ disabled={disabled}+ info={spec.description ?? undefined}+ onChange={(next) =>+ onChange(spec.name, coerceAudioOptionValue(spec, next))+ }+ />+ );+ }+ if (spec.type === "enum") {+ return (+ <div key={spec.name} className="grid gap-1.5">+ <label className="text-ui-13 font-medium text-foreground" htmlFor={id}>+ {label}+ </label>+ <Select+ value={typeof value === "string" ? value : undefined}+ onValueChange={(next) => onChange(spec.name, next)}+ disabled={disabled}+ >+ <SelectTrigger id={id} size="sm" className="w-full">+ <SelectValue placeholder="Model default" />+ </SelectTrigger>+ <SelectContent>+ {(spec.values ?? []).map((choice) => (+ <SelectItem key={choice} value={choice}>+ {spec.name === "voice" ? audioVoiceLabel(choice, family) : choice}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ <OptionHint text={spec.description} />+ </div>+ );+ }+ const numeric = spec.type === "int" || spec.type === "float";+ return (+ <div key={spec.name} className="grid gap-1.5">+ <label className="text-ui-13 font-medium text-foreground" htmlFor={id}>+ {label}+ </label>+ <Input+ id={id}+ type={numeric ? "number" : "text"}+ inputMode={numeric ? "decimal" : undefined}+ step={spec.type === "int" ? 1 : numeric ? "any" : undefined}+ min={spec.min ?? undefined}+ max={spec.max ?? undefined}+ // The typed value as typed: clamping mid-entry would turn "1" into a minimum of+ // 5 before the "0" of "10" arrives. The request clamps instead.+ value={+ values[spec.name] === undefined ? "" : String(values[spec.name])+ }+ placeholder={+ spec.default != null ? String(spec.default) : "Model default"+ }+ disabled={disabled}+ onChange={(event) => {+ const raw = event.target.value;+ if (raw === "") {+ onChange(spec.name, undefined);+ } else if (!numeric) {+ onChange(spec.name, raw);+ } else if (Number.isFinite(Number(raw))) {+ onChange(spec.name, Number(raw));+ }+ }}+ />+ <OptionHint text={spec.description} />+ </div>+ );+ })}+ </>+ );+}diff --git a/studio/frontend/src/features/audio/audio-options.ts b/studio/frontend/src/features/audio/audio-options.tsnew file mode 100644index 00000000000..b437637441f--- /dev/null+++ b/studio/frontend/src/features/audio/audio-options.ts@@ -0,0 +1,231 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++// Per-model generation options a GGUF audio model declares in its embedded spec. The backend+// reports the schema as `audio_options` on the loaded-model status and takes the chosen values+// back as `audio_options` on a speech or music request, validating them again. Values the user+// set are kept per model id in this browser. Free of app imports so the node test runner can+// load it directly.++export type AudioOptionType = "bool" | "int" | "float" | "string" | "enum";+export type AudioOptionValue = boolean | number | string;+export type AudioOptionValues = Record<string, AudioOptionValue>;++export interface AudioOptionSpec {+ name: string;+ type: AudioOptionType;+ description?: string | null;+ default?: AudioOptionValue | null;+ min?: number | null;+ max?: number | null;+ values?: readonly string[] | null;+ required?: boolean | null;+}++const OPTION_TYPES: ReadonlySet<string> = new Set([+ "bool",+ "int",+ "float",+ "string",+ "enum",+]);++const finite = (value: unknown): number | null =>+ typeof value === "number" && Number.isFinite(value) ? value : null;++/** The status field as a schema, dropping entries this build cannot render. */+export function parseAudioOptions(raw: unknown): AudioOptionSpec[] {+ if (!Array.isArray(raw)) return [];+ const specs: AudioOptionSpec[] = [];+ const seen = new Set<string>();+ for (const entry of raw) {+ if (!entry || typeof entry !== "object") continue;+ const item = entry as Record<string, unknown>;+ const name = typeof item.name === "string" ? item.name.trim() : "";+ const type = typeof item.type === "string" ? item.type : "";+ if (!name || !OPTION_TYPES.has(type) || seen.has(name)) continue;+ const values = Array.isArray(item.values)+ ? item.values.filter((value): value is string => typeof value === "string")+ : null;+ // An enum without choices has nothing to offer.+ if (type === "enum" && !values?.length) continue;+ seen.add(name);+ const spec: AudioOptionSpec = {+ name,+ type: type as AudioOptionType,+ description: typeof item.description === "string" ? item.description : null,+ min: finite(item.min),+ max: finite(item.max),+ values,+ required: item.required === true,+ };+ spec.default = coerceAudioOptionValue(spec, item.default) ?? null;+ specs.push(spec);+ }+ return specs;+}++/** `value` as this option accepts it, or undefined when it cannot be: numbers are clamped to the+ * declared range and ints rounded, an enum takes only its listed values. */+export function coerceAudioOptionValue(+ spec: AudioOptionSpec,+ value: unknown,+): AudioOptionValue | undefined {+ switch (spec.type) {+ case "bool":+ return typeof value === "boolean" ? value : undefined;+ case "int":+ case "float": {+ const number =+ typeof value === "string" && value.trim() !== "" ? Number(value) : value;+ if (typeof number !== "number" || !Number.isFinite(number)) return undefined;+ let clamped = number;+ if (spec.min != null) clamped = Math.max(spec.min, clamped);+ if (spec.max != null) clamped = Math.min(spec.max, clamped);+ return spec.type === "int" ? Math.round(clamped) : clamped;+ }+ case "enum":+ return typeof value === "string" && spec.values?.includes(value) ? value : undefined;+ case "string":+ return typeof value === "string" ? value : undefined;+ }+}++/** What a control shows: the stored value, else the declared default, else a neutral blank. */+export function audioOptionDisplayValue(+ spec: AudioOptionSpec,+ values: AudioOptionValues,+): AudioOptionValue | undefined {+ const stored = coerceAudioOptionValue(spec, values[spec.name]);+ if (stored !== undefined) return stored;+ return spec.default ?? undefined;+}++/** The values to send: only ones the user set and the schema still accepts. Everything else is+ * left to the model's own defaults on the server. */+export function audioOptionsForRequest(+ specs: readonly AudioOptionSpec[],+ values: AudioOptionValues,+): AudioOptionValues {+ const request: AudioOptionValues = {};+ for (const spec of specs) {+ const value = coerceAudioOptionValue(spec, values[spec.name]);+ if (value === undefined) continue;+ if (spec.type === "string" && value === "") continue;+ request[spec.name] = value;+ }+ return request;+}++/** Required options with neither a value nor a default, which the model would refuse. */+export function missingRequiredAudioOptions(+ specs: readonly AudioOptionSpec[],+ values: AudioOptionValues,+): AudioOptionSpec[] {+ return specs.filter((spec) => {+ if (!spec.required) return false;+ const value = audioOptionDisplayValue(spec, values);+ return value === undefined || value === "";+ });+}++/** "num_inference_steps" -> "Num inference steps"; a namespaced "yue2.cot" -> "Cot". */+export function audioOptionLabel(name: string): string {+ const leaf = name.split(".").pop() ?? name;+ const words = leaf.replace(/[_-]+/g, " ").trim();+ return words ? words[0].toUpperCase() + words.slice(1) : name;+}++// 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",+ b: "British English",+ e: "Spanish",+ f: "French",+ h: "Hindi",+ i: "Italian",+ j: "Japanese",+ p: "Brazilian Portuguese",+ z: "Mandarin Chinese",+};++function titleWords(text: string): string {+ return text+ .split(/[_\s-]+/)+ .filter(Boolean)+ .map((word) => word[0].toUpperCase() + word.slice(1))+ .join(" ");+}++/** What a built-in voice is called in the picker; the request still sends the id. */+export function audioVoiceLabel(voice: string, family?: string | null): string {+ if (family === "kokoro_tts") {+ const match = /^([a-z])([fm])_([a-z0-9_]+)$/.exec(voice);+ const language = match ? KOKORO_LANGUAGES[match[1]] : undefined;+ if (match && language) {+ return `${titleWords(match[3])} (${language}, ${match[2] === "f" ? "female" : "male"})`;+ }+ }+ return /^[a-z0-9]+(?:[_-][a-z0-9]+)*$/.test(voice) ? titleWords(voice) : voice;+}++/** A slider step for a float range: about a hundred steps, on a round number. */+export function audioOptionFloatStep(min: number, max: number): number {+ const span = max - min;+ if (!(span > 0)) return 0.01;+ const raw = span / 100;+ const magnitude = 10 ** Math.floor(Math.log10(raw));+ const normalized = raw / magnitude;+ const nice = normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10;+ return nice * magnitude;+}++export const AUDIO_OPTIONS_STORAGE_KEY = "unsloth_audio_model_options";++type StoredAudioOptions = Record<string, AudioOptionValues>;++const storageKey = (modelId: string) => modelId.trim().replace(/\/+$/, "").toLowerCase();++function readAll(): StoredAudioOptions {+ try {+ const raw = globalThis.localStorage?.getItem(AUDIO_OPTIONS_STORAGE_KEY);+ const parsed: unknown = raw ? JSON.parse(raw) : null;+ return parsed && typeof parsed === "object" && !Array.isArray(parsed)+ ? (parsed as StoredAudioOptions)+ : {};+ } catch {+ return {};+ }+}++/** The values saved for one model, unvalidated: the schema can change between loads, so+ * callers read them through the helpers above. */+export function readAudioOptionValues(modelId: string | null | undefined): AudioOptionValues {+ if (!modelId?.trim()) return {};+ const entry = readAll()[storageKey(modelId)];+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) return {};+ const values: AudioOptionValues = {};+ for (const [name, value] of Object.entries(entry)) {+ if (["boolean", "number", "string"].includes(typeof value)) {+ values[name] = value as AudioOptionValue;+ }+ }+ return values;+}++/** Remember one model's values; an empty set forgets the model. */+export function saveAudioOptionValues(+ modelId: string | null | undefined,+ values: AudioOptionValues,+): void {+ if (!modelId?.trim()) return;+ try {+ const all = readAll();+ const key = storageKey(modelId);+ if (Object.keys(values).length === 0) delete all[key];+ else all[key] = values;+ globalThis.localStorage?.setItem(AUDIO_OPTIONS_STORAGE_KEY, JSON.stringify(all));+ } catch {+ // Storage is best effort: a full or blocked store keeps the values for this session only.+ }+}diff --git a/studio/frontend/src/features/audio/audio-page-policy.ts b/studio/frontend/src/features/audio/audio-page-policy.tsindex 375641491bc..01bcc355857 100644--- a/studio/frontend/src/features/audio/audio-page-policy.ts+++ b/studio/frontend/src/features/audio/audio-page-policy.ts@@ -3,6 +3,61 @@import type { ModelSelectorChangeMeta } from "@/features/model-picker/components/model-selector/types";import { nativeAudioCheckpointIsLoadable } from "../model-picker/components/model-selector/audio-picker-policy.ts";+import {+ AUDIO_CPP_MUSIC_AUDIO_TYPE,+ AUDIO_CPP_MUSIC_MAX_SECONDS,+ AUDIO_CPP_MUSIC_MIN_SECONDS,+ AUDIO_CPP_TTS_AUDIO_TYPE,+ type AudioCppRuntimeStatus,+ audioCppDisplayName,+ audioCppModelFor,+} from "./audio-cpp-catalog.ts";++/** Why the installed audio runtime cannot run this recommended speech or music model, or null+ * when it can or cannot be told (no status yet, a server that predates the runtime block, or a+ * repo the backend judges at load). Mirrors the backend's model_runtime_problem so a pick is+ * refused before its load returns 501. */+export function audioCppRuntimeProblem(+ id: string | null | undefined,+ runtime: AudioCppRuntimeStatus | null | undefined,+): string | null {+ const model = audioCppModelFor(id);+ if (!model || model.task === "asr" || !runtime) return null;+ if (!runtime.available) {+ return "The audio runtime is not installed. Run `unsloth studio update` to install it.";+ }+ if (model.needsEspeak && !runtime.espeak) {+ return (+ `${audioCppDisplayName(model.id)} needs an audio runtime built with eSpeak-ng, and the ` ++ "installed one has none. Run `unsloth studio update` to install the Unsloth bundle."+ );+ }+ return null;+}++/** GGUF music families whose prompt needs a description beside the lyrics: MiniMax Music 3+ * takes it as the caption and YuE2 as the style. The others fall back to the lyrics. */+const DESCRIBED_MUSIC_FAMILIES = new Set(["minimax_music3", "yue2"]);++/** Whether the loaded music model refuses to generate without a description. */+export function musicNeedsDescription(+ audioType?: string | null,+ audioFamily?: string | null,+): boolean {+ return (+ audioType === "minimax_music3" ||+ (audioType === AUDIO_CPP_MUSIC_AUDIO_TYPE &&+ DESCRIBED_MUSIC_FAMILIES.has(audioFamily ?? ""))+ );+}++/** YuE2 can sing from its style description alone, so an empty lyrics field is an instrumental request. */+export function musicLyricsOptional(+ audioType?: string | null,+ audioFamily?: string | null,+): boolean {+ return audioType === AUDIO_CPP_MUSIC_AUDIO_TYPE && audioFamily === "yue2";+}export type AudioBusy =| "loading"@@ -61,7 +116,7 @@ export function audioGenerationPresentation(export type AudioPickTask = "tts" | "stt" | null;export type AudioCreateMode = "speak" | "transcribe";-export type SttEngine = "transformers" | "gguf" | "mtmd";+export type SttEngine = "transformers" | "gguf" | "mtmd" | "audiocpp";const TTS_AUDIO_TYPES = new Set(["snac",@@ -73,14 +128,25 @@ const TTS_AUDIO_TYPES = new Set(["moss_tts_nano","higgs_tts3","minimax_music3",+ AUDIO_CPP_TTS_AUDIO_TYPE,+ AUDIO_CPP_MUSIC_AUDIO_TYPE,+]);+// The GGUF runtime's speech and music load from a GGUF too, so a status may call them one.+const GGUF_TTS_AUDIO_TYPES = new Set([+ "snac",+ "bicodec",+ "dac",+ AUDIO_CPP_TTS_AUDIO_TYPE,+ AUDIO_CPP_MUSIC_AUDIO_TYPE,]);-const GGUF_TTS_AUDIO_TYPES = new Set(["snac", "bicodec", "dac"]);const NATIVE_TTS_AUDIO_TYPES = new Set(["higgs_tts2","moss_tts_local","moss_tts_nano","higgs_tts3","minimax_music3",+ AUDIO_CPP_TTS_AUDIO_TYPE,+ AUDIO_CPP_MUSIC_AUDIO_TYPE,]);export const MOSS_TTS_FRAMES_PER_SECOND = 12.5;export const MOSS_TTS_DEFAULT_SECONDS = 15;@@ -93,7 +159,7 @@ export const MINIMAX_MUSIC_MAX_FRAMES = 9000;export const MINIMAX_MUSIC_MAX_SECONDS =MINIMAX_MUSIC_MAX_FRAMES / MINIMAX_MUSIC_FRAMES_PER_SECOND;-export type NativeAudioInstructionsKind = "scene" | "style" | "music";+export type NativeAudioInstructionsKind = "scene" | "style" | "voice" | "music";export function nativeAudioInstructionsKind(audioType?: string | null,@@ -104,12 +170,36 @@ export function nativeAudioInstructionsKind(if (audioType === "moss_tts_local") {return "style";}- if (audioType === "minimax_music3") {+ // Forwarded as the runtime's instruction; families without one ignore it.+ if (audioType === AUDIO_CPP_TTS_AUDIO_TYPE) {+ return "voice";+ }+ if (+ audioType === "minimax_music3" ||+ audioType === AUDIO_CPP_MUSIC_AUDIO_TYPE+ ) {return "music";}return null;}+/** The music length range the loaded model honours. The GGUF runtime clamps tighter than the+ * MiniMax Music 3 pipeline; both take the same 25 frames per second. */+export function musicDurationRange(requiresCuda: boolean): {+ min: number;+ max: number;+} {+ return requiresCuda+ ? { min: 1, max: MINIMAX_MUSIC_MAX_SECONDS }+ : { min: AUDIO_CPP_MUSIC_MIN_SECONDS, max: AUDIO_CPP_MUSIC_MAX_SECONDS };+}++/** Whether temperature and token length reach the model. GGUF runtime speech keeps each+ * family's own sampling and lets the server bound the length, so both would be ignored. */+export function audioSamplingControlsApply(audioType?: string | null): boolean {+ return audioType !== AUDIO_CPP_TTS_AUDIO_TYPE;+}+export function minimaxMusicFramesForSeconds(seconds: number): number {const exactFrames = seconds * MINIMAX_MUSIC_FRAMES_PER_SECOND;return Math.min(@@ -183,6 +273,7 @@ type SttDownloadedStatus = {transformers?: { downloaded_models?: readonly string[] };gguf?: { downloaded_models?: readonly string[] };mtmd?: { downloaded_models?: readonly string[] };+ audiocpp?: { downloaded_models?: readonly string[] };};export interface SttDownloadedArtifact {@@ -205,6 +296,7 @@ export function sttDownloadedArtifacts(["transformers", status.transformers],["gguf", status.gguf],["mtmd", status.mtmd],+ ["audiocpp", status.audiocpp],];for (const [engine, block] of blocks) {for (const sidecarKey of block?.downloaded_models ?? []) {@@ -425,6 +517,7 @@ type SttResidencyStatus = SttEngineResidency & {transformers?: SttEngineResidency;gguf?: SttEngineResidency;mtmd?: SttEngineResidency;+ audiocpp?: SttEngineResidency;};/** Resolve the resident model from the engine-aware status shape. The legacy top-level fields@@ -480,6 +573,9 @@ export function resolveSttResidency(if (status.mtmd?.loaded_model) {return { model: status.mtmd.loaded_model, engine: "mtmd" };}+ if (status.audiocpp?.loaded_model) {+ return { model: status.audiocpp.loaded_model, engine: "audiocpp" };+ }return null;}diff --git a/studio/frontend/src/features/audio/audio-page.tsx b/studio/frontend/src/features/audio/audio-page.tsxindex 66370083244..78df6616c96 100644--- a/studio/frontend/src/features/audio/audio-page.tsx+++ b/studio/frontend/src/features/audio/audio-page.tsx@@ -141,7 +141,6 @@ import {type AudioGenerationPhase,MINIMAX_MUSIC_DEFAULT_SECONDS,MINIMAX_MUSIC_FRAMES_PER_SECOND,- MINIMAX_MUSIC_MAX_SECONDS,MOSS_TTS_DEFAULT_SECONDS,MOSS_TTS_FRAMES_PER_SECOND,MOSS_TTS_MAX_FRAMES,@@ -155,7 +154,12 @@ import {macTtsPickAction,mergeGalleryPage,micStreamRequestIsCurrent,+ audioCppRuntimeProblem,+ audioSamplingControlsApply,minimaxMusicFramesForSeconds,+ musicDurationRange,+ musicLyricsOptional,+ musicNeedsDescription as musicModelNeedsDescription,mossTtsFramesForSeconds,mossTtsMaxFrames,nativeAudioInstructionsKind,@@ -170,6 +174,24 @@ import {trainedTtsCheckpointIsLoadable,trainedTtsCheckpointIsRunnableOnMac,} from "./audio-page-policy";+import {+ AUDIO_CPP_MUSIC_AUDIO_TYPE,+ AUDIO_CPP_TTS_AUDIO_TYPE,+ type AudioCppRuntimeStatus,+ audioCppDisplayName,+ isAudioCppFolderId,+} from "./audio-cpp-catalog";+import { AudioOptionFields } from "./audio-options-fields";+import {+ type AudioOptionValue,+ type AudioOptionValues,+ audioOptionLabel,+ audioOptionsForRequest,+ missingRequiredAudioOptions,+ parseAudioOptions,+ readAudioOptionValues,+ saveAudioOptionValues,+} from "./audio-options";import {audioCapabilityLine,audioModelRequiresRemoteCode,@@ -178,9 +200,11 @@ import {ggufSiblingFor,isMusicGenerationModel,macTtsCatalogChoiceIsRunnable,+ musicGenerationRequiresCuda,sttEngineForRepoId,sttRepoIdForSidecarKey,sttSidecarKeyFor,+ type AudioSttEngine,usesNativeAudioRuntime,} from "./catalog";@@ -192,20 +216,30 @@ const MODELS_BY_MODE: Record<CreateMode, ModelOption[]> = {/** What to call a model on screen. A Hub repo is its id; a checkpoint trained here is an output* directory, and the full path in a toast reads as a bug. */function audioModelLabel(id: string): string {+ // A package folder of the shared GGUF repo is known by its folder name, as the Hub shows it.+ if (isAudioCppFolderId(id)) return audioCppDisplayName(id);if (!/^(?:[a-zA-Z]:[\\/]|[\\/]|~)/.test(id)) return id;const leaf = id.split(/[\\/]/).filter(Boolean).pop() ?? id;// Training stamps the output directory with an epoch; it means nothing to a reader.return leaf.replace(/_\d{10,}$/, "");}+/** The load toast's kind: the codec or runtime name, except for the GGUF runtime's internal ones. */+function loadedAudioKind(audioType: string | null | undefined): string {+ if (audioType === AUDIO_CPP_TTS_AUDIO_TYPE) return "speech";+ if (audioType === AUDIO_CPP_MUSIC_AUDIO_TYPE) return "music";+ return audioType ?? "audio";+}+function deviceSizeBytes(label: string): number {const match = label.trim().match(/^(\d+(?:\.\d+)?)\s*(MB|GB)$/i);if (!match) return 0;const value = Number(match[1]);return value * (match[2].toUpperCase() === "GB" ? 1024 ** 3 : 1024 ** 2);}+// Music GGUFs carry text-to-audio. The Hub rows it adds still pass the speech runtime gate.const HUB_TASKS_BY_MODE = {- speak: ["text-to-speech"],+ speak: ["text-to-speech", "text-to-audio"],transcribe: ["automatic-speech-recognition"],} as const;@@ -369,11 +403,13 @@ export function AudioPage({requestStarted: boolean;} | null>(null);- const [lastSttRepo, setLastSttRepo] = usePersistedChoice("unsloth:audio:last-stt-model", "");+ const [lastSttRepo, setLastSttRepoChoice] = usePersistedChoice("unsloth:audio:last-stt-model", "");+ // The quant a package pick (Moonshine tiny or small) asked for, so a restart reloads that one, not the default.+ const [lastSttVariant, setLastSttVariant] = usePersistedChoice("unsloth:audio:last-stt-variant", "");const [selectedSttRepo, setSelectedSttRepo] = useState<string | null>(null);const [sttLoadedModel, setSttLoadedModel] = useState<string | null>(null);const [sttLoadedEngine, setSttLoadedEngine] = useState<- "transformers" | "gguf" | "mtmd" | null+ AudioSttEngine | null>(null);const [downloadedSttArtifacts, setDownloadedSttArtifacts] = useState<SttDownloadedArtifact[]@@ -423,7 +459,22 @@ export function AudioPage({const modeRef = useRef(mode);modeRef.current = mode;const sttStatusRefreshGeneration = useRef(0);+ // What the installed GGUF audio runtime can run, from the STT status poll. Null until it answers.+ const audioCppRuntime = useRef<AudioCppRuntimeStatus | null>(null);const sttLoadGeneration = useRef(0);+ /** The GGUF quant each picked STT repo asked for, by lowercased repo id. */+ const sttGgufVariants = useRef(+ new Map<string, string>(+ lastSttRepo && lastSttVariant ? [[lastSttRepo.toLowerCase(), lastSttVariant]] : [],+ ),+ );+ const setLastSttRepo = useCallback(+ (repo: string) => {+ setLastSttRepoChoice(repo);+ setLastSttVariant(sttGgufVariants.current.get(repo.toLowerCase()) ?? "");+ },+ [setLastSttRepoChoice, setLastSttVariant],+ );const sttLoadingGeneration = useRef<number | null>(null);// Residency is not ownership: the activation resync adopts whatever a sidecar already holds, including a model// chat dictation loaded. The identity, not a boolean, since another surface can replace the sidecar's model@@ -434,7 +485,7 @@ export function AudioPage({const deferredSttLoad = useRef<{repoId: string;sidecarKey: string;- engine: "transformers" | "gguf" | "mtmd";+ engine: AudioSttEngine;} | null>(null);const ttsPickGeneration = useRef(0);const ttsInspectionGeneration = useRef<number | null>(null);@@ -616,6 +667,7 @@ export function AudioPage({: undefined,);if (generation !== sttStatusRefreshGeneration.current) return;+ audioCppRuntime.current = stt.audio_cpp_runtime ?? null;const nextDownloadedArtifacts = sttDownloadedArtifacts(stt,sttRepoIdForSidecarKey,@@ -1076,7 +1128,7 @@ export function AudioPage({const offloadNotice = offloadWarning(offloadCountsFrom(res));const showToast = offloadNotice ? toast.warning : toast.success;showToast(- `Model loaded (${res.audio_type ?? "audio"})${offloadNotice?.titleSuffix ?? ""}`,+ `Model loaded (${loadedAudioKind(res.audio_type)})${offloadNotice?.titleSuffix ?? ""}`,{id: toastId,description: offloadNotice?.description,@@ -1384,13 +1436,23 @@ export function AudioPage({isGguf: meta.isGguf,generation,};+ // A named quant is fetched as the standard variant download, as Chat does, so the backend's plan+ // brings the files it needs beside the weights and the Downloads row reads "<repo> · <quant>".stageTtsDownload([- {- repoId,- files: [ggufFilename],- bytes: meta.expectedBytes ?? 0,- ggufFilename,- },+ meta.ggufVariant+ ? {+ repoId,+ files: [],+ bytes: meta.expectedBytes ?? 0,+ ggufFilename,+ ggufVariant: meta.ggufVariant,+ }+ : {+ repoId,+ files: [ggufFilename],+ bytes: meta.expectedBytes ?? 0,+ ggufFilename,+ },]);return;}@@ -1413,7 +1475,7 @@ export function AudioPage({async (repoId: string,sidecarKey: string,- engine: "transformers" | "gguf" | "mtmd",+ engine: AudioSttEngine,) => {const generation = ++sttLoadGeneration.current;const controller = new AbortController();@@ -1428,15 +1490,31 @@ export function AudioPage({// Ownership is claimed only once the requested model is actually resident: claiming it up front meant a// cancelled download left the flag set while the backend kept the previous model, so leaving Transcribe// unloaded another surface's model.- const toastId = toast.loading(`Preparing ${sidecarKey}…`);+ const toastId = toast.loading(`Preparing ${audioModelLabel(sidecarKey)}…`);+ // The quant picked for this repo (Moonshine tiny or small), sent to the audio runtime's sidecar.+ const ggufVariant =+ engine === "audiocpp"+ ? (sttGgufVariants.current.get(repoId.toLowerCase()) ?? null)+ : null;try {try {- await loadSttModel(sidecarKey, engine, controller.signal);+ await loadSttModel(+ sidecarKey,+ engine,+ controller.signal,+ undefined,+ ggufVariant,+ );sttLoadedByThisPage.current = sidecarKey;} catch (error) {if (!(error instanceof SttModelNotDownloadedError)) throw error;if (!isCurrent()) return;- await startSttDownload(sidecarKey, hfApiToken(getHfToken()), engine);+ await startSttDownload(+ sidecarKey,+ hfApiToken(getHfToken()),+ engine,+ ggufVariant,+ );// STT owns its specialized transfer, but the existing mirror gives it the same global Downloads// row, progress and Cancel as every other model download. Do not reset an adopted row.if (!isTrackingSttDownload(sidecarKey, engine)) {@@ -1470,8 +1548,16 @@ export function AudioPage({if (!download?.downloading) break;}if (!isCurrent()) return;- toast.loading(`Loading ${sidecarKey}…`, { id: toastId });- await loadSttModel(sidecarKey, engine, controller.signal);+ toast.loading(`Loading ${audioModelLabel(sidecarKey)}…`, {+ id: toastId,+ });+ await loadSttModel(+ sidecarKey,+ engine,+ controller.signal,+ undefined,+ ggufVariant,+ );sttLoadedByThisPage.current = sidecarKey;}if (isCurrent()) {@@ -1600,10 +1686,18 @@ export function AudioPage({// Catalog first; an uncurated Hub pick falls back to its pipeline tag, or every community ASR// repo would load into the TTS slot.const task = resolveAudioPickTask(audioTaskFor(id), meta.pipelineTag);- const musicPick =- task !== "stt" && isMusicGenerationModel(id, meta.audioType);+ // A recommended GGUF speech or music row the installed audio runtime cannot run: say why+ // instead of loading into a 501.+ const runtimeProblem =+ task === "stt" ? null : audioCppRuntimeProblem(id, audioCppRuntime.current);+ if (runtimeProblem) {+ toast.error(runtimeProblem, { duration: 7000 });+ return;+ }+ const cudaMusicPick =+ task !== "stt" && musicGenerationRequiresCuda(id, meta.audioType);const selectionGeneration = ++ttsPickGeneration.current;- if (musicPick) {+ if (cudaMusicPick) {const system = await fetchSystemInfo();if (selectionGeneration !== ttsPickGeneration.current) return;if (system?.device_backend !== "cuda") {@@ -1622,7 +1716,13 @@ export function AudioPage({// An STT pick owns Transcribe: it runs on the sidecar, not the main slot.if (!transitionMode("transcribe")) return;const sidecarKey = sttSidecarKeyFor(id);- const engine = sttEngineForRepoId(id);+ const engine = sttEngineForRepoId(id, meta.isGguf);+ // Remembered per repo, so a deferred or on-demand load of this pick asks for the same quant.+ if (meta.ggufVariant) {+ sttGgufVariants.current.set(id.toLowerCase(), meta.ggufVariant);+ } else {+ sttGgufVariants.current.delete(id.toLowerCase());+ }deferredSttLoad.current = null;selectedSttRepoRef.current = id;setSelectedSttRepo(id);@@ -1643,12 +1743,14 @@ export function AudioPage({}if (ttsPickGeneration.current !== selectionGeneration) return;const exactGguf = exactGgufLoadSelector(meta);- const isGguf = Boolean(- meta.isGguf || isGgufTtsTarget({ repoId: id, ggufFilename: exactGguf }),- );+ const isGguf = isGgufTtsTarget({+ repoId: id,+ ggufFilename: exactGguf,+ isGguf: meta.isGguf,+ });const ggufSibling = isGguf ? null : ggufSiblingFor(id);const nativeRuntime =- usesNativeAudioRuntime(id, meta.audioType) && !musicPick;+ usesNativeAudioRuntime(id, meta.audioType) && !cudaMusicPick;const macAction = macTtsPickAction({isMac,isGguf,@@ -1657,7 +1759,7 @@ export function AudioPage({});if (macAction === "reject") {toast.error(- musicPick+ cudaMusicPick? `${id} currently requires an NVIDIA CUDA GPU and cannot run locally on this Mac.`: `${id} has no runnable GGUF TTS build. MLX cannot generate text-to-speech from its safetensors checkpoint on this Mac.`,{ duration: 7000 },@@ -1836,9 +1938,62 @@ export function AudioPage({status?.active_model &&isTtsAudioType(status.audio_type, status.is_gguf === true),);- const musicGeneration =- status?.audio_type === "minimax_music3" ||- isMusicGenerationModel(status?.active_model);+ const musicGeneration = isMusicGenerationModel(+ status?.active_model,+ status?.audio_type,+ );+ const cudaMusicGeneration = musicGenerationRequiresCuda(+ status?.active_model,+ status?.audio_type,+ );+ // Most GGUF music falls back to the lyrics as its prompt; MiniMax Music 3 and YuE2 need a+ // description beside them.+ const musicNeedsDescription =+ cudaMusicGeneration ||+ musicModelNeedsDescription(status?.audio_type, status?.audio_family);+ const lyricsOptional = musicLyricsOptional(+ status?.audio_type,+ status?.audio_family,+ );+ const musicRange = musicDurationRange(cudaMusicGeneration);+ // A length picked for the MiniMax pipeline can exceed what the GGUF runtime generates.+ const musicSeconds = Math.min(+ Math.max(minimaxMaxSeconds, musicRange.min),+ musicRange.max,+ );+ const samplingControls = audioSamplingControlsApply(status?.audio_type);+ const audioOptionSpecs = useMemo(+ () => parseAudioOptions(status?.audio_options),+ [status?.audio_options],+ );+ const audioOptionsModel = status?.active_model ?? null;+ const [audioOptionValues, setAudioOptionValues] = useState<AudioOptionValues>(+ () => readAudioOptionValues(audioOptionsModel),+ );+ const [audioOptionValuesModel, setAudioOptionValuesModel] = useState(+ audioOptionsModel,+ );+ // Each model keeps its own values, read back when it becomes the loaded one.+ if (audioOptionValuesModel !== audioOptionsModel) {+ setAudioOptionValuesModel(audioOptionsModel);+ setAudioOptionValues(readAudioOptionValues(audioOptionsModel));+ }+ const handleAudioOptionChange = useCallback(+ (name: string, value: AudioOptionValue | undefined) => {+ setAudioOptionValues((current) => {+ const next = { ...current };+ if (value === undefined) delete next[name];+ else next[name] = value;+ saveAudioOptionValues(audioOptionsModel, next);+ return next;+ });+ },+ [audioOptionsModel],+ );+ const handleAudioOptionsReset = useCallback(() => {+ setAudioOptionValues({});+ saveAudioOptionValues(audioOptionsModel, {});+ }, [audioOptionsModel]);const mossLocalGeneration = status?.audio_type === "moss_tts_local";const instructionsKind = musicGeneration? "music"@@ -1955,7 +2110,7 @@ export function AudioPage({const handleGenerate = useCallback(async () => {const text = prompt.trim();- if (!text) return;+ if (!text && !lyricsOptional) return;// Same gate the TTS load path uses: switching straight from Transcribe with a speech model already resident// needs no load, so nothing else waits for the sidecar teardown, and generating beside a dictation model OOMs a// device that fits either alone. Claimed before the await below, since the button only disables on `busy` and a@@ -1973,13 +2128,31 @@ export function AudioPage({return;}const instructions = audioInstructions.trim();- if (musicGeneration && !instructions) {+ if (musicNeedsDescription && !instructions) {+ updateGenerationPhase(null);+ busyRef.current = null;+ setBusy(null);+ toast.error("Add a music description. This model needs one beside the lyrics.");+ return;+ }+ const missingOptions = missingRequiredAudioOptions(+ audioOptionSpecs,+ audioOptionValues,+ );+ if (missingOptions.length > 0) {updateGenerationPhase(null);busyRef.current = null;setBusy(null);- toast.error("Add a music description for MiniMax Music 3.");+ setAdvancedOpen(true);+ toast.error(+ `Set ${missingOptions.map((spec) => audioOptionLabel(spec.name)).join(", ")} in Advanced before generating.`,+ );return;}+ const requestOptions = audioOptionsForRequest(+ audioOptionSpecs,+ audioOptionValues,+ );const language = audioLanguage.trim();saveLastPrompt("audio", prompt);const controller = new AbortController();@@ -1987,9 +2160,11 @@ export function AudioPage({updateGenerationPhase("generating");try {const generated = await generateAudio(text, {- ...(!musicGeneration && temperatureEdited ? { temperature } : {}),+ ...(!musicGeneration && samplingControls && temperatureEdited+ ? { temperature }+ : {}),max_tokens: musicGeneration- ? minimaxMusicFramesForSeconds(minimaxMaxSeconds)+ ? minimaxMusicFramesForSeconds(musicSeconds): mossFrameLimit !== null? mossTtsFramesForSeconds(mossMaxSeconds, mossFrameLimit): maxTokens,@@ -1999,6 +2174,9 @@ export function AudioPage({...(mossLocalGeneration && language? { audio_language: language }: {}),+ ...(Object.keys(requestOptions).length > 0+ ? { audio_options: requestOptions }+ : {}),signal: controller.signal,});updateGenerationPhase("finishing");@@ -2054,10 +2232,16 @@ export function AudioPage({audioInstructions,audioLanguage,musicGeneration,+ musicNeedsDescription,+ lyricsOptional,+ audioOptionSpecs,+ audioOptionValues,+ setAdvancedOpen,mossLocalGeneration,mossFrameLimit,mossMaxSeconds,- minimaxMaxSeconds,+ musicSeconds,+ samplingControls,instructionsKind,temperature,temperatureEdited,@@ -2654,7 +2838,7 @@ export function AudioPage({const capabilityLine =mode === "speak"? ttsLoaded- ? audioCapabilityLine("tts", status?.audio_type)+ ? audioCapabilityLine(musicGeneration ? "music" : "tts", status?.audio_type): status?.active_model? "The loaded model is not a TTS audio model.": "No TTS model loaded."@@ -2842,14 +3026,20 @@ export function AudioPage({? "Music description": instructionsKind === "scene"? "Scene description"- : "Style instructions"+ : instructionsKind === "voice"+ ? "Voice or style description"+ : "Style instructions"}hint={instructionsKind === "music"- ? "Describe genre, tempo, mood, vocals, and arrangement. MiniMax Music 3 requires this separately from the lyrics."+ ? musicNeedsDescription+ ? "Describe genre, tempo, mood, vocals, and arrangement. This model requires it separately from the lyrics."+ : "Optional genre, tempo, mood, vocals, and arrangement. Without it, the text above is used as the prompt.": instructionsKind === "scene"? "Optional Higgs TTS 2 scene guidance such as room acoustics, recording conditions, or background ambience."- : "Optional MOSS Local guidance such as speaking style, emotion, pace, or delivery."+ : instructionsKind === "voice"+ ? "Optional. Used by Qwen3-TTS VoiceDesign, Qwen3-TTS CustomVoice and VoxCPM2; other models ignore it."+ : "Optional MOSS Local guidance such as speaking style, emotion, pace, or delivery."}htmlFor="audio-instructions">@@ -2864,7 +3054,9 @@ export function AudioPage({? "Acoustic pop, 96 BPM, warm female lead, fingerpicked guitar and soft piano…": instructionsKind === "scene"? "Close-mic studio recording in a quiet, softly treated room…"- : "Warm, measured delivery with a calm conversational tone…"+ : instructionsKind === "voice"+ ? "A warm, low female voice, speaking slowly and calmly…"+ : "Warm, measured delivery with a calm conversational tone…"}className="min-h-24"/>@@ -2925,58 +3117,91 @@ export function AudioPage({: "New loads use the GPU when there is one, and the CPU otherwise."}</p></div>- <AdvancedDisclosure- open={advancedOpen}- onOpenChange={setAdvancedOpen}- description={- musicGeneration- ? "Generation length. Changes apply to the next audio clip."- : "Generation sampling. Changes apply to the next audio clip."- }- >- {!musicGeneration ? (- <ParamSlider- label="Temperature"- value={temperature}- min={0}- max={mossFrameLimit !== null ? 2 : 1.5}- step={0.05}- onChange={handleTemperatureChange}- />- ) : null}- {musicGeneration ? (- <ParamSlider- label="Max duration (seconds)"- value={minimaxMaxSeconds}- min={1}- max={MINIMAX_MUSIC_MAX_SECONDS}- step={1 / MINIMAX_MUSIC_FRAMES_PER_SECOND}- onChange={setMinimaxMaxSeconds}- valueSize={8}- info={`Starts at ${MINIMAX_MUSIC_DEFAULT_SECONDS} seconds. MiniMax Music 3 generates ${MINIMAX_MUSIC_FRAMES_PER_SECOND} frames per second, up to ${MINIMAX_MUSIC_MAX_SECONDS} seconds.`}- />- ) : mossFrameLimit !== null ? (- <ParamSlider- label="Max duration (seconds)"- value={mossMaxSeconds}- min={1}- max={mossMaxSecondsLimit}- step={1 / MOSS_TTS_FRAMES_PER_SECOND}- onChange={setMossMaxSeconds}- valueSize={8}- info={`Starts at ${MOSS_TTS_DEFAULT_SECONDS} seconds. This model reports ${mossFrameLimit?.toLocaleString()} frames (${mossMaxSecondsLimit.toLocaleString(undefined, { maximumFractionDigits: 2 })} seconds); the prompt uses part of that context.`}- />- ) : (- <ParamSlider- label="Max tokens"- value={maxTokens}- min={256}- max={TTS_MAX_TOKENS}- step={256}- onChange={setMaxTokens}- />- )}- </AdvancedDisclosure>+ {/* GGUF runtime speech keeps its own sampling and length; its options come from the model. */}+ {musicGeneration ||+ samplingControls ||+ audioOptionSpecs.length > 0 ? (+ <AdvancedDisclosure+ open={advancedOpen}+ onOpenChange={setAdvancedOpen}+ description={+ musicGeneration+ ? "Generation length and model options. Changes apply to the next audio clip."+ : samplingControls+ ? "Generation sampling. Changes apply to the next audio clip."+ : "Model options. Changes apply to the next audio clip."+ }+ >+ {!musicGeneration && samplingControls ? (+ <ParamSlider+ label="Temperature"+ value={temperature}+ min={0}+ max={mossFrameLimit !== null ? 2 : 1.5}+ step={0.05}+ onChange={handleTemperatureChange}+ />+ ) : null}+ {musicGeneration ? (+ <ParamSlider+ label="Max duration (seconds)"+ value={musicSeconds}+ min={musicRange.min}+ max={musicRange.max}+ step={1 / MINIMAX_MUSIC_FRAMES_PER_SECOND}+ onChange={setMinimaxMaxSeconds}+ valueSize={8}+ info={+ cudaMusicGeneration+ ? `Starts at ${MINIMAX_MUSIC_DEFAULT_SECONDS} seconds. MiniMax Music 3 generates ${MINIMAX_MUSIC_FRAMES_PER_SECOND} frames per second, up to ${musicRange.max} seconds.`+ : `Starts at ${MINIMAX_MUSIC_DEFAULT_SECONDS} seconds. This model generates between ${musicRange.min} and ${musicRange.max} seconds.`+ }+ />+ ) : mossFrameLimit !== null ? (+ <ParamSlider+ label="Max duration (seconds)"+ value={mossMaxSeconds}+ min={1}+ max={mossMaxSecondsLimit}+ step={1 / MOSS_TTS_FRAMES_PER_SECOND}+ onChange={setMossMaxSeconds}+ valueSize={8}+ info={`Starts at ${MOSS_TTS_DEFAULT_SECONDS} seconds. This model reports ${mossFrameLimit?.toLocaleString()} frames (${mossMaxSecondsLimit.toLocaleString(undefined, { maximumFractionDigits: 2 })} seconds); the prompt uses part of that context.`}+ />+ ) : samplingControls ? (+ <ParamSlider+ label="Max tokens"+ value={maxTokens}+ min={256}+ max={TTS_MAX_TOKENS}+ step={256}+ onChange={setMaxTokens}+ />+ ) : null}+ {audioOptionSpecs.length > 0 ? (+ <>+ <AudioOptionFields+ specs={audioOptionSpecs}+ values={audioOptionValues}+ onChange={handleAudioOptionChange}+ disabled={busy === "generating"}+ family={status?.audio_family}+ />+ {Object.keys(audioOptionValues).length > 0 ? (+ <Button+ type="button"+ variant="ghost"+ size="sm"+ className="self-start"+ onClick={handleAudioOptionsReset}+ >+ Reset model options+ </Button>+ ) : null}+ </>+ ) : null}+ </AdvancedDisclosure>+ ) : null}</>) : (<>@@ -3074,8 +3299,8 @@ export function AudioPage({? !generationPresentation.canStop: busy !== null ||!ttsLoaded ||- !prompt.trim() ||- (musicGeneration && !audioInstructions.trim())+ (!prompt.trim() && !lyricsOptional) ||+ (musicNeedsDescription && !audioInstructions.trim())}variant={generationPresentation?.canStop ? "destructive" : "default"@@ -3219,7 +3444,7 @@ export function AudioPage({</div>)}<div className="flex items-center gap-2 text-ui-11p5 text-muted-foreground">- <span>{selectedClip.model}</span>+ <span title={selectedClip.model}>{audioModelLabel(selectedClip.model)}</span><span>·</span><span>{formatClipDuration(selectedClip.duration_s)}</span><span className="flex-1" />@@ -3260,7 +3485,7 @@ export function AudioPage({/><div className="flex items-center gap-2 text-ui-11p5 text-muted-foreground"><span>- {fallbackClip.model}+ {audioModelLabel(fallbackClip.model)}{fallbackClip.saved? " · saved, waiting for the gallery": " · not saved to the gallery"}diff --git a/studio/frontend/src/features/audio/catalog.ts b/studio/frontend/src/features/audio/catalog.tsindex 5e48b26484a..04fbca20378 100644--- a/studio/frontend/src/features/audio/catalog.ts+++ b/studio/frontend/src/features/audio/catalog.ts@@ -7,6 +7,11 @@ import {groupForRepoId,} from "@/features/model-picker/components/model-selector/model-catalog";import type { ModelOption } from "@/features/model-picker/components/model-selector/types";+import {+ AUDIO_CPP_AUDIO_TYPES,+ AUDIO_CPP_MODELS,+ AUDIO_CPP_MUSIC_AUDIO_TYPE,+} from "./audio-cpp-catalog";import {type AudioSttEngine,isKnownSttArtifactRepoId,@@ -24,12 +29,22 @@ export {export type AudioTask = "tts" | "stt";+// Recommended GGUF speech and music load into the main slot like the native PyTorch models, but+// through the GGUF audio runtime, so they need no remote code and run on every backend it builds for.+const AUDIO_CPP_GENERATION_IDS = AUDIO_CPP_MODELS.filter(+ (model) => model.task !== "asr",+).map((model) => model.id.toLowerCase());+const AUDIO_CPP_MUSIC_IDS = AUDIO_CPP_MODELS.filter(+ (model) => model.task === "music",+).map((model) => model.id.toLowerCase());+const NATIVE_TTS_REPOS = new Set(["bosonai/higgs-tts-2-3b-base","openmoss-team/moss-tts-local-transformer-v1.5","openmoss-team/moss-tts-nano-100m","multimodalart/higgs-audio-v3-tts-4b-transformers","minimaxai/minimax-music3",+ ...AUDIO_CPP_GENERATION_IDS,]);const REMOTE_CODE_TTS_REPOS = new Set([@@ -38,13 +53,19 @@ const REMOTE_CODE_TTS_REPOS = new Set(["multimodalart/higgs-audio-v3-tts-4b-transformers",]);-const MUSIC_GENERATION_REPOS = new Set(["minimaxai/minimax-music3"]);+/** Music models that only run on NVIDIA CUDA. */+const CUDA_MUSIC_GENERATION_REPOS = new Set(["minimaxai/minimax-music3"]);+const MUSIC_GENERATION_REPOS = new Set([+ ...CUDA_MUSIC_GENERATION_REPOS,+ ...AUDIO_CPP_MUSIC_IDS,+]);const NATIVE_TTS_AUDIO_TYPES = new Set(["higgs_tts2","moss_tts_local","moss_tts_nano","higgs_tts3","minimax_music3",+ ...AUDIO_CPP_AUDIO_TYPES,]);const REMOTE_CODE_TTS_AUDIO_TYPES = new Set(["moss_tts_local",@@ -81,10 +102,22 @@ export function isMusicGenerationModel(): boolean {return Boolean(audioType === "minimax_music3" ||+ audioType === AUDIO_CPP_MUSIC_AUDIO_TYPE ||(repoId && MUSIC_GENERATION_REPOS.has(normalizedRepoId(repoId))),);}+/** The MiniMax Music 3 pipeline needs a CUDA GPU; GGUF music runs wherever the audio runtime does. */+export function musicGenerationRequiresCuda(+ repoId?: string | null,+ audioType?: string | null,+): boolean {+ return Boolean(+ audioType === "minimax_music3" ||+ (repoId && CUDA_MUSIC_GENERATION_REPOS.has(normalizedRepoId(repoId))),+ );+}+export function audioTaskFor(repoId: string): AudioTask | null {if (isKnownSttArtifactRepoId(repoId)) return "stt";return groupForRepoId(repoId, AUDIO_CATALOG)?.task ?? null;@@ -102,7 +135,7 @@ export function macTtsCatalogChoiceIsRunnable(repoId: string): boolean {if (!group || group.task !== "tts") return false;return (group.artifacts.some((artifact) => artifact.format === "gguf") ||- (usesNativeAudioRuntime(repoId) && !isMusicGenerationModel(repoId))+ (usesNativeAudioRuntime(repoId) && !musicGenerationRequiresCuda(repoId)));}@@ -115,9 +148,16 @@ export function audioModelsForTask(task: AudioTask): ModelOption[] {}export function audioCapabilityLine(- task: AudioTask,+ task: AudioTask | "music",detail?: string | null,): string {- const base = task === "tts" ? "Text-to-speech" : "Speech-to-text";- return detail ? `${base} · ${detail}` : base;+ const base =+ task === "music"+ ? "Music generation"+ : task === "tts"+ ? "Text-to-speech"+ : "Speech-to-text";+ // GGUF audio models report one runtime-wide type; the internal name means nothing to a user.+ const shown = detail && AUDIO_CPP_AUDIO_TYPES.has(detail) ? "GGUF" : detail;+ return shown ? `${base} · ${shown}` : base;}diff --git a/studio/frontend/src/features/audio/stt-artifacts.ts b/studio/frontend/src/features/audio/stt-artifacts.tsindex 71cd2ceaca7..d50b1d86eb8 100644--- a/studio/frontend/src/features/audio/stt-artifacts.ts+++ b/studio/frontend/src/features/audio/stt-artifacts.ts@@ -1,7 +1,12 @@// SPDX-License-Identifier: AGPL-3.0-only// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0-export type AudioSttEngine = "transformers" | "gguf" | "mtmd";+import {+ AUDIO_CPP_DICTATION_MODELS,+ isAudioCppFolderId,+} from "./audio-cpp-catalog.ts";++export type AudioSttEngine = "transformers" | "gguf" | "mtmd" | "audiocpp";const TRANSFORMERS_REPO_BY_KEY: Record<string, string> = {tiny: "unsloth/whisper-tiny",@@ -24,6 +29,14 @@ const GGUF_REPO_BY_KEY: Record<string, string> = {"large-v3": "unslothai/whisper-large-v3-GGUF",};+// The audiocpp engine takes any GGUF ASR repo or package folder id as its key. Dictation keys+// saved before that are distinct from every other engine's and resolve to their folder id.+const AUDIOCPP_REPO_BY_KEY: Record<string, string> = Object.fromEntries(+ AUDIO_CPP_DICTATION_MODELS.map((model) => [model.key, model.id]),+);++const GGUF_REPO_SUFFIX = /-GGUF$/i;+const KEY_BY_REPO = new Map<string, string>([...Object.entries(TRANSFORMERS_REPO_BY_KEY),@@ -57,13 +70,27 @@ export function sttRepoIdForSidecarKey(engine: AudioSttEngine = "transformers",): string {const normalized = sidecarKey.trim().toLowerCase();+ // A saved audiocpp dictation key names one folder whatever engine the caller assumed.+ if (engine === "audiocpp" || Object.hasOwn(AUDIOCPP_REPO_BY_KEY, normalized))+ return AUDIOCPP_REPO_BY_KEY[normalized] ?? sidecarKey;if (engine === "gguf") return GGUF_REPO_BY_KEY[normalized] ?? sidecarKey;if (engine === "mtmd") return MTMD_REPO_BY_KEY[normalized] ?? sidecarKey;return TRANSFORMERS_REPO_BY_KEY[normalized] ?? sidecarKey;}-/** Resolve from the picker artifact, not the shared short sidecar key. */-export function sttEngineForRepoId(repoId: string): AudioSttEngine {- const normalized = repoId.trim().toLowerCase();- return ENGINE_BY_REPO.get(normalized) ?? "transformers";+/** Resolve from the picker artifact, not the shared short sidecar key. The curated Whisper and+ * Qwen3-ASR GGUFs have engines of their own; every other GGUF ASR repo is the audio runtime's,+ * and a safetensors repo runs on Transformers. */+export function sttEngineForRepoId(+ repoId: string,+ isGguf?: boolean | null,+): AudioSttEngine {+ const normalized = repoId.trim().toLowerCase().replace(/\/+$/, "");+ const known = ENGINE_BY_REPO.get(normalized);+ if (known) return known;+ if (Object.hasOwn(AUDIOCPP_REPO_BY_KEY, normalized)) return "audiocpp";+ const leaf = normalized.split("/").pop() ?? "";+ return isGguf || isAudioCppFolderId(normalized) || GGUF_REPO_SUFFIX.test(leaf)+ ? "audiocpp"+ : "transformers";}diff --git a/studio/frontend/src/features/chat/adapters/studio-model-dictation-adapter.ts b/studio/frontend/src/features/chat/adapters/studio-model-dictation-adapter.tsindex bf4c7e95242..e8ebb954036 100644--- a/studio/frontend/src/features/chat/adapters/studio-model-dictation-adapter.ts+++ b/studio/frontend/src/features/chat/adapters/studio-model-dictation-adapter.ts@@ -2,11 +2,16 @@// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0import { withModelLoadNotice } from "@/lib/model-lifecycle-events";+import {+ type AudioCppRuntimeStatus,+ isAudioCppFolderId,+} from "../../audio/audio-cpp-catalog";import { authFetch } from "@/features/auth";import { hubTokenHeader } from "@/features/hub/lib/hub-token-header";import { useSettingsDialogStore } from "@/features/settings/stores/settings-dialog-store";import { requestSttDownload } from "@/features/settings/stores/stt-download-prompt-store";import {+ AUDIO_CPP_STT_MODELS,MTMD_STT_MODELS,type SttDevice,applyDictationDictionary,@@ -71,10 +76,18 @@ const stopStream = (stream: MediaStream | null) => {};/** Backend STT engine, decided by the model: Whisper ids run GGML through whisper.cpp, mtmd- * ids run through llama.cpp, and a custom HF repo is safetensors on Transformers. */-export type SttEngine = "transformers" | "gguf" | "mtmd";+ * ids run through llama.cpp, the GGUF audio runtime's ids (saved keys, package folders and+ * other GGUF repos) run through audiocpp, and a custom HF repo is safetensors on Transformers. */+export type SttEngine = "transformers" | "gguf" | "mtmd" | "audiocpp";export function sttEngineFor(model: string): SttEngine {+ const id = model.trim();+ if (+ AUDIO_CPP_STT_MODELS.has(id) ||+ isAudioCppFolderId(id) ||+ (!isCuratedSttModel(id) && /-GGUF\/?$/i.test(id))+ )+ return "audiocpp";// whisper.cpp is Whisper-only, so the newer ASR models go to llama.cpp.if (MTMD_STT_MODELS.has(model.trim())) return "mtmd";return isCuratedSttModel(model) ? "gguf" : "transformers";@@ -242,6 +255,9 @@ export interface SttStatus {transformers?: SttEngineStatus;gguf?: SttEngineStatus;mtmd?: SttEngineStatus;+ audiocpp?: SttEngineStatus;+ /** What the audio.cpp runtime can run; absent on servers predating it. */+ audio_cpp_runtime?: AudioCppRuntimeStatus;}// Keep load/unload requests ordered so a new recording cannot race an unload still finishing for the previous one.@@ -275,7 +291,7 @@ export async function fetchSttStatus(/** The engine block that owns `model`. A curated Whisper prefers whisper.cpp, but without* whisper-server the backend serves it through Transformers, so that is the fallback.- * mtmd models run nowhere else. */+ * mtmd and audiocpp models run nowhere else. */export function sttEngineStatusFor(status: SttStatus,model: string,@@ -283,6 +299,7 @@ export function sttEngineStatusFor(): SttEngineStatus | undefined {const engine = engineOverride ?? sttEngineFor(model);if (engine === "mtmd") return status.mtmd;+ if (engine === "audiocpp") return status.audiocpp;if (engine === "gguf" && status.gguf?.available) return status.gguf;return status.transformers;}@@ -308,12 +325,25 @@ export async function validateSttModel(}}+/** The quant an audiocpp pick names, as the request field; every other engine takes none. A saved+ * dictation key already implies its package, so callers pass nothing for one. */+function sttVariantBody(+ engine: SttEngine,+ ggufVariant: string | null | undefined,+): { gguf_variant?: string } {+ return engine === "audiocpp" && ggufVariant+ ? // biome-ignore lint/style/useNamingConvention: API schema+ { gguf_variant: ggufVariant }+ : {};+}+/** Load a selected model that is already downloaded. */export function loadSttModel(model: string,engine?: SttEngine,signal?: AbortSignal,device?: SttDevice,+ ggufVariant?: string | null,): Promise<void> {const resolvedEngine = engine ?? sttEngineFor(model);const resolvedDevice = device ?? useVoiceSettingsStore.getState().sttDevice;@@ -327,6 +357,7 @@ export function loadSttModel(model,engine: resolvedEngine,device: resolvedDevice,+ ...sttVariantBody(resolvedEngine, ggufVariant),}),signal,});@@ -346,14 +377,20 @@ export async function startSttDownload(model: string,hfToken?: string,engine?: SttEngine,+ ggufVariant?: string | null,): Promise<void> {+ const resolvedEngine = engine ?? sttEngineFor(model);const response = await authFetch("/api/inference/audio/stt/download", {method: "POST",headers: {"Content-Type": "application/json",...hubTokenHeader(hfToken),},- body: JSON.stringify({ model, engine: engine ?? sttEngineFor(model) }),+ body: JSON.stringify({+ model,+ engine: resolvedEngine,+ ...sttVariantBody(resolvedEngine, ggufVariant),+ }),});if (!response.ok) {const body = (await response.json().catch(() => null)) as {diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.tsindex 983c971e43b..b193909ee89 100644--- a/studio/frontend/src/features/chat/types/api.ts+++ b/studio/frontend/src/features/chat/types/api.ts@@ -371,6 +371,11 @@ export interface InferenceStatusResponse {memory_warning?: string | null;is_audio?: boolean;audio_type?: string | null;+ /** GGUF audio runtime family of the loaded speech or music model ("kokoro_tts", "yue2"). */+ audio_family?: string | null;+ /** The loaded GGUF audio model's generation options, as its spec declares them. Unknown-shaped+ * on purpose: the Audio page validates it with parseAudioOptions. */+ audio_options?: unknown;has_audio_input?: boolean;has_video_input?: boolean;loading: string[];diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsxindex ca6b49042d6..9be5a225a0a 100644--- a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx+++ b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx@@ -8,6 +8,10 @@ import {TooltipTrigger,} from "@/components/ui/tooltip";import { useEngines } from "@/features/model-picker/hooks/use-engines";+import {+ audioCppDisplayName,+ isAudioCppFolderId,+} from "../../audio/audio-cpp-catalog";import { hasAuthToken, mustChangePassword } from "@/features/auth/session";import { isTauri } from "@/lib/api-base";import { ChevronDownStandardIcon } from "@/lib/chevron-icons";@@ -75,6 +79,12 @@ function canUseDownloadManager(pathname: string): boolean {return hasAuthToken() && !mustChangePassword();}+/** The repo as a row names it. A package folder of the shared GGUF audio repo is known by its+ * folder name, as the Hub and the pickers show it; every other id reads as itself. */+function repoLabel(repoId: string): string {+ return isAudioCppFolderId(repoId) ? audioCppDisplayName(repoId) : repoId;+}+function variantSuffix(job: ManagedDownload): string {if (job.variant?.startsWith("@")) {// The staging page tagged the entry it picked, which is the only reliable answer: a checkpoint@@ -123,9 +133,11 @@ function DownloadRow({ jobKey }: { jobKey: string }) {<li className="flex flex-col gap-1.5 py-2.5 pl-4 pr-3"><div className="flex items-center gap-2"><span className="min-w-0 flex-1 truncate text-ui-12p5 font-medium text-foreground">- {job.presentation?.label ?? job.repoId}+ {job.presentation?.label ?? repoLabel(job.repoId)}<span className="text-muted-foreground">- {job.presentation ? ` · ${job.repoId}` : variantSuffix(job)}+ {job.presentation+ ? ` · ${repoLabel(job.repoId)}`+ : variantSuffix(job)}</span></span>{job.state === "complete" && (diff --git a/studio/frontend/src/features/hub/download-manager/use-staged-download.ts b/studio/frontend/src/features/hub/download-manager/use-staged-download.tsindex 0d7d870ea7e..af232e5917d 100644--- a/studio/frontend/src/features/hub/download-manager/use-staged-download.ts+++ b/studio/frontend/src/features/hub/download-manager/use-staged-download.ts@@ -26,10 +26,15 @@ export interface StagedDownloadEntry {bytes: number;ggufFilename?: string | null;checkpoint?: boolean;+ /** A GGUF quant fetched as the standard variant download, as Chat does: the backend's variant+ * plan brings its companion files, and the row reads "<repo> · <quant>". `files` is unused. */+ ggufVariant?: string | null;}function entryKey(entry: StagedDownloadEntry): string {- return `${entry.repoId}|${[...entry.files].sort().join(",")}`;+ return entry.ggufVariant+ ? `${entry.repoId}|${entry.ggufVariant}`+ : `${entry.repoId}|${[...entry.files].sort().join(",")}`;}/** Runs a multi-repo download plan through the shared download manager, then calls `onReady` once every entry is on disk. Staging here rather than inside the load is what puts image and video downloads in the same panel, with the same progress, cancel, resume, disk preflight and manifest verification. */@@ -48,8 +53,10 @@ export function useStagedDownload({const [staged, setStaged] = useState({ bytes: 0, plan: 0 });const current = queue?.[0] ?? null;- // Every entry is scoped, including a GGUF checkpoint: the Hub's snapshot ignore list drops *.gguf, so a plain snapshot job would finish having fetched everything EXCEPT the weights.- const activeVariant = current ? scopedVariant(scopeId) : null;+ // Every other entry is scoped, including a GGUF checkpoint: the Hub's snapshot ignore list drops *.gguf, so a plain snapshot job would finish having fetched everything EXCEPT the weights.+ const activeVariant = current+ ? (current.ggufVariant ?? scopedVariant(scopeId))+ : null;const advance = useCallback(() => {setQueue((rest) => {@@ -108,17 +115,27 @@ export function useStagedDownload({const laterEntry = noticedGeneration.current === generation.current;noticedGeneration.current = generation.current;void (async () => {- const outcome = await downloadManager.requestStart({- kind: DOWNLOAD_KIND.MODEL,- repoId: current.repoId,- variant: activeVariant,- inventoryKind: scopedDownloadInventoryKind(current.files),- expectedBytes: current.bytes,- scopeId,- files: current.files,- checkpoint: current.checkpoint,- skipXetNotice: laterEntry,- });+ const outcome = await downloadManager.requestStart(+ current.ggufVariant+ ? {+ kind: DOWNLOAD_KIND.MODEL,+ repoId: current.repoId,+ variant: current.ggufVariant,+ expectedBytes: current.bytes,+ skipXetNotice: laterEntry,+ }+ : {+ kind: DOWNLOAD_KIND.MODEL,+ repoId: current.repoId,+ variant: activeVariant,+ inventoryKind: scopedDownloadInventoryKind(current.files),+ expectedBytes: current.bytes,+ scopeId,+ files: current.files,+ checkpoint: current.checkpoint,+ skipXetNotice: laterEntry,+ },+ );if (!active) return;if (outcome === "started") return;if (inFlight.current === started) inFlight.current = null;diff --git a/studio/frontend/src/features/hub/lib/hidden-models.ts b/studio/frontend/src/features/hub/lib/hidden-models.tsindex 0ccff9efc7a..3b7069f18b0 100644--- a/studio/frontend/src/features/hub/lib/hidden-models.ts+++ b/studio/frontend/src/features/hub/lib/hidden-models.ts@@ -33,6 +33,9 @@ const HIDDEN_STT_REPOS = new Set(["unslothai/whisper-large-v3-gguf","unslothai/qwen3-asr-0.6b-gguf","unslothai/qwen3-asr-1.7b-gguf",+ // audio.cpp's umbrella repo: every speech, music and ASR package is a subfolder, reached through+ // the audio.cpp catalog ids, never as a llama.cpp chat GGUF.+ "audio-cpp/audio.cpp-gguf",]);const HIDDEN_STT_CACHE_NAMES = [...HIDDEN_STT_REPOS].map((repo) =>repo.replace("/", "--"),diff --git a/studio/frontend/src/features/loaded-models/loaded-models-sources.ts b/studio/frontend/src/features/loaded-models/loaded-models-sources.tsindex 31924f231d7..382ab0b966d 100644--- a/studio/frontend/src/features/loaded-models/loaded-models-sources.ts+++ b/studio/frontend/src/features/loaded-models/loaded-models-sources.ts@@ -6,6 +6,11 @@// common row shape. Pure and React-free so node --test can import them; the types// come from each feature's own module because the indexes re-export their pages.+import {+ audioCppDictationModelFor,+ audioCppDisplayName,+ isAudioCppFolderId,+} from "../audio/audio-cpp-catalog.ts";import type { InferenceStatusResponse } from "@/features/chat/types/api";import type { DiffusionStatus } from "@/features/images/api";import type { VideoStatus } from "@/features/video/api";@@ -17,7 +22,7 @@ export type LoadedModelKind = "text" | "tts" | "image" | "video" | "stt";export type LoadedModelSource = "chat" | "image" | "video" | "stt";/** The dictation sidecars, as /audio/stt/status names them. */-export type SttEngine = "transformers" | "mtmd" | "gguf";+export type SttEngine = "transformers" | "mtmd" | "gguf" | "audiocpp";export type LoadedModelEntry = {/** Stable across polls, so a row does not remount mid-eject. */@@ -49,12 +54,15 @@ export type SttStatusResponse = SttEngineStatus & {transformers?: SttEngineStatus | null;mtmd?: SttEngineStatus | null;gguf?: SttEngineStatus | null;+ audiocpp?: SttEngineStatus | null;};const STT_ENGINE_LABELS: Record<SttEngine, string> = {transformers: "Transformers",mtmd: "llama.cpp",gguf: "whisper.cpp",+ // The GGUF audio runtime; its engine name stays out of the UI like the model's.+ audiocpp: "GGUF",};/**@@ -108,8 +116,12 @@ function joinDetail(...parts: (string | null | undefined)[]): string {return kept.join(" · ");}-/** Keep a path's last two segments; a repo id is already short. */+/** Keep a path's last two segments; a repo id is already short. A package folder of the shared+ * GGUF audio repo is its folder name, and a saved dictation key the folder it names. */export function shortModelLabel(name: string): string {+ const dictation = audioCppDictationModelFor(name);+ if (dictation) return audioCppDisplayName(dictation.id);+ if (isAudioCppFolderId(name)) return audioCppDisplayName(name);const normalized = name.replace(/[\\/]+$/, "");const segments = normalized.split(/[\\/]+/).filter(Boolean);if (segments.length <= 2) return normalized;@@ -286,7 +298,7 @@ export function describeSttStatus(status: SttStatusResponse | null,): LoadedModelEntry[] {if (!status) return [];- const engines: SttEngine[] = ["transformers", "mtmd", "gguf"];+ const engines: SttEngine[] = ["transformers", "mtmd", "gguf", "audiocpp"];const entries: LoadedModelEntry[] = [];for (const engine of engines) {const block = sttEngineStatus(status, engine);@@ -308,7 +320,13 @@ export function describeSttStatus(kind: "stt",source: "stt",name: block.loaded_model,- detail: joinDetail(STT_ENGINE_LABELS[engine], block.device),+ // The audio runtime reports its own name and version as the device, which is not one.+ detail: joinDetail(+ STT_ENGINE_LABELS[engine],+ engine === "audiocpp" && block.device?.startsWith("audio.cpp")+ ? null+ : block.device,+ ),sttEngine: engine,});}diff --git a/studio/frontend/src/features/model-picker/components/model-config-page.tsx b/studio/frontend/src/features/model-picker/components/model-config-page.tsxindex 952f817b5ab..50111249f9d 100644--- a/studio/frontend/src/features/model-picker/components/model-config-page.tsx+++ b/studio/frontend/src/features/model-picker/components/model-config-page.tsx@@ -188,6 +188,7 @@ import {vramFractionToPercent,vramPercentToFraction,} from "../model-config/per-model-config";+import { isAudioRuntimeGguf } from "../../audio/audio-cpp-catalog";import {type RunConfigImport,SharedRunConfigControls,@@ -2342,6 +2343,10 @@ export function ModelConfigPage({stagedDims,);const resolvedIsDiffusion = classifiedIsDiffusion === true;+ // Speech, music and ASR GGUFs the backend runs on its audio runtime: no llama-server launches,+ // so none of its knobs apply. Their own options live under Advanced on the Audio page.+ const audioRuntimeGguf =+ target.isGguf && isAudioRuntimeGguf(target.id, target.meta.audioType);// The one field on this page whose stored value the local config may never have seen:// llama_extra_args can be set through the overrides API with no UI involved, so an empty box@@ -3391,7 +3396,14 @@ export function ModelConfigPage({{!target.isGguf && !targetIsMlx && !classifiedIsDiffusion && !target.meta.isLora && !target.meta.audioType && (<InferenceEnginePicker parallelism={config.engineParallelism ?? "tensor"} onParallelismChange={engineParallelism => update({ engineParallelism })} precision={config.enginePrecision ?? "auto"} onPrecisionChange={enginePrecision => update({ enginePrecision })} value={config.engine ?? "auto"} onChange={engine => update({ engine })} onReadyChange={setEngineReady} onUse={handleRun} gpuIds={config.selectedGpuIds} onGpuChange={ids => update({ selectedGpuIds: ids, selectedGpuIndexKind: "physical" })} />)}- {memoryEstimateRequest != null && (+ {audioRuntimeGguf ? (+ <p className="text-ui-12 leading-snug text-muted-foreground">+ This model runs on the audio runtime, so llama.cpp settings do not+ apply. Its generation options are under Advanced on the Audio page+ once it is loaded.+ </p>+ ) : null}+ {memoryEstimateRequest != null && !audioRuntimeGguf && (<MemoryEstimateRowestimate={memoryEstimate.estimate}loading={memoryEstimate.loading}@@ -3413,7 +3425,7 @@ export function ModelConfigPage({onExpandedChange={setMemoryBreakdownOpen}/>)}- {target.isGguf && (+ {target.isGguf && !audioRuntimeGguf && (<><div className="space-y-2"><div className={ROW_CLASS}>@@ -3561,6 +3573,7 @@ export function ModelConfigPage({{target.isGguf &&!resolvedIsDiffusion &&+ !audioRuntimeGguf &&(showAdvanced || customActive) && (<div className="mt-5 space-y-5">{customActive && <VisionRow config={config} update={update} />}diff --git a/studio/frontend/src/features/model-picker/components/model-selector/audio-picker-policy.ts b/studio/frontend/src/features/model-picker/components/model-selector/audio-picker-policy.tsindex ed6eb44bab7..edfd174fd81 100644--- a/studio/frontend/src/features/model-picker/components/model-selector/audio-picker-policy.ts+++ b/studio/frontend/src/features/model-picker/components/model-selector/audio-picker-policy.ts@@ -1,6 +1,7 @@// 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 { AUDIO_CPP_AUDIO_TYPES } from "../../../audio/audio-cpp-catalog.ts";import type { FormatFilter } from "./recommended-fit";import type { ModelSelectorChangeMeta } from "./types";@@ -10,10 +11,15 @@ const NATIVE_AUDIO_TYPES = new Set(["moss_tts_nano","higgs_tts3","minimax_music3",+ ...AUDIO_CPP_AUDIO_TYPES,]);const TTS_CODECS = new Set(["snac", "csm", "bicodec", "dac"]);+/** Hub evidence that a GGUF repo is published for the GGUF audio runtime rather than llama.cpp.+ * A Hub search row has no header to read, so its name, tags or library say so or nothing does. */+const AUDIO_RUNTIME_EVIDENCE = /audio[-_.]?cpp/;+export type CommunityModelPolicy = "none" | "search-only" | "recommended";export function shouldDiscoverCommunityModels(@@ -50,9 +56,9 @@ export function nativeAudioCheckpointIsLoadable(return !audioType || !NATIVE_AUDIO_TYPES.has(audioType) || exportType === "merged";}-/** Community ASR runs through the Transformers Whisper sidecar. Curated GGUF/MTMD artifacts- * are handled by the catalog before this gate, so an uncurated row must identify a- * non-GGUF Whisper checkpoint. */+/** Community ASR runs through the Transformers Whisper sidecar, or through the GGUF audio+ * runtime for a GGUF published for it. Curated GGUF/MTMD artifacts are handled by the catalog+ * before this gate, so an uncurated row must identify one of those two. */export function communityAudioRowIsRunnable({isStt,isTts,@@ -78,6 +84,13 @@ export function communityAudioRowIsRunnable({const evidence = [id, baseModel ?? "", ...(tags ?? [])].map((value) =>value.toLowerCase(),);+ const audioRuntimeGguf =+ isGguf &&+ (AUDIO_CPP_AUDIO_TYPES.has(audioType ?? "") ||+ [...evidence, (libraryName ?? "").toLowerCase()].some((value) =>+ AUDIO_RUNTIME_EVIDENCE.test(value),+ ));+ if (audioRuntimeGguf) return true;if (isStt) {if (isGguf) return false;if (libraryName && libraryName.toLowerCase() !== "transformers")@@ -178,7 +191,7 @@ export function audioPickIsRoutable({if (taskFromGgufArch && isGguf && task === "text-to-speech") {const codec = (audioType ?? "").toLowerCase();if (codec === "csm" || !codec) return false;- return ["snac", "bicodec", "dac"].includes(codec);+ return ["snac", "bicodec", "dac"].includes(codec) || AUDIO_CPP_AUDIO_TYPES.has(codec);}if (isCurated) return true;// A checkpoint from outputs/ has no Hub identity to judge, and the family-name heuristic woulddiff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.tsindex a20daf2c5e0..fd4822dba41 100644--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts@@ -8,6 +8,8 @@import assert from "node:assert/strict";+import { AUDIO_CPP_REPO, isAudioCppFolderId } from "../../../audio/audio-cpp-catalog.ts";+import type { CatalogGroup, ModelArtifact } from "./model-catalog.ts";import {AUDIO_CATALOG,@@ -1487,13 +1489,15 @@ async function checkCatalogAgainstTheHub(catalogs: CatalogGroup[][]): Promise<stnetworkDeadlineAt = Date.now() + NETWORK_DEADLINE_MS;const failures: string[] = [];const groups = catalogs.flat();- // One metadata call per repo id, however many artifacts share it.+ // One metadata call per repo id, however many artifacts share it. A package folder id names a folder+ // of one shared repo, so every one of them is checked against that repo.const artifactsByRepo = new Map<string, ModelArtifact[]>();for (const group of groups) {for (const artifact of group.artifacts) {- const bucket = artifactsByRepo.get(artifact.repoId);+ const hubRepo = isAudioCppFolderId(artifact.repoId) ? AUDIO_CPP_REPO : artifact.repoId;+ const bucket = artifactsByRepo.get(hubRepo);if (bucket) bucket.push(artifact);- else artifactsByRepo.set(artifact.repoId, [artifact]);+ else artifactsByRepo.set(hubRepo, [artifact]);}}@@ -1536,6 +1540,15 @@ async function checkCatalogAgainstTheHub(catalogs: CatalogGroup[][]): Promise<st}}+ for (const artifact of artifacts) {+ if (!isAudioCppFolderId(artifact.repoId)) continue;+ // The package folder is the id's first segment past the repo.+ const folder = artifact.repoId.slice(AUDIO_CPP_REPO.length + 1).split("/")[0];+ if (!(repo.siblings ?? []).some((s) => s.rfilename.startsWith(`${folder}/`))) {+ failures.push(`${artifact.repoId}: ${repoId} has no '${folder}/' folder`);+ }+ }+const declaredFiles = [...new Set(artifacts.map((a) => a.filename).filter((f): f is string => Boolean(f))),];@@ -1565,7 +1578,9 @@ async function checkCatalogAgainstTheHub(catalogs: CatalogGroup[][]): Promise<st// Advisory only. A canonicalId is a display/grouping key and 15 are deliberately not repos;// but one that is both `unsloth/*`-shaped and dead clears every owner guard in the app.- const artifactIds = new Set([...artifactsByRepo.keys()].map((id) => id.toLowerCase()));+ const artifactIds = new Set(+ groups.flatMap((g) => g.artifacts.map((a) => a.repoId.toLowerCase())),+ );const orphans = groups.map((g) => g.canonicalId).filter((id) => !artifactIds.has(id.toLowerCase()));diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.tsindex 48dd341b192..383867d2c1e 100644--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts@@ -6,6 +6,11 @@// for the device. Pure helpers, no React/DOM deps. See model-catalog.check.ts.import { normalizeDenseQuantSchemes } from "../../../../lib/dense-quant-schemes.ts";+import {+ AUDIO_CPP_MODELS,+ type AudioCppTask,+ audioCppDisplayName,+} from "../../../audio/audio-cpp-catalog.ts";import {type GgufFitClass,type GgufVariantSizes,@@ -168,6 +173,25 @@ const bf16Single = (...extra,});+const AUDIO_GGUF_DESCRIPTIONS: Record<AudioCppTask, string> = {+ tts: "Text-to-speech",+ music: "Text-to-music",+ asr: "Speech-to-text",+};++// Recommended audio GGUFs the backend runs on its audio runtime. They are plain GGUF rows, so the+// quant ladder, fit and downloads work as for any other; the backend routes them by GGUF header.+// Music lives in Speak like MiniMax Music 3, since both load into the main audio slot.+const audioGgufGroups = (tasks: readonly AudioCppTask[]): CatalogGroup[] =>+ AUDIO_CPP_MODELS.filter((model) => tasks.includes(model.task)).map((model) => ({+ canonicalId: model.id,+ displayName: audioCppDisplayName(model.id),+ description: AUDIO_GGUF_DESCRIPTIONS[model.task],+ scope: "audio",+ task: model.task === "asr" ? "stt" : "tts",+ artifacts: [gguf(model.id)],+ }));+// Sizes are steady resident estimates (GB) used only for routing; missing = never auto-pick// unless downloaded. GGUF entries carry none: pickDefaultQuant sizes the .gguf files.@@ -634,6 +658,7 @@ export const AUDIO_CATALOG: CatalogGroup[] = [}),],},+ ...audioGgufGroups(["tts", "music"]),// Llasa is deliberately absent: it speaks XCodec2 (65,536 <|s_N|> tokens), which is in neither// _AUDIO_TOKEN_PATTERNS nor AudioCodecManager, so a curated row loaded then failed at generation.// Training still works (unsloth_Llasa-3B.yaml). Re-add both rows with an xcodec2 decoder.@@ -703,6 +728,7 @@ export const AUDIO_CATALOG: CatalogGroup[] = [task: "stt",artifacts: [bf16Pipeline("unsloth/whisper-tiny", 1, { label: "Safetensors" })],},+ ...audioGgufGroups(["asr"]),];diff --git a/studio/frontend/src/features/settings/stores/stt-model-catalog.ts b/studio/frontend/src/features/settings/stores/stt-model-catalog.tsindex 781447cf240..2c21f3c7d2e 100644--- a/studio/frontend/src/features/settings/stores/stt-model-catalog.ts+++ b/studio/frontend/src/features/settings/stores/stt-model-catalog.ts@@ -5,6 +5,15 @@// out of voice-settings-store so it stays free of app imports and can be tested// directly by the node runner.+import {+ AUDIO_CPP_DICTATION_MODELS,+ AUDIO_CPP_STT_KEYS,+ type AudioCppSttKey,+ audioCppDisplayName,+ audioCppModelFor,+ audioCppSizeLabel,+} from "../../audio/audio-cpp-catalog.ts";+/** Curated dictation models, mirrored by the backend sidecars. Listed in the* order the picker shows them: the recommended models lead. */export const STT_MODELS = [@@ -15,6 +24,7 @@ export const STT_MODELS = ["small","large-v3-turbo","large-v3",+ ...AUDIO_CPP_STT_KEYS,] as const;/** Models the picker marks as recommended. Qwen3-ASR is more accurate than@@ -30,6 +40,27 @@ export const MTMD_STT_MODELS: ReadonlySet<SttModel> = new Set(["qwen3-asr-0.6b","qwen3-asr-1.7b",]);+/** Models served by the GGUF audio runtime's sidecar. Each key maps to one+ * package folder of the shared GGUF repo. */+export const AUDIO_CPP_STT_MODELS: ReadonlySet<SttModel> = new Set(+ AUDIO_CPP_STT_KEYS,+);+/** Curated models that transcribe only these primary languages; every other+ * curated model is multilingual. Moonshine and Nemotron are English-only, and+ * Canary covers en/de/es/fr. */+export const STT_MODEL_LANGUAGES: ReadonlyMap<SttModel, readonly string[]> =+ new Map(+ AUDIO_CPP_DICTATION_MODELS.flatMap((model) => {+ const languages = audioCppModelFor(model.id)?.languages;+ return languages ? [[model.key, languages] as const] : [];+ }),+ );+/** Curated models that only transcribe English. */+export const ENGLISH_ONLY_STT_MODELS: ReadonlySet<SttModel> = new Set(+ [...STT_MODEL_LANGUAGES]+ .filter(([, languages]) => languages.length === 1 && languages[0] === "en")+ .map(([model]) => model),+);export type DefaultSttModel = (typeof STT_MODELS)[number];/** A curated id or a user-selected Hugging Face `owner/model` repository. */export type SttModel = string;@@ -42,6 +73,9 @@ export const STT_MODEL_REPOS: Record<DefaultSttModel, string> = {"large-v3": "unsloth/whisper-large-v3","qwen3-asr-0.6b": "unslothai/Qwen3-ASR-0.6B-GGUF","qwen3-asr-1.7b": "unslothai/Qwen3-ASR-1.7B-GGUF",+ ...(Object.fromEntries(+ AUDIO_CPP_DICTATION_MODELS.map((model) => [model.key, model.id]),+ ) as Record<AudioCppSttKey, string>),};export const DEFAULT_STT_MODEL: DefaultSttModel = "qwen3-asr-0.6b";/** The default before Qwen3-ASR, used only by the v1 migration. */@@ -74,6 +108,15 @@ export const STT_MODEL_NAMES: Record<DefaultSttModel, string> = {"large-v3": "Whisper Large v3","qwen3-asr-0.6b": "Qwen3-ASR 0.6B","qwen3-asr-1.7b": "Qwen3-ASR 1.7B",+ // The name the Hub shows for the package, plus the size where one folder ships two.+ ...(Object.fromEntries(+ AUDIO_CPP_DICTATION_MODELS.map((model) => [+ model.key,+ "variant" in model+ ? `${audioCppDisplayName(model.id)} (${model.variant})`+ : audioCppDisplayName(model.id),+ ]),+ ) as Record<AudioCppSttKey, string>),};// Whisper sizes are f16 GGML for whisper.cpp; the mtmd entries cover the model// plus its mmproj, which is why they are larger than the weights alone.@@ -85,6 +128,12 @@ export const STT_MODEL_SIZES: Record<DefaultSttModel, string> = {"large-v3": "3.1 GB","qwen3-asr-0.6b": "1.0 GB","qwen3-asr-1.7b": "2.5 GB",+ ...(Object.fromEntries(+ AUDIO_CPP_DICTATION_MODELS.map((model) => [+ model.key,+ audioCppSizeLabel(model.sizeBytes),+ ]),+ ) as Record<AudioCppSttKey, string>),};export function sttModelName(model: SttModel): string {diff --git a/studio/frontend/src/features/settings/stores/voice-settings-store.ts b/studio/frontend/src/features/settings/stores/voice-settings-store.tsindex 28ec3a7c6ce..8826bf6df54 100644--- a/studio/frontend/src/features/settings/stores/voice-settings-store.ts+++ b/studio/frontend/src/features/settings/stores/voice-settings-store.ts@@ -8,6 +8,7 @@ import {DEFAULT_STT_MODEL,type DefaultSttModel,STT_MODELS,+ STT_MODEL_LANGUAGES,STT_MODEL_REPOS,type SttModel,migrateVoiceSettings,@@ -58,24 +59,24 @@ export function getSttModelRepo(model: SttModel): string {return STT_MODEL_REPOS[model as DefaultSttModel] ?? normalizeSttModel(model);}-// All curated models are multilingual. Custom `.en` checkpoints are treated as-// English-only so a later language change falls back safely.-export const ENGLISH_ONLY_STT_MODELS: ReadonlySet<SttModel> = new Set([]);+// Curated models are multilingual except the ones STT_MODEL_LANGUAGES limits.+// Custom `.en` checkpoints are treated as English-only so a later language+// change falls back safely./** Whether a model can honor the selected dictation language. */export function isSttModelLanguageCompatible(model: SttModel,language: string,): boolean {- const isEnglishOnly =- ENGLISH_ONLY_STT_MODELS.has(model) ||- getSttModelRepo(model).toLowerCase().endsWith(".en");- if (!isEnglishOnly) {+ const allowed =+ STT_MODEL_LANGUAGES.get(model) ??+ (getSttModelRepo(model).toLowerCase().endsWith(".en") ? ["en"] : null);+ if (!allowed) {return true;}const normalized = language.trim().replaceAll("_", "-").toLowerCase();- // Auto sends no forced language, which English-only checkpoints accept.- return normalized === "auto" || normalized.split("-", 1)[0] === "en";+ // Auto sends no forced language, which every checkpoint accepts.+ return normalized === "auto" || allowed.includes(normalized.split("-", 1)[0]);}export type DictationEngine = "browser" | "model" | "custom";@@ -94,8 +95,8 @@ export type TtsEngine = "system" | "studio" | "custom";/*** Whether a model id is curated. Whisper ids run GGML through whisper.cpp,- * mtmd ids run through llama.cpp, and custom repos are safetensors on- * Transformers.+ * mtmd ids run through llama.cpp, audiocpp ids run through audio.cpp, and+ * custom repos are safetensors on Transformers.*/export function isCuratedSttModel(model: SttModel): boolean {return (STT_MODELS as readonly string[]).includes(model.trim());diff --git a/studio/frontend/src/features/settings/tabs/voice-tab.tsx b/studio/frontend/src/features/settings/tabs/voice-tab.tsxindex ef0768828b6..d28e306d7fe 100644--- a/studio/frontend/src/features/settings/tabs/voice-tab.tsx+++ b/studio/frontend/src/features/settings/tabs/voice-tab.tsx@@ -32,6 +32,7 @@ import {releaseTtsAudioUrl,startSttDownload,sttEngineFor,+ sttEngineStatusFor,unloadSttModel,useExternalProvidersStore,validateSttModel,@@ -67,6 +68,7 @@ import {} from "../lib/stt-download-mirror";import { useSettingsDialogStore } from "../stores/settings-dialog-store";import {+ AUDIO_CPP_STT_MODELS,MTMD_STT_MODELS,RECOMMENDED_STT_MODELS,STT_MODELS,@@ -107,9 +109,12 @@ const DICTATION_LANGUAGES: { value: string; label: string }[] = [const TTS_PREVIEW_TEXT ="Hello from Unsloth! This is a preview of the selected voice.";-/** Source repository shown under a model row. Curated models download from- * the Unsloth GGUF repos, mirrored by the backend (stt_ggml_sidecar.py). */+/** Source repository shown under a model row. Curated Whisper models download+ * from the Unsloth GGUF repos, mirrored by the backend (stt_ggml_sidecar.py).+ * A package of the shared GGUF repo is already named after its folder, so its+ * row shows the name alone. */function sttModelSource(model: SttModel): string {+ if (AUDIO_CPP_STT_MODELS.has(model)) return sttModelName(model);return isCuratedSttModel(model) && !MTMD_STT_MODELS.has(model)? `unslothai/whisper-${model}-GGUF`: getSttModelRepo(model);@@ -181,7 +186,8 @@ function SttModelPicker({if (!isSttModelId(model) || validating) {return;}- if (!isCuratedSttModel(model)) {+ // The validator checks Transformers Whisper checkpoints; a GGUF audio runtime repo is checked when it loads.+ if (!isCuratedSttModel(model) && sttEngineFor(model) !== "audiocpp") {setValidating(true);try {await validateSttModel(model, hfApiToken(hfToken));@@ -519,8 +525,6 @@ export function VoiceTab() {const isCustomEngine = dictationEngine === "custom";// The model decides the backend: curated ids run GGML through whisper.cpp,// custom repos run through Transformers.- const isMtmdModel = MTMD_STT_MODELS.has(sttModel);- const isGgufModel = isCuratedSttModel(sttModel) && !isMtmdModel;// Progress of the selected engine's model download, from /stt/status.const [sttDownload, setSttDownload] = useState<SttDownloadStatus | null>(null,@@ -569,12 +573,8 @@ export function VoiceTab() {// A curated model prefers the GGUF (whisper.cpp) engine, but without whisper-server the// backend serves it through Transformers instead of failing. Fall back to the Transformers// status here too, or the model shows as unavailable and download is blocked even though it- // works. mtmd models run nowhere else, so they never fall back.- const engineStatus = isMtmdModel- ? status.mtmd- : isGgufModel && status.gguf?.available- ? status.gguf- : status.transformers;+ // works. mtmd and audio.cpp models run nowhere else, so they never fall back.+ const engineStatus = sttEngineStatusFor(status, sttModel);if (!engineStatus?.available) {setSttPhase("unavailable");return;@@ -647,8 +647,6 @@ export function VoiceTab() {};}, [isLocalEngine,- isGgufModel,- isMtmdModel,sttModel,sttRepoId,modelSttSupported,@@ -665,9 +663,11 @@ export function VoiceTab() {case "on-demand":return t("settings.voice.dictation.sttOnDemand");case "ready":- // whisper.cpp and llama.cpp report a runtime name, not a device; show a- // plain "Loaded" rather than surfacing it.- return sttDevice && !STT_RUNTIME_NAMES.has(sttDevice)+ // whisper.cpp, llama.cpp and audio.cpp report a runtime name, not a+ // device; show a plain "Loaded" rather than surfacing it.+ return sttDevice &&+ !STT_RUNTIME_NAMES.has(sttDevice) &&+ !sttDevice.startsWith("audio.cpp")? t("settings.voice.dictation.sttReady", {device: sttDevice.toUpperCase(),})diff --git a/studio/frontend/tests/audio-cpp-catalog.test.ts b/studio/frontend/tests/audio-cpp-catalog.test.tsnew file mode 100644index 00000000000..3be97669fb4--- /dev/null+++ b/studio/frontend/tests/audio-cpp-catalog.test.ts@@ -0,0 +1,551 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++// GGUF audio models the backend serves on its audio runtime are ordinary GGUF repos to the app:+// a real Hub repo id, or a package folder of the shared repo ("<repo>/<Folder>"), named as the Hub+// names them. A short recommended list seeds the Audio pickers and dictation settings; saved+// dictation keys from before still resolve.++import assert from "node:assert/strict";+import test from "node:test";++import {+ AUDIO_CPP_DICTATION_MODELS,+ AUDIO_CPP_MODELS,+ AUDIO_CPP_MUSIC_MAX_SECONDS,+ AUDIO_CPP_MUSIC_MIN_SECONDS,+ AUDIO_CPP_REPO,+ AUDIO_CPP_STT_KEYS,+ audioCppDictationModelFor,+ audioCppDisplayName,+ audioCppModelFor,+ audioCppSizeLabel,+ isAudioCppFolderId,+} from "../src/features/audio/audio-cpp-catalog.ts";+import {+ MINIMAX_MUSIC_MAX_SECONDS,+ audioCppRuntimeProblem,+ audioSamplingControlsApply,+ isGgufTtsTarget,+ isTtsAudioType,+ musicDurationRange,+ musicLyricsOptional,+ musicNeedsDescription,+ nativeAudioInstructionsKind,+ resolveSttResidency,+ sttDownloadedArtifacts,+} from "../src/features/audio/audio-page-policy.ts";+import {+ isKnownSttArtifactRepoId,+ sttEngineForRepoId,+ sttRepoIdForSidecarKey,+ sttSidecarKeyFor,+} from "../src/features/audio/stt-artifacts.ts";+import {+ audioPickIsRoutable,+ audioPipelineTagFor,+ communityAudioRowIsRunnable,+ macTtsHubRowIsRunnable,+} from "../src/features/model-picker/components/model-selector/audio-picker-policy.ts";+import {+ AUDIO_CATALOG,+ catalogToModelOptions,+ groupForRepoId,+} from "../src/features/model-picker/components/model-selector/model-catalog.ts";+import {+ isGgufId,+ matchesFormatFilter,+} from "../src/features/model-picker/components/model-selector/recommended-fit.ts";+import { hasGgufRepoSuffix } from "../src/features/hub/lib/model-identifiers.ts";+import { shortModelLabel } from "../src/features/loaded-models/loaded-models-sources.ts";+import {+ AUDIO_CPP_STT_MODELS,+ DEFAULT_STT_MODEL,+ MTMD_STT_MODELS,+ STT_MODEL_LANGUAGES,+ STT_MODEL_REPOS,+ STT_MODELS,+ sttModelName,+ sttModelSize,+} from "../src/features/settings/stores/stt-model-catalog.ts";++import {+ installLocalStorageFake,+ readSrc,+ readText,+ registerBundlerResolver,+} from "./helpers/kit.ts";++registerBundlerResolver();+installLocalStorageFake();+const { ENGLISH_ONLY_STT_MODELS, isSttModelLanguageCompatible } = await import(+ "../src/features/settings/stores/voice-settings-store.ts"+);+const {+ audioCapabilityLine,+ audioModelRequiresRemoteCode,+ audioTaskFor,+ isMusicGenerationModel,+ macTtsCatalogChoiceIsRunnable,+ musicGenerationRequiresCuda,+ usesNativeAudioRuntime,+} = await import("../src/features/audio/catalog.ts");++const KOKORO = `${AUDIO_CPP_REPO}/Kokoro-82M-GGUF`;+const ACE_STEP = `${AUDIO_CPP_REPO}/ACE-Step1.5-GGUF`;+const QWEN_ASR = `${AUDIO_CPP_REPO}/Qwen3-ASR-0.6B-GGUF`;+const MOONSHINE = `${AUDIO_CPP_REPO}/Moonshine-Streaming-GGUF`;+const MINIMAX_GGUF = "audio-cpp/MiniMax-Music3-GGUF";+const YUE2 = "audio-cpp/Yue2-3B-GGUF";++const BRAND = /audio\.cpp|audiocpp/i;++test("recommended ids are unique and name their Hub repo or package folder", () => {+ const ids = new Set(AUDIO_CPP_MODELS.map((model) => model.id.toLowerCase()));+ assert.equal(ids.size, AUDIO_CPP_MODELS.length);+ for (const model of AUDIO_CPP_MODELS) {+ assert.equal(audioCppModelFor(model.id), model);+ assert.equal(audioCppModelFor(model.id.toUpperCase()), model);+ assert.equal(audioCppModelFor(`${model.id}/`), model);+ // A folder id is the repo plus ONE top-level folder: sub-packages are variants.+ if (isAudioCppFolderId(model.id)) {+ assert.equal(model.id.split("/").length, 3, model.id);+ } else {+ assert.equal(model.id.split("/").length, 2, model.id);+ }+ assert.match(audioCppDisplayName(model.id), /-GGUF$/, model.id);+ }+ // MiniMax Music 3 and YuE2 ship as their own repos.+ assert.equal(audioCppModelFor(MINIMAX_GGUF)?.task, "music");+ assert.equal(audioCppModelFor(YUE2)?.task, "music");+ assert.equal(audioCppDisplayName(MINIMAX_GGUF), "MiniMax-Music3-GGUF");+ assert.equal(audioCppDisplayName(KOKORO), "Kokoro-82M-GGUF");+ assert.equal(audioCppDisplayName(`${ACE_STEP}/turbo`), "ACE-Step1.5-GGUF");+ assert.equal(isAudioCppFolderId(AUDIO_CPP_REPO), false);+ assert.equal(isAudioCppFolderId(`${AUDIO_CPP_REPO}/`), false);+ assert.equal(isAudioCppFolderId("unslothai/Qwen3-ASR-0.6B-GGUF"), false);+ assert.equal(audioCppModelFor("OpenMOSS-Team/MOSS-TTS-Nano-100M"), null);+ assert.equal(audioCppModelFor(""), null);+ assert.equal(audioCppSizeLabel(57.6 * 1024 * 1024), "58 MB");+ assert.equal(audioCppSizeLabel(2358.4 * 1024 * 1024), "2.3 GB");+});++test("recommended models are plain GGUF Audio rows named as on the Hub", () => {+ for (const model of AUDIO_CPP_MODELS) {+ const group = groupForRepoId(model.id, AUDIO_CATALOG);+ assert.equal(group?.canonicalId, model.id, model.id);+ assert.equal(group?.displayName, audioCppDisplayName(model.id));+ assert.equal(group?.task, model.task === "asr" ? "stt" : "tts", model.id);+ assert.equal(audioTaskFor(model.id), model.task === "asr" ? "stt" : "tts");+ assert.deepEqual(+ group?.artifacts.map((artifact) => [artifact.format, artifact.loadKind]),+ [["gguf", "gguf"]],+ );+ assert.doesNotMatch(`${group?.displayName} ${group?.description}`, BRAND);+ }+ // The folder ids do not steal the owner/name rows they resemble.+ assert.equal(+ groupForRepoId("unslothai/Qwen3-ASR-0.6B-GGUF", AUDIO_CATALOG)?.canonicalId,+ "unslothai/Qwen3-ASR-0.6B-GGUF",+ );+ assert.equal(groupForRepoId(AUDIO_CPP_REPO, AUDIO_CATALOG), null);+ for (const host of ["unknown", "gguf-only", "accelerated", "dense-quant"] as const) {+ const options = catalogToModelOptions(AUDIO_CATALOG, host);+ for (const model of AUDIO_CPP_MODELS) {+ const option = options.find((candidate) => candidate.id === model.id);+ assert.ok(option, `${host}: ${model.id}`);+ assert.equal(option.isGguf, true);+ assert.equal(option.descriptionSuffix, "GGUF");+ }+ }+});++test("GGUF heuristics treat these rows like any llama.cpp GGUF", () => {+ for (const model of AUDIO_CPP_MODELS) {+ assert.equal(isGgufId(model.id), true, model.id);+ assert.equal(hasGgufRepoSuffix(model.id), true, model.id);+ assert.equal(matchesFormatFilter(model.id, false, "gguf"), true, model.id);+ assert.equal(isGgufTtsTarget({ repoId: model.id }), true, model.id);+ }+ assert.equal(isGgufTtsTarget({ repoId: KOKORO, isGguf: true }), true);+ // A loaded GGUF runtime model reads as speech even when the status calls it GGUF.+ for (const audioType of ["audiocpp_tts", "audiocpp_music"]) {+ assert.equal(isTtsAudioType(audioType, true), true, audioType);+ assert.equal(isTtsAudioType(audioType, false), true, audioType);+ }+ assert.equal(isTtsAudioType("csm", true), false);+});++test("speech and music load on the audio runtime without remote code", () => {+ for (const model of AUDIO_CPP_MODELS) {+ if (model.task === "asr") {+ assert.equal(usesNativeAudioRuntime(model.id), false);+ continue;+ }+ assert.equal(usesNativeAudioRuntime(model.id), true, model.id);+ assert.equal(audioModelRequiresRemoteCode(model.id), false, model.id);+ assert.equal(isMusicGenerationModel(model.id), model.task === "music");+ // Metal builds run speech and music alike; only the MiniMax pipeline needs CUDA.+ assert.equal(musicGenerationRequiresCuda(model.id), false);+ assert.equal(macTtsCatalogChoiceIsRunnable(model.id), true, model.id);+ }+ for (const audioType of ["audiocpp_tts", "audiocpp_music"]) {+ assert.equal(usesNativeAudioRuntime("someone/model", audioType), true);+ assert.equal(audioModelRequiresRemoteCode("someone/model", audioType), false);+ assert.equal(audioPipelineTagFor(audioType), "text-to-speech");+ assert.equal(+ macTtsHubRowIsRunnable({+ isMac: true,+ isTts: true,+ isGguf: false,+ hasRunnableGgufSibling: false,+ audioType,+ }),+ true,+ );+ }+ assert.equal(isMusicGenerationModel(null, "audiocpp_music"), true);+ assert.equal(isMusicGenerationModel(KOKORO, "audiocpp_tts"), false);+ assert.equal(isMusicGenerationModel(ACE_STEP), true);+ assert.equal(nativeAudioInstructionsKind("audiocpp_music"), "music");+ assert.equal(nativeAudioInstructionsKind("audiocpp_tts"), "voice");+ assert.equal(musicGenerationRequiresCuda("MiniMaxAI/MiniMax-Music3"), true);+ assert.equal(musicGenerationRequiresCuda(MINIMAX_GGUF), false);+ assert.equal(macTtsCatalogChoiceIsRunnable("MiniMaxAI/MiniMax-Music3"), false);+});++test("MiniMax Music 3 and YuE2 need a description beside the lyrics", () => {+ assert.equal(musicNeedsDescription("minimax_music3"), true);+ assert.equal(musicNeedsDescription("audiocpp_music", "minimax_music3"), true);+ assert.equal(musicNeedsDescription("audiocpp_music", "yue2"), true);+ for (const family of ["ace_step", "stable_audio", null]) {+ assert.equal(musicNeedsDescription("audiocpp_music", family), false, String(family));+ }+ assert.equal(musicNeedsDescription("audiocpp_tts", "yue2"), false);+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(+ page,+ /musicModelNeedsDescription\(status\?\.audio_type, status\?\.audio_family\)/,+ );+ assert.match(page, /\(musicNeedsDescription && !audioInstructions\.trim\(\)\)/);+});++test("Hub rows published for the audio runtime are runnable on the Audio page", () => {+ const row = {+ isGguf: true,+ id: "mistral-experimental/AudioCPP-Voxtral-Mini-4B-Realtime-2602-GGUF",+ };+ assert.equal(communityAudioRowIsRunnable({ ...row, isStt: true, isTts: false }), true);+ assert.equal(+ communityAudioRowIsRunnable({+ isStt: false,+ isTts: true,+ isGguf: true,+ id: "someone/Speech-GGUF",+ tags: ["audio.cpp"],+ }),+ true,+ );+ assert.equal(+ communityAudioRowIsRunnable({+ isStt: false,+ isTts: true,+ isGguf: true,+ id: "someone/Speech-GGUF",+ audioType: "audiocpp_tts",+ }),+ true,+ );+ // Without that evidence a GGUF ASR row still has no engine, and llama.cpp speech keeps its gate.+ assert.equal(+ communityAudioRowIsRunnable({+ isStt: true,+ isTts: false,+ isGguf: true,+ id: "someone/whisper-small-GGUF",+ }),+ false,+ );+ assert.equal(+ communityAudioRowIsRunnable({+ isStt: false,+ isTts: true,+ isGguf: true,+ id: "someone/Speech-GGUF",+ }),+ false,+ );+ // A downloaded GGUF classified by header routes from Chat like an Orpheus one.+ for (const audioType of ["audiocpp_tts", "audiocpp_music"]) {+ assert.equal(+ audioPickIsRoutable({+ id: KOKORO,+ task: "text-to-speech",+ isGguf: true,+ isCurated: false,+ taskFromGgufArch: true,+ audioType,+ }),+ true,+ audioType,+ );+ }+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(page, /speak: \["text-to-speech", "text-to-audio"\]/);+});++test("ASR repos and folders run on the audiocpp engine; saved keys still resolve", () => {+ assert.equal(sttEngineForRepoId(QWEN_ASR), "audiocpp");+ assert.equal(sttEngineForRepoId(MOONSHINE.toLowerCase()), "audiocpp");+ assert.equal(sttEngineForRepoId("someone/Speech-ASR-GGUF"), "audiocpp");+ assert.equal(sttEngineForRepoId("someone/speech-asr", true), "audiocpp");+ assert.equal(sttEngineForRepoId("openai/whisper-small"), "transformers");+ // The id is the sidecar key; an old key names its folder whatever engine the caller assumed.+ assert.equal(sttSidecarKeyFor(QWEN_ASR), QWEN_ASR);+ assert.equal(sttRepoIdForSidecarKey("audiocpp-qwen3-asr-0.6b", "audiocpp"), QWEN_ASR);+ assert.equal(sttRepoIdForSidecarKey("audiocpp-moonshine-tiny"), MOONSHINE);+ assert.equal(sttRepoIdForSidecarKey(QWEN_ASR, "audiocpp"), QWEN_ASR);+ assert.equal(sttEngineForRepoId("audiocpp-moonshine-small"), "audiocpp");+ assert.equal(isKnownSttArtifactRepoId(KOKORO), false);+ // The curated Whisper and Qwen3-ASR GGUFs keep their own engines and keys.+ assert.equal(sttEngineForRepoId("unslothai/Qwen3-ASR-0.6B-GGUF"), "mtmd");+ assert.equal(sttEngineForRepoId("unslothai/whisper-small-GGUF"), "gguf");+ assert.equal(sttRepoIdForSidecarKey("qwen3-asr-0.6b", "mtmd"), "unslothai/Qwen3-ASR-0.6B-GGUF");+});++test("audiocpp status blocks feed downloads and residency, by key or by id", () => {+ for (const reported of ["audiocpp-canary-180m-flash", `${AUDIO_CPP_REPO}/Canary-180M-Flash-GGUF`]) {+ const status = {+ audiocpp: { downloaded_models: [reported], loaded_model: reported },+ };+ assert.deepEqual(sttDownloadedArtifacts(status, sttRepoIdForSidecarKey), [+ {+ repoId: `${AUDIO_CPP_REPO}/Canary-180M-Flash-GGUF`,+ sidecarKey: reported,+ engine: "audiocpp",+ },+ ]);+ assert.deepEqual(resolveSttResidency(status, "audiocpp", true), {+ model: reported,+ engine: "audiocpp",+ });+ }+});++test("dictation settings list the saved keys by their Hub name", () => {+ assert.deepEqual(+ AUDIO_CPP_STT_KEYS,+ AUDIO_CPP_DICTATION_MODELS.map((model) => model.key),+ );+ assert.deepEqual(STT_MODELS.slice(-AUDIO_CPP_STT_KEYS.length), AUDIO_CPP_STT_KEYS);+ assert.equal(STT_MODELS[0], "qwen3-asr-0.6b");+ assert.equal(DEFAULT_STT_MODEL, "qwen3-asr-0.6b");+ for (const key of AUDIO_CPP_STT_KEYS) {+ const model = audioCppDictationModelFor(key);+ assert.ok(model, key);+ assert.ok(AUDIO_CPP_STT_MODELS.has(key));+ assert.ok(!MTMD_STT_MODELS.has(key));+ // Every saved key names a recommended ASR folder.+ assert.equal(audioCppModelFor(model.id)?.task, "asr", key);+ assert.equal(STT_MODEL_REPOS[key], model.id);+ assert.doesNotMatch(sttModelName(key), BRAND);+ assert.ok(sttModelName(key).startsWith(audioCppDisplayName(model.id)), key);+ assert.equal(sttModelSize(key), audioCppSizeLabel(model.sizeBytes));+ }+ assert.equal(sttModelName("audiocpp-qwen3-asr-0.6b"), "Qwen3-ASR-0.6B-GGUF");+ assert.equal(sttModelName("audiocpp-moonshine-tiny"), "Moonshine-Streaming-GGUF (tiny)");+ const voiceTab = readSrc("features/settings/tabs/voice-tab.tsx");+ assert.match(voiceTab, /if \(AUDIO_CPP_STT_MODELS\.has\(model\)\) return sttModelName\(model\);/);+});++test("an Audio-page ASR pick sends its quant; other engines and saved keys send none", () => {+ const adapter = readSrc("features/chat/adapters/studio-model-dictation-adapter.ts");+ assert.match(+ adapter,+ /return engine === "audiocpp" && ggufVariant\s*\?[\s\S]*\{ gguf_variant: ggufVariant \}\s*:\s*\{\};/,+ );+ assert.equal(adapter.match(/\.\.\.sttVariantBody\(resolvedEngine, ggufVariant\)/g)?.length, 2);+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(page, /sttGgufVariants\.current\.set\(id\.toLowerCase\(\), meta\.ggufVariant\)/);+ assert.match(+ page,+ /engine === "audiocpp"\s*\?\s*\(sttGgufVariants\.current\.get\(repoId\.toLowerCase\(\)\) \?\? null\)/,+ );+ assert.equal(+ page.match(/controller\.signal,\s*undefined,\s*ggufVariant,/g)?.length,+ 2,+ );+ // Settings > Voice passes a saved key and no variant.+ const voiceTab = readSrc("features/settings/tabs/voice-tab.tsx");+ assert.match(voiceTab, /await startSttDownload\(sttModel, hfApiToken\(hfToken\)\);/);+});++test("sttEngineFor sends saved keys, folders and GGUF repos to the audiocpp engine", () => {+ const adapter = readSrc("features/chat/adapters/studio-model-dictation-adapter.ts");+ assert.match(adapter, /AUDIO_CPP_STT_MODELS\.has\(id\) \|\|\s*isAudioCppFolderId\(id\)/);+ assert.match(adapter, /if \(engine === "audiocpp"\) return status\.audiocpp;/);+});++test("English-only and partial-language ASR models are gated by language", () => {+ for (const key of [+ "audiocpp-moonshine-tiny",+ "audiocpp-moonshine-small",+ "audiocpp-nemotron-3.5-asr-0.6b",+ ]) {+ assert.ok(ENGLISH_ONLY_STT_MODELS.has(key), key);+ assert.equal(isSttModelLanguageCompatible(key, "en-US"), true);+ assert.equal(isSttModelLanguageCompatible(key, "ja-JP"), false);+ assert.equal(isSttModelLanguageCompatible(key, "auto"), true);+ }+ const canary = "audiocpp-canary-180m-flash";+ assert.deepEqual(STT_MODEL_LANGUAGES.get(canary), ["en", "de", "es", "fr"]);+ assert.ok(!ENGLISH_ONLY_STT_MODELS.has(canary));+ for (const language of ["en-GB", "de-DE", "es-ES", "fr-FR", "auto"]) {+ assert.equal(isSttModelLanguageCompatible(canary, language), true, language);+ }+ assert.equal(isSttModelLanguageCompatible(canary, "ja-JP"), false);+ for (const key of [+ "audiocpp-parakeet-tdt-0.6b-v3",+ "audiocpp-qwen3-asr-0.6b",+ "qwen3-asr-0.6b",+ "small",+ ]) {+ assert.equal(STT_MODEL_LANGUAGES.has(key), false, key);+ assert.equal(isSttModelLanguageCompatible(key, "ja-JP"), true, key);+ }+});++test("GGUF music length follows the backend clamp; the MiniMax pipeline keeps its own", () => {+ assert.deepEqual(musicDurationRange(false), {+ min: AUDIO_CPP_MUSIC_MIN_SECONDS,+ max: AUDIO_CPP_MUSIC_MAX_SECONDS,+ });+ assert.equal(AUDIO_CPP_MUSIC_MAX_SECONDS, 240);+ assert.deepEqual(musicDurationRange(true), { min: 1, max: MINIMAX_MUSIC_MAX_SECONDS });+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(page, /musicDurationRange\(cudaMusicGeneration\)/);+ assert.match(page, /min=\{musicRange\.min\}\s*max=\{musicRange\.max\}/);+ assert.match(page, /minimaxMusicFramesForSeconds\(musicSeconds\)/);+});++test("GGUF runtime speech trades sampling controls for the model's own options", () => {+ assert.equal(audioSamplingControlsApply("audiocpp_tts"), false);+ for (const audioType of ["audiocpp_music", "snac", "moss_tts_local", null]) {+ assert.equal(audioSamplingControlsApply(audioType), true, String(audioType));+ }+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(+ page,+ /\{musicGeneration \|\|\s*samplingControls \|\|\s*audioOptionSpecs\.length > 0 \? \(\s*<AdvancedDisclosure/,+ );+ assert.match(page, /!musicGeneration && samplingControls && temperatureEdited/);+ assert.match(page, /parseAudioOptions\(status\?\.audio_options\)/);+ assert.match(page, /\{ audio_options: requestOptions \}/);+ assert.match(page, /"Voice or style description"/);+});++test("pickers, toasts, downloads and loaded models show no engine name", () => {+ const page = readSrc("features/audio/audio-page.tsx");+ // Every user-visible string literal on the page, without comments.+ const withoutComments = page+ .replace(/\/\*[\s\S]*?\*\//g, "")+ .replace(/^\s*\/\/.*$/gm, "");+ const literals = withoutComments.match(/(["'`])(?:\\.|(?!\1)[^\\])*\1/g) ?? [];+ const branded = literals.filter(+ (literal) =>+ /audio\.cpp/i.test(literal) && !/audio-cpp-catalog|audio_cpp_runtime/.test(literal),+ );+ assert.deepEqual(branded, []);+ assert.equal(shortModelLabel(KOKORO), "Kokoro-82M-GGUF");+ assert.equal(shortModelLabel("audiocpp-qwen3-asr-0.6b"), "Qwen3-ASR-0.6B-GGUF");+ assert.equal(shortModelLabel(MINIMAX_GGUF), MINIMAX_GGUF);+ const sources = readSrc("features/loaded-models/loaded-models-sources.ts");+ assert.match(sources, /audiocpp: "GGUF"/);+ const panel = readSrc("features/hub/download-manager/download-manager-panel.tsx");+ assert.match(panel, /isAudioCppFolderId\(repoId\) \? audioCppDisplayName\(repoId\) : repoId/);+ assert.match(panel, /\{job\.presentation\?\.label \?\? repoLabel\(job\.repoId\)\}/);+});++test("an Audio GGUF pick downloads its quant as the standard variant job", () => {+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(page, /ggufVariant: meta\.ggufVariant,/);+ const staged = readSrc("features/hub/download-manager/use-staged-download.ts");+ assert.match(staged, /current\.ggufVariant \?\? scopedVariant\(scopeId\)/);+ assert.match(staged, /variant: current\.ggufVariant,/);+});++test("recommended speech and music picks are refused when the runtime cannot run them", () => {+ const full = { available: true, espeak: true, backend: "cuda", release_tag: "v1" };+ const noEspeak = { ...full, espeak: false };+ const missing = { available: false, espeak: false, backend: null, release_tag: null };+ assert.deepEqual(+ AUDIO_CPP_MODELS.filter((model) => model.needsEspeak).map((model) =>+ audioCppDisplayName(model.id),+ ),+ ["Kokoro-82M-GGUF", "KittenTTS-GGUF", "Piper-TTS-GGUF", "Inflect-Micro-v2-GGUF"],+ );+ for (const model of AUDIO_CPP_MODELS) {+ assert.equal(audioCppRuntimeProblem(model.id, null), null, model.id);+ assert.equal(audioCppRuntimeProblem(model.id, undefined), null, model.id);+ assert.equal(audioCppRuntimeProblem(model.id, full), null, model.id);+ if (model.task === "asr") {+ assert.equal(audioCppRuntimeProblem(model.id, missing), null, model.id);+ continue;+ }+ const notInstalled = audioCppRuntimeProblem(model.id, missing) ?? "";+ assert.match(notInstalled, /audio runtime is not installed/);+ assert.doesNotMatch(notInstalled, BRAND);+ const problem = audioCppRuntimeProblem(model.id, noEspeak);+ if (model.needsEspeak) {+ assert.ok(+ problem?.startsWith(+ `${audioCppDisplayName(model.id)} needs an audio runtime built with eSpeak-ng`,+ ),+ model.id,+ );+ assert.doesNotMatch(problem ?? "", BRAND);+ } else {+ assert.equal(problem, null, model.id);+ }+ }+ assert.equal(audioCppRuntimeProblem("OpenMOSS-Team/MOSS-TTS-Nano-100M", missing), null);+ assert.equal(audioCppRuntimeProblem(null, missing), null);+ const route = readText("../../backend/routes/inference.py");+ assert.match(route, /"audio_cpp_runtime": _audio_cpp_runtime_status\(\)/);+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(page, /audioCppRuntime\.current = stt\.audio_cpp_runtime \?\? null;/);+ assert.match(+ page,+ /audioCppRuntimeProblem\(id, audioCppRuntime\.current\);\s*if \(runtimeProblem\) \{\s*toast\.error\(runtimeProblem, \{ duration: 7000 \}\);\s*return;/,+ );+});++test("the capability line names GGUF audio and music, never the runtime's internal type", () => {+ assert.equal(audioCapabilityLine("tts", "audiocpp_tts"), "Text-to-speech · GGUF");+ assert.equal(audioCapabilityLine("music", "audiocpp_music"), "Music generation · GGUF");+ assert.equal(audioCapabilityLine("tts", "higgs_tts2"), "Text-to-speech · higgs_tts2");+ assert.equal(audioCapabilityLine("stt", "ready"), "Speech-to-text · ready");+});++test("YuE2 generates from a style description alone; other music still needs lyrics", () => {+ assert.equal(musicLyricsOptional("audiocpp_music", "yue2"), true);+ for (const family of ["ace_step", "minimax_music3", "stable_audio", null]) {+ assert.equal(musicLyricsOptional("audiocpp_music", family), false, String(family));+ }+ assert.equal(musicLyricsOptional("audiocpp_tts", "yue2"), false);+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(page, /\(!prompt\.trim\(\) && !lyricsOptional\)/);+ assert.match(page, /if \(!text && !lyricsOptional\) return;/);+});++test("a custom GGUF dictation repo skips the Whisper-only validator", () => {+ const tab = readSrc("features/settings/tabs/voice-tab.tsx");+ assert.match(tab, /!isCuratedSttModel\(model\) && sttEngineFor\(model\) !== "audiocpp"/);+});++test("the picked STT quant is remembered with the repo across a restart", () => {+ const page = readSrc("features/audio/audio-page.tsx");+ assert.match(page, /usePersistedChoice\("unsloth:audio:last-stt-variant", ""\)/);+ assert.match(page, /lastSttRepo && lastSttVariant \? \[\[lastSttRepo\.toLowerCase\(\), lastSttVariant\]\]/);+ assert.match(page, /setLastSttVariant\(sttGgufVariants\.current\.get\(repo\.toLowerCase\(\)\) \?\? ""\)/);+});diff --git a/studio/frontend/tests/audio-mode-task-filter.test.ts b/studio/frontend/tests/audio-mode-task-filter.test.tsindex 2dd00e40687..af285770da1 100644--- a/studio/frontend/tests/audio-mode-task-filter.test.ts+++ b/studio/frontend/tests/audio-mode-task-filter.test.ts@@ -18,7 +18,7 @@ const catalogSource = readSrc("features/audio/catalog.ts");test("Hub discovery follows the active audio mode", () => {assert.match(pageSource,- /speak: \["text-to-speech"\],[\s\S]*transcribe: \["automatic-speech-recognition"\]/,+ /speak: \["text-to-speech", "text-to-audio"\],[\s\S]*transcribe: \["automatic-speech-recognition"\]/,);assert.match(pageSource, /task=\{HUB_TASKS_BY_MODE\[mode\]\}/);});diff --git a/studio/frontend/tests/audio-model-eject.test.ts b/studio/frontend/tests/audio-model-eject.test.tsindex 5a961a916e5..6d728ebb887 100644--- a/studio/frontend/tests/audio-model-eject.test.ts+++ b/studio/frontend/tests/audio-model-eject.test.ts@@ -203,7 +203,7 @@ test("a dictation model this page did not load survives a mode switch", () => {);assert.match(source,- /await loadSttModel\(sidecarKey, engine, controller\.signal\);\s*sttLoadedByThisPage\.current = sidecarKey;/,+ /await loadSttModel\(\s*sidecarKey,\s*engine,\s*controller\.signal,\s*undefined,\s*ggufVariant,\s*\);\s*sttLoadedByThisPage\.current = sidecarKey;/,);});diff --git a/studio/frontend/tests/audio-options.test.ts b/studio/frontend/tests/audio-options.test.tsnew file mode 100644index 00000000000..2e2964c7db7--- /dev/null+++ b/studio/frontend/tests/audio-options.test.ts@@ -0,0 +1,161 @@+// 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 GGUF audio model's own options arrive as a schema on the loaded-model status and go back as+// `audio_options` on the speech request. Only what the user set is sent, checked against the+// schema, and it is remembered per model id.++import assert from "node:assert/strict";+import test from "node:test";++import { installLocalStorageFake } from "./helpers/kit.ts";++installLocalStorageFake();+const {+ AUDIO_OPTIONS_STORAGE_KEY,+ audioOptionDisplayValue,+ audioOptionFloatStep,+ audioOptionLabel,+ audioOptionsForRequest,+ audioVoiceLabel,+ coerceAudioOptionValue,+ missingRequiredAudioOptions,+ parseAudioOptions,+ readAudioOptionValues,+ saveAudioOptionValues,+} = await import("../src/features/audio/audio-options.ts");++const YUE2_OPTIONS = [+ {+ name: "num_inference_steps",+ type: "int",+ description: "Diffusion steps.",+ default: 50,+ min: 1,+ max: 200,+ required: false,+ },+ { name: "guidance_scale", type: "float", default: 1.5, min: 0, max: 10 },+ { name: "cot", type: "enum", values: ["off", "melody", "full"], default: "off" },+ { name: "abc", type: "bool", default: false },+ { name: "stop_after", type: "string" },+ { name: "voice_id", type: "string", required: true },+];++test("the status schema parses, dropping what cannot be rendered", () => {+ const specs = parseAudioOptions([+ ...YUE2_OPTIONS,+ { name: "voice_ref", type: "audio_path" },+ { name: "empty_enum", type: "enum", values: [] },+ { name: "", type: "int" },+ { name: "cot", type: "string" },+ "junk",+ null,+ ]);+ assert.deepEqual(+ specs.map((spec) => [spec.name, spec.type]),+ [+ ["num_inference_steps", "int"],+ ["guidance_scale", "float"],+ ["cot", "enum"],+ ["abc", "bool"],+ ["stop_after", "string"],+ ["voice_id", "string"],+ ],+ );+ assert.equal(specs[0].default, 50);+ assert.equal(specs[2].default, "off");+ assert.equal(specs[3].default, false);+ assert.equal(specs[4].default, null);+ assert.deepEqual(parseAudioOptions(undefined), []);+ assert.deepEqual(parseAudioOptions({ name: "x" }), []);+ // A default outside the declared range is clamped, an unlisted enum default dropped.+ const [steps, cot] = parseAudioOptions([+ { name: "steps", type: "int", default: 500, max: 200 },+ { name: "cot", type: "enum", values: ["off"], default: "full" },+ ]);+ assert.equal(steps.default, 200);+ assert.equal(cot.default, null);+});++test("values are coerced to the option's type and range", () => {+ const [steps, guidance, cot, abc, stopAfter] = parseAudioOptions(YUE2_OPTIONS);+ assert.equal(coerceAudioOptionValue(steps, 12.6), 13);+ assert.equal(coerceAudioOptionValue(steps, "400"), 200);+ assert.equal(coerceAudioOptionValue(steps, 0), 1);+ assert.equal(coerceAudioOptionValue(steps, "x"), undefined);+ assert.equal(coerceAudioOptionValue(guidance, 2.25), 2.25);+ assert.equal(coerceAudioOptionValue(cot, "melody"), "melody");+ assert.equal(coerceAudioOptionValue(cot, "bogus"), undefined);+ assert.equal(coerceAudioOptionValue(abc, true), true);+ assert.equal(coerceAudioOptionValue(abc, "true"), undefined);+ assert.equal(coerceAudioOptionValue(stopAfter, "verse"), "verse");+ assert.equal(audioOptionDisplayValue(steps, {}), 50);+ assert.equal(audioOptionDisplayValue(steps, { num_inference_steps: 20 }), 20);+});++test("only set, valid values are sent; unknown names are dropped", () => {+ const specs = parseAudioOptions(YUE2_OPTIONS);+ assert.deepEqual(+ audioOptionsForRequest(specs, {+ num_inference_steps: 999,+ cot: "full",+ abc: true,+ stop_after: "",+ guidance_scale: "high" as unknown as number,+ removed_option: 3,+ }),+ { num_inference_steps: 200, cot: "full", abc: true },+ );+ assert.deepEqual(audioOptionsForRequest(specs, {}), {});+});++test("a required option with no value or default blocks generation", () => {+ const specs = parseAudioOptions(YUE2_OPTIONS);+ assert.deepEqual(+ missingRequiredAudioOptions(specs, {}).map((spec) => spec.name),+ ["voice_id"],+ );+ assert.deepEqual(missingRequiredAudioOptions(specs, { voice_id: "alba" }), []);+ assert.deepEqual(+ missingRequiredAudioOptions(specs, { voice_id: "" }).map((spec) => spec.name),+ ["voice_id"],+ );+});++test("labels and slider steps read naturally", () => {+ assert.equal(audioOptionLabel("num_inference_steps"), "Num inference steps");+ assert.equal(audioOptionLabel("minimax_music3.duration_sec"), "Duration sec");+ assert.equal(audioOptionFloatStep(0, 10), 0.1);+ assert.equal(audioOptionFloatStep(0, 1), 0.01);+ assert.equal(audioOptionFloatStep(0, 300), 5);+ assert.equal(audioOptionFloatStep(1, 1), 0.01);+});++test("values are remembered per model id, whatever its casing", () => {+ saveAudioOptionValues("audio-cpp/Yue2-3B-GGUF", { cot: "full", num_inference_steps: 30 });+ saveAudioOptionValues("audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF", { speed: 1.2 });+ assert.deepEqual(readAudioOptionValues("AUDIO-CPP/yue2-3b-gguf/"), {+ cot: "full",+ num_inference_steps: 30,+ });+ assert.deepEqual(readAudioOptionValues("audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF"), {+ speed: 1.2,+ });+ saveAudioOptionValues("audio-cpp/Yue2-3B-GGUF", {});+ assert.deepEqual(readAudioOptionValues("audio-cpp/Yue2-3B-GGUF"), {});+ assert.deepEqual(readAudioOptionValues(null), {});+ // A corrupt store reads as empty rather than throwing.+ globalThis.localStorage.setItem(AUDIO_OPTIONS_STORAGE_KEY, "{not json");+ assert.deepEqual(readAudioOptionValues("audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF"), {});+});++test("built-in voices read as names, and Kokoro ids also name their language", () => {+ assert.equal(audioVoiceLabel("af_heart", "kokoro_tts"), "Heart (American English, female)");+ assert.equal(audioVoiceLabel("bm_george", "kokoro_tts"), "George (British English, male)");+ assert.equal(audioVoiceLabel("zf_xiaoxiao", "kokoro_tts"), "Xiaoxiao (Mandarin Chinese, female)");+ assert.equal(audioVoiceLabel("uncle_fu", "qwen3_tts"), "Uncle Fu");+ // Another family's ids that happen to look like Kokoro's are not given a language.+ assert.equal(audioVoiceLabel("af_heart", "kitten_tts"), "Af Heart");+ assert.equal(audioVoiceLabel("Custom Voice.wav", null), "Custom Voice.wav");+});diff --git a/studio/frontend/tests/audio-page-policy.test.ts b/studio/frontend/tests/audio-page-policy.test.tsindex d6590b6a50d..1d3ebab30c1 100644--- a/studio/frontend/tests/audio-page-policy.test.ts+++ b/studio/frontend/tests/audio-page-policy.test.ts@@ -141,9 +141,10 @@ test("native audio instruction fields match the runtime payload contract", () =>test("Audio sends model-specific duration and instruction payloads", () => {assert.match(audioPageSource,- /musicGeneration\s*\? minimaxMusicFramesForSeconds\(minimaxMaxSeconds\)/,+ /musicGeneration\s*\? minimaxMusicFramesForSeconds\(musicSeconds\)/,);- assert.match(audioPageSource, /max=\{MINIMAX_MUSIC_MAX_SECONDS\}/);+ // The range is per model: MiniMax Music 3 up to 360 s, audio.cpp up to its backend clamp.+ assert.match(audioPageSource, /max=\{musicRange\.max\}/);assert.match(audioPageSource,/instructionsKind !== null && instructions[\s\S]*audio_instructions: instructions/,diff --git a/studio/frontend/tests/audio-stt-download-fallback.test.ts b/studio/frontend/tests/audio-stt-download-fallback.test.tsindex 856f4d644b4..abe6b992e37 100644--- a/studio/frontend/tests/audio-stt-download-fallback.test.ts+++ b/studio/frontend/tests/audio-stt-download-fallback.test.ts@@ -23,7 +23,7 @@ test("STT download polling uses the available engine fallback", () => {test("Audio mirrors an STT transfer into Downloads without resetting an adopted job", () => {assert.match(source,- /await startSttDownload\(sidecarKey,[\s\S]*engine\);[\s\S]*if \(!isTrackingSttDownload\(sidecarKey, engine\)\) \{[\s\S]*trackSttDownload\(sidecarKey, \{[\s\S]*warmSelectedVoiceModelOnComplete: false,[\s\S]*engine,[\s\S]*repoId,[\s\S]*\}\);[\s\S]*\}[\s\S]*for \(;;\)/,+ /await startSttDownload\(\s*sidecarKey,[\s\S]*engine,\s*ggufVariant,\s*\);[\s\S]*if \(!isTrackingSttDownload\(sidecarKey, engine\)\) \{[\s\S]*trackSttDownload\(sidecarKey, \{[\s\S]*warmSelectedVoiceModelOnComplete: false,[\s\S]*engine,[\s\S]*repoId,[\s\S]*\}\);[\s\S]*\}[\s\S]*for \(;;\)/,);assert.doesNotMatch(source, /`Downloading \$\{sidecarKey\}:/);});@@ -31,7 +31,7 @@ test("Audio mirrors an STT transfer into Downloads without resetting an adoptedtest("cancelling the shared STT download never loads a partial checkpoint", () => {assert.match(source,- /if \(download\?\.cancelled\) return;[\s\S]*if \(download\?\.error\)[\s\S]*if \(!download\?\.downloading\) break;[\s\S]*await loadSttModel\(sidecarKey, engine, controller\.signal\)/,+ /if \(download\?\.cancelled\) return;[\s\S]*if \(download\?\.error\)[\s\S]*if \(!download\?\.downloading\) break;[\s\S]*await loadSttModel\(\s*sidecarKey,\s*engine,\s*controller\.signal,/,);});diff --git a/studio/frontend/tests/audio-stt-on-device.test.ts b/studio/frontend/tests/audio-stt-on-device.test.tsindex 9c1092e9893..fb24072b236 100644--- a/studio/frontend/tests/audio-stt-on-device.test.ts+++ b/studio/frontend/tests/audio-stt-on-device.test.ts@@ -6,14 +6,12 @@ import test from "node:test";import { sttDownloadedArtifacts } from "../src/features/audio/audio-page-policy.ts";import {+ type AudioSttEngine,sttEngineForRepoId,sttRepoIdForSidecarKey,} from "../src/features/audio/stt-artifacts.ts";-const repoIdForSidecarKey = (- key: string,- engine: "transformers" | "gguf" | "mtmd",-) => {+const repoIdForSidecarKey = (key: string, engine: AudioSttEngine) => {const repos: Record<string, string> =engine === "gguf"? {diff --git a/studio/frontend/tests/audio-tts-download-manager.test.ts b/studio/frontend/tests/audio-tts-download-manager.test.tsindex a3cee716446..8e1e95bfd94 100644--- a/studio/frontend/tests/audio-tts-download-manager.test.ts+++ b/studio/frontend/tests/audio-tts-download-manager.test.ts@@ -8,15 +8,16 @@ import { readSrc } from "./helpers/kit.ts";const source = readSrc("features/audio/audio-page.tsx");-test("uncached remote TTS GGUFs stage the exact file through the shared manager", () => {+test("uncached remote TTS GGUFs stage the picked quant through the shared manager", () => {assert.match(source, /useStagedDownload\(\{\s*scopeId: "audio"/);assert.match(source,/meta\.source === "hub"[\s\S]*meta\.isDownloaded === false[\s\S]*ggufFilename/,);+ // A named quant is the standard variant download, as in Chat; a bare file stays scoped.assert.match(source,- /stageTtsDownload\(\[\s*\{[\s\S]*repoId,[\s\S]*files: \[ggufFilename\],[\s\S]*bytes: meta\.expectedBytes \?\? 0/,+ /stageTtsDownload\(\[\s*meta\.ggufVariant\s*\?\s*\{[\s\S]*repoId,[\s\S]*ggufVariant: meta\.ggufVariant,[\s\S]*\}\s*:\s*\{[\s\S]*files: \[ggufFilename\],[\s\S]*bytes: meta\.expectedBytes \?\? 0/,);assert.match(source,diff --git a/studio/frontend/tests/llama-cpp-custom-config.test.ts b/studio/frontend/tests/llama-cpp-custom-config.test.tsindex b936481b7b7..e353a8440cb 100644--- a/studio/frontend/tests/llama-cpp-custom-config.test.ts+++ b/studio/frontend/tests/llama-cpp-custom-config.test.ts@@ -356,7 +356,7 @@ test("a custom config locks the managed rows and keeps the editor outside them",// Hidden behind Advanced settings unless custom mode is already on.assert.match(page,- /!resolvedIsDiffusion &&\s*\(showAdvanced \|\| customActive\)/,+ /!resolvedIsDiffusion &&\s*!audioRuntimeGguf &&\s*\(showAdvanced \|\| customActive\)/,);assert.ok(page.indexOf("{customActive && <VisionRow") > fieldsetEnd);});diff --git a/studio/frontend/tests/vision-toggle-gating.test.ts b/studio/frontend/tests/vision-toggle-gating.test.tsindex 918a4671e0f..ddc49b4eadb 100644--- a/studio/frontend/tests/vision-toggle-gating.test.ts+++ b/studio/frontend/tests/vision-toggle-gating.test.ts@@ -111,7 +111,12 @@ test("the Vision row exists only in the GGUF half of Advanced Settings", () => {const gateAbove = (index: number): string => {for (let i = index; i >= 0; i--) {const line = lines[i].trim();- if (line === "{target.isGguf && (") return "isGguf";+ // An audio-runtime GGUF launches no llama-server, so its half is gated off too.+ if (+ line === "{target.isGguf && (" ||+ line === "{target.isGguf && !audioRuntimeGguf && ("+ )+ return "isGguf";if (line === "{!target.isGguf && (") return "!isGguf";}return "none";diff --git a/studio/install_audio_cpp_prebuilt.py b/studio/install_audio_cpp_prebuilt.pynew file mode 100644index 00000000000..f6c691ccef8--- /dev/null+++ b/studio/install_audio_cpp_prebuilt.py@@ -0,0 +1,1064 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Install a prebuilt ``audiocpp_server`` (audio.cpp) for Studio's audio.cpp engine.++audio.cpp vendors its own patched ggml, so unlike whisper.cpp it cannot share the+llama.cpp runtime: every bundle is self-contained (the server links ggml statically).+Releases are named ``audio-<tag>-bin-<os>-<arch>-<backend>.{zip,tar.gz}``, the scheme+upstream uses and the Unsloth fork keeps, so one resolver serves both. Windows CUDA+bundles need the CUDA runtime DLLs, which upstream publishes as a separate+``audio-<tag>-cudart-windows-x64-<line>.zip``; that download is skipped when the+running Python's torch already ships the same CUDA runtime line.++The bundle is extracted into a staging directory beside the managed tree, started once+with ``--help`` so a bundle this host cannot load is refused, and swapped in only then,+so an interrupted or unusable install never replaces a working tree.++Every bundle and CUDA runtime archive must match a sha256 pinned in+``audio_cpp_prebuilt_pins.json`` unless the user picked the release+(``UNSLOTH_AUDIO_CPP_REPO`` / ``UNSLOTH_AUDIO_CPP_TAG``). A re-run whose install record+already names the pinned release makes no network call, and a lookup that cannot answer+keeps a complete install.++Usage:+ python studio/install_audio_cpp_prebuilt.py # auto-detect host+ python studio/install_audio_cpp_prebuilt.py --accelerator cpu+ python studio/install_audio_cpp_prebuilt.py --print-asset # resolve only+ python studio/install_audio_cpp_prebuilt.py --write-pins # regenerate the digest pins+"""++from __future__ import annotations++import argparse+import datetime+import fnmatch+import glob+import json+import os+import platform+import re+import shutil+import subprocess+import sys+import tarfile+import tempfile+import urllib.error+import urllib.request+import zipfile+from pathlib import Path+from typing import Optional, Sequence++if __package__:+ from . import prebuilt_core as core+ from .install_sd_cpp_prebuilt import (+ GitHubRateLimited,+ _is_rate_limited,+ _rate_limit_message,+ _safe_extractall,+ )+else:+ _STUDIO_DIR = os.path.dirname(os.path.abspath(__file__))+ if _STUDIO_DIR not in sys.path:+ sys.path.insert(0, _STUDIO_DIR)+ import prebuilt_core as core # type: ignore[no-redef]+ from install_sd_cpp_prebuilt import ( # type: ignore[no-redef]+ GitHubRateLimited,+ _is_rate_limited,+ _rate_limit_message,+ _safe_extractall,+ )++# The Unsloth fork publishes the bundles Studio pins (CI: .github/workflows/unsloth-prebuilt.yml there,+# like unslothai/whisper.cpp); UNSLOTH_AUDIO_CPP_REPO overrides it.+DEFAULT_REPO = "unslothai/audio.cpp"+UPSTREAM_FALLBACK_REPO = "0xShug0/audio.cpp"+# Pinned for reproducibility; UNSLOTH_AUDIO_CPP_TAG overrides ('' tracks latest). The fork's tags carry+# the Unsloth packaging (static eSpeak-ng, lean multi-arch Linux CUDA); upstream never publishes them.+DEFAULT_TAG = "v0.9.0-unsloth.1"+# The upstream release the fork tag is built from, tried when the fork cannot serve this host.+UPSTREAM_FALLBACK_TAG = "v0.9.0"++INSTALL_RECORD = "UNSLOTH_AUDIO_CPP_PREBUILT_INFO.json"+OWNERSHIP_MARKER = ".unsloth-studio-owned"+SERVER_NAME = "audiocpp_server.exe" if sys.platform == "win32" else "audiocpp_server"+# {repo: {tag: {asset: sha256}}} for the default fork tag and its upstream fallback. Regenerate with+# `python studio/install_audio_cpp_prebuilt.py --write-pins` after bumping either tag; it reads the same+# digests `gh release view <tag> -R <repo> --json assets` shows.+PINS_PATH = Path(__file__).resolve().with_name("audio_cpp_prebuilt_pins.json")++ACCELERATORS = ("auto", "cpu", "cuda", "vulkan", "metal")+# The staged server's --help must exit 0 within this long before it replaces the live tree.+SMOKE_TIMEOUT_SECONDS = 30.0+USER_AGENT = "unsloth-audio-cpp-installer"++EXIT_OK = 0+EXIT_FAILED = 1+EXIT_BUSY = 3++KEPT_EXISTING_LINE = "audio.cpp: keeping the existing complete install"+++class ReleaseLookupUnavailable(RuntimeError):+ """No release lookup answered (offline, DNS, GitHub down): says nothing about the tree on disk."""+++def log(message: str) -> None:+ # prebuilt_core's download retries report through this.+ print(f"audio.cpp: {message}", file = sys.stderr, flush = True)+++# Late-binding seam for prebuilt_core: its downloader reads USER_AGENT and log from here.+_OPS = core.ModuleOps(globals())++_OS_TOKENS = {+ "windows": ("windows", "win"),+ "linux": ("ubuntu", "linux"),+ "darwin": ("macos", "darwin"),+}+_ARCH_TOKENS = {+ "x86_64": "x64",+ "amd64": "x64",+ "x64": "x64",+ "arm64": "arm64",+ "aarch64": "arm64",+}+# "-cuda12.8" (upstream) or "-cuda12" (unslothai/audio.cpp: one lean bundle per CUDA major line).+_CUDA_LINE = re.compile(r"-cuda(\d+)(?:\.(\d+))?(?=[-.]|$)")+++def _repo() -> str:+ return (os.environ.get("UNSLOTH_AUDIO_CPP_REPO") or "").strip() or DEFAULT_REPO+++def _pinned_tag() -> Optional[str]:+ val = os.environ.get("UNSLOTH_AUDIO_CPP_TAG", DEFAULT_TAG).strip()+ return val or None+++def _user_picked_release() -> bool:+ """The user chose the repo or tag, so a digest this repo never pinned is theirs to trust."""+ return (+ bool((os.environ.get("UNSLOTH_AUDIO_CPP_REPO") or "").strip())+ or "UNSLOTH_AUDIO_CPP_TAG" in os.environ+ )+++# Every pinned Linux bundle (CPU and CUDA) is built on Ubuntu 22.04.+_PINNED_LINUX_GLIBC_FLOOR = (2, 35)+++def _glibc_below_pinned_floor() -> Optional[str]:+ """The host glibc when it is older than the pinned Linux bundles need, else ``None``. Without+ this the start check fails after a full download (~1 GB for CUDA) on every setup run."""+ if not sys.platform.startswith("linux") or _user_picked_release():+ return None+ name, version = platform.libc_ver()+ try:+ parsed = tuple(int(x) for x in version.split(".")[:2])+ except ValueError:+ return None+ if name != "glibc" or len(parsed) != 2 or parsed >= _PINNED_LINUX_GLIBC_FLOOR:+ return None+ return version+++def _release_ladder() -> list[tuple[str, Optional[str]]]:+ """``(repo, tag)`` lookups in order: the pinned tag on the primary repo, then, when the user+ pinned neither repo nor tag, the upstream release the fork tag was cut from. ``None`` (latest)+ only when the user set ``UNSLOTH_AUDIO_CPP_TAG=''``; a pinned install never drifts to an+ untested latest. A user-chosen tag never reaches a repo the user did not choose."""+ primary = _repo()+ ladder = [(primary, _pinned_tag())]+ if not _user_picked_release() and primary != UPSTREAM_FALLBACK_REPO:+ ladder.append((UPSTREAM_FALLBACK_REPO, UPSTREAM_FALLBACK_TAG))+ return ladder+++def _accelerator_from_env() -> str:+ """``UNSLOTH_AUDIO_CPP_ACCELERATOR`` (auto|cpu|cuda|vulkan|metal), for hosts whose GPU is not visible+ at install time (a Docker build). Set, it is an explicit request and never downgraded."""+ raw = (os.environ.get("UNSLOTH_AUDIO_CPP_ACCELERATOR") or "").strip().lower()+ if not raw:+ return "auto"+ if raw not in ACCELERATORS:+ print(+ f"audio.cpp: ignoring UNSLOTH_AUDIO_CPP_ACCELERATOR={raw!r} (expected one of {', '.join(ACCELERATORS)})",+ file = sys.stderr,+ flush = True,+ )+ return "auto"+ return raw+++def load_pins(path: Optional[Path] = None) -> dict:+ try:+ with open(path or PINS_PATH, "r", encoding = "utf-8") as f:+ data = json.load(f)+ except (OSError, ValueError):+ return {}+ releases = data.get("releases") if isinstance(data, dict) else None+ return releases if isinstance(releases, dict) else {}+++def pinned_sha256(repo: str, tag: Optional[str], asset: str) -> Optional[str]:+ if not tag:+ return None+ digest = ((load_pins().get(repo) or {}).get(tag) or {}).get(asset)+ return core.normalize_sha256_digest(digest)+++def _expected_sha256(repo: str, tag: Optional[str], asset: dict) -> Optional[str]:+ """The sha256 an asset must hash to: the in-repo pin, which GitHub's own digest must agree with.+ Unpinned assets are refused unless the user picked the release, where GitHub's digest (if any)+ is the best available."""+ name = asset["name"]+ published = core.normalize_sha256_digest(asset.get("digest"))+ pinned = pinned_sha256(repo, tag, name)+ if pinned:+ if published and published != pinned:+ raise RuntimeError(+ f"{name}: GitHub reports sha256 {published} but {PINS_PATH.name} pins {pinned}; refusing it"+ )+ return pinned+ if _user_picked_release():+ return published+ raise RuntimeError(+ f"{name} from {repo} {tag or 'latest'} has no sha256 pinned in {PINS_PATH.name}; refusing an unpinned "+ "download (set UNSLOTH_AUDIO_CPP_REPO or UNSLOTH_AUDIO_CPP_TAG to install a release you chose)"+ )+++def default_install_dir() -> Path:+ """``<UNSLOTH_HOME>/audio.cpp``, else ``<STUDIO_HOME>/audio.cpp``, else ``~/.unsloth/audio.cpp``.++ Kept in step with ``audio_cpp_server.managed_audio_cpp_dir``; separate because this+ script runs before the backend package is importable.+ """+ master = (os.environ.get("UNSLOTH_HOME") or "").strip()+ if master:+ return Path(master).expanduser().resolve() / "audio.cpp"+ home = (os.environ.get("UNSLOTH_STUDIO_HOME") or os.environ.get("STUDIO_HOME") or "").strip()+ legacy = Path.home() / ".unsloth" / "audio.cpp"+ if not home:+ return legacy+ root = Path(home).expanduser().resolve()+ return legacy if root == (Path.home() / ".unsloth" / "studio").resolve() else root / "audio.cpp"+++def nvidia_driver_cuda_version() -> Optional[tuple[int, int]]:+ """The CUDA version the installed NVIDIA driver supports, from nvidia-smi, or None."""+ exe = shutil.which("nvidia-smi")+ if not exe:+ return None+ try:+ out = subprocess.run([exe], capture_output = True, text = True, timeout = 15).stdout+ except (OSError, subprocess.SubprocessError):+ return None+ # Newer drivers print "CUDA UMD Version: X.Y" in place of "CUDA Version: X.Y" (same rule as the llama installer).+ match = re.search(r"CUDA(?: UMD)? Version:\s*(\d+)\.(\d+)", out or "")+ return (int(match.group(1)), int(match.group(2))) if match else None+++def detect_accelerator() -> str:+ system = platform.system().lower()+ if system == "darwin":+ return "metal"+ if nvidia_driver_cuda_version() is not None:+ return "cuda"+ return "cpu"+++def torch_cuda_major() -> Optional[int]:+ """The CUDA major line of the torch importable here, without importing torch."""+ try:+ import importlib.metadata as md+ version = md.version("torch")+ except Exception: # noqa: BLE001 - no torch+ return None+ match = re.search(r"\+cu(\d+)", version)+ if match:+ digits = match.group(1)+ return int(digits[:-1]) if len(digits) >= 3 else int(digits[:2])+ return None+++def resolve_release_asset(+ asset_names: Sequence[str],+ *,+ system: str,+ machine: str,+ accelerator: str,+ driver_cuda: Optional[tuple[int, int]] = None,+ prefer_cuda_major: Optional[int] = None,+) -> Optional[str]:+ """Pick the bundle for a host, or None. Pure: the caller passes the release's asset names.++ CUDA picks the newest line the driver can run, preferring ``prefer_cuda_major`` (the+ torch line, whose runtime DLLs can then be reused). CPU prefers the portable build,+ which avoids host-ISA features a native build may assume.+ """+ system = system.lower()+ accel = (accelerator or "cpu").lower()+ os_tokens = _OS_TOKENS.get(system)+ arch = _ARCH_TOKENS.get(machine.lower())+ if not os_tokens or not arch:+ return None+ bundles = [+ n+ for n in asset_names+ if "-bin-" in n+ and (n.endswith(".zip") or n.endswith(".tar.gz"))+ and any(f"-bin-{tok}-{arch}-" in n for tok in os_tokens)+ ]++ def backend_of(name: str) -> str:+ stem = name[: -len(".tar.gz")] if name.endswith(".tar.gz") else name[: -len(".zip")]+ return stem.split(f"-{arch}-", 1)[1]++ if accel == "metal":+ pool = [n for n in bundles if backend_of(n).startswith("metal")]+ return pool[0] if pool else None+ if accel == "cuda":+ candidates = []+ for n in bundles:+ match = _CUDA_LINE.search("-" + backend_of(n))+ if not match:+ continue+ line = (int(match.group(1)), int(match.group(2) or 0))+ if driver_cuda is not None and line > driver_cuda:+ continue+ candidates.append((line, n))+ if not candidates:+ return None+ preferred = [+ c for c in candidates if prefer_cuda_major is not None and c[0][0] == prefer_cuda_major+ ]+ # At equal lines a general build beats upstream's Colab one, which carries sm_75 kernels only.+ return max(preferred or candidates, key = lambda c: (c[0], "colab" not in c[1]))[1]+ if accel == "vulkan":+ pool = sorted(+ (n for n in bundles if backend_of(n).startswith("vulkan")),+ key = lambda n: "portable" not in n,+ )+ return pool[0] if pool else None+ pool = sorted(+ (n for n in bundles if backend_of(n).startswith("cpu")), key = lambda n: "portable" not in n+ )+ return pool[0] if pool else None+++def cudart_asset_for(asset_names: Sequence[str], bundle: str) -> Optional[str]:+ """The separate Windows CUDA runtime archive matching a CUDA bundle's line."""+ match = _CUDA_LINE.search(bundle)+ if not match or "-windows-" not in bundle:+ return None+ line = match.group(0)[1:]+ for name in asset_names:+ if "-cudart-windows-" in name and name.endswith(f"-{line}.zip"):+ return name+ return None+++def _torch_lib_dir() -> Optional[Path]:+ try:+ import importlib.util+ spec = importlib.util.find_spec("torch")+ except Exception: # noqa: BLE001+ return None+ if spec is None or not spec.submodule_search_locations:+ return None+ return Path(list(spec.submodule_search_locations)[0]) / "lib"+++def torch_provides_cuda_runtime(cuda_major: int) -> bool:+ """Whether this Python's torch ships the CUDA runtime DLLs a line-``cuda_major`` bundle loads."""+ if sys.platform != "win32":+ return False+ lib = _torch_lib_dir()+ if lib is None:+ return False+ needed = (f"cudart64_{cuda_major}*.dll", f"cublas64_{cuda_major}*.dll", "cufft64_*.dll")+ return all(glob.glob(str(lib / pattern)) for pattern in needed)+++def _fetch_release(+ repo: str,+ tag: Optional[str],+ token: Optional[str],+ timeout: float = 30.0,+) -> Optional[dict]:+ headers = {"Accept": "application/vnd.github+json", "User-Agent": USER_AGENT}+ if token:+ headers["Authorization"] = f"Bearer {token}"+ url = f"https://api.github.com/repos/{repo}/releases/" + (f"tags/{tag}" if tag else "latest")+ req = urllib.request.Request(url, headers = headers)+ attempts = core.JSON_FETCH_ATTEMPTS+ for attempt in range(1, attempts + 1):+ try:+ with urllib.request.urlopen(req, timeout = timeout) as resp: # noqa: S310+ return json.loads(resp.read().decode("utf-8"))+ except urllib.error.HTTPError as exc:+ if _is_rate_limited(exc):+ raise GitHubRateLimited(_rate_limit_message()) from exc+ if exc.code == 404:+ return None+ if attempt >= attempts or not core.is_retryable_url_error(exc):+ raise+ core.sleep_backoff(attempt, exc = exc)+ except Exception as exc: # noqa: BLE001 - classified below+ if attempt >= attempts or not core.is_retryable_url_error(exc):+ raise+ core.sleep_backoff(attempt, exc = exc)+ return None # pragma: no cover - the loop returns or raises+++def resolve(accelerator: str, token: Optional[str]) -> tuple[str, Optional[dict], Optional[str]]:+ """``(repo, release, asset)`` for this host along ``_release_ladder()``. Raises+ ``ReleaseLookupUnavailable`` when no lookup answered, so a caller can keep what is installed."""+ primary = _repo()+ driver = nvidia_driver_cuda_version() if accelerator == "cuda" else None+ prefer = torch_cuda_major()+ answered = False+ failures = []+ for repo, want in _release_ladder():+ try:+ release = _fetch_release(repo, want, token)+ except GitHubRateLimited:+ raise+ except Exception as exc: # noqa: BLE001 - network: try the next rung+ print(f"audio.cpp: {repo} release lookup failed ({exc})", file = sys.stderr, flush = True)+ failures.append(f"{repo}: {exc}")+ continue+ answered = True+ if not release:+ continue+ names = [a["name"] for a in release.get("assets") or []]+ chosen = resolve_release_asset(+ names,+ system = platform.system(),+ machine = platform.machine(),+ accelerator = accelerator,+ driver_cuda = driver,+ prefer_cuda_major = prefer,+ )+ if chosen:+ if repo != primary:+ print(f"audio.cpp: falling back to {repo}", file = sys.stderr, flush = True)+ return repo, release, chosen+ if not answered:+ raise ReleaseLookupUnavailable(+ "no audio.cpp release lookup answered (" + "; ".join(failures) + ")"+ )+ return primary, None, None+++def resolve_for_request(+ requested: str, detected: Optional[str], token: Optional[str]+) -> tuple[str, str, Optional[dict], Optional[str]]:+ """``(accelerator, repo, release, asset)``. An auto-detected GPU the published bundles do not+ cover (an older driver, Linux arm64) falls back to the CPU build, which still runs every model;+ an explicit request is never downgraded."""+ accel = detected if requested == "auto" and detected else requested+ repo, release, chosen = resolve(accel, token)+ if requested == "auto" and accel == "cuda" and chosen:+ major = _cuda_major(chosen)+ if not _linux_cuda_runtime_available(major):+ # The Linux CUDA bundles load cudart / cuBLAS from torch's nvidia-* wheels, as the+ # llama.cpp ones do; a Studio without torch (or with another CUDA line) runs the CPU build.+ print(+ f"audio.cpp: no CUDA {major} runtime (cudart, cuBLAS) for {chosen}; installing the CPU build",+ flush = True,+ )+ accel = "cpu"+ repo, release, chosen = resolve(accel, token)+ if (release is None or not chosen) and requested == "auto" and accel != "cpu":+ print(f"audio.cpp: no {accel} bundle for this host; installing the CPU build", flush = True)+ accel = "cpu"+ repo, release, chosen = resolve(accel, token)+ return accel, repo, release, chosen+++def write_pins(path: Optional[Path] = None, token: Optional[str] = None) -> Path:+ """Regenerate the digest pins from GitHub for the default fork tag and its upstream fallback.+ Only runtime archives are pinned: host bundles (``-bin-``) and Windows CUDA runtimes (``-cudart-``)."""+ releases: dict = {}+ for repo, tag in ((DEFAULT_REPO, DEFAULT_TAG), (UPSTREAM_FALLBACK_REPO, UPSTREAM_FALLBACK_TAG)):+ release = _fetch_release(repo, tag, token)+ if not release:+ raise RuntimeError(f"{repo} has no release {tag}")+ digests = {}+ for asset in release.get("assets") or []:+ name = asset.get("name") or ""+ if "-bin-" not in name and "-cudart-" not in name:+ continue+ digest = core.normalize_sha256_digest(asset.get("digest"))+ if not digest:+ raise RuntimeError(f"{repo} {tag} publishes no sha256 digest for {name}")+ digests[name] = digest+ if not digests:+ raise RuntimeError(f"{repo} {tag} has no audio.cpp runtime assets")+ releases.setdefault(repo, {})[tag] = dict(sorted(digests.items()))+ payload = {+ "schema_version": 1,+ "comment": (+ "Trust anchor for install_audio_cpp_prebuilt.py: sha256 of each audio.cpp runtime archive, "+ "copied from the GitHub release asset digests. Generated; do not edit by hand. To bump: change "+ "DEFAULT_TAG / UPSTREAM_FALLBACK_TAG, then run `python studio/install_audio_cpp_prebuilt.py "+ "--write-pins` (the same digests `gh release view <tag> -R <repo> --json assets` lists)."+ ),+ "releases": releases,+ }+ target = path or PINS_PATH+ target.write_text(json.dumps(payload, indent = 2) + "\n", encoding = "utf-8", newline = "\n")+ return target+++def _download(url: str, dest: Path) -> None:+ """Retried, progress-reporting download (prebuilt_core's), written atomically to ``dest``."""+ core.download_file(_OPS, url, dest)+++def _verify(path: Path, expected_sha256: Optional[str]) -> str:+ """sha256 of ``path``; raises when an expected digest is known and differs."""+ got = core.sha256_file(path)+ if expected_sha256:+ if expected_sha256.lower() != got:+ raise RuntimeError(+ f"sha256 mismatch for {path.name}: expected {expected_sha256.lower()}, got {got}"+ )+ else:+ print(f"audio.cpp: WARNING no published digest for {path.name}", flush = True)+ return got+++def _extract(archive: Path, target: Path) -> None:+ if archive.name.endswith(".zip"):+ with zipfile.ZipFile(archive) as zf:+ _safe_extractall(zf, target)+ return+ with tarfile.open(archive, "r:gz") as tf:+ if hasattr(tarfile, "data_filter"):+ # Refuses absolute paths, parent traversal, device files and links leaving the tree.+ tf.extractall(target, filter = "data")+ return+ # Pythons without extraction filters: the same containment rules, checked by hand.+ base = target.resolve()+ for member in tf.getmembers():+ dest = (base / member.name).resolve()+ if dest != base and base not in dest.parents:+ raise RuntimeError(f"unsafe path in archive: {member.name!r}")+ if member.isdev() or member.isfifo():+ raise RuntimeError(f"special file in archive: {member.name!r}")+ if member.issym() or member.islnk():+ link = (+ (dest.parent / member.linkname).resolve()+ if member.issym()+ else (base / member.linkname).resolve()+ )+ if link != base and base not in link.parents:+ raise RuntimeError(f"unsafe link in archive: {member.name!r}")+ tf.extractall(target)+++def _locate_server(root: Path) -> Optional[Path]:+ for p in sorted(root.rglob(SERVER_NAME), key = lambda p: len(p.parts)):+ if p.is_file():+ return p+ return None+++def read_install_record(root: Path) -> dict:+ try:+ with open(root / INSTALL_RECORD, "r", encoding = "utf-8") as f:+ rec = json.load(f)+ return rec if isinstance(rec, dict) else {}+ except (OSError, ValueError):+ return {}+++def _backend_of(asset: str) -> str:+ # The Intel macOS bundle keeps the "-metal" name but is built with Metal off (Intel runners+ # have no usable GPU), so it can only run on the CPU backend.+ if "-macos-x64-" in asset:+ return "cpu"+ if "-metal" in asset:+ return "metal"+ if "-cuda" in asset:+ return "cuda"+ if "-vulkan" in asset:+ return "vulkan"+ return "cpu"+++# What earlier Studio builds left in the managed dir without an ownership marker: the server's+# scratch home. A tree holding nothing else is Studio's, not the user's.+_STUDIO_LEFTOVERS = frozenset({".child_home"})+++def _sweep_retired_trees(target: Path) -> None:+ """Remove ``<target>.old-*`` trees an earlier swap could not delete (Windows keeps a running+ server's files open). Best-effort: one still in use stays for the next run."""+ for old in target.parent.glob(target.name + ".old-*"):+ if old.is_dir() and (old / OWNERSHIP_MARKER).is_file():+ shutil.rmtree(old, ignore_errors = True)+ # Staging dirs of a killed run; the install lock is held, so none belongs to a live one.+ for staging in target.parent.glob(".audio.cpp-staging-*"):+ if staging.is_dir() and not staging.is_symlink():+ shutil.rmtree(staging, ignore_errors = True)+++def _server_in_use(server: Optional[Path]) -> bool:+ """Whether a running audiocpp_server holds this binary. Windows maps a running image+ without write sharing, so opening it for writing fails; elsewhere a replace is safe anyway."""+ if server is None or sys.platform != "win32":+ return False+ try:+ with open(server, "r+b"):+ return False+ except PermissionError:+ return True+ except OSError:+ return False+++def _cuda_runtime_satisfied(record: dict) -> bool:+ """A CUDA install that skipped its cudart archive still has torch's runtime to lean on."""+ if (+ record.get("backend") != "cuda"+ or record.get("cudart_asset")+ or record.get("os") != "windows"+ ):+ return True+ match = _CUDA_LINE.search(str(record.get("asset") or ""))+ return bool(match) and torch_provides_cuda_runtime(int(match.group(1)))+++def _intact_install(target: Path, record: dict) -> Optional[Path]:+ """The server of a complete, unaltered Studio install of ``record``, or None."""+ if not record or not (target / OWNERSHIP_MARKER).is_file():+ return None+ rel = record.get("server_relpath")+ want = core.normalize_sha256_digest(record.get("server_sha256"))+ if not isinstance(rel, str) or not rel or not want:+ return None+ server = target / rel+ try:+ if not server.is_file() or core.sha256_file(server) != want:+ return None+ except OSError:+ return None+ # Removed or quarantined phonemizer data: reinstall rather than keep a bundle Kokoro cannot use.+ if record.get("espeak") is True and not (server.parent / "espeak-ng-data.bin").is_file():+ return None+ # A Windows CUDA install that leaned on torch's runtime is broken once torch moves lines.+ return server if _cuda_runtime_satisfied(record) else None+++def _pinned_install_matches(+ target: Path, record: dict, requested: str, detected: Optional[str]+) -> Optional[Path]:+ """Answer "already matches" with no network call: the record names a (repo, tag) this run would+ look up, its archive digest is the pinned one, it was installed for the same accelerator request+ (and, for auto, the same detected host), and the server on disk is the one it installed."""+ ladder = _release_ladder()+ if not record or any(tag is None for _, tag in ladder):+ return None+ repo, tag = record.get("published_repo"), record.get("release_tag")+ # Only the first rung: a fallback install (the fork lookup failed that run) must ask again.+ if (repo, tag) != ladder[0]:+ return None+ pin = pinned_sha256(repo, tag, str(record.get("asset") or ""))+ if pin is None and not _user_picked_release():+ return None+ if pin is not None and pin != record.get("asset_sha256"):+ return None+ if record.get("accelerator_request") != requested:+ return None+ if requested == "auto" and record.get("detected_accelerator") != detected:+ return None+ if (+ requested == "auto"+ and detected == "cuda"+ and record.get("accelerator") == "cpu"+ and _linux_cuda_runtime_available(torch_cuda_major())+ ):+ # Installed as the CPU fallback; torch's CUDA runtime is here now, so look up the GPU build.+ return None+ return _intact_install(target, record)+++_WINDOWS_LOADER_FAILURES = {+ 0xC0000135: "a DLL it needs was not found",+ 0xC000007B: "a DLL it loads is built for another architecture",+ 0xC0000139: "a DLL it loads lacks an entry point it needs",+}+++def _scrubbed_environ() -> dict:+ """``os.environ`` without secrets, through the backend's ``child_env.scrub_env`` so the staged+ server sees what Studio will later launch it with."""+ import importlib.util++ path = Path(__file__).resolve().parent / "backend" / "utils" / "prebuilt" / "child_env.py"+ try:+ spec = importlib.util.spec_from_file_location("_unsloth_audio_cpp_child_env", path)+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module.scrub_env(os.environ)+ except Exception: # noqa: BLE001 - a partial checkout: drop the obvious secret names+ markers = ("TOKEN", "SECRET", "PASSWORD", "CREDENTIAL", "API_KEY", "PROXY")+ return {k: v for k, v in os.environ.items() if not any(m in k.upper() for m in markers)}+++def _loader_env(server: Path, extra_dirs: Sequence[Path] = ()) -> dict:+ """The environment with the server's own directory first on the loader path, as the backend's+ ``child_env`` launches it."""+ env = _scrubbed_environ()+ if sys.platform == "win32":+ var = "PATH"+ elif sys.platform == "darwin":+ var = "DYLD_LIBRARY_PATH"+ else:+ var = "LD_LIBRARY_PATH"+ existing = [p for p in env.get(var, "").split(os.pathsep) if p]+ env[var] = os.pathsep.join([str(server.parent), *(str(d) for d in extra_dirs), *existing])+ return env+++def _cuda_runtime_dirs(backend: str) -> list[str]:+ """The CUDA libraries the backend's ``child_env`` puts after the bundle dir: the Linux CUDA server+ links cuBLAS, cudart, cuFFT and NCCL dynamically and finds them in torch's nvidia-* wheels, and a+ Windows bundle installed without its cudart archive uses torch's DLLs."""+ if backend != "cuda" or sys.platform == "darwin":+ return []+ try:+ if __package__:+ from .install_llama_prebuilt import python_runtime_dirs+ else:+ from install_llama_prebuilt import python_runtime_dirs # type: ignore[no-redef]++ return list(python_runtime_dirs())+ except Exception: # noqa: BLE001 - no wheel runtime to offer+ return []+++def _cuda_major(asset: str) -> Optional[int]:+ match = _CUDA_LINE.search(asset)+ return int(match.group(1)) if match else None+++def _ldconfig_libs() -> set[str]:+ try:+ out = subprocess.run(["ldconfig", "-p"], capture_output = True, text = True, timeout = 10).stdout+ except Exception: # noqa: BLE001 - no ldconfig: only the wheel dirs count+ return set()+ return {line.split()[0] for line in out.splitlines()[1:] if line.strip()}+++def _linux_cuda_runtime_available(major: Optional[int]) -> bool:+ """Whether the CUDA libraries a line-``major`` Linux bundle links but does not ship (cudart,+ cuBLAS, cuFFT) are in torch's nvidia-* wheels or on the system loader path. True off Linux,+ where the bundle (or its cudart archive) carries them."""+ if not sys.platform.startswith("linux"):+ return True+ if major is None:+ return False+ dirs = [Path(d) for d in _cuda_runtime_dirs("cuda")]+ system = _ldconfig_libs()++ def present(pattern: str) -> bool:+ if any(any(d.glob(pattern)) for d in dirs):+ return True+ return any(fnmatch.fnmatch(name, pattern) for name in system)++ return all(+ present(pattern)+ for pattern in (f"libcudart.so.{major}", f"libcublas.so.{major}", "libcufft.so.*")+ )+++def _run_staged(server: Path, arg: str, env: dict, timeout: float) -> subprocess.CompletedProcess:+ return subprocess.run(+ [str(server), arg],+ capture_output = True,+ text = True,+ encoding = "utf-8",+ errors = "replace",+ timeout = timeout,+ env = env,+ cwd = str(server.parent),+ **core.windows_hidden_subprocess_kwargs(),+ )+++def smoke_test_staged_server(+ server: Path,+ *,+ backend: str,+ extra_dirs: Sequence[Path] = (),+) -> Optional[str]:+ """Start the staged server once with ``--help``: a bundle this host cannot load (a newer glibc, a+ missing DLL) raises here, before it replaces a working tree. Returns its ``--version`` text+ (build and enabled backends) when it prints one."""+ env = _loader_env(server, extra_dirs)+ try:+ result = _run_staged(server, "--help", env, SMOKE_TIMEOUT_SECONDS)+ except subprocess.TimeoutExpired as exc:+ raise RuntimeError(+ f"staged {SERVER_NAME} --help did not exit within {SMOKE_TIMEOUT_SECONDS:.0f}s; keeping the existing install"+ ) from exc+ except OSError as exc:+ raise RuntimeError(+ f"staged {SERVER_NAME} could not be started ({exc}); keeping the existing install"+ ) from exc+ if result.returncode != 0:+ output = "\n".join(s.strip() for s in (result.stderr, result.stdout) if s and s.strip())+ if backend == "cuda" and "libcuda.so" in output and nvidia_driver_cuda_version() is None:+ # No NVIDIA driver on this host (a Docker image build): libcuda arrives with the driver at run time.+ print(+ "audio.cpp: no NVIDIA driver here to load the CUDA build; skipping its start check",+ flush = True,+ )+ return None+ hint = (+ _WINDOWS_LOADER_FAILURES.get(result.returncode & 0xFFFFFFFF)+ if sys.platform == "win32"+ else None+ )+ detail = "\n".join(output.splitlines()[-20:]) or hint or "no output"+ raise RuntimeError(+ f"staged {SERVER_NAME} --help exited {result.returncode}; this host cannot run the bundle, "+ f"keeping the existing install:\n{detail}"+ )+ try:+ version = _run_staged(server, "--version", env, 10.0)+ except (OSError, subprocess.SubprocessError):+ return None+ text = (version.stdout or "").strip()+ return text[:2000] if version.returncode == 0 and text else None+++def install(+ *,+ install_dir: Optional[Path] = None,+ accelerator: str = "auto",+ token: Optional[str] = None,+ force: bool = False,+) -> Path:+ """Install (or keep) the bundle for ``accelerator``; ``"auto"`` detects the host here, so the+ CPU fallback for an uncovered GPU applies. Serialised on prebuilt_core's install lock."""+ if accelerator not in ACCELERATORS:+ raise RuntimeError(+ f"unknown accelerator {accelerator!r}; expected one of {', '.join(ACCELERATORS)}"+ )+ target = (install_dir or default_install_dir()).resolve()+ if target.exists() and not target.is_dir():+ raise RuntimeError(f"audio.cpp install target is not a directory: {target}")+ if target.exists() and not (target / OWNERSHIP_MARKER).is_file():+ entries = {p.name for p in target.iterdir()}+ if entries - _STUDIO_LEFTOVERS:+ raise RuntimeError(+ f"{target} already exists and is not an Unsloth-managed directory; refusing to replace it. "+ "Move it away or pass a different --install-dir."+ )+ with core.install_lock(core.install_lock_path(target)):+ return _install_locked(target, accelerator, token, force)+++def _install_locked(target: Path, requested: str, token: Optional[str], force: bool) -> Path:+ _sweep_retired_trees(target)+ detected = detect_accelerator() if requested == "auto" else None+ existing = read_install_record(target)+ if not force:+ server = _pinned_install_matches(target, existing, requested, detected)+ if server is not None:+ print(f"audio.cpp: already matches {existing.get('asset')}", flush = True)+ return server+ old_glibc = _glibc_below_pinned_floor()+ if old_glibc:+ raise RuntimeError(+ f"audio.cpp prebuilt bundles need glibc {'.'.join(map(str, _PINNED_LINUX_GLIBC_FLOOR))}+; "+ f"this host has {old_glibc}. Set UNSLOTH_AUDIO_CPP_PATH to a local build instead."+ )+ token = token or os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")+ try:+ accel, repo, release, chosen = resolve_for_request(requested, detected, token)+ except (ReleaseLookupUnavailable, GitHubRateLimited) as exc:+ # The lookup could not answer, which says nothing about the tree on disk. Keep a complete one+ # unless this run asked for something it is not (--force, another explicit accelerator).+ kept = None if force else _intact_install(target, existing)+ if kept is None or (requested != "auto" and existing.get("accelerator") != requested):+ raise+ # "keeping the existing complete install" is the substring setup.sh and setup.ps1 grep for.+ print(KEPT_EXISTING_LINE, flush = True)+ print(+ f"audio.cpp: {existing.get('release_tag')} stays; release lookup unavailable ({exc})",+ file = sys.stderr,+ flush = True,+ )+ return kept+ if release is None or not chosen:+ raise RuntimeError(+ f"No prebuilt audiocpp_server for {platform.system()}/{platform.machine()} "+ f"(accelerator={accel}) from {repo}. Build it from source: https://github.com/{repo}"+ )+ assets = {a["name"]: a for a in release.get("assets") or []}+ asset = assets[chosen]+ tag = release.get("tag_name")+ expected = _expected_sha256(repo, tag, asset)+ if (+ not force+ and expected+ and existing.get("asset") == chosen+ and existing.get("asset_sha256") == expected+ and _intact_install(target, existing) is not None+ ):+ print(f"audio.cpp: already matches {chosen}", flush = True)+ return _intact_install(target, existing)++ cudart = cudart_asset_for(list(assets), chosen)+ cuda_match = _CUDA_LINE.search(chosen)+ cuda_major = int(cuda_match.group(1)) if cuda_match else None+ torch_runtime = bool(cudart and cuda_major and torch_provides_cuda_runtime(cuda_major))+ cudart_expected = (+ _expected_sha256(repo, tag, assets[cudart]) if cudart and not torch_runtime else None+ )++ if target.exists() and _server_in_use(_locate_server(target)):+ # Checked again before the swap; here it saves the download.+ raise PermissionError(f"audiocpp_server in {target} is running")+ target.parent.mkdir(parents = True, exist_ok = True)+ staging = Path(tempfile.mkdtemp(prefix = ".audio.cpp-staging-", dir = str(target.parent)))+ try:+ archive = staging / chosen+ print(f"audio.cpp: downloading {chosen} from {repo} {tag}", flush = True)+ _download(asset["browser_download_url"], archive)+ digest = _verify(archive, expected)+ tree = staging / "tree"+ tree.mkdir()+ _extract(archive, tree)+ archive.unlink()+ server = _locate_server(tree)+ if server is None:+ raise RuntimeError(f"{chosen} contains no {SERVER_NAME}")+ cudart_used = None+ if cudart and not torch_runtime:+ print(f"audio.cpp: downloading CUDA runtime {cudart}", flush = True)+ rt_archive = staging / cudart+ _download(assets[cudart]["browser_download_url"], rt_archive)+ _verify(rt_archive, cudart_expected)+ with zipfile.ZipFile(rt_archive) as zf:+ _safe_extractall(zf, server.parent)+ rt_archive.unlink()+ cudart_used = cudart+ if sys.platform != "win32":+ server.chmod(server.stat().st_mode | 0o111)+ backend = _backend_of(chosen)+ version = smoke_test_staged_server(+ server, backend = backend, extra_dirs = _cuda_runtime_dirs(backend)+ )+ (tree / OWNERSHIP_MARKER).touch()+ record = {+ "schema_version": 1,+ "component": "audio.cpp",+ "published_repo": repo,+ "release_tag": tag,+ "asset": chosen,+ "asset_sha256": digest,+ "cudart_asset": cudart_used,+ "backend": backend,+ # What was asked and seen, so a re-run knows without a lookup whether this still fits.+ "accelerator": accel,+ "accelerator_request": requested,+ "detected_accelerator": detected,+ # Static eSpeak-ng builds ship their phoneme data beside the server; upstream bundles do not.+ "espeak": (server.parent / "espeak-ng-data.bin").is_file(),+ "server_relpath": server.relative_to(tree).as_posix(),+ "server_sha256": core.sha256_file(server),+ "server_version": version,+ "os": platform.system().lower(),+ "arch": _ARCH_TOKENS.get(platform.machine().lower(), platform.machine().lower()),+ "installed_at_utc": datetime.datetime.now(datetime.timezone.utc).isoformat(),+ }+ (tree / INSTALL_RECORD).write_text(json.dumps(record, indent = 2), encoding = "utf-8")+ # A running server would keep its files after the swap and serve the old build; the+ # caller stops it (or reports busy) instead.+ if target.exists() and _server_in_use(_locate_server(target)):+ raise PermissionError(f"audiocpp_server in {target} is running")+ # Swap: the old tree moves aside first so a failed rename can put it back.+ retired = None+ if target.exists():+ retired = target.with_name(target.name + f".old-{os.getpid()}")+ os.replace(target, retired)+ try:+ os.replace(tree, target)+ except OSError:+ if retired is not None:+ os.replace(retired, target)+ raise+ if retired is not None:+ shutil.rmtree(retired, ignore_errors = True)+ finally:+ shutil.rmtree(staging, ignore_errors = True)+ installed = target / record["server_relpath"]+ print(f"audio.cpp: installed {installed}", flush = True)+ return installed+++def main(argv: Optional[list[str]] = None) -> int:+ p = argparse.ArgumentParser(description = "Install a prebuilt audiocpp_server (audio.cpp).")+ p.add_argument(+ "--accelerator",+ default = _accelerator_from_env(),+ # setup.sh / setup.ps1 forward UNSLOTH_AUDIO_CPP_ACCELERATOR verbatim ("CUDA", " cpu ").+ type = lambda value: value.strip().lower(),+ choices = list(ACCELERATORS),+ help = "default: UNSLOTH_AUDIO_CPP_ACCELERATOR, else auto (detect; CPU when no bundle covers the GPU)",+ )+ p.add_argument("--install-dir", default = None)+ p.add_argument("--force", action = "store_true", help = "reinstall even when the bundle matches")+ p.add_argument("--print-asset", action = "store_true", help = "resolve and print the asset only")+ p.add_argument(+ "--write-pins",+ action = "store_true",+ help = f"regenerate {PINS_PATH.name} from the pinned GitHub releases",+ )+ args = p.parse_args(argv)+ token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")+ try:+ if args.write_pins:+ print(f"audio.cpp: wrote {write_pins(token = token)}")+ return EXIT_OK+ if args.print_asset:+ detected = detect_accelerator() if args.accelerator == "auto" else None+ _, repo, release, chosen = resolve_for_request(args.accelerator, detected, token)+ print(f"{repo} {release.get('tag_name') if release else '-'} {chosen or '(none)'}")+ return EXIT_OK if chosen else EXIT_FAILED+ install(+ install_dir = Path(args.install_dir).expanduser() if args.install_dir else None,+ accelerator = args.accelerator,+ force = args.force,+ )+ except GitHubRateLimited as exc:+ print(f"error: {exc}", file = sys.stderr)+ return EXIT_FAILED+ except core.BusyInstallConflict as exc:+ # Another setup (the desktop app, a second shell) holds the install lock.+ print(f"error: another audio.cpp install is running ({exc})", file = sys.stderr)+ return EXIT_BUSY+ except PermissionError as exc:+ # Windows: a running audiocpp_server holds the tree open.+ print(+ f"error: the audio.cpp runtime is in use ({exc}); stop Studio and retry",+ file = sys.stderr,+ )+ return EXIT_BUSY+ except (RuntimeError, OSError) as exc:+ print(f"error: {exc}", file = sys.stderr)+ return EXIT_FAILED+ return EXIT_OK+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/studio/setup.ps1 b/studio/setup.ps1index fb6af63460d..a412c9c2fa4 100644--- a/studio/setup.ps1+++ b/studio/setup.ps1@@ -10092,6 +10092,67 @@ if ($env:WHISPER_SERVER_PATH -or $env:UNSLOTH_WHISPER_CPP_PATH) {}}+# ==========================================================================+# PHASE 3.4b: Install the audio.cpp prebuilt (speech, music and dictation runtime)+# ==========================================================================+# audio.cpp vendors its own patched ggml, so its bundles are self-contained and do not+# pair with the llama install. Failure is never fatal: every other audio engine keeps working.+$AudioCppDir = Join-Path $UnslothHome "audio.cpp"+$AudioCppInstaller = Join-Path $PSScriptRoot "install_audio_cpp_prebuilt.py"+if ($env:AUDIOCPP_SERVER_PATH -or $env:UNSLOTH_AUDIO_CPP_PATH) {+ substep "audio.cpp: using a user-configured binary/dir; skipping managed install"+} elseif ($env:UNSLOTH_SKIP_AUDIO_CPP_INSTALL -eq "1") {+ substep "audio.cpp: install skipped (UNSLOTH_SKIP_AUDIO_CPP_INSTALL=1)"+} elseif ($RuntimeRootIsCustom -and (Test-Path -LiteralPath $AudioCppInstaller) -and+ (Assert-StudioOwnedOrAbsent -Path $AudioCppDir -Label "audio.cpp install" -NonFatal -IsCustom $RuntimeRootIsCustom) -eq "Denied") {+ step "audio.cpp" "install directory cannot be read: access is denied; audio.cpp models are unavailable; restore access to $AudioCppDir or move it aside, then re-run setup" "Yellow"+} elseif (Test-Path -LiteralPath $AudioCppInstaller) {+ if ($RuntimeRootIsCustom) {+ Assert-StudioOwnedOrAbsent -Path $AudioCppDir -Label "audio.cpp install" -IsCustom $RuntimeRootIsCustom+ }+ $audioCppArgs = @($AudioCppInstaller, "--install-dir", $AudioCppDir)+ # A host whose GPU is invisible at install time names its bundle here.+ if ($env:UNSLOTH_AUDIO_CPP_ACCELERATOR) {+ $audioCppArgs += @("--accelerator", $env:UNSLOTH_AUDIO_CPP_ACCELERATOR)+ }+ $prevEAPAudioCpp = $ErrorActionPreference+ $ErrorActionPreference = "Continue"+ $previousNativeErrorPreferenceA = $null+ $restoreNativeErrorPreferenceA = $false+ if ($PSVersionTable.PSVersion.Major -ge 7) {+ $previousNativeErrorPreferenceA = $PSNativeCommandUseErrorActionPreference+ $PSNativeCommandUseErrorActionPreference = $false+ $restoreNativeErrorPreferenceA = $true+ }+ try {+ $audioCppOutput = & python @audioCppArgs 2>&1 | Show-DownloadProgress | Out-String+ $audioCppExit = $LASTEXITCODE+ } finally {+ if ($restoreNativeErrorPreferenceA) {+ $PSNativeCommandUseErrorActionPreference = $previousNativeErrorPreferenceA+ }+ }+ $ErrorActionPreference = $prevEAPAudioCpp+ if ($audioCppExit -eq 0) {+ if ($audioCppOutput -match "already matches") {+ step "audio.cpp" "prebuilt up to date"+ } elseif ($audioCppOutput -match "keeping the existing complete install") {+ # The release lookup could not answer and the install on disk is complete; "prebuilt+ # installed" would name a release nothing fetched. whisper.cpp's wording.+ step "audio.cpp" "update unavailable, existing prebuilt kept" "Yellow"+ } else {+ step "audio.cpp" "prebuilt installed"+ }+ if ($RuntimeRootIsCustom -and (Test-PathQuiet $AudioCppDir "Container")) {+ Mark-StudioOwned -Path $AudioCppDir+ }+ } elseif ($audioCppExit -eq 3) {+ step "audio.cpp" "install busy; keeping existing runtime" "Yellow"+ } else {+ step "audio.cpp" "prebuilt install failed; audio.cpp models are unavailable; retry setup or inspect verbose output; other audio engines remain available" "Yellow"+ }+}+if ($StageRoot -and $NeedLlamaSourceBuild) {Exit-SetupFailure "Background staging cannot install system build tools for llama.cpp; retry with the foreground updater."}diff --git a/studio/setup.sh b/studio/setup.shindex 32402279550..c1c8ef225d8 100755--- a/studio/setup.sh+++ b/studio/setup.sh@@ -5705,6 +5705,54 @@ PYfifi+# ── audio.cpp (speech, music and dictation engine) ──+# audio.cpp vendors its own patched ggml, so its bundles are self-contained and do not pair with+# the llama install. Fail-open like whisper.cpp: every other audio engine keeps working.+AUDIO_CPP_DIR="$UNSLOTH_HOME/audio.cpp"+if [ -n "${AUDIOCPP_SERVER_PATH:-}" ] || [ -n "${UNSLOTH_AUDIO_CPP_PATH:-}" ]; then+ verbose_substep "audio.cpp: using a user-configured binary/dir; skipping managed install"+elif [ "${UNSLOTH_SKIP_AUDIO_CPP_INSTALL:-0}" = "1" ]; then+ verbose_substep "audio.cpp: install skipped (UNSLOTH_SKIP_AUDIO_CPP_INSTALL=1)"+elif [ -f "$SCRIPT_DIR/install_audio_cpp_prebuilt.py" ]; then+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ]; then+ _assert_studio_owned_or_absent "$AUDIO_CPP_DIR" "audio.cpp install" "$_RUNTIME_ROOT_IS_CUSTOM"+ fi+ _AUDIO_CPP_CMD=(python "$SCRIPT_DIR/install_audio_cpp_prebuilt.py" --install-dir "$AUDIO_CPP_DIR")+ # A host whose GPU is invisible at install time (a Docker image build) names its bundle here.+ if [ -n "${UNSLOTH_AUDIO_CPP_ACCELERATOR:-}" ]; then+ _AUDIO_CPP_CMD+=(--accelerator "$UNSLOTH_AUDIO_CPP_ACCELERATOR")+ fi+ _AUDIO_CPP_LOG="$(mktemp)"+ set +e+ if _is_verbose || [ "${UNSLOTH_TAURI_UPDATE:-0}" = "1" ] || [ "${UNSLOTH_TAURI_UPDATE:-0}" = "true" ]; then+ "${_AUDIO_CPP_CMD[@]}" 2>&1 | tee "$_AUDIO_CPP_LOG" | _filter_download_output+ _AUDIO_CPP_STATUS=${PIPESTATUS[0]}+ else+ "${_AUDIO_CPP_CMD[@]}" >"$_AUDIO_CPP_LOG" 2>&1+ _AUDIO_CPP_STATUS=$?+ fi+ set -e+ if [ "$_AUDIO_CPP_STATUS" -eq 0 ]; then+ if grep -Fq "already matches" "$_AUDIO_CPP_LOG"; then+ step "audio.cpp" "prebuilt up to date"+ elif grep -Fq "keeping the existing complete install" "$_AUDIO_CPP_LOG"; then+ # The release lookup could not answer and the install on disk is complete; "prebuilt+ # installed" would name a release nothing fetched. whisper.cpp's wording.+ step "audio.cpp" "update unavailable, existing prebuilt kept" "$C_WARN"+ else+ step "audio.cpp" "prebuilt installed"+ fi+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ] && [ -d "$AUDIO_CPP_DIR" ]; then+ : > "$AUDIO_CPP_DIR/$_STUDIO_OWNED_MARKER" 2>/dev/null || true+ fi+ elif [ "$_AUDIO_CPP_STATUS" -eq 3 ]; then+ step "audio.cpp" "install busy; keeping existing runtime" "$C_WARN"+ else+ step "audio.cpp" "prebuilt install failed; audio.cpp models are unavailable; retry setup or inspect verbose output; other audio engines remain available" "$C_WARN"+ fi+ rm -f "$_AUDIO_CPP_LOG"+fi+# Named in the footer: every path to a lost GPU exits 0, and a mid-log line is what #9255's reporters scrolled past._print_llama_gpu_notes() {if [ -n "$_LLAMA_KEPT_GPU_PREBUILT" ]; thendiff --git a/studio/src-tauri/src/install.rs b/studio/src-tauri/src/install.rsindex bfa85139f9c..a776b3b306f 100644--- a/studio/src-tauri/src/install.rs+++ b/studio/src-tauri/src/install.rs@@ -2015,6 +2015,12 @@ mod tests {context.observe_stdout("whisper.cpp prebuilt install failed; browser and Transformers dictation remain available",);+ context.observe_stderr(+ "error: staged audiocpp_server --help exited 127; this host cannot run the bundle, keeping the existing install:",+ );+ context.observe_stdout(+ "audio.cpp prebuilt install failed; audio.cpp models are unavailable; retry setup or inspect verbose output; other audio engines remain available",+ );for index in 0..10 {context.observe_stdout(&format!("setup footer line {index}"));}@@ -2030,6 +2036,7 @@ mod tests {let mut context = InstallFailureContext::default();context.observe_stdout("long paths failed to enable");context.observe_stderr("Triton install failed; torch.compile may not work");+ context.observe_stdout("audio.cpp install busy; keeping existing runtime");assert!(context.observe_stdout("[TAURI:ERROR_DEFAULT] studio setup failed (exit code 3)"));assert_eq!(context.message(3),diff --git a/studio/src-tauri/src/process.rs b/studio/src-tauri/src/process.rsindex 32d4d594eb9..5f633dd8325 100644--- a/studio/src-tauri/src/process.rs+++ b/studio/src-tauri/src/process.rs@@ -1975,8 +1975,10 @@ pub(crate) const RELATIVE_PATH_ENV: &[&str] = &["UNSLOTH_LLAMA_CPP_SCRIPTS_DIR","UNSLOTH_SD_CPP_PATH","UNSLOTH_WHISPER_CPP_PATH",+ "UNSLOTH_AUDIO_CPP_PATH","LLAMA_SERVER_PATH","WHISPER_SERVER_PATH",+ "AUDIOCPP_SERVER_PATH","SD_CLI_PATH","SD_SERVER_PATH","LLAMA_ARG_MODEL",diff --git a/studio/src-tauri/src/staged_update.rs b/studio/src-tauri/src/staged_update.rsindex d2e2c0fe984..293ddc239ac 100644--- a/studio/src-tauri/src/staged_update.rs+++ b/studio/src-tauri/src/staged_update.rs@@ -25,7 +25,7 @@ const RUNTIME_ENTRIES: [&str; 4] = [".venv_t5_550",".venv_t5_510",];-const HELPER_RUNTIME_ENTRIES: [&str; 3] = ["node", "llama.cpp", "whisper.cpp"];+const HELPER_RUNTIME_ENTRIES: [&str; 4] = ["node", "llama.cpp", "whisper.cpp", "audio.cpp"];fn all_runtime_entries() -> impl Iterator<Item = &'static str> {RUNTIME_ENTRIES.into_iter().chain(HELPER_RUNTIME_ENTRIES)diff --git a/tests/python/test_docker_hub_readme.py b/tests/python/test_docker_hub_readme.pyindex 949d8174656..eadee589eb9 100644--- a/tests/python/test_docker_hub_readme.py+++ b/tests/python/test_docker_hub_readme.py@@ -271,6 +271,11 @@ def test_the_hub_readme_matches_what_each_image_ships():text = HUB_README.read_text(encoding = "utf-8")# whisper.cpp comes from Studio's setup, so only that image has itassert "The `latest` image adds whisper.cpp" in text+ # audio.cpp too, and the CUDA bundle only where Dockerfile.studio names it (no GPU at build time)+ assert "audio.cpp (CUDA build on `linux/amd64`)" in text+ studio_df = (HUB_README.parent / "Dockerfile.studio").read_text(encoding = "utf-8")+ assert 'amd64) TORCH_FAMILY="cu128"; AUDIO_CPP_ACCELERATOR="cuda"' in studio_df+ assert 'UNSLOTH_AUDIO_CPP_ACCELERATOR="${AUDIO_CPP_ACCELERATOR}"' in studio_df# SYNC disables the notebooks entirely; REFRESH only skips the GitHub fetchassert "`UNSLOTH_SKIP_NOTEBOOK_REFRESH=1` | Do not refresh the notebooks from GitHub" in textassert "`UNSLOTH_SKIP_NOTEBOOK_SYNC=1` | Do not set up the notebooks at all" in textdiff --git a/tests/sh/test_setup_staged_root.sh b/tests/sh/test_setup_staged_root.shindex 3a89216a109..8f7e475a191 100755--- a/tests/sh/test_setup_staged_root.sh+++ b/tests/sh/test_setup_staged_root.sh@@ -82,6 +82,13 @@ check "setup.sh forwards the staged helper root to whisper.cpp source builds" \"$(has "$SETUP_SH" 'env UNSLOTH_HOME="$UNSLOTH_HOME" sh "$_WHISPER_BUILD"')"check "whisper.cpp source builds honor the managed helper root" \"$(has "$SCRIPT_DIR/../../scripts/build_whisper_cpp.sh" '${UNSLOTH_HOME:-}')"+# audio.cpp installs under the same helper root, so a staged run writes it into the stage.+check "setup.sh stages audio.cpp with llama.cpp and whisper.cpp" \+ "$(has "$SETUP_SH" 'AUDIO_CPP_DIR="$UNSLOTH_HOME/audio.cpp"')"+check "setup.sh hands the audio.cpp installer that directory" \+ "$(has "$SETUP_SH" 'install_audio_cpp_prebuilt.py" --install-dir "$AUDIO_CPP_DIR"')"+check "setup.ps1 stages audio.cpp beside the staged llama.cpp" \+ "$(grep -qF '$UnslothHome = Split-Path -Parent $LlamaCppDir' "$SETUP_PS1" && grep -qF '$AudioCppDir = Join-Path $UnslothHome "audio.cpp"' "$SETUP_PS1" && grep -qF '@($AudioCppInstaller, "--install-dir", $AudioCppDir)' "$SETUP_PS1" && echo 0 || echo 1)"check "setup.sh does not install global uv while staging" \"$(has "$SETUP_SH" 'step "uv" "using pip inside the staged environment"')"check "setup.ps1 stages the managed Node runtime" \diff --git a/tests/sh/test_uninstall_master_root.sh b/tests/sh/test_uninstall_master_root.shindex e642818f4fb..441c837ca1d 100755--- a/tests/sh/test_uninstall_master_root.sh+++ b/tests/sh/test_uninstall_master_root.sh@@ -58,16 +58,21 @@ run_block() {echo "== an owned master root loses its runtime children =="MR="$_TMP_ROOT/portable"-mkdir -p "$MR"/{studio,llama.cpp,node,whisper.cpp}-for d in llama.cpp node whisper.cpp; do : > "$MR/$d/.unsloth-studio-owned"; done+mkdir -p "$MR"/{studio,llama.cpp,node,whisper.cpp,audio.cpp}+for d in llama.cpp node whisper.cpp audio.cpp; do : > "$MR/$d/.unsloth-studio-owned"; done: > "$MR/.llama.cpp.install.lock": > "$MR/.node.install.lock"+: > "$MR/.audio.cpp.install.lock"+: > "$MR/.audio.cpp.install.lock.stale.31337"run_block "$HOME" "$MR"assert_nodir "llama.cpp removed" "$MR/llama.cpp"assert_nodir "node removed" "$MR/node"assert_nodir "whisper.cpp removed" "$MR/whisper.cpp"+assert_nodir "audio.cpp removed" "$MR/audio.cpp"assert_nodir "llama lock removed" "$MR/.llama.cpp.install.lock"assert_nodir "node lock removed" "$MR/.node.install.lock"+assert_nodir "audio.cpp lock removed" "$MR/.audio.cpp.install.lock"+assert_nodir "stale audio.cpp lock removed" "$MR/.audio.cpp.install.lock.stale.31337"assert_dir "studio root left to the Studio removal" "$MR/studio"echo "== only a FILE is removed from an install-lock path =="@@ -94,12 +99,15 @@ assert_dir "and so is everything under it" "$MRL/.node.install.lock/keeecho "== an unmarked tree is somebody else's and is kept =="MR2="$_TMP_ROOT/mixed"-mkdir -p "$MR2"/{llama.cpp,node}+mkdir -p "$MR2"/{llama.cpp,node,audio.cpp}: > "$MR2/node/.unsloth-studio-owned": > "$MR2/llama.cpp/my-own-build"+# A clone of the audio.cpp repo is named exactly this.+: > "$MR2/audio.cpp/CMakeLists.txt"run_block "$HOME" "$MR2"assert_dir "unmarked llama.cpp kept" "$MR2/llama.cpp"assert_dir "its contents kept" "$MR2/llama.cpp/my-own-build"+assert_dir "unmarked audio.cpp kept" "$MR2/audio.cpp/CMakeLists.txt"assert_nodir "marked node removed" "$MR2/node"echo "== an emptied master root is pruned, a used one is not =="diff --git a/tests/sh/test_uninstall_prebuilt_artifacts.sh b/tests/sh/test_uninstall_prebuilt_artifacts.shindex b6cca4c4b99..89e23edc45f 100644--- a/tests/sh/test_uninstall_prebuilt_artifacts.sh+++ b/tests/sh/test_uninstall_prebuilt_artifacts.sh@@ -5,7 +5,7 @@# then prune ~/.unsloth itself.## Each prebuilt serializes on <parent>/.<name>.install.lock (prebuilt_core.py-# install_lock_path), so llama.cpp, node and whisper.cpp each leave one behind.+# install_lock_path), so llama.cpp, node, whisper.cpp and audio.cpp each leave one behind.# A stray lock is a zero-byte file that looks harmless, but the final# `rmdir "$HOME/.unsloth"` refuses a non-empty directory, so one missed lock# keeps the whole tree on disk. whisper.cpp only installs when a prebuilt@@ -37,6 +37,12 @@ trap 'rm -rf "$_TMP_ROOT"' EXIT# Isolate every environment-controlled removal path.unset UNSLOTH_STUDIO_HOME STUDIO_HOME UNSLOTH_UNINSTALL_ROCM+# audio.cpp's link farm sits beside the HF hub cache these name; the default is under HOME.+unset HF_HUB_CACHE HUGGINGFACE_HUB_CACHE HF_HOME XDG_CACHE_HOME+# ...and its fallback scratch home under the temp dir, one per uid.+TMPDIR="$_TMP_ROOT/tmp"+export TMPDIR+mkdir -p "$TMPDIR"XDG_RUNTIME_DIR="$_TMP_ROOT/run"export XDG_RUNTIME_DIRmkdir -p "$XDG_RUNTIME_DIR"@@ -66,6 +72,11 @@ make_home() {"$FIXTURE_HOME/.unsloth/llama.cpp/build/bin" \"$FIXTURE_HOME/.unsloth/node/bin" \"$FIXTURE_HOME/.unsloth/whisper.cpp/build/bin" \+ "$FIXTURE_HOME/.unsloth/audio.cpp" \+ "$FIXTURE_HOME/.cache/huggingface/hub/models--audio-cpp--audio.cpp-gguf" \+ "$FIXTURE_HOME/.cache/huggingface/unsloth-audiocpp-links/kokoro" \+ "$TMPDIR/unsloth-audiocpp-home-$(id -u)/.config" \+ "$TMPDIR/unsloth-audiocpp-home-not-this-user" \"$FIXTURE_HOME/.unsloth/.cache" \"$FIXTURE_HOME/.unsloth/.staging" \"$FIXTURE_HOME/.local/share/unsloth" \@@ -75,9 +86,15 @@ make_home() {: > "$FIXTURE_HOME/.unsloth/llama.cpp/build/bin/llama-server": > "$FIXTURE_HOME/.unsloth/node/bin/node": > "$FIXTURE_HOME/.unsloth/whisper.cpp/build/bin/whisper-server"+ : > "$FIXTURE_HOME/.unsloth/audio.cpp/audiocpp_server"+ : > "$FIXTURE_HOME/.unsloth/audio.cpp/.unsloth-studio-owned"+ : > "$FIXTURE_HOME/.cache/huggingface/hub/models--audio-cpp--audio.cpp-gguf/model.gguf"+ : > "$FIXTURE_HOME/.cache/huggingface/unsloth-audiocpp-links/kokoro/model.gguf": > "$FIXTURE_HOME/.unsloth/.llama.cpp.install.lock": > "$FIXTURE_HOME/.unsloth/.node.install.lock": > "$FIXTURE_HOME/.unsloth/.whisper.cpp.install.lock"+ : > "$FIXTURE_HOME/.unsloth/.audio.cpp.install.lock"+ : > "$FIXTURE_HOME/.unsloth/.audio.cpp.install.lock.stale.4242"# Taking over an abandoned lock renames it rather than deleting it# (install_node_prebuilt.py), so these accumulate across interrupted runs.: > "$FIXTURE_HOME/.unsloth/.node.install.lock.stale.12345"@@ -96,11 +113,18 @@ assert_gone "studio install dir" "$FIXTURE_HOME/.unsloth/studio"assert_gone "llama.cpp prebuilt" "$FIXTURE_HOME/.unsloth/llama.cpp"assert_gone "node runtime" "$FIXTURE_HOME/.unsloth/node"assert_gone "whisper.cpp prebuilt" "$FIXTURE_HOME/.unsloth/whisper.cpp"-assert_gone "prebuilt cache" "$FIXTURE_HOME/.unsloth/.cache"+assert_gone "audio.cpp prebuilt" "$FIXTURE_HOME/.unsloth/audio.cpp"+assert_gone "prebuilt cache" "$FIXTURE_HOME/.unsloth/.cache"assert_gone "staging dir" "$FIXTURE_HOME/.unsloth/.staging"assert_gone "llama.cpp install lock" "$FIXTURE_HOME/.unsloth/.llama.cpp.install.lock"assert_gone "node install lock" "$FIXTURE_HOME/.unsloth/.node.install.lock"assert_gone "whisper.cpp install lock" "$FIXTURE_HOME/.unsloth/.whisper.cpp.install.lock"+assert_gone "audio.cpp install lock" "$FIXTURE_HOME/.unsloth/.audio.cpp.install.lock"+assert_gone "stale audio.cpp lock" "$FIXTURE_HOME/.unsloth/.audio.cpp.install.lock.stale.4242"+assert_gone "audio.cpp model link farm" "$FIXTURE_HOME/.cache/huggingface/unsloth-audiocpp-links"+assert_kept "the HF cache itself stays" "$FIXTURE_HOME/.cache/huggingface/hub/models--audio-cpp--audio.cpp-gguf/model.gguf"+assert_gone "audio.cpp scratch home" "$TMPDIR/unsloth-audiocpp-home-$(id -u)"+assert_kept "another user's is kept" "$TMPDIR/unsloth-audiocpp-home-not-this-user"assert_gone "stale node lock" "$FIXTURE_HOME/.unsloth/.node.install.lock.stale.12345"assert_gone "stale llama.cpp lock" "$FIXTURE_HOME/.unsloth/.llama.cpp.install.lock.stale.6789"assert_gone "~/.unsloth is pruned" "$FIXTURE_HOME/.unsloth"@@ -123,6 +147,16 @@ assert_kept "~/.unsloth kept for user content" "$FIXTURE_HOME/.unsloth"assert_gone "artifacts still cleared" "$FIXTURE_HOME/.unsloth/whisper.cpp"assert_gone "locks still cleared" "$FIXTURE_HOME/.unsloth/.node.install.lock"+echo "=== an unmarked ~/.unsloth/audio.cpp is the user's own build ==="++make_home+rm -f "$FIXTURE_HOME/.unsloth/audio.cpp/.unsloth-studio-owned"+HOME="$FIXTURE_HOME" sh "$UNINSTALL_SH" > "$_TMP_ROOT/out4.log" 2>&1 || {+ echo " FAIL: uninstall exited $?"; FAIL=$((FAIL + 1)); cat "$_TMP_ROOT/out4.log"; }++assert_kept "an unmarked audio.cpp build survives" "$FIXTURE_HOME/.unsloth/audio.cpp/audiocpp_server"+assert_gone "marked siblings still go" "$FIXTURE_HOME/.unsloth/whisper.cpp"+echo "=== a missing ~/.unsloth is a clean no-op ==="FIXTURE_HOME=$(mktemp -d "$_TMP_ROOT/empty.XXXXXX")diff --git a/tests/studio/install/test_install_audio_cpp_prebuilt_logic.py b/tests/studio/install/test_install_audio_cpp_prebuilt_logic.pynew file mode 100644index 00000000000..da1661f413a--- /dev/null+++ b/tests/studio/install/test_install_audio_cpp_prebuilt_logic.py@@ -0,0 +1,1151 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Logic tests for studio/install_audio_cpp_prebuilt.py -- the self-contained audiocpp_server installer.+# No network/GPU: asset lists are the real upstream v0.8.2 release names, archives are built in a tmp dir.++import importlib.util+import json+import sys+import zipfile+from pathlib import Path++import pytest++PACKAGE_ROOT = Path(__file__).resolve().parents[3]+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_audio_cpp_prebuilt.py"+_STUDIO_DIR = str(MODULE_PATH.parent)+if _STUDIO_DIR not in sys.path:+ sys.path.insert(0, _STUDIO_DIR)+SPEC = importlib.util.spec_from_file_location("studio_install_audio_cpp_prebuilt", MODULE_PATH)+assert SPEC is not None and SPEC.loader is not None+M = importlib.util.module_from_spec(SPEC)+sys.modules[SPEC.name] = M+SPEC.loader.exec_module(M)++TAG = "v0.8.2-audio8-perf-hotfix"+ASSETS = [+ "asr_validation.tar.gz",+ f"audio-{TAG}-bin-macos-arm64-metal.tar.gz",+ f"audio-{TAG}-bin-macos-x64-metal.tar.gz",+ f"audio-{TAG}-bin-ubuntu-x64-cpu-portable.tar.gz",+ f"audio-{TAG}-bin-ubuntu-x64-cpu.tar.gz",+ f"audio-{TAG}-bin-ubuntu-x64-cuda12.8-colab.tar.gz",+ f"audio-{TAG}-bin-ubuntu-x64-vulkan-portable.tar.gz",+ f"audio-{TAG}-bin-ubuntu-x64-vulkan.tar.gz",+ f"audio-{TAG}-bin-windows-x64-cpu-portable.zip",+ f"audio-{TAG}-bin-windows-x64-cpu.zip",+ f"audio-{TAG}-bin-windows-x64-cuda12.4.zip",+ f"audio-{TAG}-bin-windows-x64-cuda13.3.zip",+ f"audio-{TAG}-bin-windows-x64-vulkan.zip",+ f"audio-{TAG}-cudart-windows-x64-cuda12.4.zip",+ f"audio-{TAG}-cudart-windows-x64-cuda13.3.zip",+ "framework.tar.gz",+ "resources.tar.gz",+]+++def pick(system, machine, accel, **kw):+ return M.resolve_release_asset(ASSETS, system = system, machine = machine, accelerator = accel, **kw)+++ "system,machine,accel,expected",+ [+ ("Windows", "AMD64", "cpu", "bin-windows-x64-cpu-portable.zip"),+ ("Windows", "AMD64", "vulkan", "bin-windows-x64-vulkan.zip"),+ ("Linux", "x86_64", "cpu", "bin-ubuntu-x64-cpu-portable.tar.gz"),+ ("Linux", "x86_64", "vulkan", "bin-ubuntu-x64-vulkan-portable.tar.gz"),+ ("Linux", "x86_64", "cuda", "bin-ubuntu-x64-cuda12.8-colab.tar.gz"),+ ("Darwin", "arm64", "metal", "bin-macos-arm64-metal.tar.gz"),+ ("Darwin", "x86_64", "metal", "bin-macos-x64-metal.tar.gz"),+ ],+)+def test_resolves_the_host_bundle(system, machine, accel, expected):+ assert pick(system, machine, accel).endswith(expected)+++def test_no_bundle_for_an_unbuilt_host():+ # Upstream publishes no Linux arm64 or Windows arm64 bundles: the caller must fall back, not install x64.+ assert pick("Linux", "aarch64", "cpu") is None+ assert pick("Windows", "ARM64", "cpu") is None+ assert pick("Windows", "AMD64", "metal") is None+++def test_cuda_takes_the_newest_line_the_driver_runs():+ assert pick("Windows", "AMD64", "cuda", driver_cuda = (13, 4)).endswith("cuda13.3.zip")+ # A 12.x driver cannot load a 13.3 bundle.+ assert pick("Windows", "AMD64", "cuda", driver_cuda = (12, 8)).endswith("cuda12.4.zip")+ # Nothing old enough for this driver: no CUDA bundle rather than one that fails to load.+ assert pick("Windows", "AMD64", "cuda", driver_cuda = (11, 8)) is None+++def test_cuda_prefers_the_torch_line_so_its_runtime_can_be_reused():+ assert pick("Windows", "AMD64", "cuda", driver_cuda = (13, 4), prefer_cuda_major = 12).endswith(+ "cuda12.4.zip"+ )+ assert pick("Windows", "AMD64", "cuda", driver_cuda = (13, 4), prefer_cuda_major = 13).endswith(+ "cuda13.3.zip"+ )+++def test_linux_cuda_prefers_the_multi_arch_build_over_colab():+ # The Unsloth fork adds a multi-arch cuda12.8 bundle next to upstream's sm_75-only Colab one.+ names = ASSETS + [f"audio-{TAG}-bin-ubuntu-x64-cuda12.8.tar.gz"]+ got = M.resolve_release_asset(names, system = "Linux", machine = "x86_64", accelerator = "cuda")+ assert got.endswith("bin-ubuntu-x64-cuda12.8.tar.gz")+++def test_cudart_archive_matches_the_bundle_line():+ assert M.cudart_asset_for(ASSETS, f"audio-{TAG}-bin-windows-x64-cuda12.4.zip").endswith(+ "cudart-windows-x64-cuda12.4.zip"+ )+ assert M.cudart_asset_for(ASSETS, f"audio-{TAG}-bin-windows-x64-cuda13.3.zip").endswith(+ "cudart-windows-x64-cuda13.3.zip"+ )+ assert M.cudart_asset_for(ASSETS, f"audio-{TAG}-bin-ubuntu-x64-cuda12.8-colab.tar.gz") is None+ assert M.cudart_asset_for(ASSETS, f"audio-{TAG}-bin-windows-x64-cpu.zip") is None+++ "version,major",+ [("2.10.0+cu130", 13), ("2.8.0+cu128", 12), ("2.5.1+cu124", 12), ("2.8.0", None)],+)+def test_torch_cuda_major(monkeypatch, version, major):+ import importlib.metadata as md+ monkeypatch.setattr(md, "version", lambda name: version)+ assert M.torch_cuda_major() == major+++ "smi,expected",+ [+ ("| NVIDIA-SMI 560.35 Driver Version: 560.35 CUDA Version: 12.6 |", (12, 6)),+ ("| NVIDIA-SMI 617.14 KMD Version: 617.14 CUDA UMD Version: 13.4 |", (13, 4)),+ ],+)+def test_driver_cuda_version_reads_both_spellings(monkeypatch, smi, expected):+ monkeypatch.setattr(M.shutil, "which", lambda name: "nvidia-smi")+ monkeypatch.setattr(M.subprocess, "run", lambda *a, **k: type("R", (), {"stdout": smi})())+ assert M.nvidia_driver_cuda_version() == expected+++# Install flow. Archives are real zips in tmp_path; the download copies them, the staged-server check+# is stubbed (its own tests below), and pins are a per-test dict.++FORK = M.DEFAULT_REPO+FORK_TAG = M.DEFAULT_TAG+CPU_ZIP = f"audio-{FORK_TAG}-bin-windows-x64-cpu-portable.zip"+# The real functions, before any test replaces them.+RESOLVE = M.resolve+SMOKE = M.smoke_test_staged_server++[email protected](autouse = True)+def _isolated_env(monkeypatch):+ for var in (+ "UNSLOTH_AUDIO_CPP_REPO",+ "UNSLOTH_AUDIO_CPP_TAG",+ "UNSLOTH_AUDIO_CPP_ACCELERATOR",+ "GH_TOKEN",+ "GITHUB_TOKEN",+ ):+ monkeypatch.delenv(var, raising = False)+ monkeypatch.setattr(M.core, "sleep_backoff", lambda *a, **k: None)+++def pins(monkeypatch):+ table = {}+ monkeypatch.setattr(M, "pinned_sha256", lambda repo, tag, asset: table.get((repo, tag, asset)))+ return table+++def _sha(path):+ return M.core.sha256_file(path)+++def _release(+ tmp_path,+ bundle_name,+ server_path = "bin/audiocpp_server.exe",+ tag = FORK_TAG,+ extra = (),+):+ archive = tmp_path / "src" / bundle_name+ archive.parent.mkdir(parents = True, exist_ok = True)+ with zipfile.ZipFile(archive, "w") as zf:+ zf.writestr(+ server_path.replace("audiocpp_server.exe", M.SERVER_NAME),+ b"binary " + bundle_name.encode(),+ )+ zf.writestr("bin/README.txt", b"hi")+ for name, data in extra:+ zf.writestr(name, data)+ return {+ "tag_name": tag,+ "assets": [+ {+ "name": bundle_name,+ "browser_download_url": str(archive),+ "digest": "sha256:" + _sha(archive),+ }+ ],+ }+++def _pin_release(+ pins,+ release,+ repo = FORK,+):+ for asset in release["assets"]:+ pins[(repo, release["tag_name"], asset["name"])] = asset["digest"].partition(":")[2]+++def _fake_download(url, dest):+ dest.write_bytes(Path(url).read_bytes())+++def _stub_install_io(monkeypatch, version = "audio.cpp test\nbackends: cpu"):+ monkeypatch.setattr(M, "_download", _fake_download)+ monkeypatch.setattr(M, "smoke_test_staged_server", lambda server, **kw: version)+ monkeypatch.setattr(M, "detect_accelerator", lambda: "cpu")+ monkeypatch.setattr(M, "_linux_cuda_runtime_available", lambda major: True)+++def _install(+ monkeypatch,+ tmp_path,+ release,+ pins = None,+ repo = FORK,+ accelerator = "cpu",+ **kw,+):+ bundle = release["assets"][0]["name"]+ if pins is not None:+ _pin_release(pins, release, repo)+ monkeypatch.setattr(M, "resolve", lambda accel, token: (repo, release, bundle))+ _stub_install_io(monkeypatch)+ return M.install(install_dir = tmp_path / "audio.cpp", accelerator = accelerator, **kw)+++def _tree_digest(root):+ return {p.relative_to(root).as_posix(): _sha(p) for p in sorted(root.rglob("*")) if p.is_file()}+++def test_install_swaps_in_a_complete_tree_and_records_it(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ server = _install(monkeypatch, tmp_path, release, pins)+ root = tmp_path / "audio.cpp"+ assert server.is_file() and server.parent == root / "bin"+ record = json.loads((root / M.INSTALL_RECORD).read_text())+ assert record["backend"] == "cpu"+ assert record["server_relpath"] == f"bin/{M.SERVER_NAME}"+ assert record["published_repo"] == FORK and record["release_tag"] == FORK_TAG+ assert record["server_sha256"] == _sha(server)+ assert record["server_version"].startswith("audio.cpp test")+ assert (+ record["accelerator"],+ record["accelerator_request"],+ record["detected_accelerator"],+ ) == ("cpu", "cpu", None)+ assert (root / M.OWNERSHIP_MARKER).is_file()+ # No staging directory survives, and the install lock is prebuilt_core's.+ assert not [p for p in tmp_path.iterdir() if p.name.startswith(".audio.cpp-staging-")]+ assert M.core.install_lock_path(root) == tmp_path / ".audio.cpp.install.lock"+++# G2: a no-op re-run does no network work+++def test_rerun_on_the_pinned_install_makes_no_release_lookup(monkeypatch, tmp_path, pins, capsys):+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins, accelerator = "auto")+ before = _tree_digest(tmp_path / "audio.cpp")+ monkeypatch.setattr(+ M, "resolve", lambda *a: pytest.fail("resolve must not run on a matching install")+ )+ monkeypatch.setattr(M, "_download", lambda *a: pytest.fail("no download expected"))+ capsys.readouterr()+ assert M.main(["--install-dir", str(tmp_path / "audio.cpp")]) == M.EXIT_OK+ assert f"audio.cpp: already matches {CPU_ZIP}" in capsys.readouterr().out+ assert _tree_digest(tmp_path / "audio.cpp") == before+++ "mutate",+ [+ pytest.param(lambda root, rec: rec.update(release_tag = "v0.8.1-unsloth.1"), id = "older-tag"),+ pytest.param(lambda root, rec: rec.update(asset_sha256 = "0" * 64), id = "unpinned-digest"),+ pytest.param(lambda root, rec: rec.update(detected_accelerator = "cuda"), id = "host-changed"),+ pytest.param(+ lambda root, rec: (root / rec["server_relpath"]).write_bytes(b"tampered"),+ id = "server-changed",+ ),+ ],+)+def test_a_record_that_no_longer_fits_still_looks_up(monkeypatch, tmp_path, pins, mutate):+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins, accelerator = "auto")+ root = tmp_path / "audio.cpp"+ record = json.loads((root / M.INSTALL_RECORD).read_text())+ mutate(root, record)+ (root / M.INSTALL_RECORD).write_text(json.dumps(record))+ asked = []+ monkeypatch.setattr(+ M, "resolve", lambda accel, token: asked.append(accel) or (FORK, release, CPU_ZIP)+ )+ M.install(install_dir = root, accelerator = "auto")+ assert asked == ["cpu"]+++def test_an_explicit_request_does_not_match_an_auto_install(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins, accelerator = "auto")+ asked = []+ monkeypatch.setattr(+ M, "resolve", lambda accel, token: asked.append(accel) or (FORK, None, None)+ )+ with pytest.raises(RuntimeError, match = "No prebuilt"):+ M.install(install_dir = tmp_path / "audio.cpp", accelerator = "vulkan")+ assert asked == ["vulkan"]+++def test_tracking_latest_always_looks_up(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins)+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_TAG", "")+ root = tmp_path / "audio.cpp"+ assert M._pinned_install_matches(root, M.read_install_record(root), "cpu", None) is None+++# G2/AC3: a lookup that cannot answer keeps a complete install+++def _offline(monkeypatch):+ def fetch(+ repo,+ tag,+ token,+ timeout = 30.0,+ ):+ raise OSError("network is unreachable")++ monkeypatch.setattr(M, "_fetch_release", fetch)+++def _installed_then_stale(+ monkeypatch,+ tmp_path,+ pins,+ accelerator = "auto",+):+ """A complete install whose record no longer names the pinned tag, so the run must look up."""+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins, accelerator = accelerator)+ root = tmp_path / "audio.cpp"+ record = json.loads((root / M.INSTALL_RECORD).read_text())+ record["release_tag"] = "v0.8.1-unsloth.1"+ (root / M.INSTALL_RECORD).write_text(json.dumps(record))+ monkeypatch.setattr(M, "resolve", RESOLVE)+ return root+++def test_offline_rerun_keeps_a_complete_install(monkeypatch, tmp_path, pins, capsys):+ root = _installed_then_stale(monkeypatch, tmp_path, pins)+ before = _tree_digest(root)+ _offline(monkeypatch)+ capsys.readouterr()+ assert M.main(["--install-dir", str(root)]) == M.EXIT_OK+ out = capsys.readouterr().out+ assert "audio.cpp: keeping the existing complete install" in out.splitlines()+ assert _tree_digest(root) == before+++def test_rate_limited_rerun_keeps_a_complete_install(monkeypatch, tmp_path, pins, capsys):+ root = _installed_then_stale(monkeypatch, tmp_path, pins)++ def fetch(+ repo,+ tag,+ token,+ timeout = 30.0,+ ):+ raise M.GitHubRateLimited("rate limited")++ monkeypatch.setattr(M, "_fetch_release", fetch)+ assert M.main(["--install-dir", str(root)]) == M.EXIT_OK+ assert M.KEPT_EXISTING_LINE in capsys.readouterr().out+++def test_offline_without_an_install_fails(monkeypatch, tmp_path, capsys):+ _stub_install_io(monkeypatch)+ _offline(monkeypatch)+ assert M.main(["--install-dir", str(tmp_path / "audio.cpp")]) == M.EXIT_FAILED+ assert "no audio.cpp release lookup answered" in capsys.readouterr().err+++def test_offline_keeps_nothing_for_a_tampered_server(monkeypatch, tmp_path, pins, capsys):+ root = _installed_then_stale(monkeypatch, tmp_path, pins)+ (root / "bin" / M.SERVER_NAME).write_bytes(b"truncated")+ _offline(monkeypatch)+ assert M.main(["--install-dir", str(root)]) == M.EXIT_FAILED+ assert M.KEPT_EXISTING_LINE not in capsys.readouterr().out+++def test_offline_does_not_keep_an_install_for_another_explicit_accelerator(+ monkeypatch, tmp_path, pins+):+ root = _installed_then_stale(monkeypatch, tmp_path, pins)+ _offline(monkeypatch)+ assert M.main(["--install-dir", str(root), "--accelerator", "vulkan"]) == M.EXIT_FAILED+ assert M.main(["--install-dir", str(root), "--force"]) == M.EXIT_FAILED+++# G1: main() leaves "auto" to install(), so the CPU fallback runs from the real CLI+++def _resolve_recording(release, covers = ("cpu",)):+ asked = []++ def resolve(accel, token):+ asked.append(accel)+ if accel in covers:+ return FORK, release, release["assets"][0]["name"]+ return FORK, None, None++ return asked, resolve+++def test_main_auto_detected_gpu_without_a_bundle_installs_the_cpu_build(+ monkeypatch, tmp_path, pins+):+ release = _release(tmp_path, CPU_ZIP)+ _pin_release(pins, release)+ asked, resolve = _resolve_recording(release)+ _stub_install_io(monkeypatch)+ monkeypatch.setattr(M, "resolve", resolve)+ monkeypatch.setattr(M, "detect_accelerator", lambda: "cuda")+ assert M.main(["--install-dir", str(tmp_path / "audio.cpp")]) == M.EXIT_OK+ assert asked == ["cuda", "cpu"]+ record = json.loads((tmp_path / "audio.cpp" / M.INSTALL_RECORD).read_text())+ assert (record["backend"], record["accelerator_request"], record["detected_accelerator"]) == (+ "cpu",+ "auto",+ "cuda",+ )+++def test_auto_cuda_without_a_cuda_runtime_installs_the_cpu_build_and_reruns_offline(+ monkeypatch, tmp_path, pins+):+ release = _release(tmp_path, CPU_ZIP)+ _pin_release(pins, release)+ asked, resolve = _resolve_recording(release, covers = ("cpu", "cuda"))+ _stub_install_io(monkeypatch)+ seen = []+ monkeypatch.setattr(+ M, "_linux_cuda_runtime_available", lambda major: seen.append(major) or False+ )+ monkeypatch.setattr(M, "resolve", resolve)+ monkeypatch.setattr(M, "detect_accelerator", lambda: "cuda")+ assert M.main(["--install-dir", str(tmp_path / "audio.cpp")]) == M.EXIT_OK+ assert asked == ["cuda", "cpu"]+ record = json.loads((tmp_path / "audio.cpp" / M.INSTALL_RECORD).read_text())+ assert (record["backend"], record["accelerator_request"], record["detected_accelerator"]) == (+ "cpu",+ "auto",+ "cuda",+ )+ monkeypatch.setattr(M, "resolve", lambda *a: pytest.fail("a matching rerun must not look up"))+ assert M.main(["--install-dir", str(tmp_path / "audio.cpp")]) == M.EXIT_OK+ # torch's CUDA runtime arrived: the CPU fallback is no longer a match, so the GPU build is looked up.+ monkeypatch.setattr(M, "_linux_cuda_runtime_available", lambda major: True)+ looked = []+ monkeypatch.setattr(+ M, "resolve", lambda accel, token: looked.append(accel) or (FORK, release, CPU_ZIP)+ )+ assert M.main(["--install-dir", str(tmp_path / "audio.cpp")]) == M.EXIT_OK+ assert looked == ["cuda"]+++def test_explicit_cuda_is_not_downgraded_for_a_missing_cuda_runtime(monkeypatch):+ monkeypatch.setattr(M, "_linux_cuda_runtime_available", lambda major: False)+ asked = []+ monkeypatch.setattr(+ M,+ "resolve",+ lambda accel, token: asked.append(accel)+ or (FORK, {"assets": []}, "a-bin-ubuntu-x64-cuda13.tar.gz"),+ )+ M.resolve_for_request("cuda", None, None)+ assert asked == ["cuda"]+++def test_cuda_runtime_probe_needs_the_bundle_major(monkeypatch, tmp_path):+ monkeypatch.setattr(M.sys, "platform", "linux")+ monkeypatch.setattr(M, "_cuda_runtime_dirs", lambda backend: [str(tmp_path)])+ monkeypatch.setattr(M, "_ldconfig_libs", lambda: set())+ assert M._linux_cuda_runtime_available(13) is False+ for name in ("libcudart.so.13", "libcublas.so.13", "libcufft.so.12"):+ (tmp_path / name).write_bytes(b"")+ assert M._linux_cuda_runtime_available(13) is True+ assert M._linux_cuda_runtime_available(12) is False+ assert M._linux_cuda_runtime_available(None) is False+ monkeypatch.setattr(M, "_cuda_runtime_dirs", lambda backend: [])+ monkeypatch.setattr(+ M, "_ldconfig_libs", lambda: {"libcudart.so.12", "libcublas.so.12", "libcufft.so.11"}+ )+ assert M._linux_cuda_runtime_available(12) is True+ monkeypatch.setattr(M.sys, "platform", "win32")+ assert M._linux_cuda_runtime_available(None) is True+++ "names, driver, prefer, want",+ [+ (("cuda12", "cuda13"), (13, 1), 13, "cuda13"),+ (("cuda12", "cuda13"), (12, 4), None, "cuda12"),+ (("cuda12", "cuda13"), (13, 1), 12, "cuda12"),+ (("cuda12.8", "cuda12.8-colab"), (12, 8), None, "cuda12.8"),+ ],+)+def test_cuda_lines_with_and_without_a_minor(names, driver, prefer, want):+ assets = [f"audio-T-bin-ubuntu-x64-{n}.tar.gz" for n in names]+ got = M.resolve_release_asset(+ assets,+ system = "Linux",+ machine = "x86_64",+ accelerator = "cuda",+ driver_cuda = driver,+ prefer_cuda_major = prefer,+ )+ assert got == f"audio-T-bin-ubuntu-x64-{want}.tar.gz"+ win = ["audio-T-bin-windows-x64-cuda13.zip", "audio-T-cudart-windows-x64-cuda13.zip"]+ assert M.cudart_asset_for(win, win[0]) == win[1]+++def test_main_explicit_gpu_request_is_never_downgraded(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ asked, resolve = _resolve_recording(release)+ _stub_install_io(monkeypatch)+ monkeypatch.setattr(M, "resolve", resolve)+ monkeypatch.setattr(+ M, "detect_accelerator", lambda: pytest.fail("explicit request must not detect")+ )+ assert (+ M.main(["--install-dir", str(tmp_path / "audio.cpp"), "--accelerator", "cuda"])+ == M.EXIT_FAILED+ )+ assert asked == ["cuda"]+ assert not (tmp_path / "audio.cpp").exists()+++def test_print_asset_resolves_like_install(monkeypatch, tmp_path, capsys):+ release = _release(tmp_path, CPU_ZIP)+ asked, resolve = _resolve_recording(release)+ monkeypatch.setattr(M, "resolve", resolve)+ monkeypatch.setattr(M, "detect_accelerator", lambda: "cuda")+ # A CUDA host with its CUDA runtime, whatever the runner has (one without resolves CPU only).+ monkeypatch.setattr(M, "_linux_cuda_runtime_available", lambda major: True)+ assert M.main(["--print-asset"]) == M.EXIT_OK+ assert asked == ["cuda", "cpu"]+ assert capsys.readouterr().out.strip().endswith(CPU_ZIP)+++# G12: UNSLOTH_AUDIO_CPP_ACCELERATOR+++def test_accelerator_env_is_an_explicit_request(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ asked, resolve = _resolve_recording(release, covers = ("cpu", "cuda"))+ _stub_install_io(monkeypatch)+ monkeypatch.setattr(M, "resolve", resolve)+ _pin_release(pins, release)+ monkeypatch.setattr(+ M, "detect_accelerator", lambda: pytest.fail("an explicit accelerator must not detect")+ )+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_ACCELERATOR", "CUDA")+ assert M.main(["--install-dir", str(tmp_path / "audio.cpp")]) == M.EXIT_OK+ assert asked == ["cuda"]+ assert (+ json.loads((tmp_path / "audio.cpp" / M.INSTALL_RECORD).read_text())["accelerator_request"]+ == "cuda"+ )+++def test_an_unknown_accelerator_env_falls_back_to_auto(monkeypatch, capsys):+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_ACCELERATOR", "rocm")+ assert M._accelerator_from_env() == "auto"+ assert "ignoring UNSLOTH_AUDIO_CPP_ACCELERATOR" in capsys.readouterr().err+++# G11: release ladder and digest pins+++def test_default_ladder_is_the_pinned_fork_tag_then_its_upstream_release(monkeypatch):+ tried = []+ monkeypatch.setattr(+ M, "_fetch_release", lambda repo, tag, token: tried.append((repo, tag)) or None+ )+ monkeypatch.setattr(M, "nvidia_driver_cuda_version", lambda: None)+ assert M.resolve("cpu", None) == (FORK, None, None)+ # No "latest" rungs: a pinned install never drifts to an untested release.+ assert tried == [+ (M.DEFAULT_REPO, M.DEFAULT_TAG),+ (M.UPSTREAM_FALLBACK_REPO, M.UPSTREAM_FALLBACK_TAG),+ ]+++def test_latest_is_tried_only_when_the_user_asks_for_it(monkeypatch):+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_TAG", "")+ assert M._release_ladder() == [(M.DEFAULT_REPO, None)]+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_REPO", "someone/audio.cpp")+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_TAG", "v1")+ assert M._release_ladder() == [("someone/audio.cpp", "v1")]+++def test_a_user_chosen_tag_never_reaches_the_upstream_repo(monkeypatch):+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_TAG", "v9")+ assert M._release_ladder() == [(M.DEFAULT_REPO, "v9")]+++ "libc, refused",+ [+ (("glibc", "2.31"), True),+ (("glibc", "2.34"), True),+ (("glibc", "2.35"), False),+ (("glibc", "2.39"), False),+ (("", ""), False),+ (("glibc", "weird"), False),+ ],+)+def test_old_glibc_is_refused_before_any_download(monkeypatch, tmp_path, libc, refused):+ monkeypatch.setattr(M.sys, "platform", "linux")+ monkeypatch.setattr(M.platform, "libc_ver", lambda: libc)+ lookups = []+ monkeypatch.setattr(+ M, "resolve_for_request", lambda *a: lookups.append(a) or ("cpu", FORK, None, None)+ )+ with pytest.raises(RuntimeError) as exc:+ M._install_locked(tmp_path / "audio.cpp", "cpu", None, False)+ assert ("need glibc 2.35+" in str(exc.value)) is refused+ assert (lookups == []) is refused+++def test_old_glibc_is_not_refused_for_a_user_chosen_release(monkeypatch):+ monkeypatch.setattr(M.sys, "platform", "linux")+ monkeypatch.setattr(M.platform, "libc_ver", lambda: ("glibc", "2.31"))+ assert M._glibc_below_pinned_floor() == "2.31"+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_REPO", "someone/audio.cpp")+ assert M._glibc_below_pinned_floor() is None+++def test_an_unpinned_asset_is_refused_by_default(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ with pytest.raises(RuntimeError, match = "no sha256 pinned"):+ _install(monkeypatch, tmp_path, release)+ assert not (tmp_path / "audio.cpp").exists()+++def test_an_unpinned_asset_is_allowed_for_a_release_the_user_picked(monkeypatch, tmp_path, pins):+ monkeypatch.setenv("UNSLOTH_AUDIO_CPP_TAG", FORK_TAG)+ release = _release(tmp_path, CPU_ZIP)+ assert _install(monkeypatch, tmp_path, release).is_file()+++def test_a_github_digest_that_disagrees_with_the_pin_is_refused(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ _pin_release(pins, release)+ release["assets"][0]["digest"] = "sha256:" + "1" * 64+ with pytest.raises(RuntimeError, match = "pins"):+ _install(monkeypatch, tmp_path, release)+++def test_a_download_that_does_not_hash_to_the_pin_is_refused(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ pins[(FORK, FORK_TAG, CPU_ZIP)] = "0" * 64+ release["assets"][0]["digest"] = None+ with pytest.raises(RuntimeError, match = "sha256 mismatch"):+ _install(monkeypatch, tmp_path, release)+ assert not (tmp_path / "audio.cpp").exists()+++def test_the_pins_file_covers_both_default_releases():+ table = M.load_pins()+ for repo, tag in (+ (M.DEFAULT_REPO, M.DEFAULT_TAG),+ (M.UPSTREAM_FALLBACK_REPO, M.UPSTREAM_FALLBACK_TAG),+ ):+ names = list(table[repo][tag])+ # Stale after a tag bump until `--write-pins` regenerates it.+ assert names and all(f"audio-{tag}-" in n for n in names), (repo, tag)+ assert all(M.core.normalize_sha256_digest(table[repo][tag][n]) for n in names)+ for system, machine, accel in (+ ("Windows", "AMD64", "cpu"),+ ("Windows", "AMD64", "cuda"),+ ("Linux", "x86_64", "cpu"),+ ("Linux", "x86_64", "cuda"),+ ("Darwin", "arm64", "metal"),+ ):+ chosen = M.resolve_release_asset(+ names, system = system, machine = machine, accelerator = accel+ )+ assert chosen, (repo, tag, system, accel)+ if system == "Windows" and accel == "cuda":+ assert M.cudart_asset_for(names, chosen) in names+++def test_write_pins_regenerates_from_the_release_digests(monkeypatch, tmp_path):+ releases = {+ (M.DEFAULT_REPO, M.DEFAULT_TAG): [+ {+ "name": f"audio-{M.DEFAULT_TAG}-bin-windows-x64-cpu.zip",+ "digest": "sha256:" + "b" * 64,+ },+ {+ "name": f"audio-{M.DEFAULT_TAG}-cudart-windows-x64-cuda12.4.zip",+ "digest": "sha256:" + "c" * 64,+ },+ {+ "name": f"audio-{M.DEFAULT_TAG}-bin-macos-arm64-metal.tar.gz",+ "digest": "sha256:" + "a" * 64,+ },+ {"name": "framework.tar.gz", "digest": None},+ ],+ (M.UPSTREAM_FALLBACK_REPO, M.UPSTREAM_FALLBACK_TAG): [+ {+ "name": f"audio-{M.UPSTREAM_FALLBACK_TAG}-bin-windows-x64-cpu.zip",+ "digest": "sha256:" + "d" * 64,+ },+ ],+ }+ monkeypatch.setattr(+ M,+ "_fetch_release",+ lambda repo, tag, token: {"tag_name": tag, "assets": releases[(repo, tag)]},+ )+ out = M.write_pins(tmp_path / "pins.json")+ first = out.read_bytes()+ assert M.write_pins(tmp_path / "pins.json").read_bytes() == first+ table = M.load_pins(out)+ fork = table[M.DEFAULT_REPO][M.DEFAULT_TAG]+ assert list(fork) == sorted(fork) and "framework.tar.gz" not in fork+ assert fork[f"audio-{M.DEFAULT_TAG}-cudart-windows-x64-cuda12.4.zip"] == "c" * 64+ releases[(M.DEFAULT_REPO, M.DEFAULT_TAG)][0]["digest"] = None+ with pytest.raises(RuntimeError, match = "no sha256 digest"):+ M.write_pins(tmp_path / "pins.json")+++# G3(b): the staged server must start before it replaces anything+++class _Ran:+ def __init__(+ self,+ returncode,+ stdout = "",+ stderr = "",+ ):+ self.returncode, self.stdout, self.stderr = returncode, stdout, stderr+++def test_a_staged_server_that_cannot_start_keeps_the_old_tree(monkeypatch, tmp_path, pins, capsys):+ good = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, good, pins)+ root = tmp_path / "audio.cpp"+ before = _tree_digest(root)+ newer = _release(tmp_path, f"audio-{FORK_TAG}-bin-windows-x64-cpu.zip")+ _pin_release(pins, newer)+ monkeypatch.setattr(+ M, "resolve", lambda accel, token: (FORK, newer, newer["assets"][0]["name"])+ )+ monkeypatch.setattr(M, "smoke_test_staged_server", SMOKE)+ loader_error = (+ "audiocpp_server: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found"+ )+ monkeypatch.setattr(M.subprocess, "run", lambda *a, **k: _Ran(127, stderr = loader_error))+ assert M.main(["--install-dir", str(root), "--accelerator", "cpu", "--force"]) == M.EXIT_FAILED+ err = capsys.readouterr().err+ assert "GLIBC_2.38" in err and "keeping the existing install" in err+ assert _tree_digest(root) == before+ assert not [p for p in tmp_path.iterdir() if p.name.startswith(".audio.cpp-staging-")]+++def test_staged_server_check_puts_the_bundle_dir_first_and_records_the_version(+ monkeypatch, tmp_path+):+ server = tmp_path / "bin" / M.SERVER_NAME+ server.parent.mkdir()+ server.write_bytes(b"x")+ calls = []++ def run(cmd, **kw):+ calls.append((cmd, kw))+ return _Ran(+ 0, stdout = "audio.cpp 0.8.2\nbackends: cpu,cuda\n" if cmd[1] == "--version" else "usage"+ )++ monkeypatch.setattr(M.subprocess, "run", run)+ extra = tmp_path / "torch-lib"+ assert (+ SMOKE(server, backend = "cuda", extra_dirs = [extra]) == "audio.cpp 0.8.2\nbackends: cpu,cuda"+ )+ assert [c[0][1] for c in calls] == ["--help", "--version"]+ assert calls[0][1]["timeout"] == M.SMOKE_TIMEOUT_SECONDS+ var = (+ "PATH"+ if sys.platform == "win32"+ else "DYLD_LIBRARY_PATH"+ if sys.platform == "darwin"+ else "LD_LIBRARY_PATH"+ )+ assert calls[0][1]["env"][var].split(M.os.pathsep)[:2] == [str(server.parent), str(extra)]+++def test_a_cuda_bundle_is_checked_with_the_wheel_cuda_runtime_on_the_loader_path(+ monkeypatch, tmp_path, pins+):+ # The Linux CUDA server links libcublas/libcudart/libcufft/libnccl dynamically: without torch's+ # nvidia-* wheel dirs the check would refuse every CUDA install.+ import types++ fake = types.ModuleType("install_llama_prebuilt")+ fake.python_runtime_dirs = lambda: ["/venv/nvidia/cublas/lib"]+ monkeypatch.setitem(sys.modules, "install_llama_prebuilt", fake)+ monkeypatch.setattr(M.sys, "platform", "linux")+ assert M._cuda_runtime_dirs("cuda") == ["/venv/nvidia/cublas/lib"]+ assert M._cuda_runtime_dirs("cpu") == []+ monkeypatch.setattr(M.sys, "platform", "darwin")+ assert M._cuda_runtime_dirs("cuda") == []+++def test_staged_server_check_times_out(monkeypatch, tmp_path):+ def run(cmd, **kw):+ raise M.subprocess.TimeoutExpired(cmd, kw["timeout"])++ monkeypatch.setattr(M.subprocess, "run", run)+ with pytest.raises(RuntimeError, match = "did not exit within 30s"):+ SMOKE(tmp_path / M.SERVER_NAME, backend = "cpu")+++def test_a_cuda_build_is_not_refused_for_a_missing_driver_it_gets_at_run_time(+ monkeypatch, tmp_path+):+ # A Docker image build sees no GPU; libcuda.so.1 comes with the driver when the container runs.+ monkeypatch.setattr(+ M.subprocess,+ "run",+ lambda *a, **k: _Ran(127, stderr = "error while loading shared libraries: libcuda.so.1"),+ )+ monkeypatch.setattr(M, "nvidia_driver_cuda_version", lambda: None)+ assert SMOKE(tmp_path / M.SERVER_NAME, backend = "cuda") is None+ with pytest.raises(RuntimeError, match = "libcuda"):+ SMOKE(tmp_path / M.SERVER_NAME, backend = "cpu")+ monkeypatch.setattr(M, "nvidia_driver_cuda_version", lambda: (12, 8))+ with pytest.raises(RuntimeError, match = "libcuda"):+ SMOKE(tmp_path / M.SERVER_NAME, backend = "cuda")+++ sys.platform == "win32", reason = "needs an executable shell script as the server"+)+def test_staged_server_check_runs_the_real_binary(tmp_path):+ server = tmp_path / M.SERVER_NAME+ server.write_text(+ '#!/bin/sh\n[ "$1" = --version ] && echo "audio.cpp fake" && exit 0\necho "loader: nope" >&2\nexit 127\n'+ )+ server.chmod(0o755)+ with pytest.raises(RuntimeError, match = "loader: nope"):+ SMOKE(server, backend = "cpu")+ server.write_text('#!/bin/sh\n[ "$1" = --version ] && echo "audio.cpp fake"\nexit 0\n')+ assert SMOKE(server, backend = "cpu") == "audio.cpp fake"+++# G17: install lock and retried downloads+++def test_a_held_install_lock_reports_busy(monkeypatch, tmp_path, capsys):+ monkeypatch.setattr(M.core, "INSTALL_LOCK_TIMEOUT_SECONDS", 0.3)+ _stub_install_io(monkeypatch)+ monkeypatch.setattr(M, "resolve", lambda *a: pytest.fail("must not resolve without the lock"))+ target = tmp_path / "audio.cpp"+ with M.core.install_lock(M.core.install_lock_path(target)):+ assert M.main(["--install-dir", str(target), "--accelerator", "cpu"]) == M.EXIT_BUSY+ assert "another audio.cpp install is running" in capsys.readouterr().err+++def test_downloads_are_retried(monkeypatch, tmp_path):+ import io+ import urllib.error++ attempts = []++ class Response(io.BytesIO):+ headers = {"Content-Length": "4"}++ def __enter__(self):+ return self++ def __exit__(self, *exc):+ return False++ class Opener:+ def open(+ self,+ request,+ timeout = None,+ ):+ attempts.append(request.full_url)+ if len(attempts) == 1:+ raise urllib.error.URLError("connection reset")+ return Response(b"data")++ monkeypatch.setattr(M, "_URL_OPENER", Opener(), raising = False)+ M._download("https://github.com/o/r/releases/download/t/a.zip", tmp_path / "a.zip")+ assert (tmp_path / "a.zip").read_bytes() == b"data" and len(attempts) == 2+++def test_release_lookups_are_retried(monkeypatch):+ import io+ import urllib.error++ attempts = []++ def urlopen(req, timeout = None):+ attempts.append(req.full_url)+ if len(attempts) < 3:+ raise urllib.error.URLError("temporary failure in name resolution")+ return io.BytesIO(b'{"tag_name": "t", "assets": []}')++ monkeypatch.setattr(M.urllib.request, "urlopen", urlopen)+ assert M._fetch_release("o/r", "t", None)["tag_name"] == "t"+ assert len(attempts) == 3+++# Carried over from the first installer+++def test_refuses_to_replace_a_directory_it_does_not_own(monkeypatch, tmp_path, pins):+ foreign = tmp_path / "audio.cpp"+ foreign.mkdir()+ (foreign / "mine.txt").write_text("user data")+ release = _release(tmp_path, CPU_ZIP)+ with pytest.raises(RuntimeError, match = "not an Unsloth-managed directory"):+ _install(monkeypatch, tmp_path, release, pins)+ assert (foreign / "mine.txt").read_text() == "user data"+++def test_bundle_without_a_server_leaves_the_old_tree(monkeypatch, tmp_path, pins):+ good = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, good, pins)+ bad = _release(+ tmp_path, f"audio-{FORK_TAG}-bin-windows-x64-cpu.zip", server_path = "bin/other.exe"+ )+ with pytest.raises(RuntimeError, match = "contains no"):+ _install(monkeypatch, tmp_path, bad, pins, force = True)+ assert (tmp_path / "audio.cpp" / "bin" / M.SERVER_NAME).is_file()+++def test_auto_detected_gpu_without_a_bundle_installs_the_cpu_build(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ _pin_release(pins, release)+ asked, resolve = _resolve_recording(release)+ _stub_install_io(monkeypatch)+ monkeypatch.setattr(M, "resolve", resolve)+ monkeypatch.setattr(M, "detect_accelerator", lambda: "cuda")+ M.install(install_dir = tmp_path / "audio.cpp", accelerator = "auto")+ assert asked == ["cuda", "cpu"]+ assert json.loads((tmp_path / "audio.cpp" / M.INSTALL_RECORD).read_text())["backend"] == "cpu"+++def test_an_explicit_gpu_request_is_never_downgraded(monkeypatch, tmp_path):+ monkeypatch.setattr(M, "resolve", lambda accel, token: (FORK, None, None))+ with pytest.raises(RuntimeError, match = "No prebuilt"):+ M.install(install_dir = tmp_path / "audio.cpp", accelerator = "cuda")+++def test_intel_mac_bundle_runs_on_the_cpu_backend():+ assert M._backend_of(f"audio-{TAG}-bin-macos-x64-metal.tar.gz") == "cpu"+ assert M._backend_of(f"audio-{TAG}-bin-macos-arm64-metal.tar.gz") == "metal"+++def test_record_notes_a_static_espeak_build(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP, extra = [("bin/espeak-ng-data.bin", b"data")])+ _install(monkeypatch, tmp_path, release, pins)+ assert json.loads((tmp_path / "audio.cpp" / M.INSTALL_RECORD).read_text())["espeak"] is True+ target = tmp_path / "audio.cpp"+ record = json.loads((target / M.INSTALL_RECORD).read_text())+ assert M._intact_install(target, record) is not None+ # Quarantined phonemizer data makes the install incomplete, so the next update repairs it.+ next(target.rglob("espeak-ng-data.bin")).unlink()+ assert M._intact_install(target, record) is None+++def test_a_dir_holding_only_the_old_child_home_is_adopted(monkeypatch, tmp_path, pins):+ leftover = tmp_path / "audio.cpp" / ".child_home" / "AppData"+ leftover.mkdir(parents = True)+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins)+ assert (tmp_path / "audio.cpp" / M.OWNERSHIP_MARKER).is_file()+ assert not (tmp_path / "audio.cpp" / ".child_home").exists()+++def test_retired_trees_are_swept_on_the_next_run(monkeypatch, tmp_path, pins):+ stale = tmp_path / "audio.cpp.old-1234"+ stale.mkdir()+ (stale / M.OWNERSHIP_MARKER).touch()+ foreign = tmp_path / "audio.cpp.old-user"+ foreign.mkdir()+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins)+ assert not stale.exists() and foreign.exists()+++def test_a_running_server_reports_busy_before_downloading(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins)+ monkeypatch.setattr(M, "_server_in_use", lambda server: True)+ downloaded = []+ monkeypatch.setattr(M, "_download", lambda *a, **k: downloaded.append(a))+ with pytest.raises(PermissionError):+ M.install(install_dir = tmp_path / "audio.cpp", accelerator = "cpu", force = True)+ assert downloaded == []+++def test_up_to_date_check_notices_a_lost_cuda_runtime(monkeypatch):+ record = {+ "backend": "cuda",+ "os": "windows",+ "cudart_asset": None,+ "asset": f"audio-{TAG}-bin-windows-x64-cuda13.3.zip",+ }+ monkeypatch.setattr(M, "torch_provides_cuda_runtime", lambda major: False)+ assert M._cuda_runtime_satisfied(record) is False+ monkeypatch.setattr(M, "torch_provides_cuda_runtime", lambda major: major == 13)+ assert M._cuda_runtime_satisfied(record) is True+ assert M._cuda_runtime_satisfied({**record, "cudart_asset": "x.zip"}) is True+ assert M._cuda_runtime_satisfied({"backend": "cpu"}) is True+++def test_tar_extraction_without_filters_still_refuses_traversal(monkeypatch, tmp_path):+ import io+ import tarfile++ archive = tmp_path / "evil.tar.gz"+ with tarfile.open(archive, "w:gz") as tf:+ data = b"x"+ info = tarfile.TarInfo("../escape.txt")+ info.size = len(data)+ tf.addfile(info, io.BytesIO(data))+ monkeypatch.delattr(tarfile, "data_filter", raising = False)+ (tmp_path / "out").mkdir()+ with pytest.raises(RuntimeError, match = "unsafe path"):+ M._extract(archive, tmp_path / "out")+ assert not (tmp_path / "escape.txt").exists()+++def test_an_upstream_fallback_install_asks_for_the_fork_again(monkeypatch, tmp_path, pins):+ # The fork lookup failed on the run that installed upstream; the next run must not call that a match.+ up_zip = f"audio-{M.UPSTREAM_FALLBACK_TAG}-bin-windows-x64-cpu-portable.zip"+ release = _release(tmp_path, up_zip, tag = M.UPSTREAM_FALLBACK_TAG)+ _install(monkeypatch, tmp_path, release, pins, repo = M.UPSTREAM_FALLBACK_REPO)+ root = tmp_path / "audio.cpp"+ record = M.read_install_record(root)+ assert record["published_repo"] == M.UPSTREAM_FALLBACK_REPO+ assert M._pinned_install_matches(root, record, "cpu", None) is None+++def test_the_accelerator_flag_takes_what_setup_forwards(monkeypatch, tmp_path, pins):+ release = _release(tmp_path, CPU_ZIP)+ asked, resolve = _resolve_recording(release, covers = ("cpu", "cuda"))+ _stub_install_io(monkeypatch)+ monkeypatch.setattr(M, "resolve", resolve)+ _pin_release(pins, release)+ root = str(tmp_path / "audio.cpp")+ assert M.main(["--install-dir", root, "--accelerator", " CUDA "]) == M.EXIT_OK+ assert asked == ["cuda"]+++def test_a_killed_install_leaves_no_staging_dir_behind(monkeypatch, tmp_path, pins):+ stranded = tmp_path / ".audio.cpp-staging-killed"+ stranded.mkdir()+ (stranded / "partial.zip").write_bytes(b"x" * 16)+ release = _release(tmp_path, CPU_ZIP)+ _install(monkeypatch, tmp_path, release, pins)+ assert not stranded.exists()+++def test_the_staged_server_never_sees_secrets(monkeypatch, tmp_path):+ for name in ("GH_TOKEN", "HF_TOKEN", "AWS_SECRET_ACCESS_KEY"):+ monkeypatch.setenv(name, "secret")+ env = M._loader_env(tmp_path / "bin" / M.SERVER_NAME)+ assert not {"GH_TOKEN", "HF_TOKEN", "AWS_SECRET_ACCESS_KEY"} & set(env)+ assert (+ str(tmp_path / "bin")+ in env[+ "PATH"+ if M.sys.platform == "win32"+ else ("DYLD_LIBRARY_PATH" if M.sys.platform == "darwin" else "LD_LIBRARY_PATH")+ ]+ )+++# The asset set unslothai/audio.cpp's prebuilt CI publishes (v0.8.2-audio8-perf-hotfix-unsloth.1).+_FORK_T = "v0.8.2-audio8-perf-hotfix-unsloth.1"+_FORK_ASSETS = [+ f"audio-{_FORK_T}-bin-{n}"+ for n in (+ "macos-arm64-metal.tar.gz",+ "macos-x64-metal.tar.gz",+ "ubuntu-arm64-cpu.tar.gz",+ "ubuntu-x64-cpu-portable.tar.gz",+ "ubuntu-x64-cpu.tar.gz",+ "ubuntu-x64-cuda12.tar.gz",+ "ubuntu-x64-cuda13.tar.gz",+ "ubuntu-x64-vulkan.tar.gz",+ "windows-x64-cpu-portable.zip",+ "windows-x64-cpu.zip",+ "windows-x64-cuda12.zip",+ "windows-x64-cuda13.zip",+ "windows-x64-vulkan.zip",+ )+] + [f"audio-{_FORK_T}-cudart-windows-x64-cuda{m}.zip" for m in (12, 13)]+++ "system, machine, accel, driver, prefer, want, cudart",+ [+ ("Linux", "x86_64", "cpu", None, None, "ubuntu-x64-cpu-portable.tar.gz", None),+ ("Linux", "x86_64", "vulkan", None, None, "ubuntu-x64-vulkan.tar.gz", None),+ ("Linux", "x86_64", "cuda", (13, 1), 13, "ubuntu-x64-cuda13.tar.gz", None),+ ("Linux", "x86_64", "cuda", (13, 1), 12, "ubuntu-x64-cuda12.tar.gz", None),+ ("Linux", "x86_64", "cuda", (12, 4), None, "ubuntu-x64-cuda12.tar.gz", None),+ ("Linux", "x86_64", "cuda", (11, 8), None, None, None),+ ("Linux", "aarch64", "cpu", None, None, "ubuntu-arm64-cpu.tar.gz", None),+ ("Linux", "aarch64", "cuda", (13, 0), 13, None, None),+ ("Windows", "AMD64", "cpu", None, None, "windows-x64-cpu-portable.zip", None),+ ("Windows", "AMD64", "vulkan", None, None, "windows-x64-vulkan.zip", None),+ ("Windows", "AMD64", "cuda", (13, 2), None, "windows-x64-cuda13.zip", "cuda13"),+ ("Windows", "AMD64", "cuda", (12, 8), 12, "windows-x64-cuda12.zip", "cuda12"),+ ("Darwin", "arm64", "metal", None, None, "macos-arm64-metal.tar.gz", None),+ ("Darwin", "x86_64", "metal", None, None, "macos-x64-metal.tar.gz", None),+ ],+)+def test_the_fork_release_covers_every_host(system, machine, accel, driver, prefer, want, cudart):+ got = M.resolve_release_asset(+ _FORK_ASSETS,+ system = system,+ machine = machine,+ accelerator = accel,+ driver_cuda = driver,+ prefer_cuda_major = prefer,+ )+ if want is None:+ # No bundle: resolve_for_request falls back to the CPU build for an auto request.+ assert got is None+ return+ assert got == f"audio-{_FORK_T}-bin-{want}"+ rt = M.cudart_asset_for(_FORK_ASSETS, got)+ assert rt == (f"audio-{_FORK_T}-cudart-windows-x64-{cudart}.zip" if cudart else None)diff --git a/tests/studio/install/test_pr10648_offline_and_status.py b/tests/studio/install/test_pr10648_offline_and_status.pyindex 11f81226054..123e43276ff 100644--- a/tests/studio/install/test_pr10648_offline_and_status.py+++ b/tests/studio/install/test_pr10648_offline_and_status.py@@ -688,8 +688,9 @@ def test_the_keep_arm_sits_beside_the_status_arms_it_did_not_replace():# own test rather than, say, both scripts growing the sh spelling.sh_keeps = [line for line in setup_sh.splitlines() if KEEP_TOKEN in line]ps1_keeps = [line for line in setup_ps1.splitlines() if KEEP_TOKEN in line]- assert len(sh_keeps) == 2, sh_keeps- assert len(ps1_keeps) == 2, ps1_keeps+ # llama.cpp, whisper.cpp and audio.cpp.+ assert len(sh_keeps) == 3, sh_keeps+ assert len(ps1_keeps) == 3, ps1_keepsassert all("grep -Fq" in line for line in sh_keeps), sh_keepsassert all("-match" in line for line in ps1_keeps), ps1_keeps@@ -699,8 +700,8 @@ def test_the_keep_arm_sits_beside_the_status_arms_it_did_not_replace():assert f'$prebuiltOutput -match "{MATCH_TOKEN}"' in setup_ps1for script in (setup_sh, setup_ps1):assert (- script.count("update unavailable, existing prebuilt kept") == 2- ), "llama and whisper each have exactly one keep arm"+ script.count("update unavailable, existing prebuilt kept") == 3+ ), "llama, whisper and audio.cpp each have exactly one keep arm"# ══ Part 2: the status contract, executed in both shells ═════════════════════════════diff --git a/tests/studio/install/test_update_idempotency.py b/tests/studio/install/test_update_idempotency.pyindex e5e2ba83706..f41753c127e 100644--- a/tests/studio/install/test_update_idempotency.py+++ b/tests/studio/install/test_update_idempotency.py@@ -150,6 +150,10 @@ NO_WORK_MARKERS = ("dependencies up to date", "prebuilt up to date", "sidecar cu# whisper.cpp at all, and every run says so on this line (setup.sh / setup.ps1). That is the# pairing gate working, not a prebuilt being re-validated.WHISPER_UNPAIRED = re.compile(r"whisper\.cpp\s+no compatible prebuilt \(")+# audio.cpp's step line (setup.sh / setup.ps1): printed whenever its installer ran, so a run that+# shows it must also answer from the install record. Skipped installs (UNSLOTH_SKIP_AUDIO_CPP_INSTALL,+# a user-configured server) print only a verbose substep and owe no answer.+AUDIO_CPP_STEP = re.compile(r"^\s*audio\.cpp\s+\S", re.MULTILINE)# setup.sh's column-padded frontend line: a rebuild on a warm npm cache talks to no forbidden host,# so the log line is the only witness.FRONTEND_CURRENT_MARKER = re.compile(r"frontend\s+up to date")@@ -629,6 +633,7 @@ def snapshot(venv_python: pathlib.Path) -> dict:for marker in ("UNSLOTH_PREBUILT_INFO.json","UNSLOTH_WHISPER_PREBUILT_INFO.json",+ "UNSLOTH_AUDIO_CPP_PREBUILT_INFO.json","UNSLOTH_NODE_PREBUILT_INFO.json",):found = sorted(unsloth_home.glob(f"*/{marker}")) if unsloth_home.is_dir() else []@@ -648,6 +653,7 @@ def snapshot(venv_python: pathlib.Path) -> dict:"llama.cpp/**/llama-server*","llama.cpp/**/llama-quantize*","whisper.cpp/**/whisper-server*",+ "audio.cpp/**/audiocpp_server*","node/**/node*",):for path in unsloth_home.glob(pattern):@@ -666,8 +672,9 @@ def expected_prebuilt_answers(log: str) -> int:unless this run reported its release unpaired. Read from the run, not the disk: an installthat had a paired whisper.cpp keeps its binary when llama.cpp moves ahead, and the pairinggate rejects it all the same. Without the unpaired line a whisper.cpp that re-validated or- silently went missing leaves one answer short of two, and the count fails."""- return 1 if WHISPER_UNPAIRED.search(log) else 2+ silently went missing leaves one answer short of two, and the count fails. audio.cpp adds one+ whenever its step line shows its installer ran: "prebuilt installed" there is a re-download."""+ return (1 if WHISPER_UNPAIRED.search(log) else 2) + (1 if AUDIO_CPP_STEP.search(log) else 0)# ── run 1 and run 2 ──@@ -1259,6 +1266,23 @@ def test_without_the_unpaired_line_both_prebuilts_must_answer():assert expected_prebuilt_answers(" llama.cpp prebuilt up to date") == 2+def test_an_installed_audio_cpp_owes_one_more_answer():+ log = " llama.cpp prebuilt up to date\n whisper.cpp prebuilt up to date\n"+ assert expected_prebuilt_answers(log + " audio.cpp prebuilt up to date\n") == 3+ # A re-download still owes the answer it failed to give.+ assert expected_prebuilt_answers(log + " audio.cpp prebuilt installed\n") == 3+ # "audio.cpp" inside another line (a path, a skip substep) is not its step line.+ assert expected_prebuilt_answers(log + " [verbose] audio.cpp: install skipped\n") == 2+++def test_the_audio_cpp_step_pattern_matches_both_installers():+ root = pathlib.Path(__file__).resolve().parents[3]+ for script in ("studio/setup.sh", "studio/setup.ps1"):+ text = (root / script).read_text(encoding = "utf-8")+ assert 'step "audio.cpp" "prebuilt up to date"' in text, script+ assert 'step "audio.cpp" "update unavailable, existing prebuilt kept"' in text, script++def test_the_unpaired_pattern_matches_both_installers():root = pathlib.Path(__file__).resolve().parents[3]for script in ("studio/setup.sh", "studio/setup.ps1"):diff --git a/tests/studio/test_model_picker_contracts.py b/tests/studio/test_model_picker_contracts.pyindex 3c812ce0a18..e600cc02e50 100644--- a/tests/studio/test_model_picker_contracts.py+++ b/tests/studio/test_model_picker_contracts.py@@ -2109,13 +2109,18 @@ def test_staged_downloads_always_scope_their_files():it would finish instantly having fetched everything except the weights and leave therepo on device unloadable."""src = _read("features/hub/download-manager/use-staged-download.ts")- start = re.search(r"downloadManager\.requestStart\(\{.*?\}\);", src, re.S)+ # A GGUF quant entry goes out as the standard variant download (its plan brings companions);+ # every other entry is the scoped branch.+ start = re.search(r"downloadManager\.requestStart\(.*?\n \);", src, re.S)assert start, "requestStart call not found"body = start.group(0)# Unconditional: no branch may send a null scope or omit the files.assert "scopeId," in body and "files: current.files," in bodyassert "? null" not in body and "? undefined" not in body- assert "const activeVariant = current ? scopedVariant(scopeId) : null;" in src+ assert re.search(+ r"const activeVariant = current\s*\?\s*\(current\.ggufVariant \?\? scopedVariant\(scopeId\)\)\s*:\s*null;",+ src,+ )def test_staged_downloads_use_one_actionable_download_surface():@@ -2160,7 +2165,7 @@ def test_staged_plans_label_the_checkpoint_without_guessing_from_the_extension()staged = _read("features/hub/download-manager/use-staged-download.ts")assert "checkpoint?: boolean;" in staged- start = re.search(r"downloadManager\.requestStart\(\{.*?\}\);", staged, re.S)+ start = re.search(r"downloadManager\.requestStart\(.*?\n \);", staged, re.S)assert start, "requestStart call not found"assert "checkpoint: current.checkpoint," in start.group(0)diff --git a/tests/studio/test_uninstall_prebuilt_parity.ps1 b/tests/studio/test_uninstall_prebuilt_parity.ps1index 35fecb78141..aef57e7ddbd 100644--- a/tests/studio/test_uninstall_prebuilt_parity.ps1+++ b/tests/studio/test_uninstall_prebuilt_parity.ps1@@ -49,6 +49,21 @@ foreach ($artifact in $shArtifacts) {Check "uninstall.ps1 removes ~/.unsloth/$artifact" ($ps1Text -match [regex]::Escape($artifact))}+# Every install lock uninstall.sh removes from ~/.unsloth, uninstall.ps1 removes too (the lock+# list and the stale-lock pattern alike): one surviving lock blocks the ~/.unsloth prune.+$shLocks = [regex]::Matches($shText, '_remove_lock_file\s+"\$HOME/\.unsloth/\.([^"/]+)\.install\.lock"') |+ ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique+Check "found the POSIX lock list" ($shLocks -contains "audio.cpp")+$stalePattern = [regex]::Match($ps1Text, "StaleLockPattern = '([^']+)'").Groups[1].Value+foreach ($lock in $shLocks) {+ Check "uninstall.ps1 removes ~/.unsloth/.$lock.install.lock" ($ps1Text -match [regex]::Escape("`".$lock.install.lock`""))+ Check "uninstall.ps1 sweeps stale .$lock.install.lock" (".$lock.install.lock.stale.123" -match $stalePattern)+}++# audio.cpp's model link farm beside the Hugging Face hub cache goes on both sides.+Check "uninstall.sh removes the audio.cpp link farm" ($shText -match 'unsloth-audiocpp-links')+Check "uninstall.ps1 removes the audio.cpp link farm" ($ps1Text -match 'unsloth-audiocpp-links')+# The stale-lock sweep must exist on both sides: a crash between the rename and# the unlink in install_node_prebuilt.py strands a `.stale.<pid>` file, and that# alone blocks the ~/.unsloth prune.diff --git a/tests/test_installer_interactive_prompts.py b/tests/test_installer_interactive_prompts.pyindex 0fc499ee467..1695aea267c 100644--- a/tests/test_installer_interactive_prompts.py+++ b/tests/test_installer_interactive_prompts.py@@ -44,6 +44,7 @@ SCANNED_SCRIPTS = ENTRY_POINTS + ("scripts/install_rocm_wsl_strixhalo.sh","scripts/uninstall.sh","scripts/uninstall.ps1",+ "studio/install_audio_cpp_prebuilt.py","studio/install_lemonade_prebuilt.py","studio/install_llama_prebuilt.py","studio/install_manifest.py",diff --git a/tests/test_managed_tools_master_root.py b/tests/test_managed_tools_master_root.pyindex 6abdccdc342..47433faf796 100644--- a/tests/test_managed_tools_master_root.py+++ b/tests/test_managed_tools_master_root.py@@ -27,6 +27,14 @@ sys.path.insert(0, os.environ["_BACKEND"])from utils.paths import storage_roots as srfrom utils.node_runtime import managed_node_dirfrom core.inference.stt_ggml_sidecar import _managed_whisper_cpp_dir+from core.inference.audio_cpp_server import managed_audio_cpp_dir++# The audio.cpp installer runs before the backend is importable, so it keeps its own copy of the+# rule (default_install_dir); both have to land where setup's $UNSLOTH_HOME/audio.cpp does.+import importlib.util+_spec = importlib.util.spec_from_file_location("_audio_installer", os.environ["_AUDIO_INSTALLER"])+_audio_installer = importlib.util.module_from_spec(_spec)+_spec.loader.exec_module(_audio_installer)# studio_root() is called constantly, so a warning it emits for a supported# layout is not one line, it is a flooded log.@@ -38,6 +46,8 @@ print(json.dumps({"master": None if sr.unsloth_home() is None else str(sr.unsloth_home()),"node": str(managed_node_dir()),"whisper": str(_managed_whisper_cpp_dir()),+ "audio": str(managed_audio_cpp_dir()),+ "audio_installer": str(_audio_installer.default_install_dir()),"warnings": _warnings,}))"""@@ -49,6 +59,7 @@ def _resolve(env_overrides: dict[str, str], home: Path) -> dict[str, str]:"HOME": str(home),"USERPROFILE": str(home),"_BACKEND": str(BACKEND),+ "_AUDIO_INSTALLER": str(REPO / "studio" / "install_audio_cpp_prebuilt.py"),}# A hand-built environment has to carry what the interpreter needs: Windows python exits 1# with no usable message when SYSTEMROOT is absent, which read as "the resolver answered@@ -74,6 +85,7 @@ def test_portable_root_puts_the_tools_beside_studio(tmp_path):assert r["master"] == str(root)assert r["node"] == str(root / "node")assert r["whisper"] == str(root / "whisper.cpp")+ assert r["audio"] == r["audio_installer"] == str(root / "audio.cpp")def test_a_default_install_is_untouched(tmp_path):@@ -84,6 +96,7 @@ def test_a_default_install_is_untouched(tmp_path):assert r["studio"] == str(home / ".unsloth" / "studio")assert r["node"] == str(home / ".unsloth" / "node")assert r["whisper"] == str(home / ".unsloth" / "whisper.cpp")+ assert r["audio"] == r["audio_installer"] == str(home / ".unsloth" / "audio.cpp")def test_a_plain_custom_studio_home_is_untouched(tmp_path):@@ -96,6 +109,7 @@ def test_a_plain_custom_studio_home_is_untouched(tmp_path):assert r["studio"] == str(custom)assert r["node"] == str(custom / "node")assert r["whisper"] == str(custom / "whisper.cpp")+ assert r["audio"] == r["audio_installer"] == str(custom / "audio.cpp")def test_a_flat_root_keeps_the_tools_at_that_root(tmp_path):@@ -107,6 +121,7 @@ def test_a_flat_root_keeps_the_tools_at_that_root(tmp_path):assert r["studio"] == str(root)assert r["node"] == str(root / "node")assert r["whisper"] == str(root / "whisper.cpp")+ assert r["audio"] == r["audio_installer"] == str(root / "audio.cpp")# Path.parents excludes the path itself, so the equality check is what keeps this warning off.assert r["warnings"] == []@@ -158,9 +173,22 @@ def test_a_recorded_master_root_outlives_the_command_that_set_it(tmp_path):assert r["studio"] == str(studio)assert r["node"] == str(root / "node")assert r["whisper"] == str(root / "whisper.cpp")+ # The installer reads no note; setup.sh / setup.ps1 hand it --install-dir "$UNSLOTH_HOME/audio.cpp".+ assert r["audio"] == str(root / "audio.cpp")assert r["warnings"] == []+def test_setup_installs_audio_cpp_where_the_backend_looks():+ # Both shells name the directory outright, so the installer's own default never decides it.+ for script, needle in (+ ("studio/setup.sh", 'AUDIO_CPP_DIR="$UNSLOTH_HOME/audio.cpp"'),+ ("studio/setup.ps1", '$AudioCppDir = Join-Path $UnslothHome "audio.cpp"'),+ ):+ text = (REPO / script).read_text(encoding = "utf-8")+ assert needle in text, script+ assert "install_audio_cpp_prebuilt.py" in text and "--install-dir" in text, script++def test_a_note_whose_root_has_since_moved_is_ignored(tmp_path):# A note licenses this process to adopt a root for caches and runtimes both. One naming a# tree that is no longer there must not win over the layout in front of it.diff --git a/unsloth_cli/_system_dir_guard.py b/unsloth_cli/_system_dir_guard.pyindex 790dd15c0e2..54038007e8c 100644--- a/unsloth_cli/_system_dir_guard.py+++ b/unsloth_cli/_system_dir_guard.py@@ -294,8 +294,10 @@ _RELATIVE_PATH_ENV = ("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR","UNSLOTH_SD_CPP_PATH","UNSLOTH_WHISPER_CPP_PATH",+ "UNSLOTH_AUDIO_CPP_PATH","LLAMA_SERVER_PATH","WHISPER_SERVER_PATH",+ "AUDIOCPP_SERVER_PATH","SD_CLI_PATH","SD_SERVER_PATH",# Model files llama-server reads from the environment and Unsloth reads back when sizing a