Skip to content

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

Studio: say when the audio runtime is not the release Studio installs (#12809)

Etherl1135dbd8e6c7
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 3ad90b4fc25..e03689ac8a3 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -24280,26 +24280,67 @@ def _account_stt_status(status):
return status
+_AUDIO_CPP_RUNTIME_MISSING = {
+ "available": False,
+ "espeak": False,
+ "backend": None,
+ "release_tag": None,
+ "expected_tag": None,
+ "outdated": False,
+}
+
+
+def _audio_cpp_release_ladder() -> list:
+ studio_dir = str(Path(__file__).resolve().parents[2])
+ if studio_dir not in sys.path:
+ sys.path.insert(0, studio_dir)
+ import install_audio_cpp_prebuilt
+
+ return install_audio_cpp_prebuilt._release_ladder()
+
+
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}
+ return dict(_AUDIO_CPP_RUNTIME_MISSING)
record = audio_cpp_server.read_install_record(binary)
backend = record.get("backend")
release_tag = record.get("release_tag")
- return {
+ status = {
"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,
+ "expected_tag": None,
+ "outdated": False,
}
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}
+ return dict(_AUDIO_CPP_RUNTIME_MISSING)
+ # only the managed tree is updatable; setup skips it under any of these, whatever the path.
+ setup_skips = (
+ os.environ.get("AUDIOCPP_SERVER_PATH")
+ or os.environ.get("UNSLOTH_AUDIO_CPP_PATH")
+ or os.environ.get("UNSLOTH_SKIP_AUDIO_CPP_INSTALL") == "1"
+ )
+ try:
+ managed_dir = audio_cpp_server.managed_audio_cpp_dir().resolve()
+ managed = not setup_skips and (
+ Path(binary).resolve().is_relative_to(managed_dir)
+ and (managed_dir / ".unsloth-studio-owned").is_file()
+ )
+ ladder = _audio_cpp_release_ladder() if managed else []
+ except Exception as exc: # noqa: BLE001 - cannot tell is not outdated
+ logger.debug("audio.cpp release lookup failed: %s", exc)
+ ladder = []
+ # a None tag tracks the latest release, so an installed release cannot be compared.
+ if status["release_tag"] and ladder and all(tag for _, tag in ladder):
+ status["expected_tag"] = ladder[0][1]
+ status["outdated"] = (record.get("published_repo"), release_tag) not in ladder
+ return status
@studio_router.get("/audio/stt/status")
diff --git a/studio/backend/tests/test_audio_cpp_runtime_status.py b/studio/backend/tests/test_audio_cpp_runtime_status.py
index 1c7009903e0..d2546fd7ccd 100644
--- a/studio/backend/tests/test_audio_cpp_runtime_status.py
+++ b/studio/backend/tests/test_audio_cpp_runtime_status.py
@@ -6,6 +6,8 @@
import asyncio
import json
+import pytest
+
from core.inference import audio_cpp_server
from routes import inference
@@ -34,17 +36,21 @@ def test_runtime_available_with_espeak(monkeypatch):
"espeak": True,
"backend": "cuda",
"release_tag": "v0.4.0",
+ "expected_tag": None,
+ "outdated": False,
}
def test_runtime_available_without_espeak(monkeypatch):
- # A custom or upstream build: no install record, no eSpeak data beside the server.
+ # custom or upstream builds lack install records and 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,
+ "expected_tag": None,
+ "outdated": False,
}
@@ -55,6 +61,8 @@ def test_runtime_missing(monkeypatch):
"espeak": False,
"backend": None,
"release_tag": None,
+ "expected_tag": None,
+ "outdated": False,
}
@@ -77,6 +85,157 @@ def test_malformed_record_fields_are_dropped(monkeypatch):
assert status["backend"] is None and status["release_tag"] is None
+_LADDER = [("unslothai/audio.cpp", "v0.9.0-unsloth.1"), ("0xShug0/audio.cpp", "v0.9.0")]
+# setup.sh / setup.ps1 leave the managed tree alone when any of these is set.
+_SETUP_SKIPS = ("AUDIOCPP_SERVER_PATH", "UNSLOTH_AUDIO_CPP_PATH", "UNSLOTH_SKIP_AUDIO_CPP_INSTALL")
+
+
+def _managed(
+ monkeypatch,
+ tmp_path,
+ record,
+ ladder = _LADDER,
+):
+ """a Studio-managed install of ``record`` and the releases setup would install."""
+ for name in _SETUP_SKIPS:
+ monkeypatch.delenv(name, raising = False)
+ tmp_path.mkdir(parents = True, exist_ok = True)
+ (tmp_path / ".unsloth-studio-owned").touch()
+ _patch(monkeypatch, binary = str(tmp_path / "audiocpp_server"), record = record, espeak = True)
+ monkeypatch.setattr(audio_cpp_server, "managed_audio_cpp_dir", lambda: tmp_path)
+ monkeypatch.setattr(inference, "_audio_cpp_release_ladder", lambda: ladder)
+
+
+def test_managed_install_of_the_pinned_release_is_current(monkeypatch, tmp_path):
+ _managed(
+ monkeypatch,
+ tmp_path,
+ {"published_repo": "unslothai/audio.cpp", "release_tag": "v0.9.0-unsloth.1"},
+ )
+ status = inference._audio_cpp_runtime_status()
+ assert status["expected_tag"] == "v0.9.0-unsloth.1"
+ assert status["outdated"] is False
+
+
+def test_managed_fallback_install_is_current(monkeypatch, tmp_path):
+ # setup falls back to the upstream release when the fork cannot serve the host.
+ _managed(
+ monkeypatch, tmp_path, {"published_repo": "0xShug0/audio.cpp", "release_tag": "v0.9.0"}
+ )
+ assert inference._audio_cpp_runtime_status()["outdated"] is False
+
+
+def test_managed_install_of_an_old_release_is_outdated(monkeypatch, tmp_path):
+ # setup keeps the old tree when the release lookup fails after a pin bump.
+ _managed(
+ monkeypatch,
+ tmp_path,
+ {"published_repo": "unslothai/audio.cpp", "release_tag": "v0.8.0-unsloth.1"},
+ )
+ status = inference._audio_cpp_runtime_status()
+ assert status["release_tag"] == "v0.8.0-unsloth.1"
+ assert status["expected_tag"] == "v0.9.0-unsloth.1"
+ assert status["outdated"] is True
+
+
+def test_same_tag_from_another_repo_is_outdated(monkeypatch, tmp_path):
+ _managed(
+ monkeypatch, tmp_path, {"published_repo": "someone/audio.cpp", "release_tag": "v0.9.0"}
+ )
+ assert inference._audio_cpp_runtime_status()["outdated"] is True
+
+
+def test_latest_tracking_ladder_cannot_tell(monkeypatch, tmp_path):
+ # UNSLOTH_AUDIO_CPP_TAG='' tracks the latest release, which no record can be checked against.
+ _managed(
+ monkeypatch,
+ tmp_path,
+ {"published_repo": "unslothai/audio.cpp", "release_tag": "v0.8.0"},
+ ladder = [("unslothai/audio.cpp", None)],
+ )
+ status = inference._audio_cpp_runtime_status()
+ assert status["expected_tag"] is None and status["outdated"] is False
+
+
+def test_managed_install_without_a_tag_is_not_flagged(monkeypatch, tmp_path):
+ _managed(monkeypatch, tmp_path, {})
+ status = inference._audio_cpp_runtime_status()
+ assert status["release_tag"] is None and status["outdated"] is False
+
+
+def test_managed_path_without_ownership_marker_is_not_flagged(monkeypatch, tmp_path):
+ _managed(
+ monkeypatch,
+ tmp_path,
+ {"published_repo": "unslothai/audio.cpp", "release_tag": "v0.8.0-unsloth.1"},
+ )
+ (tmp_path / ".unsloth-studio-owned").unlink()
+ status = inference._audio_cpp_runtime_status()
+ assert status["available"] is True
+ assert status["expected_tag"] is None and status["outdated"] is False
+
+
+def test_user_configured_binary_is_never_outdated(monkeypatch, tmp_path):
+ # AUDIOCPP_SERVER_PATH, UNSLOTH_AUDIO_CPP_PATH or PATH: setup skips it, so updating cannot help.
+ _managed(
+ monkeypatch,
+ tmp_path / "managed",
+ {"published_repo": "unslothai/audio.cpp", "release_tag": "v0.8.0-unsloth.1"},
+ )
+ custom = str(tmp_path / "custom" / "audiocpp_server")
+ monkeypatch.setattr(audio_cpp_server, "find_audio_cpp_server_binary", lambda: custom)
+ status = inference._audio_cpp_runtime_status()
+ assert status["available"] is True
+ assert status["expected_tag"] is None and status["outdated"] is False
+
+
+ "name, value",
+ [
+ # A stale path makes discovery fall back to the managed tree.
+ ("AUDIOCPP_SERVER_PATH", "/gone/audiocpp_server"),
+ ("UNSLOTH_AUDIO_CPP_PATH", "<managed>"),
+ ("UNSLOTH_SKIP_AUDIO_CPP_INSTALL", "1"),
+ ],
+)
+def test_managed_binary_is_not_outdated_when_setup_skips_it(monkeypatch, tmp_path, name, value):
+ # An update would not touch the tree, so its notice could never clear.
+ _managed(
+ monkeypatch,
+ tmp_path,
+ {"published_repo": "unslothai/audio.cpp", "release_tag": "v0.8.0-unsloth.1"},
+ )
+ monkeypatch.setenv(name, str(tmp_path) if value == "<managed>" else value)
+ status = inference._audio_cpp_runtime_status()
+ assert status["available"] is True
+ assert status["expected_tag"] is None and status["outdated"] is False
+
+
+def test_release_lookup_error_is_not_outdated(monkeypatch, tmp_path):
+ _managed(
+ monkeypatch,
+ tmp_path,
+ {"published_repo": "unslothai/audio.cpp", "release_tag": "v0.8.0-unsloth.1"},
+ )
+
+ def boom():
+ raise ImportError("installer missing")
+
+ monkeypatch.setattr(inference, "_audio_cpp_release_ladder", boom)
+ status = inference._audio_cpp_runtime_status()
+ assert status["available"] is True and status["outdated"] is False
+
+
+def test_release_ladder_comes_from_the_installer(monkeypatch):
+ monkeypatch.delenv("UNSLOTH_AUDIO_CPP_REPO", raising = False)
+ monkeypatch.delenv("UNSLOTH_AUDIO_CPP_TAG", raising = False)
+ import install_audio_cpp_prebuilt as installer
+
+ ladder = inference._audio_cpp_release_ladder()
+ assert ladder[0] == (installer.DEFAULT_REPO, installer.DEFAULT_TAG)
+ assert (installer.UPSTREAM_FALLBACK_REPO, installer.UPSTREAM_FALLBACK_TAG) in ladder
+
+
def test_stt_status_payload_includes_runtime_block(monkeypatch):
_patch(
monkeypatch,
@@ -92,4 +251,6 @@ def test_stt_status_payload_includes_runtime_block(monkeypatch):
"espeak": False,
"backend": "vulkan",
"release_tag": "v0.4.0",
+ "expected_tag": None,
+ "outdated": False,
}
diff --git a/studio/frontend/src/features/audio/audio-cpp-catalog.ts b/studio/frontend/src/features/audio/audio-cpp-catalog.ts
index 1450a5f1dfe..f274764f047 100644
--- a/studio/frontend/src/features/audio/audio-cpp-catalog.ts
+++ b/studio/frontend/src/features/audio/audio-cpp-catalog.ts
@@ -33,19 +33,23 @@ export interface AudioCppModel {
id: string;
task: AudioCppTask;
workflows?: readonly AudioCppWorkflow[];
- /** ASR only: the primary language codes the model transcribes. Absent = multilingual. */
+ /** ASR only: primary language codes; absent means multilingual. */
languages?: readonly string[];
- /** Phonemizes with eSpeak-ng, which upstream runtime bundles lack (backend needs_espeak). */
+ /** uses eSpeak-ng phonemization, absent from upstream runtime bundles. */
needsEspeak?: boolean;
stems?: readonly string[];
}
-/** The `audio_cpp_runtime` block of /api/inference/audio/stt/status. */
+/** 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;
+ /** update target tag; null for unmanaged or unknown runtimes. */
+ expected_tag?: string | null;
+ /** managed runtime differs from the target; absent on older servers. */
+ outdated?: boolean;
}
const MB = 1024 * 1024;
diff --git a/studio/frontend/src/features/audio/audio-page-policy.ts b/studio/frontend/src/features/audio/audio-page-policy.ts
index 5991e416a26..576d43d2478 100644
--- a/studio/frontend/src/features/audio/audio-page-policy.ts
+++ b/studio/frontend/src/features/audio/audio-page-policy.ts
@@ -36,6 +36,15 @@ export function audioCppRuntimeProblem(
return null;
}
+/** setup keeps the old managed runtime when it cannot reach the release. */
+export function audioCppRuntimeUpdate(
+ runtime: AudioCppRuntimeStatus | null | undefined,
+): { installed: string; expected: string } | null {
+ if (!runtime?.available || !runtime.outdated) return null;
+ if (!runtime.release_tag || !runtime.expected_tag) return null;
+ return { installed: runtime.release_tag, expected: runtime.expected_tag };
+}
+
/** 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"]);
diff --git a/studio/frontend/src/features/audio/audio-page.tsx b/studio/frontend/src/features/audio/audio-page.tsx
index ad217a64e73..d39cff4678f 100644
--- a/studio/frontend/src/features/audio/audio-page.tsx
+++ b/studio/frontend/src/features/audio/audio-page.tsx
@@ -4,7 +4,7 @@
// Stays mounted across tab switches (__root.tsx), so `active` gates polling, popovers and the recorder.
import { TestTubeOutlineIcon } from "@/lib/hugeicons-derived";
-import { SparklesIcon } from "@hugeicons/core-free-icons";
+import { Alert02Icon, SparklesIcon } from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";
import { LibraryPageLink } from "@/components/media-page-link";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -323,6 +323,7 @@ export function AudioPage({
selectedSttRepoRef,
sttStatusRefreshGeneration,
audioCppRuntime,
+ runtimeUpdate,
sttLoadGeneration,
sttGgufVariants,
setLastSttRepo,
@@ -1688,10 +1689,9 @@ export function AudioPage({
settingsFadeClass,
)}
>
- {/* One child, so the scroll fades see the rail grow (they watch only the first child): with
- the heading first, opening Advanced left the bottom fade over the last controls. */}
+ {/* keep one child because scroll fades watch only the first child. */}
<div className="flex flex-col gap-4">
- {/* Same heading treatment as the Images and Video Create panes, so the media panes stay level (#7986). */}
+ {/* match Images and Video headings to keep media panes level (#7986). */}
<div className="mb-2 grid gap-1.5">
<WorkflowTitleMenu
workflow={pageWorkflow}
@@ -1703,6 +1703,31 @@ export function AudioPage({
<p className="text-xs leading-snug text-muted-foreground">
{capabilityLine}
</p>
+ {runtimeUpdate ? (
+ <p
+ role="status"
+ className="mt-1 flex items-start gap-1.5 text-ui-12 leading-snug text-foreground"
+ >
+ <HugeiconsIcon
+ icon={Alert02Icon}
+ className="mt-0.5 size-3.5 shrink-0 text-muted-foreground"
+ />
+ <span>
+ Your audio runtime is{" "}
+ <span className="whitespace-nowrap">
+ {runtimeUpdate.installed}
+ </span>
+ ; this Studio expects{" "}
+ <span className="whitespace-nowrap">
+ {runtimeUpdate.expected}
+ </span>
+ . Some models may not work until you update. Stop Studio,{" "}
+ run{" "}
+ <code className="font-mono">unsloth studio update</code>,
+ then start Studio again.
+ </span>
+ </p>
+ ) : null}
</div>
{mode === "speak" ? (
diff --git a/studio/frontend/src/features/audio/hooks/use-stt-sidecar.ts b/studio/frontend/src/features/audio/hooks/use-stt-sidecar.ts
index a0be8df6a36..5827b43b0cd 100644
--- a/studio/frontend/src/features/audio/hooks/use-stt-sidecar.ts
+++ b/studio/frontend/src/features/audio/hooks/use-stt-sidecar.ts
@@ -19,6 +19,7 @@ import { usePersistedChoice } from "@/hooks/use-persisted-choice";
import { toast } from "@/lib/toast";
import type { AudioCppRuntimeStatus } from "../audio-cpp-catalog";
import {
+ audioCppRuntimeUpdate,
reconcileSttSelection,
resolveSttResidency,
type SttDownloadedArtifact,
@@ -52,6 +53,9 @@ export function useSttSidecar({
selectedSttRepoRef.current = selectedSttRepo;
const sttStatusRefreshGeneration = useRef(0);
const audioCppRuntime = useRef<AudioCppRuntimeStatus | null>(null);
+ // state drives the page display; the ref only gates a pick.
+ const [runtimeUpdate, setRuntimeUpdate] =
+ useState<ReturnType<typeof audioCppRuntimeUpdate>>(null);
const sttLoadGeneration = useRef(0);
const sttGgufVariants = useRef(
new Map<string, string>(
@@ -91,6 +95,13 @@ export function useSttSidecar({
);
if (generation !== sttStatusRefreshGeneration.current) return;
audioCppRuntime.current = stt.audio_cpp_runtime ?? null;
+ const nextUpdate = audioCppRuntimeUpdate(audioCppRuntime.current);
+ setRuntimeUpdate((current) =>
+ current?.installed === nextUpdate?.installed &&
+ current?.expected === nextUpdate?.expected
+ ? current
+ : nextUpdate,
+ );
const nextDownloadedArtifacts = sttDownloadedArtifacts(
stt,
sttRepoIdForSidecarKey,
@@ -298,6 +309,7 @@ export function useSttSidecar({
selectedSttRepoRef,
sttStatusRefreshGeneration,
audioCppRuntime,
+ runtimeUpdate,
sttLoadGeneration,
sttGgufVariants,
setLastSttRepo,
diff --git a/studio/frontend/tests/audio-cpp-catalog.test.ts b/studio/frontend/tests/audio-cpp-catalog.test.ts
index 1353e28280b..330d97f0913 100644
--- a/studio/frontend/tests/audio-cpp-catalog.test.ts
+++ b/studio/frontend/tests/audio-cpp-catalog.test.ts
@@ -27,6 +27,7 @@ import {
import {
MINIMAX_MUSIC_MAX_SECONDS,
audioCppRuntimeProblem,
+ audioCppRuntimeUpdate,
audioSamplingControlsApply,
isGgufTtsTarget,
isTtsAudioType,
@@ -564,6 +565,42 @@ test("recommended speech and music picks are refused when the runtime cannot run
);
});
+test("an outdated managed runtime names both releases; anything else shows no notice", () => {
+ const current = {
+ available: true,
+ espeak: true,
+ backend: "cuda",
+ release_tag: "v0.9.0-unsloth.1",
+ expected_tag: "v0.9.0-unsloth.1",
+ outdated: false,
+ };
+ const outdated = { ...current, release_tag: "v0.8.0-unsloth.1", outdated: true };
+ assert.deepEqual(audioCppRuntimeUpdate(outdated), {
+ installed: "v0.8.0-unsloth.1",
+ expected: "v0.9.0-unsloth.1",
+ });
+ assert.equal(audioCppRuntimeUpdate(current), null);
+ assert.equal(audioCppRuntimeUpdate(null), null);
+ assert.equal(audioCppRuntimeUpdate(undefined), null);
+ // support servers older than these fields or unable to name either release.
+ assert.equal(
+ audioCppRuntimeUpdate({ available: true, espeak: true, backend: null, release_tag: "v0.8.0" }),
+ null,
+ );
+ assert.equal(audioCppRuntimeUpdate({ ...outdated, expected_tag: null }), null);
+ assert.equal(audioCppRuntimeUpdate({ ...outdated, release_tag: null }), null);
+ assert.equal(audioCppRuntimeUpdate({ ...outdated, available: false }), null);
+ const route = readText("../../backend/routes/inference.py");
+ assert.match(route, /"expected_tag": None,\s*"outdated": False,/);
+ const page = readAudioWorkspaceSource();
+ assert.match(page, /const nextUpdate = audioCppRuntimeUpdate\(audioCppRuntime\.current\);/);
+ assert.match(page, /\{runtimeUpdate \? \(/);
+ assert.match(
+ page,
+ /Stop Studio,\{" "\}\s*run\{" "\}\s*<code className="font-mono">unsloth studio update<\/code>,\s*then start Studio again\./,
+ );
+});
+
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");