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: 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.pyindex 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_serverbinary = 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 probelogger.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.pyindex 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 asyncioimport json+import pytest+from core.inference import audio_cpp_serverfrom 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.tsindex 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.tsindex 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.tsxindex 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"><WorkflowTitleMenuworkflow={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.tsindex 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.tsindex 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");