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: keep the Transcribe loaded state and Eject in step with the sidecar (#13514)

Etherl6aaa1f36fa73
diff --git a/studio/backend/core/inference/stt_audiocpp_sidecar.py b/studio/backend/core/inference/stt_audiocpp_sidecar.py
index e02699077d1..28f2627b1d0 100644
--- a/studio/backend/core/inference/stt_audiocpp_sidecar.py
+++ b/studio/backend/core/inference/stt_audiocpp_sidecar.py
@@ -173,9 +173,7 @@ def resolve_audio_cpp_stt_model(
)
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."
- )
+ raise SttModelNotDownloadedError(f"STT model '{base}' is not downloaded yet.")
if found is None:
raise SttModelIdError(
f"STT model '{model}' is not an audio GGUF the audio runtime can transcribe with."
@@ -188,8 +186,7 @@ def resolve_audio_cpp_stt_model(
row = resolve(base, None, hf_token, network = False)
if row is not None and row.task == "asr" and row.unsupported is None:
raise SttModelNotDownloadedError(
- f"STT model '{base}' ({variant or ref_variant}) is not downloaded. Download "
- "it in Settings, then Voice, before loading it."
+ f"STT model '{base}' ({variant or ref_variant}) is not downloaded yet."
) from exc
raise SttModelIdError(str(exc)) from exc
return found
@@ -689,8 +686,9 @@ class AudioCppSttSidecar:
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)
+ # Row ids on both sides: a legacy key and its folder id name the same model,
+ # and hub ids match case-insensitively.
+ return current.casefold() == acm_row_id(expected).casefold()
except Exception: # noqa: BLE001 - an unresolvable name is not this model
return False
@@ -763,8 +761,7 @@ class AudioCppSttSidecar:
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."
+ f"STT model '{model.display_name}' ({model.variant.key}) is not downloaded yet."
) from None
except AudioCppUnavailableError as exc:
# A path the runtime cannot open (Windows MAX_PATH) is a runtime limit, not a missing download.
diff --git a/studio/backend/core/inference/stt_ggml_sidecar.py b/studio/backend/core/inference/stt_ggml_sidecar.py
index 14454f359ed..48638dbb737 100644
--- a/studio/backend/core/inference/stt_ggml_sidecar.py
+++ b/studio/backend/core/inference/stt_ggml_sidecar.py
@@ -987,8 +987,7 @@ class GgmlSttSidecar:
path = _cached_model_path(model_id)
if path is None:
raise SttModelNotDownloadedError(
- f"STT model '{model_id}' (GGUF) is not downloaded. "
- "Download it in Settings, then Voice, before loading it."
+ f"STT model '{model_id}' (GGUF) is not downloaded yet."
)
return path
diff --git a/studio/backend/core/inference/stt_mtmd_sidecar.py b/studio/backend/core/inference/stt_mtmd_sidecar.py
index 9b56f4ec0ce..9dbe23f5ed8 100644
--- a/studio/backend/core/inference/stt_mtmd_sidecar.py
+++ b/studio/backend/core/inference/stt_mtmd_sidecar.py
@@ -832,10 +832,7 @@ class MtmdSttSidecar:
def _ensure_model_downloaded(self, model_id: str) -> tuple[str, str]:
paths = _cached_model_paths(model_id)
if paths is None:
- raise SttModelNotDownloadedError(
- f"STT model '{model_id}' is not downloaded. "
- "Download it in Settings, then Voice, before loading it."
- )
+ raise SttModelNotDownloadedError(f"STT model '{model_id}' is not downloaded yet.")
return paths
def load(
diff --git a/studio/backend/core/inference/stt_sidecar.py b/studio/backend/core/inference/stt_sidecar.py
index b4bb238caca..aa5c15d0281 100644
--- a/studio/backend/core/inference/stt_sidecar.py
+++ b/studio/backend/core/inference/stt_sidecar.py
@@ -1517,10 +1517,7 @@ class WhisperSttSidecar:
)
snapshot_path = _find_complete_cached_snapshot(model_id)
if snapshot_path is None:
- raise SttModelNotDownloadedError(
- f"STT model '{model_id}' is not downloaded. "
- "Download it in Settings, then Voice, before loading it."
- )
+ raise SttModelNotDownloadedError(f"STT model '{model_id}' is not downloaded yet.")
if model_id in STT_MODELS:
return _CachedSttSnapshot(path = snapshot_path, is_multilingual = True)
@@ -1599,8 +1596,7 @@ class WhisperSttSidecar:
snapshot_path = cached.path
if snapshot_path is None:
raise SttModelNotDownloadedError(
- f"STT model '{model_id}' is not downloaded. "
- "Download it in Settings, then Voice, before loading it."
+ f"STT model '{model_id}' is not downloaded yet."
)
self._raise_if_load_cancelled(cancel_event)
device, dtype = _pick_device(preference)
@@ -1616,8 +1612,7 @@ class WhisperSttSidecar:
def not_downloaded(cause: BaseException) -> SttModelNotDownloadedError:
return SttModelNotDownloadedError(
- f"STT model '{model_id}' is not downloaded. "
- "Download it in Settings, then Voice, before loading it."
+ f"STT model '{model_id}' is not downloaded yet."
)
retry_on_cpu = False
@@ -1883,10 +1878,10 @@ class WhisperSttSidecar:
current = self._model_id
if current is None:
return False
- if current == expected:
+ if current.casefold() == expected.casefold():
return True
try:
- return current == resolve_model_id(expected)
+ return current.casefold() == resolve_model_id(expected).casefold()
except Exception: # noqa: BLE001 - an unresolvable name is not this model
return False
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 1049fc206d8..5ade0daca64 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -24915,6 +24915,14 @@ def _stt_sidecar_for(engine: str):
return stt_registry.sidecar_for(engine)
+def _stt_resident_model(engine: str) -> Optional[str]:
+ """The model an engine holds right now, or None when that cannot be read."""
+ try:
+ return _stt_sidecar_for(engine).loaded_model
+ except Exception: # noqa: BLE001 - a broken sidecar holds nothing we can report
+ return None
+
+
def _stt_lifecycle() -> tuple:
"""(load, unload) for dictation models, off the orchestrator when it exists.
@@ -25481,6 +25489,10 @@ async def stt_unload(
f"stt:{candidate}", _stt_sidecar_for(candidate).loaded_model
)
]
+ from core.inference.stt_registry import STT_ENGINES
+
+ targets = list(STT_ENGINES if engines is None else engines)
+ before = {name: _stt_resident_model(name) for name in targets}
# Every engine is attempted even if one raises, so failing to free one never
# skips the other (both can be resident after a switch).
_, unload_stt = _stt_lifecycle()
@@ -25497,7 +25509,12 @@ async def stt_unload(
status_code = 500,
detail = f"Failed to unload STT engine(s): {', '.join(failed)}",
)
- return JSONResponse(content = {"loaded_model": None, "device": None})
+ # The sidecar keeps a model it does not recognise as the claimed one (or one
+ # mid-request under wait=false, or one swapped in before its lock), so report
+ # whether an engine that held a model is actually empty now.
+ held = [name for name, model_id in before.items() if model_id is not None]
+ released = not held or any(_stt_resident_model(name) is None for name in held)
+ return JSONResponse(content = {"loaded_model": None, "device": None, "released": released})
async def _transcribe_audio_bytes(
diff --git a/studio/backend/tests/test_stt_registry.py b/studio/backend/tests/test_stt_registry.py
index dabd5714ff4..4ce10832a35 100644
--- a/studio/backend/tests/test_stt_registry.py
+++ b/studio/backend/tests/test_stt_registry.py
@@ -551,3 +551,123 @@ def test_the_registry_passes_the_claimed_model_to_each_sidecar(monkeypatch):
)
stt_registry.unload(["gguf"], expected_model = "small")
assert seen == [("gguf", "small")]
+
+
+def test_a_scoped_unload_matches_a_custom_repo_case_insensitively():
+ from core.inference.stt_sidecar import WhisperSttSidecar
+
+ sidecar = WhisperSttSidecar.__new__(WhisperSttSidecar)
+ sidecar._lock = threading.RLock()
+ sidecar._model_id = "SomeOrg/Whisper-Custom"
+ released = []
+ sidecar._release_engine_locked = lambda: released.append(True)
+
+ WhisperSttSidecar.unload(sidecar, expected_model = "someorg/other-whisper")
+ assert released == []
+ WhisperSttSidecar.unload(sidecar, expected_model = "someorg/whisper-custom")
+ assert released == [True]
+
+
+_ACM_ID = "audio-cpp/audio.cpp-gguf/Qwen3-ASR-0.6B-GGUF"
+
+
+class _FakeAudioCppServer:
+ backend = "cpu"
+
+ def __init__(self):
+ self.stopped = False
+
+ def alive(self):
+ return not self.stopped
+
+ def stop(self):
+ self.stopped = True
+
+
+def _resident_audiocpp(model_id: str = _ACM_ID, loaded_as = None):
+ from core.inference.stt_audiocpp_sidecar import AudioCppSttSidecar
+
+ sidecar = AudioCppSttSidecar(keep_alive_seconds = 999)
+ sidecar._server = _FakeAudioCppServer()
+ sidecar._model_id = model_id
+ sidecar._loaded_as = loaded_as
+ return sidecar
+
+
+ "model_id, loaded_as, expected",
+ [
+ (_ACM_ID, None, _ACM_ID.lower()),
+ (_ACM_ID.lower(), None, _ACM_ID),
+ (_ACM_ID, "audiocpp-qwen3-asr-0.6b", "audiocpp-qwen3-asr-0.6b"),
+ (_ACM_ID, None, _ACM_ID + ":Q8_0"),
+ ],
+)
+def test_an_audiocpp_scoped_unload_releases_the_same_model_under_any_spelling(
+ model_id, loaded_as, expected
+):
+ sidecar = _resident_audiocpp(model_id, loaded_as)
+ sidecar.unload(expected_model = expected)
+ assert sidecar.loaded_model is None
+
+
+def test_an_audiocpp_scoped_unload_keeps_a_different_folder():
+ sidecar = _resident_audiocpp()
+ sidecar.unload(expected_model = "audio-cpp/audio.cpp-gguf/Whisper-Large-v3-GGUF")
+ assert sidecar.loaded_model == _ACM_ID
+
+
+def _unload_route(monkeypatch, sidecar, model):
+ import asyncio
+ import json
+
+ import routes.inference as ri
+
+ monkeypatch.setattr(ri, "_resolve_serving_stt_engine", lambda engine: engine)
+ monkeypatch.setattr(stt_registry, "sidecar_for", lambda engine: sidecar)
+ response = asyncio.run(ri.stt_unload(engine = "audiocpp", model = model, current_subject = "tester"))
+ assert response.status_code == 200
+ return json.loads(response.body)
+
+
+def test_the_unload_route_reports_a_release_for_a_lowercased_id(monkeypatch):
+ sidecar = _resident_audiocpp()
+ body = _unload_route(monkeypatch, sidecar, _ACM_ID.lower())
+ assert body == {"loaded_model": None, "device": None, "released": True}
+ assert sidecar.loaded_model is None
+
+
+def test_the_unload_route_reports_a_model_it_kept(monkeypatch):
+ sidecar = _resident_audiocpp()
+ body = _unload_route(monkeypatch, sidecar, "audio-cpp/audio.cpp-gguf/Whisper-Large-v3-GGUF")
+ assert body["released"] is False
+ assert "loaded_model" in body and "device" in body
+ assert sidecar.loaded_model == _ACM_ID
+
+
+def test_the_unload_route_reports_a_replacement_as_kept(monkeypatch):
+ # Another surface swaps in a new model between the route's snapshot and the sidecar lock.
+ sidecar = _resident_audiocpp()
+ unload = sidecar.unload
+ other = "audio-cpp/audio.cpp-gguf/Whisper-Large-v3-GGUF"
+
+ def replaced_then_unload(*args, **kwargs):
+ sidecar._model_id = other
+ return unload(*args, **kwargs)
+
+ sidecar.unload = replaced_then_unload
+ body = _unload_route(monkeypatch, sidecar, _ACM_ID)
+ assert body["released"] is False
+ assert sidecar.loaded_model == other
+
+
+def test_no_stt_sidecar_points_at_a_settings_path_for_downloads():
+ from pathlib import Path
+ inference = Path(__file__).resolve().parents[1] / "core" / "inference"
+ for name in (
+ "stt_audiocpp_sidecar.py",
+ "stt_ggml_sidecar.py",
+ "stt_mtmd_sidecar.py",
+ "stt_sidecar.py",
+ ):
+ assert "Settings, then Voice" not in (inference / name).read_text(encoding = "utf-8"), name
diff --git a/studio/frontend/src/features/audio/audio-page-policy.ts b/studio/frontend/src/features/audio/audio-page-policy.ts
index 8878be15971..37814c241e9 100644
--- a/studio/frontend/src/features/audio/audio-page-policy.ts
+++ b/studio/frontend/src/features/audio/audio-page-policy.ts
@@ -569,20 +569,68 @@ export function persistedClipForGeneration<T extends { id: string }>(
return clipId ? (refreshed.find((clip) => clip.id === clipId) ?? null) : null;
}
+/** Compare a picker row with the sidecar's resident name by row id. A legacy dictation key
+ * (`audiocpp-qwen3-asr-0.6b`) names the same folder as the Transcribe row, and ids differ in case. */
+export function sttSameModel(
+ selectedRepo: string,
+ loadedModel: string,
+ sidecarKeyFor: (repoId: string) => string,
+ engine?: SttEngine | null,
+ repoIdForSidecarKey?: (sidecarKey: string, engine?: SttEngine) => string,
+): boolean {
+ if (loadedModel === sidecarKeyFor(selectedRepo)) return true;
+ if (!repoIdForSidecarKey) return false;
+ const rowId = (id: string) =>
+ repoIdForSidecarKey(id, engine ?? undefined).trim().toLowerCase();
+ return rowId(loadedModel) === rowId(sidecarKeyFor(selectedRepo));
+}
+
export function sttSelectionReady(
selectedRepo: string | null,
loadedModel: string | null,
sidecarKeyFor: (repoId: string) => string,
selectedEngine?: SttEngine | null,
loadedEngine?: SttEngine | null,
+ repoIdForSidecarKey?: (sidecarKey: string, engine?: SttEngine) => string,
): boolean {
return Boolean(
selectedRepo &&
- loadedModel === sidecarKeyFor(selectedRepo) &&
+ loadedModel &&
+ sttSameModel(
+ selectedRepo,
+ loadedModel,
+ sidecarKeyFor,
+ loadedEngine ?? selectedEngine,
+ repoIdForSidecarKey,
+ ) &&
(!selectedEngine || !loadedEngine || selectedEngine === loadedEngine),
);
}
+/** Eject only what is resident: the selector keeps showing the last Transcribe model after an
+ * unload, and an Eject there had nothing to release. */
+export function audioEjectAvailable({
+ mode,
+ busy,
+ hasValue,
+ showLastPageModel,
+ sttReady,
+}: {
+ mode: string;
+ busy: AudioBusy;
+ hasValue: boolean;
+ showLastPageModel: boolean;
+ sttReady: boolean;
+}): boolean {
+ if (!hasValue || busy !== null || showLastPageModel) return false;
+ return mode !== "transcribe" || sttReady;
+}
+
+/** Older backends return no `released` flag; treat that as released, like before. */
+export function sttEjectSucceeded(released: boolean | undefined): boolean {
+ return released !== false;
+}
+
type SttEngineResidency = {
loaded_model?: string | null;
loading?: boolean;
@@ -677,7 +725,13 @@ export function reconcileSttSelection({
if (loadedModel) {
if (
selectedRepo &&
- sidecarKeyFor(selectedRepo) === loadedModel &&
+ sttSameModel(
+ selectedRepo,
+ loadedModel,
+ sidecarKeyFor,
+ loadedEngine,
+ repoIdForSidecarKey,
+ ) &&
(!loadedEngine ||
!engineForRepo ||
engineForRepo(selectedRepo) === loadedEngine)
diff --git a/studio/frontend/src/features/audio/audio-page.tsx b/studio/frontend/src/features/audio/audio-page.tsx
index b9defd9fe18..2647be1c83a 100644
--- a/studio/frontend/src/features/audio/audio-page.tsx
+++ b/studio/frontend/src/features/audio/audio-page.tsx
@@ -40,6 +40,7 @@ import {
import {
type AudioBusy,
type AudioGenerationPhase,
+ audioEjectAvailable,
audioGenerationPresentation,
} from "./audio-page-policy";
import { clipReference } from "./audio-run-request";
@@ -327,6 +328,8 @@ export function AudioPage({
runtimeUpdate,
sttLoadGeneration,
sttGgufVariants,
+ sttEngines,
+ sttEngineFor,
setLastSttRepo,
sttLoadingGeneration,
sttLoadAbort,
@@ -335,6 +338,8 @@ export function AudioPage({
sttSelected,
sttReady,
releaseTranscribeSelection,
+ ejectTranscribeModel,
+ readSttResidency,
ensureSttLoaded,
} = useSttSidecar({ setBusy, activeRef });
@@ -372,6 +377,9 @@ export function AudioPage({
ensureSttLoaded,
setLastSttRepo,
refreshSttStatus,
+ sttEngineFor,
+ readSttResidency,
+ sttLoadGeneration,
});
const {
@@ -479,8 +487,13 @@ export function AudioPage({
isMac,
status,
releaseTranscribeSelection,
+ ejectTranscribeModel,
ensureSttLoaded,
sttGgufVariants,
+ sttEngines,
+ sttEngineFor,
+ refreshSttStatus,
+ sttLoadedModel,
selectedSttRepoRef,
setSelectedSttRepo,
deferredSttLoad,
@@ -1254,7 +1267,10 @@ export function AudioPage({
string | null
>(null);
const transcribeRepo = (selectedSttRepo ?? lastSttRepo) || null;
- const transcribeCaps = useTranscribeCapabilities(transcribeRepo);
+ const transcribeCaps = useTranscribeCapabilities(
+ transcribeRepo,
+ transcribeRepo ? sttEngineFor(transcribeRepo) : null,
+ );
const transcribeOptions = transcribeSwitches(
transcribeCaps.caps,
transcribePrefs,
@@ -1604,7 +1620,13 @@ export function AudioPage({
value={selectorValue}
onValueChange={handleModelSelect}
onEject={
- busy === null && selectorValue && !showLastPageModel
+ audioEjectAvailable({
+ mode,
+ busy,
+ hasValue: Boolean(selectorValue),
+ showLastPageModel,
+ sttReady,
+ })
? handleEject
: undefined
}
diff --git a/studio/frontend/src/features/audio/hooks/use-audio-handoff.ts b/studio/frontend/src/features/audio/hooks/use-audio-handoff.ts
index 2d95d20ffd8..9fcdd0dc58f 100644
--- a/studio/frontend/src/features/audio/hooks/use-audio-handoff.ts
+++ b/studio/frontend/src/features/audio/hooks/use-audio-handoff.ts
@@ -6,8 +6,17 @@ import { translate } from "@/i18n";
import { loadGalleryUntil } from "@/lib/gallery-deep-link";
import { toast } from "@/lib/toast";
import { useNavigate, useSearch } from "@tanstack/react-router";
-import { audioRouteIntent, audioWorkflowForPick } from "../route-search";
-import { clipWorkflow, isAudioWorkflowId } from "../workflows";
+import {
+ audioRouteIntent,
+ audioWorkflowForPick,
+ audioWorkflowUrlAction,
+} from "../route-search";
+import { useAudioWorkspaceStore } from "../stores/audio-workspace-store";
+import {
+ type AudioWorkflowId,
+ clipWorkflow,
+ isAudioWorkflowId,
+} from "../workflows";
import type { AudioHostState } from "./audio-host-state";
import { type AudioGallery, galleryCache } from "./use-audio-gallery";
import type { AudioModelSlot } from "./use-audio-model-slot";
@@ -40,20 +49,63 @@ export function useAudioHandoff({
gguf?: boolean;
item?: string;
};
+ const committedWorkflow = useAudioWorkspaceStore((state) => state.workflow);
const handledRouteModel = useRef<string | null>(null);
+ // The workflow the URL and the page last agreed on; cleared while hidden, so back/forward
+ // into Audio reads the URL as a request.
+ const lastSyncedWorkflow = useRef<AudioWorkflowId | null>(null);
+ // A write the router has not rendered yet: until it lands, the old URL is not a request.
+ const pendingWrite = useRef<{ from: AudioWorkflowId | null } | null>(null);
useEffect(() => {
- if (!active) return;
+ if (!active) {
+ lastSyncedWorkflow.current = null;
+ pendingWrite.current = null;
+ return;
+ }
const wanted = routeSearch.model;
if (!wanted) {
handledRouteModel.current = null;
// An explicit workflow, else the one the task names (text-to-audio is Music).
- const routedWorkflow = audioRouteIntent(routeSearch);
- if (routedWorkflow === null) return;
- // Left in the URL when refused, so it retries once busy releases.
- if (!transitionWorkflow(routedWorkflow)) return;
- void navigateSelf({ to: "/audio", search: {}, replace: true });
+ const urlWorkflow = audioRouteIntent(routeSearch);
+ if (pendingWrite.current !== null) {
+ if (urlWorkflow === pendingWrite.current.from) return;
+ pendingWrite.current = null;
+ }
+ const action = audioWorkflowUrlAction({
+ urlWorkflow,
+ lastSynced: lastSyncedWorkflow.current,
+ committed: committedWorkflow,
+ hasModel: false,
+ hasItem: Boolean(routeSearch.item),
+ });
+ if (action.kind === "none") {
+ if (urlWorkflow === committedWorkflow) {
+ lastSyncedWorkflow.current = urlWorkflow;
+ }
+ return;
+ }
+ if (action.kind === "intent") {
+ // Left in the URL when refused, so it retries once busy releases.
+ if (!transitionWorkflow(action.workflow)) return;
+ lastSyncedWorkflow.current = action.workflow;
+ // Only the page stays: ?task= and other leftovers go with the request.
+ void navigateSelf({
+ to: "/audio",
+ search: { workflow: action.workflow },
+ replace: true,
+ });
+ return;
+ }
+ lastSyncedWorkflow.current = action.workflow;
+ pendingWrite.current = { from: urlWorkflow };
+ void navigateSelf({
+ to: "/audio",
+ search: (prev) => ({ ...prev, workflow: action.workflow }),
+ replace: true,
+ });
return;
}
+ pendingWrite.current = null;
const key = `${wanted}|${routeSearch.quant ?? ""}|${routeSearch.ggufQuant ?? ""}|${routeSearch.task ?? ""}|${routeSearch.audioType ?? ""}|${routeSearch.loadId ?? ""}|${routeSearch.gguf ? "gguf" : ""}|${routeSearch.workflow ?? ""}`;
if (handledRouteModel.current === key) return;
if (busyRef.current !== null) return;
@@ -89,10 +141,18 @@ export function useAudioHandoff({
: undefined,
pipelineTag: routeSearch.task ?? null,
});
- void navigateSelf({ to: "/audio", search: {}, replace: true });
+ // The page stays in the URL, so a reload reopens it.
+ const settledWorkflow = routedWorkflow ?? committedWorkflow;
+ lastSyncedWorkflow.current = settledWorkflow;
+ void navigateSelf({
+ to: "/audio",
+ search: { workflow: settledWorkflow },
+ replace: true,
+ });
}, [
active,
busy,
+ committedWorkflow,
routeSearch.model,
routeSearch.quant,
routeSearch.ggufQuant,
@@ -101,6 +161,7 @@ export function useAudioHandoff({
routeSearch.audioType,
routeSearch.loadId,
routeSearch.gguf,
+ routeSearch.item,
handleModelSelect,
navigateSelf,
transitionWorkflow,
diff --git a/studio/frontend/src/features/audio/hooks/use-audio-model-slot.ts b/studio/frontend/src/features/audio/hooks/use-audio-model-slot.ts
index 744b5ebb541..0976cca9e7f 100644
--- a/studio/frontend/src/features/audio/hooks/use-audio-model-slot.ts
+++ b/studio/frontend/src/features/audio/hooks/use-audio-model-slot.ts
@@ -71,6 +71,8 @@ import {
import type { AudioHostState } from "./audio-host-state";
import type { SttSidecar } from "./use-stt-sidecar";
+const STT_STATUS_POLL_MS = 30_000;
+
export function useAudioModelSlot({
active,
activeRef,
@@ -87,8 +89,13 @@ export function useAudioModelSlot({
isMac,
status,
releaseTranscribeSelection,
+ ejectTranscribeModel,
ensureSttLoaded,
sttGgufVariants,
+ sttEngines,
+ sttEngineFor,
+ refreshSttStatus,
+ sttLoadedModel,
selectedSttRepoRef,
setSelectedSttRepo,
deferredSttLoad,
@@ -119,8 +126,13 @@ export function useAudioModelSlot({
Pick<
SttSidecar,
| "releaseTranscribeSelection"
+ | "ejectTranscribeModel"
| "ensureSttLoaded"
| "sttGgufVariants"
+ | "sttEngines"
+ | "sttEngineFor"
+ | "refreshSttStatus"
+ | "sttLoadedModel"
| "selectedSttRepoRef"
| "setSelectedSttRepo"
| "deferredSttLoad"
@@ -698,7 +710,7 @@ export function useAudioModelSlot({
? {
repoId,
sidecarKey: sttSidecarKeyFor(repoId),
- engine: sttEngineForRepoId(repoId),
+ engine: sttEngineFor(repoId),
}
: null;
sttLoadGeneration.current += 1;
@@ -782,6 +794,7 @@ export function useAudioModelSlot({
if (!transitionMode("transcribe")) return;
const sidecarKey = sttSidecarKeyFor(id);
const engine = sttEngineForRepoId(id, meta.isGguf);
+ sttEngines.current.set(id.toLowerCase(), engine);
if (meta.ggufVariant) {
sttGgufVariants.current.set(id.toLowerCase(), meta.ggufVariant);
} else {
@@ -889,6 +902,24 @@ export function useAudioModelSlot({
],
);
+ // The sidecar unloads itself after its idle keep-alive and emits nothing, so re-read status
+ // while a model shows as loaded here.
+ useEffect(() => {
+ if (!active || mode !== "transcribe" || busy !== null || !sttLoadedModel)
+ return;
+ const refresh = () => {
+ if (!document.hidden) void refreshSttStatus();
+ };
+ const interval = window.setInterval(refresh, STT_STATUS_POLL_MS);
+ window.addEventListener("focus", refresh);
+ document.addEventListener("visibilitychange", refresh);
+ return () => {
+ window.clearInterval(interval);
+ window.removeEventListener("focus", refresh);
+ document.removeEventListener("visibilitychange", refresh);
+ };
+ }, [active, busy, mode, refreshSttStatus, sttLoadedModel]);
+
const handleEject = useCallback(() => {
if (busy !== null) {
toast.info("Stop the active audio task before ejecting its model.");
@@ -907,11 +938,20 @@ export function useAudioModelSlot({
const toastId = toast.loading("Unloading transcription model…");
void (async () => {
try {
- await releaseTranscribeSelection();
- toast.success("Transcription model unloaded", {
- id: toastId,
- duration: 1200,
- });
+ const outcome = await ejectTranscribeModel();
+ if (outcome === "unloaded") {
+ toast.success("Transcription model unloaded", {
+ id: toastId,
+ duration: 1200,
+ });
+ } else if (outcome === "kept") {
+ toast.info(
+ "A different transcription model is loaded, so nothing was unloaded.",
+ { id: toastId },
+ );
+ } else {
+ toast.dismiss(toastId);
+ }
} catch (error) {
toast.error(
error instanceof Error
@@ -977,6 +1017,7 @@ export function useAudioModelSlot({
})();
}, [
busy,
+ ejectTranscribeModel,
mode,
refreshStatus,
releaseTranscribeSelection,
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 c8cb82388b7..f8948938199 100644
--- a/studio/frontend/src/features/audio/hooks/use-stt-sidecar.ts
+++ b/studio/frontend/src/features/audio/hooks/use-stt-sidecar.ts
@@ -23,6 +23,7 @@ import {
resolveSttResidency,
type SttDownloadedArtifact,
sttDownloadedArtifacts,
+ sttEjectSucceeded,
sttSelectionReady,
} from "../audio-page-policy";
import { audioModelLabel } from "../audio-workspace-utils";
@@ -32,6 +33,7 @@ import {
sttRepoIdForSidecarKey,
sttSidecarKeyFor,
} from "../catalog";
+import { isAudioSttEngine } from "../stt-artifacts";
import type { AudioHostState } from "./audio-host-state";
export function useSttSidecar({
@@ -40,6 +42,7 @@ export function useSttSidecar({
}: Pick<AudioHostState, "setBusy" | "activeRef">) {
const [lastSttRepo, setLastSttRepoChoice] = usePersistedChoice("unsloth:audio:last-stt-model", "");
const [lastSttVariant, setLastSttVariant] = usePersistedChoice("unsloth:audio:last-stt-variant", "");
+ const [lastSttEngine, setLastSttEngine] = usePersistedChoice("unsloth:audio:last-stt-engine", "");
const [selectedSttRepo, setSelectedSttRepo] = useState<string | null>(null);
const [sttLoadedModel, setSttLoadedModel] = useState<string | null>(null);
const [sttLoadedEngine, setSttLoadedEngine] = useState<
@@ -61,12 +64,27 @@ export function useSttSidecar({
lastSttRepo && lastSttVariant ? [[lastSttRepo.toLowerCase(), lastSttVariant]] : [],
),
);
+ // The engine resolved at pick time (a GGUF repo without a -GGUF suffix runs on audio.cpp);
+ // re-deriving it from the id alone sends later status reads and loads to Transformers.
+ const sttEngines = useRef(
+ new Map<string, AudioSttEngine>(
+ lastSttRepo && isAudioSttEngine(lastSttEngine)
+ ? [[lastSttRepo.toLowerCase(), lastSttEngine]]
+ : [],
+ ),
+ );
+ const sttEngineFor = useCallback(
+ (repo: string): AudioSttEngine =>
+ sttEngines.current.get(repo.toLowerCase()) ?? sttEngineForRepoId(repo),
+ [],
+ );
const setLastSttRepo = useCallback(
(repo: string) => {
setLastSttRepoChoice(repo);
setLastSttVariant(sttGgufVariants.current.get(repo.toLowerCase()) ?? "");
+ setLastSttEngine(sttEngines.current.get(repo.toLowerCase()) ?? "");
},
- [setLastSttRepoChoice, setLastSttVariant],
+ [setLastSttRepoChoice, setLastSttVariant, setLastSttEngine],
);
const sttLoadingGeneration = useRef<number | null>(null);
// Residency is not ownership: track the owned model identity, since other surfaces can swap the sidecar.
@@ -83,9 +101,7 @@ export function useSttSidecar({
try {
const selectedRepo = selectedSttRepoRef.current;
const selectedKey = selectedRepo ? sttSidecarKeyFor(selectedRepo) : null;
- const selectedEngine = selectedRepo
- ? sttEngineForRepoId(selectedRepo)
- : null;
+ const selectedEngine = selectedRepo ? sttEngineFor(selectedRepo) : null;
const stt = await fetchSttStatus(
undefined,
selectedEngine === "transformers"
@@ -140,8 +156,15 @@ export function useSttSidecar({
preservePending,
sidecarKeyFor: sttSidecarKeyFor,
repoIdForSidecarKey: sttRepoIdForSidecarKey,
- engineForRepo: sttEngineForRepoId,
+ engineForRepo: sttEngineFor,
});
+ // A pick made while this read was in flight owns the selection now.
+ if (selectedSttRepoRef.current !== selectedRepo) return;
+ // The resident engine wins even for the same repo id: another tab can swap a
+ // suffix-less repo onto audio.cpp under the same name.
+ if (reconciled && residency) {
+ sttEngines.current.set(reconciled.toLowerCase(), residency.engine);
+ }
selectedSttRepoRef.current = reconciled;
setSelectedSttRepo(reconciled);
} catch {
@@ -149,17 +172,26 @@ export function useSttSidecar({
setSttLoadedModel(null);
setSttLoadedEngine(null);
}
- }, []);
+ }, [sttEngineFor]);
const sttSelected = selectedSttRepo !== null;
const sttReady = sttSelectionReady(
selectedSttRepo,
sttLoadedModel,
sttSidecarKeyFor,
- selectedSttRepo ? sttEngineForRepoId(selectedSttRepo) : null,
+ selectedSttRepo ? sttEngineFor(selectedSttRepo) : null,
sttLoadedEngine,
+ sttRepoIdForSidecarKey,
);
+ const forgetSttSelection = useCallback(() => {
+ deferredSttLoad.current = null;
+ selectedSttRepoRef.current = null;
+ sttLoadGeneration.current += 1;
+ sttLoadedByThisPage.current = null;
+ setSelectedSttRepo(null);
+ }, []);
+
const releaseTranscribeSelection = useCallback(async () => {
const selected = selectedSttRepoRef.current;
const claim = sttLoadedByThisPage.current;
@@ -168,22 +200,40 @@ export function useSttSidecar({
selected !== null &&
claim !== null &&
claim === sttLoadedModel;
- const forget = () => {
- deferredSttLoad.current = null;
- selectedSttRepoRef.current = null;
- sttLoadGeneration.current += 1;
- sttLoadedByThisPage.current = null;
- setSelectedSttRepo(null);
- };
if (!owned) {
- forget();
+ forgetSttSelection();
return;
}
// Forget only once released, else a failed unload leaves the model in VRAM with no Eject.
- await unloadSttModel(sttEngineForRepoId(selected), claim);
- forget();
+ await unloadSttModel(sttEngineFor(selected), claim);
+ forgetSttSelection();
+ await refreshSttStatus();
+ }, [forgetSttSelection, refreshSttStatus, sttEngineFor, sttReady, sttLoadedModel]);
+
+ /** An explicit Eject releases whatever is resident, whoever loaded it (a reload, Settings > Voice
+ * or dictation leave no page claim); the backend's expected-model guard keeps a newer model. */
+ const ejectTranscribeModel = useCallback(async (): Promise<
+ "unloaded" | "kept" | "none"
+ > => {
+ if (!sttLoadedModel) {
+ forgetSttSelection();
+ await refreshSttStatus();
+ return "none";
+ }
+ const { released } = await unloadSttModel(
+ sttLoadedEngine ?? undefined,
+ sttLoadedModel,
+ );
+ forgetSttSelection();
await refreshSttStatus();
- }, [refreshSttStatus, sttReady, sttLoadedModel]);
+ return sttEjectSucceeded(released) ? "unloaded" : "kept";
+ }, [forgetSttSelection, refreshSttStatus, sttLoadedEngine, sttLoadedModel]);
+
+ /** Read residency fresh: the sidecar unloads itself after its idle keep-alive. */
+ const readSttResidency = useCallback(async (engine: AudioSttEngine) => {
+ const stt = await fetchSttStatus();
+ return resolveSttResidency(stt, engine, false);
+ }, []);
const ensureSttLoaded = useCallback(
async (
@@ -311,6 +361,8 @@ export function useSttSidecar({
runtimeUpdate,
sttLoadGeneration,
sttGgufVariants,
+ sttEngines,
+ sttEngineFor,
setLastSttRepo,
sttLoadingGeneration,
sttLoadedByThisPage,
@@ -320,6 +372,8 @@ export function useSttSidecar({
sttSelected,
sttReady,
releaseTranscribeSelection,
+ ejectTranscribeModel,
+ readSttResidency,
ensureSttLoaded,
};
}
diff --git a/studio/frontend/src/features/audio/hooks/use-transcribe-capabilities.ts b/studio/frontend/src/features/audio/hooks/use-transcribe-capabilities.ts
index ccbe5ac6a8f..fd1ec23862b 100644
--- a/studio/frontend/src/features/audio/hooks/use-transcribe-capabilities.ts
+++ b/studio/frontend/src/features/audio/hooks/use-transcribe-capabilities.ts
@@ -2,16 +2,23 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { useCallback, useEffect, useState } from "react";
-import { sttEngineForRepoId, sttSidecarKeyFor } from "../catalog";
+import {
+ type AudioSttEngine,
+ sttEngineForRepoId,
+ sttSidecarKeyFor,
+} from "../catalog";
import { fetchSttCapabilities } from "../transcribe-api";
import type { SttCapabilities } from "../transcribe-capabilities";
// Answers change only after an aligner download, so one fetch per model per visit.
const cache = new Map<string, SttCapabilities>();
-export function useTranscribeCapabilities(repo: string | null) {
+export function useTranscribeCapabilities(
+ repo: string | null,
+ repoEngine?: AudioSttEngine | null,
+) {
const model = repo ? sttSidecarKeyFor(repo) : null;
- const engine = repo ? sttEngineForRepoId(repo) : null;
+ const engine = repo ? (repoEngine ?? sttEngineForRepoId(repo)) : null;
const key = model ? `${engine ?? ""}:${model}` : null;
const [caps, setCaps] = useState<SttCapabilities | null>(
key ? (cache.get(key) ?? null) : null,
diff --git a/studio/frontend/src/features/audio/hooks/use-transcription.ts b/studio/frontend/src/features/audio/hooks/use-transcription.ts
index 21b42f87c20..d9a0518af35 100644
--- a/studio/frontend/src/features/audio/hooks/use-transcription.ts
+++ b/studio/frontend/src/features/audio/hooks/use-transcription.ts
@@ -9,7 +9,8 @@ import { copyToClipboard } from "@/lib/copy-to-clipboard";
import { toast } from "@/lib/toast";
import { AudioApiError } from "../api";
import { type AudioSourceSelection, sourceRefOf } from "../audio-run-request";
-import { sttEngineForRepoId, sttSidecarKeyFor } from "../catalog";
+import { sttSameModel } from "../audio-page-policy";
+import { sttRepoIdForSidecarKey, sttSidecarKeyFor } from "../catalog";
import {
getTranscript,
renameTranscriptSpeakers,
@@ -65,6 +66,9 @@ export function useTranscription({
ensureSttLoaded,
setLastSttRepo,
refreshSttStatus,
+ sttEngineFor,
+ readSttResidency,
+ sttLoadGeneration,
}: Pick<AudioHostState, "activeRef" | "busyRef" | "setBusy"> &
Pick<
SttSidecar,
@@ -76,6 +80,9 @@ export function useTranscription({
| "ensureSttLoaded"
| "setLastSttRepo"
| "refreshSttStatus"
+ | "sttEngineFor"
+ | "readSttResidency"
+ | "sttLoadGeneration"
>) {
const [draftKey] = useState(transcriptDraftKey);
const [recoveredTranscript] = useState(() => readTranscriptDraft(draftKey));
@@ -184,8 +191,35 @@ export function useTranscription({
selectedSttRepoRef.current = repo;
setSelectedSttRepo(repo);
const model = sttSidecarKeyFor(repo);
- const engine = sttEngineForRepoId(repo);
- if (sttLoadedModel !== model || sttLoadedEngine !== engine) {
+ const engine = sttEngineFor(repo);
+ // An Eject or another pick during the read below bumps this.
+ const generation = sttLoadGeneration.current;
+ // Page state lags an idle unload; transcribing against it skipped the load and hit a 409.
+ const resident = await readSttResidency(engine).catch(() =>
+ sttLoadedModel && sttLoadedEngine
+ ? { model: sttLoadedModel, engine: sttLoadedEngine }
+ : null,
+ );
+ // Nothing is busy during that read, so an Eject, a pick or leaving the page meanwhile wins; a
+ // status refresh that cleared the selection (nothing resident yet) does not.
+ if (sttLoadGeneration.current !== generation || !activeRef.current) return null;
+ const current = selectedSttRepoRef.current;
+ if (current !== null && current !== repo) return null;
+ if (current === null) {
+ selectedSttRepoRef.current = repo;
+ setSelectedSttRepo(repo);
+ }
+ if (
+ !resident ||
+ resident.engine !== engine ||
+ !sttSameModel(
+ repo,
+ resident.model,
+ sttSidecarKeyFor,
+ engine,
+ sttRepoIdForSidecarKey,
+ )
+ ) {
if (!(await ensureSttLoaded(repo, model, engine))) return null;
}
setLastSttRepo(repo);
@@ -194,6 +228,8 @@ export function useTranscription({
lastSttRepo,
sttLoadedModel,
sttLoadedEngine,
+ sttEngineFor,
+ readSttResidency,
ensureSttLoaded,
setLastSttRepo,
]);
diff --git a/studio/frontend/src/features/audio/route-search.ts b/studio/frontend/src/features/audio/route-search.ts
index 5f09e2e05ca..167d47c3860 100644
--- a/studio/frontend/src/features/audio/route-search.ts
+++ b/studio/frontend/src/features/audio/route-search.ts
@@ -80,6 +80,41 @@ export function audioRouteIntent(search: {
return audioWorkflowForTask(search.task);
}
+export type AudioWorkflowUrlAction =
+ | { kind: "intent"; workflow: AudioWorkflowId }
+ | { kind: "write"; workflow: AudioWorkflowId }
+ | { kind: "none" };
+
+/** Keeps `?workflow=` in step with the committed page, like the Hub's `?tab=`, so a reload
+ * reopens it. A URL that moved off the last synced value is a request (a link, back/forward);
+ * one still on it means the page moved on, so the URL catches up. */
+export function audioWorkflowUrlAction({
+ urlWorkflow,
+ lastSynced,
+ committed,
+ hasModel,
+ hasItem,
+}: {
+ urlWorkflow: AudioWorkflowId | null;
+ lastSynced: AudioWorkflowId | null;
+ committed: AudioWorkflowId;
+ hasModel: boolean;
+ hasItem: boolean;
+}): AudioWorkflowUrlAction {
+ // The model and Library handoffs own the URL until they clean it up.
+ if (hasModel || hasItem) return { kind: "none" };
+ // The first URL seen (a reload, a ?task= link) is a request even for the current page, so it
+ // commits before the loaded model's page can replace it.
+ if (urlWorkflow !== null && lastSynced === null) {
+ return { kind: "intent", workflow: urlWorkflow };
+ }
+ if (urlWorkflow === committed) return { kind: "none" };
+ if (urlWorkflow !== null && urlWorkflow !== lastSynced) {
+ return { kind: "intent", workflow: urlWorkflow };
+ }
+ return { kind: "write", workflow: committed };
+}
+
export function audioWorkflowForPick(pick: {
id: string;
task?: string | null;
diff --git a/studio/frontend/src/features/audio/stt-artifacts.ts b/studio/frontend/src/features/audio/stt-artifacts.ts
index d50b1d86eb8..6379315c6da 100644
--- a/studio/frontend/src/features/audio/stt-artifacts.ts
+++ b/studio/frontend/src/features/audio/stt-artifacts.ts
@@ -8,6 +8,15 @@ import {
export type AudioSttEngine = "transformers" | "gguf" | "mtmd" | "audiocpp";
+export function isAudioSttEngine(value: unknown): value is AudioSttEngine {
+ return (
+ value === "transformers" ||
+ value === "gguf" ||
+ value === "mtmd" ||
+ value === "audiocpp"
+ );
+}
+
const TRANSFORMERS_REPO_BY_KEY: Record<string, string> = {
tiny: "unsloth/whisper-tiny",
base: "unsloth/whisper-base",
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.ts
index 01fdcfd2e06..4ba25ab9b60 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
@@ -288,9 +288,9 @@ export interface SttStatus {
// Keep load/unload requests ordered so a new recording cannot race an unload still finishing for the previous one.
let sttLifecycle: Promise<void> = Promise.resolve();
-function queueSttLifecycle(operation: () => Promise<void>): Promise<void> {
+function queueSttLifecycle<T>(operation: () => Promise<T>): Promise<T> {
const result = sttLifecycle.catch(() => {}).then(operation);
- sttLifecycle = result.catch(() => {});
+ sttLifecycle = result.then(() => {}, () => {});
return result;
}
@@ -475,7 +475,7 @@ export function unloadSttModel(
engine?: SttEngine,
model?: string,
options?: { wait?: boolean },
-): Promise<void> {
+): Promise<{ released?: boolean }> {
return queueSttLifecycle(async () => {
const params = new URLSearchParams();
if (engine) params.set("engine", engine);
@@ -494,6 +494,11 @@ export function unloadSttModel(
} | null;
throw new Error(body?.detail ?? `HTTP ${response.status}`);
}
+ // `released` is false when the backend kept a model it was not asked to unload.
+ const body = (await response.json().catch(() => null)) as {
+ released?: boolean;
+ } | null;
+ return { released: body?.released };
});
}
diff --git a/studio/frontend/tests/audio-handoff-intent.test.ts b/studio/frontend/tests/audio-handoff-intent.test.ts
index 71af5412c60..0524e97e395 100644
--- a/studio/frontend/tests/audio-handoff-intent.test.ts
+++ b/studio/frontend/tests/audio-handoff-intent.test.ts
@@ -11,6 +11,7 @@ const {
audioPickSearch,
audioRouteIntent,
audioWorkflowForPick,
+ audioWorkflowUrlAction,
validateAudioSearch,
} = await import("../src/features/audio/route-search.ts");
@@ -256,3 +257,141 @@ test("a GGUF pick keeps its format through the Audio route", async () => {
// Without it the slot picks the STT engine from the repo name alone.
assert.match(handoff, /isGguf: routeSearch\.gguf/);
});
+
+test("?workflow= follows the committed page, and a moved URL is a request", () => {
+ const base = { hasModel: false, hasItem: false } as const;
+ // A reload (nothing synced yet) on another page's URL asks for that page.
+ assert.deepEqual(
+ audioWorkflowUrlAction({
+ ...base,
+ urlWorkflow: "transcribe",
+ lastSynced: null,
+ committed: "speak",
+ }),
+ { kind: "intent", workflow: "transcribe" },
+ );
+ // Back/forward off the synced value is a request too.
+ assert.deepEqual(
+ audioWorkflowUrlAction({
+ ...base,
+ urlWorkflow: "clone",
+ lastSynced: "music",
+ committed: "music",
+ }),
+ { kind: "intent", workflow: "clone" },
+ );
+ // A refused request leaves the inputs unchanged, so it is asked again once busy settles.
+ const refused = {
+ ...base,
+ urlWorkflow: "music",
+ lastSynced: "speak",
+ committed: "speak",
+ } as const;
+ assert.deepEqual(audioWorkflowUrlAction(refused), {
+ kind: "intent",
+ workflow: "music",
+ });
+ assert.deepEqual(audioWorkflowUrlAction(refused), {
+ kind: "intent",
+ workflow: "music",
+ });
+ // The page moved on (a tab or title-menu pick): the URL catches up.
+ assert.deepEqual(
+ audioWorkflowUrlAction({
+ ...base,
+ urlWorkflow: "speak",
+ lastSynced: "speak",
+ committed: "separate",
+ }),
+ { kind: "write", workflow: "separate" },
+ );
+ // A bare /audio gets the committed page written in.
+ assert.deepEqual(
+ audioWorkflowUrlAction({
+ ...base,
+ urlWorkflow: null,
+ lastSynced: null,
+ committed: "speak",
+ }),
+ { kind: "write", workflow: "speak" },
+ );
+ assert.deepEqual(
+ audioWorkflowUrlAction({
+ ...base,
+ urlWorkflow: null,
+ lastSynced: "clone",
+ committed: "clone",
+ }),
+ { kind: "write", workflow: "clone" },
+ );
+ // In sync: nothing to do, and no transition (Transcribe's has side effects).
+ assert.deepEqual(
+ audioWorkflowUrlAction({
+ ...base,
+ urlWorkflow: "transcribe",
+ lastSynced: "transcribe",
+ committed: "transcribe",
+ }),
+ { kind: "none" },
+ );
+});
+
+test("the model and Library handoffs own the URL until they clean it up", () => {
+ for (const flags of [
+ { hasModel: true, hasItem: false },
+ { hasModel: false, hasItem: true },
+ ]) {
+ assert.deepEqual(
+ audioWorkflowUrlAction({
+ ...flags,
+ urlWorkflow: "music",
+ lastSynced: null,
+ committed: "speak",
+ }),
+ { kind: "none" },
+ );
+ assert.deepEqual(
+ audioWorkflowUrlAction({
+ ...flags,
+ urlWorkflow: null,
+ lastSynced: "speak",
+ committed: "clone",
+ }),
+ { kind: "none" },
+ );
+ }
+});
+
+test("the URL keeps the page after a handoff instead of clearing it", () => {
+ const handoff = readSrc("features/audio/hooks/use-audio-handoff.ts");
+ // A model handoff leaves its page in the URL, so a reload reopens it.
+ assert.match(
+ handoff,
+ /const settledWorkflow = routedWorkflow \?\? committedWorkflow;\s*lastSyncedWorkflow\.current = settledWorkflow;\s*void navigateSelf\(\{\s*to: "\/audio",\s*search: \{ workflow: settledWorkflow \},\s*replace: true,\s*\}\);/,
+ );
+ assert.doesNotMatch(handoff, /search: \{\}/);
+ // Every write the handoff makes replaces the entry, so syncing never stacks history.
+ const navigations = handoff.match(/navigateSelf\(\{[\s\S]*?\}\);/g) ?? [];
+ assert.ok(navigations.length >= 4, String(navigations.length));
+ for (const call of navigations) assert.match(call, /replace: true/);
+});
+
+test("the first URL commits its page, so the loaded model's page cannot replace it", () => {
+ const base = { hasModel: false, hasItem: false, lastSynced: null } as const;
+ // A reload of ?workflow=speak, or a ?task=text-to-speech link, while the store still holds
+ // its default Speak: without a commit, a loaded music model moved the page to Music.
+ assert.deepEqual(
+ audioWorkflowUrlAction({ ...base, urlWorkflow: "speak", committed: "speak" }),
+ { kind: "intent", workflow: "speak" },
+ );
+ // A bare /audio asks for nothing, so the loaded model's page may still be adopted.
+ assert.deepEqual(
+ audioWorkflowUrlAction({ ...base, urlWorkflow: null, committed: "speak" }),
+ { kind: "write", workflow: "speak" },
+ );
+ const handoff = readSrc("features/audio/hooks/use-audio-handoff.ts");
+ assert.match(
+ handoff,
+ /const urlWorkflow = audioRouteIntent\(routeSearch\);/,
+ );
+});
diff --git a/studio/frontend/tests/audio-model-eject.test.ts b/studio/frontend/tests/audio-model-eject.test.ts
index 8a36284628b..d1eacf9d9b9 100644
--- a/studio/frontend/tests/audio-model-eject.test.ts
+++ b/studio/frontend/tests/audio-model-eject.test.ts
@@ -11,9 +11,10 @@ const source = readAudioWorkspaceSource();
const adapterSource = readSrc("features/chat/adapters/studio-model-dictation-adapter.ts");
test("Audio exposes the shared picker eject action only while idle", () => {
+ // The selector keeps showing the last Transcribe model once it is unloaded; Eject there did nothing.
assert.match(
source,
- /onEject=\{\s*busy === null && selectorValue && !showLastPageModel\s*\? handleEject\s*: undefined\s*\}/,
+ /onEject=\{\s*audioEjectAvailable\(\{\s*mode,\s*busy,\s*hasValue: Boolean\(selectorValue\),\s*showLastPageModel,\s*sttReady,\s*\}\)\s*\? handleEject\s*: undefined\s*\}/,
);
assert.match(source, /const handleEject = useCallback\(\(\) => \{\s*if \(busy !== null\) \{/);
assert.match(
@@ -126,33 +127,64 @@ test("a load confirmed after Audio is hidden is deferred, not sent", () => {
);
});
-test("Transcribe eject only unloads a sidecar owned by the current selection", () => {
+test("the Generate-mode release only unloads a sidecar owned by the current selection", () => {
assert.match(
source,
/const handleEject[\s\S]*?if \(mode === "transcribe"\)/,
);
- // One release path, shared with the Generate-mode transition, so both stay owned.
// The selection is forgotten only after the unload lands, so a 500 leaves Eject usable.
assert.match(
source,
- /const releaseTranscribeSelection = useCallback\([\s\S]*await unloadSttModel\(sttEngineForRepoId\(selected\), claim\);\s*forget\(\);\s*await refreshSttStatus\(\)/,
+ /const releaseTranscribeSelection = useCallback\([\s\S]*?await unloadSttModel\(sttEngineFor\(selected\), claim\);\s*forgetSttSelection\(\);\s*await refreshSttStatus\(\)/,
);
assert.match(
source,
- /const forget = \(\) => \{[\s\S]*setSelectedSttRepo\(null\);\s*\};[\s\S]*if \(!owned\) \{\s*forget\(\);/,
+ /const forgetSttSelection = useCallback\(\(\) => \{[\s\S]*?setSelectedSttRepo\(null\);\s*\}, \[\]\);[\s\S]*?if \(!owned\) \{\s*forgetSttSelection\(\);/,
);
assert.match(
+ adapterSource,
+ /unloadSttModel\(\s*engine\?: SttEngine,[\s\S]*params\.set\("engine", engine\)/,
+ );
+ assert.match(
+ source,
+ /if \(!sttReady\) \{[\s\S]*sttStatusRefreshGeneration\.current \+= 1;[\s\S]*void releaseTranscribeSelection\(\)/,
+ );
+});
+
+test("an explicit Transcribe eject unloads what is resident, claimed or not", () => {
+ // A reload, Settings > Voice or dictation leave no page claim; the claim-gated release then
+ // skipped the unload while the page still toasted success.
+ const eject = source.match(
+ /const ejectTranscribeModel = useCallback\([\s\S]*?\n {2}\}, \[/,
+ )?.[0];
+ assert.ok(eject);
+ assert.match(
+ eject,
+ /const \{ released \} = await unloadSttModel\(\s*sttLoadedEngine \?\? undefined,\s*sttLoadedModel,\s*\);\s*forgetSttSelection\(\);\s*await refreshSttStatus\(\);\s*return sttEjectSucceeded\(released\) \? "unloaded" : "kept";/,
+ );
+ assert.doesNotMatch(eject, /sttLoadedByThisPage|claim/);
+ assert.match(
+ source,
+ /if \(mode === "transcribe"\)[\s\S]*?const outcome = await ejectTranscribeModel\(\);\s*if \(outcome === "unloaded"\) \{\s*toast\.success\("Transcription model unloaded"/,
+ );
+ // Only the Generate-mode transition keeps the ownership-gated release.
+ assert.doesNotMatch(
source,
- /if \(mode === "transcribe"\)[\s\S]*await releaseTranscribeSelection\(\)/,
+ /const handleEject[\s\S]*?await releaseTranscribeSelection\(\)[\s\S]*?const activeModel = status\?\.active_model;/,
);
assert.match(
adapterSource,
- /unloadSttModel\(\s*engine\?: SttEngine,[\s\S]*params\.set\("engine", engine\)/,
+ /const body = \(await response\.json\(\)\.catch\(\(\) => null\)\) as \{\s*released\?: boolean;\s*\} \| null;\s*return \{ released: body\?\.released \};/,
);
+});
+
+test("Transcribe re-reads STT status while a model shows as loaded", () => {
+ // The sidecar unloads after its idle keep-alive without telling the page.
assert.match(
source,
- /if \(!sttReady\) \{[\s\S]*sttStatusRefreshGeneration\.current \+= 1;[\s\S]*void releaseTranscribeSelection\(\)/,
+ /if \(!active \|\| mode !== "transcribe" \|\| busy !== null \|\| !sttLoadedModel\)\s*return;[\s\S]*?window\.setInterval\(refresh, STT_STATUS_POLL_MS\);[\s\S]*?return \(\) => \{\s*window\.clearInterval\(interval\);\s*window\.removeEventListener\("focus", refresh\);\s*document\.removeEventListener\("visibilitychange", refresh\);/,
);
+ assert.match(source, /if \(!document\.hidden\) void refreshSttStatus\(\);/);
});
test("leaving Transcribe releases the sidecar it loaded", () => {
@@ -207,7 +239,7 @@ test("the eject unload names the model this page claimed", () => {
// request lands; an unscoped unload then tore down a model this page never owned.
assert.match(
source,
- /await unloadSttModel\(sttEngineForRepoId\(selected\), claim\);/,
+ /await unloadSttModel\(sttEngineFor\(selected\), claim\);/,
);
});
@@ -216,3 +248,59 @@ test("the unload request carries the claimed model to the backend", () => {
assert.match(adapter, /export function unloadSttModel\(\s*engine\?: SttEngine,\s*model\?: string,/);
assert.match(adapter, /if \(model\) params\.set\("model", model\);/);
});
+
+test("the engine picked for a Transcribe model is remembered and reused", () => {
+ // Re-deriving it from the id drops the GGUF flag, so a suffix-less GGUF repo read as Transformers.
+ assert.match(
+ source,
+ /const engine = sttEngineForRepoId\(id, meta\.isGguf\);\s*sttEngines\.current\.set\(id\.toLowerCase\(\), engine\);/,
+ );
+ assert.match(source, /usePersistedChoice\("unsloth:audio:last-stt-engine", ""\)/);
+ assert.match(
+ source,
+ /setLastSttEngine\(sttEngines\.current\.get\(repo\.toLowerCase\(\)\) \?\? ""\);/,
+ );
+ assert.match(source, /engineForRepo: sttEngineFor,/);
+ assert.match(source, /selectedSttRepo \? sttEngineFor\(selectedSttRepo\) : null,/);
+ assert.match(source, /const engine = sttEngineFor\(repo\);[\s\S]{0,400}?await readSttResidency\(engine\)/);
+});
+
+test("Transcribe reuses a resident model that a legacy key or other casing names", () => {
+ // An exact compare reloaded it on every run and took over dictation's model.
+ assert.match(
+ source,
+ /const resident = await readSttResidency\(engine\)[\s\S]*?if \(\s*!resident \|\|\s*resident\.engine !== engine \|\|\s*!sttSameModel\(\s*repo,\s*resident\.model,\s*sttSidecarKeyFor,\s*engine,\s*sttRepoIdForSidecarKey,\s*\)\s*\) \{\s*if \(!\(await ensureSttLoaded\(repo, model, engine\)\)\) return null;/,
+ );
+});
+
+test("a status read never overwrites a pick made while it was in flight", () => {
+ // The poll widened the window in which a stale read reverted the selection and dropped the pick.
+ assert.match(
+ source,
+ /if \(selectedSttRepoRef\.current !== selectedRepo\) return;[\s\S]{0,400}?selectedSttRepoRef\.current = reconciled;\s*setSelectedSttRepo\(reconciled\);/,
+ );
+});
+
+test("the resident engine is adopted even when the repo id is unchanged", () => {
+ // Reconcile returns the same id when only the engine moved, so a guard on a changed id
+ // left a stale Transformers engine and the row never showed ready.
+ assert.match(
+ source,
+ /if \(reconciled && residency\) \{\s*sttEngines\.current\.set\(reconciled\.toLowerCase\(\), residency\.engine\);\s*\}/,
+ );
+});
+
+test("a pick made while Transcribe reads residency is not overridden by the old run", () => {
+ assert.match(
+ source,
+ /const generation = sttLoadGeneration\.current;[\s\S]*?await readSttResidency\(engine\)[\s\S]*?if \(sttLoadGeneration\.current !== generation \|\| !activeRef\.current\) return null;\s*const current = selectedSttRepoRef\.current;\s*if \(current !== null && current !== repo\) return null;\s*if \(current === null\) \{\s*selectedSttRepoRef\.current = repo;\s*setSelectedSttRepo\(repo\);\s*\}/,
+ );
+});
+
+test("leaving Audio during the residency read skips the transcription load", () => {
+ // The hidden page has no load to abort yet, so ensureSttLoaded would still post /stt/load.
+ assert.match(
+ source,
+ /await readSttResidency\(engine\)[\s\S]{0,400}?\|\| !activeRef\.current\) return null;[\s\S]*?await ensureSttLoaded\(repo, model, engine\)/,
+ );
+});
diff --git a/studio/frontend/tests/audio-page-policy.test.ts b/studio/frontend/tests/audio-page-policy.test.ts
index c837e9457a9..2865ad26a07 100644
--- a/studio/frontend/tests/audio-page-policy.test.ts
+++ b/studio/frontend/tests/audio-page-policy.test.ts
@@ -9,6 +9,7 @@ import {
MINIMAX_MUSIC_FRAMES_PER_SECOND,
MINIMAX_MUSIC_MAX_FRAMES,
MINIMAX_MUSIC_MAX_SECONDS,
+ audioEjectAvailable,
audioGenerationPresentation,
audioRuntimeNoticeMode,
canTransitionAudioMode,
@@ -27,8 +28,14 @@ import {
resolveSttResidency,
selectAutoGgufVariant,
stagedTtsLoadIsOwned,
+ sttEjectSucceeded,
sttSelectionReady,
} from "../src/features/audio/audio-page-policy.ts";
+import {
+ sttEngineForRepoId,
+ sttRepoIdForSidecarKey,
+ sttSidecarKeyFor,
+} from "../src/features/audio/stt-artifacts.ts";
import { readSrc } from "./helpers/kit.ts";
import { readAudioWorkspaceSource } from "./helpers/audio-workspace.ts";
@@ -879,3 +886,123 @@ test("the outdated-runtime notice refreshes the page however the update ran", ()
assert.match(notice, /applying: applying \|\| refreshing,/);
assert.doesNotMatch(notice, /toast\.success\([^;]*;\s*onUpdated\(\)/);
});
+
+test("Eject is offered only for a resident Transcribe model, and never while busy", () => {
+ const idle = { busy: null, hasValue: true, showLastPageModel: false } as const;
+ assert.equal(audioEjectAvailable({ ...idle, mode: "transcribe", sttReady: true }), true);
+ // After an unload the selector still shows the last model; Eject there released nothing.
+ assert.equal(audioEjectAvailable({ ...idle, mode: "transcribe", sttReady: false }), false);
+ assert.equal(audioEjectAvailable({ ...idle, mode: "speak", sttReady: false }), true);
+ assert.equal(
+ audioEjectAvailable({ ...idle, mode: "speak", sttReady: false, busy: "loading" }),
+ false,
+ );
+ assert.equal(
+ audioEjectAvailable({ ...idle, mode: "transcribe", sttReady: true, busy: "unloading" }),
+ false,
+ );
+ assert.equal(
+ audioEjectAvailable({ ...idle, mode: "speak", sttReady: false, hasValue: false }),
+ false,
+ );
+ assert.equal(
+ audioEjectAvailable({ ...idle, mode: "speak", sttReady: false, showLastPageModel: true }),
+ false,
+ );
+});
+
+test("a legacy dictation key or other casing still marks the Transcribe row ready", () => {
+ const row = "audio-cpp/audio.cpp-gguf/Qwen3-ASR-0.6B-GGUF";
+ const ready = (loaded: string, selected = row) =>
+ sttSelectionReady(
+ selected,
+ loaded,
+ sttSidecarKeyFor,
+ "audiocpp",
+ "audiocpp",
+ sttRepoIdForSidecarKey,
+ );
+ assert.equal(ready("audiocpp-qwen3-asr-0.6b"), true);
+ assert.equal(ready(row.toLowerCase()), true);
+ assert.equal(ready(row), true);
+ assert.equal(ready("audio-cpp/audio.cpp-gguf/Qwen3-ASR-1.7B-GGUF"), false);
+ assert.equal(ready("audiocpp-qwen3-asr-1.7b"), false);
+ // Without the mapping (older callers) only the exact key matches.
+ assert.equal(
+ sttSelectionReady(row, "audiocpp-qwen3-asr-0.6b", sttSidecarKeyFor, "audiocpp", "audiocpp"),
+ false,
+ );
+ // An engine mismatch is still not ready.
+ assert.equal(
+ sttSelectionReady(
+ row,
+ "audiocpp-qwen3-asr-0.6b",
+ sttSidecarKeyFor,
+ "transformers",
+ "audiocpp",
+ sttRepoIdForSidecarKey,
+ ),
+ false,
+ );
+ // Reconcile keeps the picked row instead of swapping it for the legacy key's id.
+ assert.equal(
+ reconcileSttSelection({
+ selectedRepo: row,
+ loadedModel: "audiocpp-qwen3-asr-0.6b",
+ loadedEngine: "audiocpp",
+ preservePending: false,
+ sidecarKeyFor: sttSidecarKeyFor,
+ repoIdForSidecarKey: sttRepoIdForSidecarKey,
+ engineForRepo: sttEngineForRepoId,
+ }),
+ row,
+ );
+});
+
+test("a GGUF repo without a -GGUF suffix keeps the engine it was picked with", () => {
+ const repo = "someorg/whisper-quant";
+ // Re-derived from the id alone it resolves to Transformers, so it never showed ready.
+ assert.equal(sttEngineForRepoId(repo), "transformers");
+ const engines = new Map([[repo, sttEngineForRepoId(repo, true)]]);
+ const engineFor = (id: string) => engines.get(id) ?? sttEngineForRepoId(id);
+ assert.equal(engineFor(repo), "audiocpp");
+ assert.equal(
+ sttSelectionReady(repo, repo, sttSidecarKeyFor, engineFor(repo), "audiocpp"),
+ true,
+ );
+ assert.equal(
+ reconcileSttSelection({
+ selectedRepo: repo,
+ loadedModel: repo,
+ loadedEngine: "audiocpp",
+ preservePending: false,
+ sidecarKeyFor: sttSidecarKeyFor,
+ repoIdForSidecarKey: sttRepoIdForSidecarKey,
+ engineForRepo: engineFor,
+ }),
+ repo,
+ );
+});
+
+test("an eject counts as done unless the backend says it kept the model", () => {
+ assert.equal(sttEjectSucceeded(true), true);
+ assert.equal(sttEjectSucceeded(undefined), true);
+ assert.equal(sttEjectSucceeded(false), false);
+});
+
+test("reconcile keeps the same repo id when only the resident engine changed", () => {
+ // The hook therefore has to adopt the engine without waiting for the id to change.
+ const repo = "someorg/whisper-quant";
+ assert.equal(
+ reconcileSttSelection({
+ selectedRepo: repo,
+ loadedModel: repo,
+ loadedEngine: "audiocpp",
+ preservePending: false,
+ sidecarKeyFor: sttSidecarKeyFor,
+ repoIdForSidecarKey: sttRepoIdForSidecarKey,
+ engineForRepo: () => "transformers",
+ }),
+ repo,
+ );
+});
diff --git a/studio/frontend/tests/audio-workspace-split.test.ts b/studio/frontend/tests/audio-workspace-split.test.ts
index 2f3b03dcc59..51489c69d3e 100644
--- a/studio/frontend/tests/audio-workspace-split.test.ts
+++ b/studio/frontend/tests/audio-workspace-split.test.ts
@@ -57,8 +57,29 @@ test("?workflow= names the page ahead of ?task=, and both go through the workflo
// Task-only links take the same gate as ?workflow=, so a Speak/Music switch never skips the busy check.
assert.match(
handoff,
- /const routedWorkflow = audioRouteIntent\(routeSearch\);\s*if \(routedWorkflow === null\) return;[\s\S]{0,120}?if \(!transitionWorkflow\(routedWorkflow\)\) return;\s*void navigateSelf\(\{ to: "\/audio", search: \{\}, replace: true \}\);/,
+ /const urlWorkflow = audioRouteIntent\(routeSearch\);[\s\S]*?const action = audioWorkflowUrlAction\(\{\s*urlWorkflow,/,
);
+ // A successful switch keeps only the page in the URL, so a reload reopens it.
+ assert.match(
+ handoff,
+ /if \(action\.kind === "intent"\) \{[\s\S]{0,120}?if \(!transitionWorkflow\(action\.workflow\)\) return;\s*lastSyncedWorkflow\.current = action\.workflow;[\s\S]{0,120}?void navigateSelf\(\{\s*to: "\/audio",\s*search: \{ workflow: action\.workflow \},\s*replace: true,\s*\}\);/,
+ );
+ // The committed page is written back with replace only, and only while Audio is the route.
+ assert.match(
+ handoff,
+ /useEffect\(\(\) => \{\s*if \(!active\) \{\s*lastSyncedWorkflow\.current = null;\s*pendingWrite\.current = null;\s*return;\s*\}/,
+ );
+ assert.match(
+ handoff,
+ /lastSyncedWorkflow\.current = action\.workflow;\s*pendingWrite\.current = \{ from: urlWorkflow \};\s*void navigateSelf\(\{\s*to: "\/audio",\s*search: \(prev\) => \(\{ \.\.\.prev, workflow: action\.workflow \}\),\s*replace: true,\s*\}\);/,
+ );
+ // A write still in flight is not read back as a request for the page it left.
+ assert.match(
+ handoff,
+ /if \(urlWorkflow === pendingWrite\.current\.from\) return;/,
+ );
+ assert.doesNotMatch(handoff, /search: \{\}/);
+ assert.doesNotMatch(handoff, /replace: false/);
assert.doesNotMatch(handoff, /commitWorkflow\(/);
// A Library clip asks for its page through ?workflow=, so a busy page retries it later.
assert.match(
diff --git a/studio/frontend/tests/read-aloud-tts-model-row.test.ts b/studio/frontend/tests/read-aloud-tts-model-row.test.ts
index 9cb46f3d822..7c031f34cb2 100644
--- a/studio/frontend/tests/read-aloud-tts-model-row.test.ts
+++ b/studio/frontend/tests/read-aloud-tts-model-row.test.ts
@@ -31,13 +31,15 @@ test("the row lands on the TTS selector, not the mode Audio was left in", () =>
// the task names the page, through the same busy gate as ?workflow=.
assert.match(
audioSource,
- /const routedWorkflow = audioRouteIntent\(routeSearch\);\s*if \(routedWorkflow === null\) return;/,
+ /const urlWorkflow = audioRouteIntent\(routeSearch\);[\s\S]*?audioWorkflowUrlAction\(\{\s*urlWorkflow,/,
);
- // A refused switch keeps the parameter, so the retry rides the effect's busy dep.
+ // A refused switch returns before navigating and keeps the parameter, so the retry rides the
+ // effect's busy dep; a successful one leaves only the page (the task is dropped).
assert.match(
audioSource,
- /if \(!transitionWorkflow\(routedWorkflow\)\) return;\s*void navigateSelf\(\{ to: "\/audio", search: \{\}, replace: true \}\);/,
+ /if \(!transitionWorkflow\(action\.workflow\)\) return;\s*lastSyncedWorkflow\.current = action\.workflow;[\s\S]{0,120}?void navigateSelf\(\{\s*to: "\/audio",\s*search: \{ workflow: action\.workflow \},\s*replace: true,\s*\}\);/,
);
+ assert.match(audioSource, /\}, \[\s*active,\s*busy,/);
});
test("custom TTS explains the strict voice default", () => {