chore: ignore output/ directory (spotted in #946)

The Docker compose file bind-mounts output/ but it was never ignored.

.bumpversion.cfg

@@ -37,3 +37,7 @@ replace = "version": "{new_version}"
 [bumpversion:file:backend/__init__.py]
 search = __version__ = "{current_version}"
 replace = __version__ = "{new_version}"
+
+[bumpversion:file:backend/pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"

.gitattributes

@@ -0,0 +1,2 @@
+package.json text eol=lf
+scripts/*.sh text eol=lf

.github/workflows/ci.yml

@@ -6,6 +6,10 @@ on:
     branches:
       - main
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   frontend-quality:
     runs-on: ubuntu-latest
@@ -19,8 +23,70 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Lint (biome)
+        run: bun run lint
+
       - name: Typecheck app + web
         run: bun run typecheck
 
+      - name: Unit tests
+        run: bun run test
+
       - name: Build web smoke test
         run: bun run build:web
+
+  backend-quality:
+    # macOS arm64 matches the primary user platform and lets the MLX-path
+    # tests run instead of being skipped.
+    runs-on: macos-14
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Cache pip downloads
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-${{ runner.os }}-${{ hashFiles('backend/requirements*.txt', 'justfile') }}
+          restore-keys: pip-${{ runner.os }}-
+
+      - name: Install just
+        run: brew install just
+
+      - name: Install backend dependencies
+        run: just setup-python
+
+      - name: Lint (ruff)
+        run: venv/bin/ruff check .
+        working-directory: backend
+
+      - name: Run tests
+        run: venv/bin/python -m pytest tests -q
+        working-directory: backend
+
+  rust-quality:
+    runs-on: macos-14
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: tauri/src-tauri
+
+      - name: Stub sidecar binaries
+        # tauri-build validates externalBin paths; real sidecars are only
+        # produced by the release pipeline.
+        run: |
+          mkdir -p tauri/src-tauri/binaries tauri/dist
+          touch tauri/src-tauri/binaries/voicebox-server-aarch64-apple-darwin
+          touch tauri/src-tauri/binaries/voicebox-mcp-aarch64-apple-darwin
+
+      - name: Cargo check
+        run: cargo check --manifest-path tauri/src-tauri/Cargo.toml

CONTRIBUTING.md

@@ -18,9 +18,9 @@ Thank you for your interest in contributing to Voicebox! This document provides
   curl -fsSL https://bun.sh/install | bash
   ```
 
-- **[Python 3.11+](https://python.org)** - For backend development
+- **[Python 3.12+](https://python.org)** - For backend development
   ```bash
-  python --version  # Should be 3.11 or higher
+  python --version  # Should be 3.12 or higher
   ```
 
 - **[Rust](https://rustup.rs)** - For Tauri desktop app (installed automatically by Tauri CLI)
@@ -91,7 +91,7 @@ On Windows, to build with CUDA support for local testing:
 just build-local  # Build CPU + CUDA server binaries + Tauri installer
 ```
 
-This builds the CPU sidecar (bundled with the app), the CUDA binary (placed in `%APPDATA%/com.voicebox.app/backends/` for runtime GPU switching), and the installable Tauri app.
+This builds the CPU sidecar (bundled with the app), the CUDA binary (placed in `%APPDATA%/sh.voicebox.app/backends/` for runtime GPU switching), and the installable Tauri app.
 
 Creates platform-specific installers (`.dmg`, `.msi`, `.AppImage`) in `tauri/src-tauri/target/release/bundle/`.
 
@@ -115,14 +115,6 @@ just build-server
 
 This makes PyInstaller use your local qwen-tts version instead of the pip-installed package.
 
-### Generate OpenAPI Client
-
-After starting the backend server:
-```bash
-./scripts/generate-api.sh
-```
-This downloads the OpenAPI schema and generates the TypeScript client in `app/src/lib/api/`
-
 ### Convert Assets to Web Formats
 
 To optimize images and videos for the web, run:
@@ -212,7 +204,7 @@ export const ProfileCard = (props) => { ... }
 - Follow PEP 8 style guide
 - Use type hints
 - Use async/await for I/O operations
-- Format with Black (if configured)
+- Format and lint with ruff (configured in `backend/pyproject.toml`)
 
 ```python
 # Good
@@ -242,9 +234,12 @@ voicebox/
 │       ├── lib/          # Utilities and API client
 │       └── hooks/        # React hooks
 ├── backend/          # Python FastAPI server
-│   ├── main.py       # API routes
-│   ├── tts.py        # Voice synthesis
-│   └── ...
+│   ├── main.py       # Entry point (FastAPI app assembled in app.py)
+│   ├── routes/       # API routers, one per domain
+│   ├── services/     # Business logic (generation, transcription, profiles, ...)
+│   ├── backends/     # TTS engine implementations
+│   ├── database/     # SQLAlchemy models, sessions, migrations
+│   └── tests/        # pytest suite
 ├── tauri/            # Desktop app wrapper
 │   └── src-tauri/    # Rust backend
 └── scripts/          # Build scripts
@@ -289,23 +284,26 @@ voicebox/
 
 When adding new API endpoints:
 
-1. **Add route in `backend/main.py`**
+1. **Add the route to the relevant router in `backend/routes/`** (new routers get registered in `backend/routes/__init__.py`)
 2. **Create Pydantic models in `backend/models.py`**
 3. **Implement business logic in appropriate module**
 4. **Update OpenAPI schema** (automatic with FastAPI)
-5. **Regenerate TypeScript client:**
-   ```bash
-   bun run generate:api
-   ```
+5. **Update the TypeScript client** — add matching types to `app/src/lib/api/types.ts` and a method to `app/src/lib/api/client.ts`
 6. **Update `backend/README.md`** with endpoint documentation
 
 ## Testing
 
-Currently, testing is primarily manual. When adding tests:
+Backend tests live in `backend/tests/` and run with pytest:
 
-- **Backend**: Use pytest for Python tests
-- **Frontend**: Use Vitest for React component tests
-- **E2E**: Use Playwright for end-to-end tests (future)
+```bash
+cd backend
+venv/bin/python -m pytest tests
+```
+
+CI runs the backend test suite on every PR, along with frontend lint and typecheck (`bun run lint`, `bun run typecheck`) and a `cargo check` of the Tauri app (see `.github/workflows/ci.yml`). Add backend tests alongside your changes where it makes sense.
+
+- **Frontend**: Vitest for React component tests (coverage is still sparse — contributions welcome)
+- **E2E**: Playwright for end-to-end tests (future)
 
 ## Pull Request Process
 
@@ -363,7 +361,7 @@ See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/
 
 **Quick fixes:**
 
-- **Backend won't start:** Check Python version (3.11+), ensure venv is activated, install dependencies
+- **Backend won't start:** Check Python version (3.12+), ensure venv is activated, install dependencies
 - **Tauri build fails:** Ensure Rust is installed, clean build with `cd tauri/src-tauri && cargo clean`
 - **OpenAPI client generation fails:** Ensure backend is running, check `curl http://localhost:17493/openapi.json`
 
@@ -379,7 +377,7 @@ See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/
 - [README.md](README.md) - Project overview
 - [backend/README.md](backend/README.md) - API documentation
 - [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) - Living engineering roadmap: architecture, shipped vs in-flight work, prioritized open issues, candidate TTS engines under evaluation, architectural bottlenecks. Keep this updated when you ship significant features, close or backlog a model integration, or identify new bottlenecks.
-- [docs/AUTOUPDATER_QUICKSTART.md](docs/AUTOUPDATER_QUICKSTART.md) - Auto-updater setup
+- [docs/content/docs/developer/autoupdater.mdx](docs/content/docs/developer/autoupdater.mdx) - Auto-updater setup (published at [voicebox.sh docs](https://voicebox.sh/docs/developer/autoupdater))
 - [SECURITY.md](SECURITY.md) - Security policy
 - [CHANGELOG.md](CHANGELOG.md) - Version history
 

Dockerfile

@@ -20,8 +20,11 @@ COPY package.json bun.lock CHANGELOG.md ./
 COPY app/ ./app/
 COPY web/ ./web/
 
-# Strip workspaces not needed for web build, and fix trailing comma
-RUN sed -i '/"tauri"/d; /"landing"/d' package.json && \
+# Normalize line endings first (a Windows CRLF checkout would otherwise
+# defeat the `-z 's/,\n  ]/…/'` match below, since it's LF-anchored), then
+# strip workspaces not needed for web build, and fix trailing comma
+RUN sed -i 's/\r$//' package.json && \
+    sed -i '/"tauri"/d; /"landing"/d' package.json && \
     sed -i -z 's/,\n  ]/\n  ]/' package.json
 RUN bun install --no-save
 # Build frontend (skip tsc — upstream has pre-existing type errors)
@@ -61,7 +64,7 @@ RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
 RUN pip install --no-cache-dir --prefix=/install --no-deps chatterbox-tts
 RUN pip install --no-cache-dir --prefix=/install --no-deps hume-tada
 RUN pip install --no-cache-dir --prefix=/install \
-    git+https://github.com/QwenLM/Qwen3-TTS.git
+    git+https://github.com/QwenLM/Qwen3-TTS.git@022e286b98fbec7e1e916cb940cdf532cd9f488e
 
 
 # === Stage 3: Runtime ===
@@ -100,7 +103,11 @@ EXPOSE 17493
 HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=60s \
     CMD curl -f http://localhost:17493/health || exit 1
 
-# Entrypoint joins GPU groups then drops to the voicebox user
+# Entrypoint joins GPU groups then drops to the voicebox user.
+# Normalize CRLF (a Windows checkout otherwise leaves the shebang as
+# `#!/bin/sh\r`, which Linux can't resolve — reported as a misleading
+# "no such file or directory" even though the file exists).
 COPY --chmod=755 scripts/rocm-entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN sed -i 's/\r$//' /usr/local/bin/entrypoint.sh
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
 CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "17493"]

SECURITY.md

@@ -6,8 +6,8 @@ We release patches for security vulnerabilities. Which versions are eligible for
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 0.3.x   | :white_check_mark: |
-| < 0.3   | :x:                |
+| 0.5.x   | :white_check_mark: |
+| < 0.5   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -39,7 +39,7 @@ We will:
 ### For Developers
 
 - **Dependencies** - Keep all dependencies up to date
-- **Code review** - All PRs require review before merging
+- **CI checks** - Every PR must pass typecheck, lint, backend tests, and `cargo check` before merging
 - **Secrets** - Never commit API keys or signing keys
 - **Signing** - All releases are cryptographically signed
 
@@ -82,7 +82,7 @@ Timeline may vary based on severity and complexity.
 ## Security Updates
 
 Security updates will be:
-- Released as patch versions (e.g., 0.3.2)
+- Released as patch versions (e.g., 0.5.1)
 - Documented in CHANGELOG.md
 - Announced via GitHub releases
 - Automatically delivered via auto-updater

app/index.html

@@ -6,7 +6,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>voicebox</title>
     <script>
-      (function () {
+      (() => {
         try {
           var theme = 'system';
           var raw = localStorage.getItem('voicebox-ui');

app/package.json

@@ -7,6 +7,7 @@
     "dev": "vite",
     "build": "vite build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
     "preview": "vite preview",
     "lint": "biome lint src",
     "lint:fix": "biome lint --write src",
@@ -60,6 +61,7 @@
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.1.18",
+    "@types/bun": "^1.3.4",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.0",

app/src/components/DictateWindow/DictateWindow.tsx

@@ -35,19 +35,17 @@ export function DictateWindow() {
     };
   }, []);
 
-  // Snapshot of the focused UI element at chord-start, shipped over from
-  // Rust on the ``dictate:start`` payload. Held in a ref so it survives
-  // the 1–2 s transcribe + refine window — the paste only fires once the
-  // final text comes back.
-  const focusRef = useRef<FocusSnapshot | null>(null);
+  // Mirrored from the main window: true only when dictation is armed and the
+  // user opted into keeping the microphone ready.
+  const [micWarm, setMicWarm] = useState(false);
 
   const session = useCaptureRecordingSession({
-    onFinalText: async (text, _capture, allowAutoPaste) => {
-      const focus = focusRef.current;
-      // Consume-once: a second chord before this fires would overwrite
-      // focusRef, but nulling it here guards against the late-arriving
-      // refine-result firing a paste after the user has moved on.
-      focusRef.current = null;
+    keepMicWarm: micWarm,
+    onFinalText: async (text, _capture, allowAutoPaste, context) => {
+      // Focus is the snapshot taken at chord-start and threaded through as this
+      // take's context, so it survives the 1–2 s transcribe + refine window and
+      // overlapping dictations can't paste into each other's target.
+      const focus = context as FocusSnapshot | null;
       if (!allowAutoPaste) return;
       if (!focus || !text.trim()) return;
       try {
@@ -72,23 +70,41 @@ export function DictateWindow() {
   sessionRef.current = session;
 
   useEffect(() => {
-    const unlistens: Promise<UnlistenFn>[] = [];
-    unlistens.push(
+    let disposed = false;
+    const unlistens: UnlistenFn[] = [];
+    const registrations = [
       listen<{ focus: FocusSnapshot | null }>('dictate:start', (event) => {
-        focusRef.current = event.payload?.focus ?? null;
-        sessionRef.current.startRecording();
+        sessionRef.current.startRecording(event.payload?.focus ?? null);
       }),
-    );
-    unlistens.push(
       listen('dictate:stop', () => {
-        if (sessionRef.current.isRecording) sessionRef.current.stopRecording();
+        // Forward stops that arrive while getUserMedia is still resolving.
+        sessionRef.current.stopRecording();
       }),
-    );
+      listen<boolean>('dictate:warm', (event) => {
+        setMicWarm(Boolean(event.payload));
+      }),
+    ];
+    Promise.all(registrations)
+      .then((registered) => {
+        if (disposed) {
+          for (const unlisten of registered) unlisten();
+          return;
+        }
+        unlistens.push(...registered);
+        emit('dictate:warm-request').catch(() => {});
+      })
+      .catch((err) => console.warn('[dictate] event listener registration failed:', err));
     return () => {
-      for (const p of unlistens) p.then((fn) => fn()).catch(() => {});
+      disposed = true;
+      for (const unlisten of unlistens) unlisten();
     };
   }, []);
 
+  useEffect(() => {
+    if (micWarm) void session.prewarm();
+    else session.releaseWarm();
+  }, [micWarm, session.prewarm, session.releaseWarm]);
+
   // --- Agent-speak cycle ---------------------------------------------------
 
   const [speaking, setSpeaking] = useState<{

app/src/components/Generation/EngineModelSelector.tsx

@@ -139,7 +139,7 @@ export function EngineModelSelector({ form, compact, selectedProfile }: EngineMo
           <SelectValue />
         </SelectTrigger>
       </FormControl>
-      <SelectContent>
+      <SelectContent side={compact ? 'top' : undefined}>
         {availableOptions.map((opt) => (
           <SelectItem key={opt.value} value={opt.value} className={itemClass}>
             {opt.label}

app/src/components/Generation/FloatingGenerateBox.tsx

@@ -555,7 +555,7 @@ export function FloatingGenerateBox({
                         <SelectTrigger className="h-8 text-xs bg-card border-border rounded-full hover:bg-background/50 transition-all w-full">
                           <SelectValue placeholder={t('generation.voiceSelector.placeholder')} />
                         </SelectTrigger>
-                        <SelectContent>
+                        <SelectContent side="top">
                           {profiles?.map((profile) => (
                             <SelectItem key={profile.id} value={profile.id} className="text-xs">
                               {profile.name}
@@ -582,7 +582,7 @@ export function FloatingGenerateBox({
                                 <SelectValue />
                               </SelectTrigger>
                             </FormControl>
-                            <SelectContent>
+                            <SelectContent side="top">
                               {engineLangs.map((lang) => (
                                 <SelectItem key={lang.value} value={lang.value} className="text-xs">
                                   {lang.label}
@@ -610,7 +610,7 @@ export function FloatingGenerateBox({
                       <SelectTrigger className="h-8 text-xs bg-card border-border rounded-full hover:bg-background/50 transition-all">
                         <SelectValue placeholder={t('generation.effects.none')} />
                       </SelectTrigger>
-                      <SelectContent>
+                      <SelectContent side="top">
                         <SelectItem value="none" className="text-xs">
                           {t('generation.effects.none')}
                         </SelectItem>

app/src/components/ServerTab/CapturesPage.tsx

@@ -138,6 +138,7 @@ export function CapturesPage() {
   const allowAutoPaste = settings?.allow_auto_paste ?? true;
   const defaultVoiceId = settings?.default_playback_voice_id ?? null;
   const hotkeyEnabled = settings?.hotkey_enabled ?? false;
+  const keepMicWarm = settings?.keep_mic_warm ?? false;
   const pushToTalkKeys = settings?.chord_push_to_talk_keys ?? defaultChordKeys('push');
   const toggleToTalkKeys = settings?.chord_toggle_to_talk_keys ?? defaultChordKeys('toggle');
 
@@ -221,6 +222,22 @@ export function CapturesPage() {
           <InputMonitoringNotice enabled={hotkeyEnabled} />
         </div>
 
+        <SettingRow
+          title={t('settings.captures.dictation.keepMicWarm.title')}
+          description={t('settings.captures.dictation.keepMicWarm.description')}
+          htmlFor="keepMicWarm"
+          action={
+            <Toggle
+              id="keepMicWarm"
+              checked={keepMicWarm}
+              disabled={!hotkeyEnabled}
+              onCheckedChange={(v) => {
+                update({ keep_mic_warm: v });
+              }}
+            />
+          }
+        />
+
         <SettingRow
           title={t('settings.captures.dictation.pushToTalk.title')}
           description={t('settings.captures.dictation.pushToTalk.description')}

app/src/components/ServerTab/CloudSection.tsx

@@ -0,0 +1,151 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Cloud, Loader2 } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { Button } from '@/components/ui/button';
+import { useToast } from '@/components/ui/use-toast';
+import { apiClient } from '@/lib/api/client';
+import { SettingRow, SettingSection } from './SettingRow';
+
+// "Log in with browser" device pairing. The backend opens the system browser
+// and completes the code exchange; here we just kick it off and poll status
+// until the link goes live. The API key never touches the frontend.
+export function CloudSection() {
+  const { toast } = useToast();
+  const queryClient = useQueryClient();
+  const [polling, setPolling] = useState(false);
+
+  const { data: status } = useQuery({
+    queryKey: ['cloud-status'],
+    queryFn: () => apiClient.getCloudStatus(),
+    refetchInterval: polling ? 2000 : false,
+  });
+
+  const connected = status?.connected ?? false;
+
+  // Once the browser flow completes, stop polling and celebrate.
+  useEffect(() => {
+    if (connected && polling) {
+      setPolling(false);
+      toast({
+        title: 'Connected to Voicebox Cloud',
+        description: `Linked as ${status?.device_name ?? 'this device'}.`,
+      });
+    }
+  }, [connected, polling, status?.device_name, toast]);
+
+  // Give up after two minutes so an abandoned browser flow doesn't leave the
+  // button stuck on "Waiting for browser…". The backend state stays valid for
+  // ten, so the user can simply start again.
+  useEffect(() => {
+    if (!polling) return;
+    const timeoutId = window.setTimeout(() => {
+      setPolling(false);
+      toast({
+        title: 'Sign-in timed out',
+        description: 'The browser sign-in was not completed. Try again.',
+        variant: 'destructive',
+      });
+    }, 120_000);
+    return () => window.clearTimeout(timeoutId);
+  }, [polling, toast]);
+
+  const startLogin = useMutation({
+    mutationFn: () => apiClient.startCloudLogin(),
+    onSuccess: () => {
+      setPolling(true);
+      toast({
+        title: 'Continue in your browser',
+        description: 'Authorize this device, then return here.',
+      });
+    },
+    onError: (error: Error) =>
+      toast({
+        title: 'Could not start sign-in',
+        description: error.message,
+        variant: 'destructive',
+      }),
+  });
+
+  const disconnect = useMutation({
+    mutationFn: () => apiClient.disconnectCloud(),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['cloud-status'] });
+      toast({
+        title: 'Disconnected',
+        description:
+          'This device is no longer linked. The key stays valid until revoked in your account.',
+      });
+    },
+    onError: (error: Error) =>
+      toast({ title: 'Could not disconnect', description: error.message, variant: 'destructive' }),
+  });
+
+  const busy = startLogin.isPending || polling;
+
+  return (
+    <SettingSection
+      title="Voicebox Cloud"
+      description="End-to-end encrypted backup & sync across your devices."
+    >
+      <SettingRow
+        title={connected ? 'Connected' : 'Account'}
+        description={
+          connected
+            ? `Linked as ${status?.device_name ?? 'this device'}${
+                status?.key_prefix ? ` · ${status.key_prefix}…` : ''
+              }`
+            : 'Log in to back up and sync your captures and generations.'
+        }
+        action={
+          connected ? (
+            <Button
+              disabled={disconnect.isPending}
+              onClick={() => disconnect.mutate()}
+              size="sm"
+              variant="outline"
+            >
+              {disconnect.isPending ? (
+                <>
+                  <Loader2 className="h-3.5 w-3.5 mr-1.5 animate-spin" />
+                  Disconnecting…
+                </>
+              ) : (
+                'Disconnect'
+              )}
+            </Button>
+          ) : (
+            <Button disabled={busy} onClick={() => startLogin.mutate()} size="sm">
+              {busy ? (
+                <>
+                  <Loader2 className="h-3.5 w-3.5 mr-1.5 animate-spin" />
+                  {polling ? 'Waiting for browser…' : 'Opening…'}
+                </>
+              ) : (
+                <>
+                  <Cloud className="h-3.5 w-3.5 mr-1.5" />
+                  Log in with browser
+                </>
+              )}
+            </Button>
+          )
+        }
+      />
+
+      {connected && (
+        <SettingRow
+          title="Manage"
+          description="Revoke this device, add API keys, or manage billing from your account."
+        >
+          <a
+            className="text-sm text-accent hover:underline"
+            href={status?.dashboard_url ?? 'https://voicebox.sh/account'}
+            rel="noopener noreferrer"
+            target="_blank"
+          >
+            Open account dashboard ↗
+          </a>
+        </SettingRow>
+      )}
+    </SettingSection>
+  );
+}

app/src/components/ServerTab/GeneralPage.tsx

@@ -14,6 +14,7 @@ import { useAutoUpdater } from '@/hooks/useAutoUpdater';
 import { useServerHealth } from '@/lib/hooks/useServer';
 import { usePlatform } from '@/platform/PlatformContext';
 import { useServerStore } from '@/stores/serverStore';
+import { CloudSection } from './CloudSection';
 import { LanguageSelect } from './LanguageSelect';
 import { SettingRow, SettingSection } from './SettingRow';
 import { ThemeSelect } from './ThemeSelect';
@@ -207,6 +208,8 @@ export function GeneralPage() {
         />
       </SettingSection>
 
+      <CloudSection />
+
       <ApiReferenceCard serverUrl={serverUrl} />
 
       {platform.metadata.isTauri && <UpdatesSection />}

app/src/components/StoriesTab/StoryTrackEditor.tsx

@@ -38,6 +38,7 @@ import {
   useUpdateStoryItemVolume,
 } from '@/lib/hooks/useStories';
 import { cn } from '@/lib/utils/cn';
+import { computeTrimValues } from '@/lib/utils/trim';
 import { useGenerationStore } from '@/stores/generationStore';
 import { useStoryStore } from '@/stores/storyStore';
 
@@ -600,41 +601,17 @@ export function StoryTrackEditor({ storyId, items }: StoryTrackEditorProps) {
       const deltaMs = pixelsToMs(deltaX); // Signed delta in milliseconds
 
       const { item, initialTrimStart, initialTrimEnd } = trimStartItemRef.current;
-      const originalDurationMs = item.duration * 1000;
-
-      let newTrimStart = initialTrimStart;
-      let newTrimEnd = initialTrimEnd;
-
-      if (trimSide === 'start') {
-        // Moving right increases trim_start (trims more from start)
-        // Moving left decreases trim_start (restores from start)
-        newTrimStart = Math.round(
-          Math.max(
-            0,
-            Math.min(initialTrimStart + deltaMs, originalDurationMs - initialTrimEnd - 100),
-          ),
-        );
-      } else {
-        // Moving right decreases trim_end (restores from end)
-        // Moving left increases trim_end (trims more from end)
-        newTrimEnd = Math.round(
-          Math.max(
-            0,
-            Math.min(initialTrimEnd - deltaMs, originalDurationMs - initialTrimStart - 100),
-          ),
-        );
-      }
-
-      // Validate that we don't exceed duration
-      if (newTrimStart + newTrimEnd >= originalDurationMs - 100) {
-        return; // Don't allow trimming to less than 100ms
-      }
+      const newTrimValues = computeTrimValues(
+        trimSide,
+        deltaMs,
+        initialTrimStart,
+        initialTrimEnd,
+        item.duration * 1000,
+      );
+      if (!newTrimValues) return;
 
       // Update temporary trim values for visual feedback
-      setTempTrimValues({
-        trim_start_ms: newTrimStart,
-        trim_end_ms: newTrimEnd,
-      });
+      setTempTrimValues(newTrimValues);
     },
     [trimmingItem, trimSide, trimStartX, pixelsToMs],
   );

app/src/i18n/locales/en/translation.json

@@ -887,6 +887,10 @@
           "title": "Global shortcut",
           "description": "Hold the shortcut to record from anywhere on your machine. Release to transcribe."
         },
+        "keepMicWarm": {
+          "title": "Keep microphone ready",
+          "description": "Hold the microphone open while dictation is enabled so the first words are never clipped. The macOS microphone indicator stays lit while it's on."
+        },
         "pushToTalk": {
           "title": "Push-to-talk shortcut",
           "description": "Hold these keys anywhere on your system to record. Release to stop and transcribe.",

app/src/lib/api/client.ts

@@ -1,4 +1,5 @@
 import type { LanguageCode } from '@/lib/constants/languages';
+import { formatErrorDetail } from '@/lib/api/errors';
 import { useServerStore } from '@/stores/serverStore';
 import type {
   ActiveTasksResponse,
@@ -51,23 +52,10 @@ import type {
   MCPClientBinding,
   MCPClientBindingListResponse,
   MCPClientBindingUpsert,
+  CloudLoginStartResponse,
+  CloudStatus,
 } from './types';
 
-function formatErrorDetail(detail: unknown, fallback: string): string {
-  if (typeof detail === 'string') return detail;
-  if (Array.isArray(detail)) {
-    return detail
-      .map((e: Record<string, unknown>) => e.msg || e.message || JSON.stringify(e))
-      .join('; ');
-  }
-  if (detail && typeof detail === 'object') {
-    const obj = detail as Record<string, unknown>;
-    if (typeof obj.message === 'string') return obj.message;
-    return JSON.stringify(detail);
-  }
-  return fallback;
-}
-
 class ApiClient {
   private getBaseUrl(): string {
     const serverUrl = useServerStore.getState().serverUrl;
@@ -938,6 +926,21 @@ class ApiClient {
 
     return response.blob();
   }
+
+  // Cloud (backup & sync) — browser-based device login. startCloudLogin opens
+  // the system browser server-side; the UI then polls getCloudStatus until the
+  // backend completes the exchange and the link goes live.
+  async getCloudStatus(): Promise<CloudStatus> {
+    return this.request<CloudStatus>('/cloud/status');
+  }
+
+  async startCloudLogin(): Promise<CloudLoginStartResponse> {
+    return this.request<CloudLoginStartResponse>('/cloud/login/start', { method: 'POST' });
+  }
+
+  async disconnectCloud(): Promise<CloudStatus> {
+    return this.request<CloudStatus>('/cloud/disconnect', { method: 'POST' });
+  }
 }
 
 export const apiClient = new ApiClient();

app/src/lib/api/core/ApiError.ts

@@ -1,25 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-import type { ApiRequestOptions } from './ApiRequestOptions';
-import type { ApiResult } from './ApiResult';
-
-export class ApiError extends Error {
-  public readonly url: string;
-  public readonly status: number;
-  public readonly statusText: string;
-  public readonly body: any;
-  public readonly request: ApiRequestOptions;
-
-  constructor(request: ApiRequestOptions, response: ApiResult, message: string) {
-    super(message);
-
-    this.name = 'ApiError';
-    this.url = response.url;
-    this.status = response.status;
-    this.statusText = response.statusText;
-    this.body = response.body;
-    this.request = request;
-  }
-}

app/src/lib/api/core/ApiRequestOptions.ts

@@ -1,17 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export type ApiRequestOptions = {
-  readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH';
-  readonly url: string;
-  readonly path?: Record<string, any>;
-  readonly cookies?: Record<string, any>;
-  readonly headers?: Record<string, any>;
-  readonly query?: Record<string, any>;
-  readonly formData?: Record<string, any>;
-  readonly body?: any;
-  readonly mediaType?: string;
-  readonly responseHeader?: string;
-  readonly errors?: Record<number, string>;
-};

app/src/lib/api/core/ApiResult.ts

@@ -1,11 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export type ApiResult = {
-  readonly url: string;
-  readonly ok: boolean;
-  readonly status: number;
-  readonly statusText: string;
-  readonly body: any;
-};

app/src/lib/api/core/CancelablePromise.ts

@@ -1,130 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export class CancelError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'CancelError';
-  }
-
-  public get isCancelled(): boolean {
-    return true;
-  }
-}
-
-export interface OnCancel {
-  readonly isResolved: boolean;
-  readonly isRejected: boolean;
-  readonly isCancelled: boolean;
-
-  (cancelHandler: () => void): void;
-}
-
-export class CancelablePromise<T> implements Promise<T> {
-  #isResolved: boolean;
-  #isRejected: boolean;
-  #isCancelled: boolean;
-  readonly #cancelHandlers: (() => void)[];
-  readonly #promise: Promise<T>;
-  #resolve?: (value: T | PromiseLike<T>) => void;
-  #reject?: (reason?: any) => void;
-
-  constructor(
-    executor: (
-      resolve: (value: T | PromiseLike<T>) => void,
-      reject: (reason?: any) => void,
-      onCancel: OnCancel,
-    ) => void,
-  ) {
-    this.#isResolved = false;
-    this.#isRejected = false;
-    this.#isCancelled = false;
-    this.#cancelHandlers = [];
-    this.#promise = new Promise<T>((resolve, reject) => {
-      this.#resolve = resolve;
-      this.#reject = reject;
-
-      const onResolve = (value: T | PromiseLike<T>): void => {
-        if (this.#isResolved || this.#isRejected || this.#isCancelled) {
-          return;
-        }
-        this.#isResolved = true;
-        if (this.#resolve) this.#resolve(value);
-      };
-
-      const onReject = (reason?: any): void => {
-        if (this.#isResolved || this.#isRejected || this.#isCancelled) {
-          return;
-        }
-        this.#isRejected = true;
-        if (this.#reject) this.#reject(reason);
-      };
-
-      const onCancel = (cancelHandler: () => void): void => {
-        if (this.#isResolved || this.#isRejected || this.#isCancelled) {
-          return;
-        }
-        this.#cancelHandlers.push(cancelHandler);
-      };
-
-      Object.defineProperty(onCancel, 'isResolved', {
-        get: (): boolean => this.#isResolved,
-      });
-
-      Object.defineProperty(onCancel, 'isRejected', {
-        get: (): boolean => this.#isRejected,
-      });
-
-      Object.defineProperty(onCancel, 'isCancelled', {
-        get: (): boolean => this.#isCancelled,
-      });
-
-      return executor(onResolve, onReject, onCancel as OnCancel);
-    });
-  }
-
-  get [Symbol.toStringTag]() {
-    return 'Cancellable Promise';
-  }
-
-  public then<TResult1 = T, TResult2 = never>(
-    onFulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
-    onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
-  ): Promise<TResult1 | TResult2> {
-    return this.#promise.then(onFulfilled, onRejected);
-  }
-
-  public catch<TResult = never>(
-    onRejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null,
-  ): Promise<T | TResult> {
-    return this.#promise.catch(onRejected);
-  }
-
-  public finally(onFinally?: (() => void) | null): Promise<T> {
-    return this.#promise.finally(onFinally);
-  }
-
-  public cancel(): void {
-    if (this.#isResolved || this.#isRejected || this.#isCancelled) {
-      return;
-    }
-    this.#isCancelled = true;
-    if (this.#cancelHandlers.length) {
-      try {
-        for (const cancelHandler of this.#cancelHandlers) {
-          cancelHandler();
-        }
-      } catch (error) {
-        console.warn('Cancellation threw an error', error);
-        return;
-      }
-    }
-    this.#cancelHandlers.length = 0;
-    if (this.#reject) this.#reject(new CancelError('Request aborted'));
-  }
-
-  public get isCancelled(): boolean {
-    return this.#isCancelled;
-  }
-}

app/src/lib/api/core/OpenAPI.ts

@@ -1,32 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-import type { ApiRequestOptions } from './ApiRequestOptions';
-
-type Resolver<T> = (options: ApiRequestOptions) => Promise<T>;
-type Headers = Record<string, string>;
-
-export type OpenAPIConfig = {
-  BASE: string;
-  VERSION: string;
-  WITH_CREDENTIALS: boolean;
-  CREDENTIALS: 'include' | 'omit' | 'same-origin';
-  TOKEN?: string | Resolver<string> | undefined;
-  USERNAME?: string | Resolver<string> | undefined;
-  PASSWORD?: string | Resolver<string> | undefined;
-  HEADERS?: Headers | Resolver<Headers> | undefined;
-  ENCODE_PATH?: ((path: string) => string) | undefined;
-};
-
-export const OpenAPI: OpenAPIConfig = {
-  BASE: '',
-  VERSION: '0.1.0',
-  WITH_CREDENTIALS: false,
-  CREDENTIALS: 'include',
-  TOKEN: undefined,
-  USERNAME: undefined,
-  PASSWORD: undefined,
-  HEADERS: undefined,
-  ENCODE_PATH: undefined,
-};

app/src/lib/api/core/request.ts

@@ -1,341 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-import { ApiError } from './ApiError';
-import type { ApiRequestOptions } from './ApiRequestOptions';
-import type { ApiResult } from './ApiResult';
-import { CancelablePromise } from './CancelablePromise';
-import type { OnCancel } from './CancelablePromise';
-import type { OpenAPIConfig } from './OpenAPI';
-
-export const isDefined = <T>(
-  value: T | null | undefined,
-): value is Exclude<T, null | undefined> => {
-  return value !== undefined && value !== null;
-};
-
-export const isString = (value: any): value is string => {
-  return typeof value === 'string';
-};
-
-export const isStringWithValue = (value: any): value is string => {
-  return isString(value) && value !== '';
-};
-
-export const isBlob = (value: any): value is Blob => {
-  return (
-    typeof value === 'object' &&
-    typeof value.type === 'string' &&
-    typeof value.stream === 'function' &&
-    typeof value.arrayBuffer === 'function' &&
-    typeof value.constructor === 'function' &&
-    typeof value.constructor.name === 'string' &&
-    /^(Blob|File)$/.test(value.constructor.name) &&
-    /^(Blob|File)$/.test(value[Symbol.toStringTag])
-  );
-};
-
-export const isFormData = (value: any): value is FormData => {
-  return value instanceof FormData;
-};
-
-export const base64 = (str: string): string => {
-  try {
-    return btoa(str);
-  } catch (err) {
-    // @ts-ignore
-    return Buffer.from(str).toString('base64');
-  }
-};
-
-export const getQueryString = (params: Record<string, any>): string => {
-  const qs: string[] = [];
-
-  const append = (key: string, value: any) => {
-    qs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
-  };
-
-  const process = (key: string, value: any) => {
-    if (isDefined(value)) {
-      if (Array.isArray(value)) {
-        value.forEach((v) => {
-          process(key, v);
-        });
-      } else if (typeof value === 'object') {
-        Object.entries(value).forEach(([k, v]) => {
-          process(`${key}[${k}]`, v);
-        });
-      } else {
-        append(key, value);
-      }
-    }
-  };
-
-  Object.entries(params).forEach(([key, value]) => {
-    process(key, value);
-  });
-
-  if (qs.length > 0) {
-    return `?${qs.join('&')}`;
-  }
-
-  return '';
-};
-
-const getUrl = (config: OpenAPIConfig, options: ApiRequestOptions): string => {
-  const encoder = config.ENCODE_PATH || encodeURI;
-
-  const path = options.url
-    .replace('{api-version}', config.VERSION)
-    .replace(/{(.*?)}/g, (substring: string, group: string) => {
-      if (options.path?.hasOwnProperty(group)) {
-        return encoder(String(options.path[group]));
-      }
-      return substring;
-    });
-
-  const url = `${config.BASE}${path}`;
-  if (options.query) {
-    return `${url}${getQueryString(options.query)}`;
-  }
-  return url;
-};
-
-export const getFormData = (options: ApiRequestOptions): FormData | undefined => {
-  if (options.formData) {
-    const formData = new FormData();
-
-    const process = (key: string, value: any) => {
-      if (isString(value) || isBlob(value)) {
-        formData.append(key, value);
-      } else {
-        formData.append(key, JSON.stringify(value));
-      }
-    };
-
-    Object.entries(options.formData)
-      .filter(([_, value]) => isDefined(value))
-      .forEach(([key, value]) => {
-        if (Array.isArray(value)) {
-          value.forEach((v) => process(key, v));
-        } else {
-          process(key, value);
-        }
-      });
-
-    return formData;
-  }
-  return undefined;
-};
-
-type Resolver<T> = (options: ApiRequestOptions) => Promise<T>;
-
-export const resolve = async <T>(
-  options: ApiRequestOptions,
-  resolver?: T | Resolver<T>,
-): Promise<T | undefined> => {
-  if (typeof resolver === 'function') {
-    return (resolver as Resolver<T>)(options);
-  }
-  return resolver;
-};
-
-export const getHeaders = async (
-  config: OpenAPIConfig,
-  options: ApiRequestOptions,
-): Promise<Headers> => {
-  const [token, username, password, additionalHeaders] = await Promise.all([
-    resolve(options, config.TOKEN),
-    resolve(options, config.USERNAME),
-    resolve(options, config.PASSWORD),
-    resolve(options, config.HEADERS),
-  ]);
-
-  const headers = Object.entries({
-    Accept: 'application/json',
-    ...additionalHeaders,
-    ...options.headers,
-  })
-    .filter(([_, value]) => isDefined(value))
-    .reduce(
-      (headers, [key, value]) => ({
-        ...headers,
-        [key]: String(value),
-      }),
-      {} as Record<string, string>,
-    );
-
-  if (isStringWithValue(token)) {
-    headers['Authorization'] = `Bearer ${token}`;
-  }
-
-  if (isStringWithValue(username) && isStringWithValue(password)) {
-    const credentials = base64(`${username}:${password}`);
-    headers['Authorization'] = `Basic ${credentials}`;
-  }
-
-  if (options.body !== undefined) {
-    if (options.mediaType) {
-      headers['Content-Type'] = options.mediaType;
-    } else if (isBlob(options.body)) {
-      headers['Content-Type'] = options.body.type || 'application/octet-stream';
-    } else if (isString(options.body)) {
-      headers['Content-Type'] = 'text/plain';
-    } else if (!isFormData(options.body)) {
-      headers['Content-Type'] = 'application/json';
-    }
-  }
-
-  return new Headers(headers);
-};
-
-export const getRequestBody = (options: ApiRequestOptions): any => {
-  if (options.body !== undefined) {
-    if (options.mediaType?.includes('/json')) {
-      return JSON.stringify(options.body);
-    } else if (isString(options.body) || isBlob(options.body) || isFormData(options.body)) {
-      return options.body;
-    } else {
-      return JSON.stringify(options.body);
-    }
-  }
-  return undefined;
-};
-
-export const sendRequest = async (
-  config: OpenAPIConfig,
-  options: ApiRequestOptions,
-  url: string,
-  body: any,
-  formData: FormData | undefined,
-  headers: Headers,
-  onCancel: OnCancel,
-): Promise<Response> => {
-  const controller = new AbortController();
-
-  const request: RequestInit = {
-    headers,
-    body: body ?? formData,
-    method: options.method,
-    signal: controller.signal,
-  };
-
-  if (config.WITH_CREDENTIALS) {
-    request.credentials = config.CREDENTIALS;
-  }
-
-  onCancel(() => controller.abort());
-
-  return await fetch(url, request);
-};
-
-export const getResponseHeader = (
-  response: Response,
-  responseHeader?: string,
-): string | undefined => {
-  if (responseHeader) {
-    const content = response.headers.get(responseHeader);
-    if (isString(content)) {
-      return content;
-    }
-  }
-  return undefined;
-};
-
-export const getResponseBody = async (response: Response): Promise<any> => {
-  if (response.status !== 204) {
-    try {
-      const contentType = response.headers.get('Content-Type');
-      if (contentType) {
-        const jsonTypes = ['application/json', 'application/problem+json'];
-        const isJSON = jsonTypes.some((type) => contentType.toLowerCase().startsWith(type));
-        if (isJSON) {
-          return await response.json();
-        } else {
-          return await response.text();
-        }
-      }
-    } catch (error) {
-      console.error(error);
-    }
-  }
-  return undefined;
-};
-
-export const catchErrorCodes = (options: ApiRequestOptions, result: ApiResult): void => {
-  const errors: Record<number, string> = {
-    400: 'Bad Request',
-    401: 'Unauthorized',
-    403: 'Forbidden',
-    404: 'Not Found',
-    500: 'Internal Server Error',
-    502: 'Bad Gateway',
-    503: 'Service Unavailable',
-    ...options.errors,
-  };
-
-  const error = errors[result.status];
-  if (error) {
-    throw new ApiError(options, result, error);
-  }
-
-  if (!result.ok) {
-    const errorStatus = result.status ?? 'unknown';
-    const errorStatusText = result.statusText ?? 'unknown';
-    const errorBody = (() => {
-      try {
-        return JSON.stringify(result.body, null, 2);
-      } catch (e) {
-        return undefined;
-      }
-    })();
-
-    throw new ApiError(
-      options,
-      result,
-      `Generic Error: status: ${errorStatus}; status text: ${errorStatusText}; body: ${errorBody}`,
-    );
-  }
-};
-
-/**
- * Request method
- * @param config The OpenAPI configuration object
- * @param options The request options from the service
- * @returns CancelablePromise<T>
- * @throws ApiError
- */
-export const request = <T>(
-  config: OpenAPIConfig,
-  options: ApiRequestOptions,
-): CancelablePromise<T> => {
-  return new CancelablePromise(async (resolve, reject, onCancel) => {
-    try {
-      const url = getUrl(config, options);
-      const formData = getFormData(options);
-      const body = getRequestBody(options);
-      const headers = await getHeaders(config, options);
-
-      if (!onCancel.isCancelled) {
-        const response = await sendRequest(config, options, url, body, formData, headers, onCancel);
-        const responseBody = await getResponseBody(response);
-        const responseHeader = getResponseHeader(response, options.responseHeader);
-
-        const result: ApiResult = {
-          url,
-          ok: response.ok,
-          status: response.status,
-          statusText: response.statusText,
-          body: responseHeader ?? responseBody,
-        };
-
-        catchErrorCodes(options, result);
-
-        resolve(result.body);
-      }
-    } catch (error) {
-      reject(error);
-    }
-  });
-};

app/src/lib/api/errors.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test';
+import { formatErrorDetail } from './errors';
+
+const FALLBACK = 'HTTP error! status: 500';
+
+describe('formatErrorDetail', () => {
+  test('returns string details as-is', () => {
+    expect(formatErrorDetail('Profile not found', FALLBACK)).toBe('Profile not found');
+  });
+
+  test('returns empty string details as-is (not the fallback)', () => {
+    expect(formatErrorDetail('', FALLBACK)).toBe('');
+  });
+
+  test('joins FastAPI validation error arrays on msg', () => {
+    const detail = [
+      { loc: ['body', 'text'], msg: 'field required', type: 'value_error.missing' },
+      { loc: ['body', 'seed'], msg: 'value is not a valid integer', type: 'type_error.integer' },
+    ];
+    expect(formatErrorDetail(detail, FALLBACK)).toBe(
+      'field required; value is not a valid integer',
+    );
+  });
+
+  test('falls back to message key within array entries', () => {
+    expect(formatErrorDetail([{ message: 'boom' }], FALLBACK)).toBe('boom');
+  });
+
+  test('stringifies array entries with neither msg nor message', () => {
+    expect(formatErrorDetail([{ code: 42 }], FALLBACK)).toBe('{"code":42}');
+  });
+
+  test('returns empty string for an empty array', () => {
+    expect(formatErrorDetail([], FALLBACK)).toBe('');
+  });
+
+  test('uses message property of object details', () => {
+    expect(formatErrorDetail({ message: 'engine offline' }, FALLBACK)).toBe('engine offline');
+  });
+
+  test('stringifies objects without a string message', () => {
+    expect(formatErrorDetail({ message: 42, hint: 'x' }, FALLBACK)).toBe(
+      '{"message":42,"hint":"x"}',
+    );
+    expect(formatErrorDetail({ error: 'nested' }, FALLBACK)).toBe('{"error":"nested"}');
+  });
+
+  test('falls back for null, undefined, and primitives', () => {
+    expect(formatErrorDetail(null, FALLBACK)).toBe(FALLBACK);
+    expect(formatErrorDetail(undefined, FALLBACK)).toBe(FALLBACK);
+    expect(formatErrorDetail(404, FALLBACK)).toBe(FALLBACK);
+    expect(formatErrorDetail(true, FALLBACK)).toBe(FALLBACK);
+  });
+
+  test('preserves unicode in messages', () => {
+    expect(formatErrorDetail('模型未加载 🎙️', FALLBACK)).toBe('模型未加载 🎙️');
+  });
+});

app/src/lib/api/errors.ts

@@ -0,0 +1,21 @@
+/**
+ * Normalizes a FastAPI error `detail` payload into a human-readable message.
+ *
+ * FastAPI returns `detail` as a plain string for HTTPException, an array of
+ * validation error objects for 422 responses, or an arbitrary object for
+ * custom handlers. Anything unrecognized falls back to the provided default.
+ */
+export function formatErrorDetail(detail: unknown, fallback: string): string {
+  if (typeof detail === 'string') return detail;
+  if (Array.isArray(detail)) {
+    return detail
+      .map((e: Record<string, unknown>) => e.msg || e.message || JSON.stringify(e))
+      .join('; ');
+  }
+  if (detail && typeof detail === 'object') {
+    const obj = detail as Record<string, unknown>;
+    if (typeof obj.message === 'string') return obj.message;
+    return JSON.stringify(detail);
+  }
+  return fallback;
+}

app/src/lib/api/index.ts

@@ -1,44 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export { ApiError } from './core/ApiError';
-export { CancelablePromise, CancelError } from './core/CancelablePromise';
-export { OpenAPI } from './core/OpenAPI';
-export type { OpenAPIConfig } from './core/OpenAPI';
-
-export type { Body_add_profile_sample_profiles__profile_id__samples_post } from './models/Body_add_profile_sample_profiles__profile_id__samples_post';
-export type { Body_transcribe_audio_transcribe_post } from './models/Body_transcribe_audio_transcribe_post';
-export type { GenerationRequest } from './models/GenerationRequest';
-export type { GenerationResponse } from './models/GenerationResponse';
-export type { HealthResponse } from './models/HealthResponse';
-export type { HistoryListResponse } from './models/HistoryListResponse';
-export type { HistoryResponse } from './models/HistoryResponse';
-export type { HTTPValidationError } from './models/HTTPValidationError';
-export type { ModelDownloadRequest } from './models/ModelDownloadRequest';
-export type { ModelStatus } from './models/ModelStatus';
-export type { ModelStatusListResponse } from './models/ModelStatusListResponse';
-export type { ProfileSampleResponse } from './models/ProfileSampleResponse';
-export type { TranscriptionResponse } from './models/TranscriptionResponse';
-export type { ValidationError } from './models/ValidationError';
-export type { VoiceProfileCreate } from './models/VoiceProfileCreate';
-export type { VoiceProfileResponse } from './models/VoiceProfileResponse';
-
-export { $Body_add_profile_sample_profiles__profile_id__samples_post } from './schemas/$Body_add_profile_sample_profiles__profile_id__samples_post';
-export { $Body_transcribe_audio_transcribe_post } from './schemas/$Body_transcribe_audio_transcribe_post';
-export { $GenerationRequest } from './schemas/$GenerationRequest';
-export { $GenerationResponse } from './schemas/$GenerationResponse';
-export { $HealthResponse } from './schemas/$HealthResponse';
-export { $HistoryListResponse } from './schemas/$HistoryListResponse';
-export { $HistoryResponse } from './schemas/$HistoryResponse';
-export { $HTTPValidationError } from './schemas/$HTTPValidationError';
-export { $ModelDownloadRequest } from './schemas/$ModelDownloadRequest';
-export { $ModelStatus } from './schemas/$ModelStatus';
-export { $ModelStatusListResponse } from './schemas/$ModelStatusListResponse';
-export { $ProfileSampleResponse } from './schemas/$ProfileSampleResponse';
-export { $TranscriptionResponse } from './schemas/$TranscriptionResponse';
-export { $ValidationError } from './schemas/$ValidationError';
-export { $VoiceProfileCreate } from './schemas/$VoiceProfileCreate';
-export { $VoiceProfileResponse } from './schemas/$VoiceProfileResponse';
-
-export { DefaultService } from './services/DefaultService';

app/src/lib/api/models/Body_add_profile_sample_profiles__profile_id__samples_post.ts

@@ -1,8 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export type Body_add_profile_sample_profiles__profile_id__samples_post = {
-  file: Blob;
-  reference_text: string;
-};

app/src/lib/api/models/Body_transcribe_audio_transcribe_post.ts

@@ -1,8 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export type Body_transcribe_audio_transcribe_post = {
-  file: Blob;
-  language?: string | null;
-};

app/src/lib/api/models/GenerationRequest.ts

@@ -1,15 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Request model for voice generation.
- */
-export type GenerationRequest = {
-  profile_id: string;
-  text: string;
-  language?: string;
-  seed?: number | null;
-  model_size?: string | null;
-  instruct?: string | null;
-};

app/src/lib/api/models/GenerationResponse.ts

@@ -1,18 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Response model for voice generation.
- */
-export type GenerationResponse = {
-  id: string;
-  profile_id: string;
-  text: string;
-  language: string;
-  audio_path: string;
-  duration: number;
-  seed: number | null;
-  instruct: string | null;
-  created_at: string;
-};

app/src/lib/api/models/HTTPValidationError.ts

@@ -1,8 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-import type { ValidationError } from './ValidationError';
-export type HTTPValidationError = {
-  detail?: Array<ValidationError>;
-};

app/src/lib/api/models/HealthResponse.ts

@@ -1,15 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Response model for health check.
- */
-export type HealthResponse = {
-  status: string;
-  model_loaded: boolean;
-  model_downloaded?: boolean | null;
-  model_size?: string | null;
-  gpu_available: boolean;
-  vram_used_mb?: number | null;
-};

app/src/lib/api/models/HistoryListResponse.ts

@@ -1,12 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-import type { HistoryResponse } from './HistoryResponse';
-/**
- * Response model for history list.
- */
-export type HistoryListResponse = {
-  items: Array<HistoryResponse>;
-  total: number;
-};

app/src/lib/api/models/HistoryResponse.ts

@@ -1,19 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Response model for history entry (includes profile name).
- */
-export type HistoryResponse = {
-  id: string;
-  profile_id: string;
-  profile_name: string;
-  text: string;
-  language: string;
-  audio_path: string;
-  duration: number;
-  seed: number | null;
-  instruct: string | null;
-  created_at: string;
-};

app/src/lib/api/models/ModelDownloadRequest.ts

@@ -1,10 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Request model for triggering model download.
- */
-export type ModelDownloadRequest = {
-  model_name: string;
-};

app/src/lib/api/models/ModelStatus.ts

@@ -1,15 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Response model for model status.
- */
-export type ModelStatus = {
-  model_name: string;
-  display_name: string;
-  downloaded: boolean;
-  downloading?: boolean; // True if download is in progress
-  size_mb?: number | null;
-  loaded?: boolean;
-};

app/src/lib/api/models/ModelStatusListResponse.ts

@@ -1,11 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-import type { ModelStatus } from './ModelStatus';
-/**
- * Response model for model status list.
- */
-export type ModelStatusListResponse = {
-  models: Array<ModelStatus>;
-};

app/src/lib/api/models/ProfileSampleResponse.ts

@@ -1,13 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Response model for profile sample.
- */
-export type ProfileSampleResponse = {
-  id: string;
-  profile_id: string;
-  audio_path: string;
-  reference_text: string;
-};

app/src/lib/api/models/TranscriptionResponse.ts

@@ -1,11 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Response model for transcription.
- */
-export type TranscriptionResponse = {
-  text: string;
-  duration: number;
-};

app/src/lib/api/models/ValidationError.ts

@@ -1,9 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export type ValidationError = {
-  loc: Array<string | number>;
-  msg: string;
-  type: string;
-};

app/src/lib/api/models/VoiceProfileCreate.ts

@@ -1,12 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Request model for creating a voice profile.
- */
-export type VoiceProfileCreate = {
-  name: string;
-  description?: string | null;
-  language?: string;
-};

app/src/lib/api/models/VoiceProfileResponse.ts

@@ -1,15 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-/**
- * Response model for voice profile.
- */
-export type VoiceProfileResponse = {
-  id: string;
-  name: string;
-  description: string | null;
-  language: string;
-  created_at: string;
-  updated_at: string;
-};

app/src/lib/api/schemas/$Body_add_profile_sample_profiles__profile_id__samples_post.ts

@@ -1,17 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $Body_add_profile_sample_profiles__profile_id__samples_post = {
-  properties: {
-    file: {
-      type: 'binary',
-      isRequired: true,
-      format: 'binary',
-    },
-    reference_text: {
-      type: 'string',
-      isRequired: true,
-    },
-  },
-} as const;

app/src/lib/api/schemas/$Body_transcribe_audio_transcribe_post.ts

@@ -1,24 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $Body_transcribe_audio_transcribe_post = {
-  properties: {
-    file: {
-      type: 'binary',
-      isRequired: true,
-      format: 'binary',
-    },
-    language: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'string',
-        },
-        {
-          type: 'null',
-        },
-      ],
-    },
-  },
-} as const;

app/src/lib/api/schemas/$GenerationRequest.ts

@@ -1,46 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $GenerationRequest = {
-  description: `Request model for voice generation.`,
-  properties: {
-    profile_id: {
-      type: 'string',
-      isRequired: true,
-    },
-    text: {
-      type: 'string',
-      isRequired: true,
-      maxLength: 5000,
-      minLength: 1,
-    },
-    language: {
-      type: 'string',
-      pattern: '^(en|zh)$',
-    },
-    seed: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'number',
-        },
-        {
-          type: 'null',
-        },
-      ],
-    },
-    model_size: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'string',
-          pattern: '^(1\\.7B|0\\.6B)$',
-        },
-        {
-          type: 'null',
-        },
-      ],
-    },
-  },
-} as const;

app/src/lib/api/schemas/$GenerationResponse.ts

@@ -1,50 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $GenerationResponse = {
-  description: `Response model for voice generation.`,
-  properties: {
-    id: {
-      type: 'string',
-      isRequired: true,
-    },
-    profile_id: {
-      type: 'string',
-      isRequired: true,
-    },
-    text: {
-      type: 'string',
-      isRequired: true,
-    },
-    language: {
-      type: 'string',
-      isRequired: true,
-    },
-    audio_path: {
-      type: 'string',
-      isRequired: true,
-    },
-    duration: {
-      type: 'number',
-      isRequired: true,
-    },
-    seed: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'number',
-        },
-        {
-          type: 'null',
-        },
-      ],
-      isRequired: true,
-    },
-    created_at: {
-      type: 'string',
-      isRequired: true,
-      format: 'date-time',
-    },
-  },
-} as const;

app/src/lib/api/schemas/$HTTPValidationError.ts

@@ -1,14 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $HTTPValidationError = {
-  properties: {
-    detail: {
-      type: 'array',
-      contains: {
-        type: 'ValidationError',
-      },
-    },
-  },
-} as const;

app/src/lib/api/schemas/$HealthResponse.ts

@@ -1,54 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $HealthResponse = {
-  description: `Response model for health check.`,
-  properties: {
-    status: {
-      type: 'string',
-      isRequired: true,
-    },
-    model_loaded: {
-      type: 'boolean',
-      isRequired: true,
-    },
-    model_downloaded: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'boolean',
-        },
-        {
-          type: 'null',
-        },
-      ],
-    },
-    model_size: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'string',
-        },
-        {
-          type: 'null',
-        },
-      ],
-    },
-    gpu_available: {
-      type: 'boolean',
-      isRequired: true,
-    },
-    vram_used_mb: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'number',
-        },
-        {
-          type: 'null',
-        },
-      ],
-    },
-  },
-} as const;

app/src/lib/api/schemas/$HistoryListResponse.ts

@@ -1,20 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $HistoryListResponse = {
-  description: `Response model for history list.`,
-  properties: {
-    items: {
-      type: 'array',
-      contains: {
-        type: 'HistoryResponse',
-      },
-      isRequired: true,
-    },
-    total: {
-      type: 'number',
-      isRequired: true,
-    },
-  },
-} as const;

app/src/lib/api/schemas/$HistoryResponse.ts

@@ -1,54 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $HistoryResponse = {
-  description: `Response model for history entry (includes profile name).`,
-  properties: {
-    id: {
-      type: 'string',
-      isRequired: true,
-    },
-    profile_id: {
-      type: 'string',
-      isRequired: true,
-    },
-    profile_name: {
-      type: 'string',
-      isRequired: true,
-    },
-    text: {
-      type: 'string',
-      isRequired: true,
-    },
-    language: {
-      type: 'string',
-      isRequired: true,
-    },
-    audio_path: {
-      type: 'string',
-      isRequired: true,
-    },
-    duration: {
-      type: 'number',
-      isRequired: true,
-    },
-    seed: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'number',
-        },
-        {
-          type: 'null',
-        },
-      ],
-      isRequired: true,
-    },
-    created_at: {
-      type: 'string',
-      isRequired: true,
-      format: 'date-time',
-    },
-  },
-} as const;

app/src/lib/api/schemas/$ModelDownloadRequest.ts

@@ -1,13 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $ModelDownloadRequest = {
-  description: `Request model for triggering model download.`,
-  properties: {
-    model_name: {
-      type: 'string',
-      isRequired: true,
-    },
-  },
-} as const;

app/src/lib/api/schemas/$ModelStatus.ts

@@ -1,35 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $ModelStatus = {
-  description: `Response model for model status.`,
-  properties: {
-    model_name: {
-      type: 'string',
-      isRequired: true,
-    },
-    display_name: {
-      type: 'string',
-      isRequired: true,
-    },
-    downloaded: {
-      type: 'boolean',
-      isRequired: true,
-    },
-    size_mb: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'number',
-        },
-        {
-          type: 'null',
-        },
-      ],
-    },
-    loaded: {
-      type: 'boolean',
-    },
-  },
-} as const;

app/src/lib/api/schemas/$ModelStatusListResponse.ts

@@ -1,16 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $ModelStatusListResponse = {
-  description: `Response model for model status list.`,
-  properties: {
-    models: {
-      type: 'array',
-      contains: {
-        type: 'ModelStatus',
-      },
-      isRequired: true,
-    },
-  },
-} as const;

app/src/lib/api/schemas/$ProfileSampleResponse.ts

@@ -1,25 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $ProfileSampleResponse = {
-  description: `Response model for profile sample.`,
-  properties: {
-    id: {
-      type: 'string',
-      isRequired: true,
-    },
-    profile_id: {
-      type: 'string',
-      isRequired: true,
-    },
-    audio_path: {
-      type: 'string',
-      isRequired: true,
-    },
-    reference_text: {
-      type: 'string',
-      isRequired: true,
-    },
-  },
-} as const;

app/src/lib/api/schemas/$TranscriptionResponse.ts

@@ -1,17 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $TranscriptionResponse = {
-  description: `Response model for transcription.`,
-  properties: {
-    text: {
-      type: 'string',
-      isRequired: true,
-    },
-    duration: {
-      type: 'number',
-      isRequired: true,
-    },
-  },
-} as const;

app/src/lib/api/schemas/$ValidationError.ts

@@ -1,31 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $ValidationError = {
-  properties: {
-    loc: {
-      type: 'array',
-      contains: {
-        type: 'any-of',
-        contains: [
-          {
-            type: 'string',
-          },
-          {
-            type: 'number',
-          },
-        ],
-      },
-      isRequired: true,
-    },
-    msg: {
-      type: 'string',
-      isRequired: true,
-    },
-    type: {
-      type: 'string',
-      isRequired: true,
-    },
-  },
-} as const;

app/src/lib/api/schemas/$VoiceProfileCreate.ts

@@ -1,31 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $VoiceProfileCreate = {
-  description: `Request model for creating a voice profile.`,
-  properties: {
-    name: {
-      type: 'string',
-      isRequired: true,
-      maxLength: 100,
-      minLength: 1,
-    },
-    description: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'string',
-          maxLength: 500,
-        },
-        {
-          type: 'null',
-        },
-      ],
-    },
-    language: {
-      type: 'string',
-      pattern: '^(en|zh)$',
-    },
-  },
-} as const;

app/src/lib/api/schemas/$VoiceProfileResponse.ts

@@ -1,43 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-export const $VoiceProfileResponse = {
-  description: `Response model for voice profile.`,
-  properties: {
-    id: {
-      type: 'string',
-      isRequired: true,
-    },
-    name: {
-      type: 'string',
-      isRequired: true,
-    },
-    description: {
-      type: 'any-of',
-      contains: [
-        {
-          type: 'string',
-        },
-        {
-          type: 'null',
-        },
-      ],
-      isRequired: true,
-    },
-    language: {
-      type: 'string',
-      isRequired: true,
-    },
-    created_at: {
-      type: 'string',
-      isRequired: true,
-      format: 'date-time',
-    },
-    updated_at: {
-      type: 'string',
-      isRequired: true,
-      format: 'date-time',
-    },
-  },
-} as const;

app/src/lib/api/services/DefaultService.ts

@@ -1,459 +0,0 @@
-/* generated using openapi-typescript-codegen -- do not edit */
-/* istanbul ignore file */
-/* tslint:disable */
-/* eslint-disable */
-import type { Body_add_profile_sample_profiles__profile_id__samples_post } from '../models/Body_add_profile_sample_profiles__profile_id__samples_post';
-import type { Body_transcribe_audio_transcribe_post } from '../models/Body_transcribe_audio_transcribe_post';
-import type { GenerationRequest } from '../models/GenerationRequest';
-import type { GenerationResponse } from '../models/GenerationResponse';
-import type { HealthResponse } from '../models/HealthResponse';
-import type { HistoryListResponse } from '../models/HistoryListResponse';
-import type { HistoryResponse } from '../models/HistoryResponse';
-import type { ModelDownloadRequest } from '../models/ModelDownloadRequest';
-import type { ModelStatusListResponse } from '../models/ModelStatusListResponse';
-import type { ProfileSampleResponse } from '../models/ProfileSampleResponse';
-import type { TranscriptionResponse } from '../models/TranscriptionResponse';
-import type { VoiceProfileCreate } from '../models/VoiceProfileCreate';
-import type { VoiceProfileResponse } from '../models/VoiceProfileResponse';
-import type { CancelablePromise } from '../core/CancelablePromise';
-import { OpenAPI } from '../core/OpenAPI';
-import { request as __request } from '../core/request';
-export class DefaultService {
-  /**
-   * Root
-   * Root endpoint.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static rootGet(): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/',
-    });
-  }
-  /**
-   * Health
-   * Health check endpoint.
-   * @returns HealthResponse Successful Response
-   * @throws ApiError
-   */
-  public static healthHealthGet(): CancelablePromise<HealthResponse> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/health',
-    });
-  }
-  /**
-   * List Profiles
-   * List all voice profiles.
-   * @returns VoiceProfileResponse Successful Response
-   * @throws ApiError
-   */
-  public static listProfilesProfilesGet(): CancelablePromise<Array<VoiceProfileResponse>> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/profiles',
-    });
-  }
-  /**
-   * Create Profile
-   * Create a new voice profile.
-   * @returns VoiceProfileResponse Successful Response
-   * @throws ApiError
-   */
-  public static createProfileProfilesPost({
-    requestBody,
-  }: {
-    requestBody: VoiceProfileCreate;
-  }): CancelablePromise<VoiceProfileResponse> {
-    return __request(OpenAPI, {
-      method: 'POST',
-      url: '/profiles',
-      body: requestBody,
-      mediaType: 'application/json',
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Get Profile
-   * Get a voice profile by ID.
-   * @returns VoiceProfileResponse Successful Response
-   * @throws ApiError
-   */
-  public static getProfileProfilesProfileIdGet({
-    profileId,
-  }: {
-    profileId: string;
-  }): CancelablePromise<VoiceProfileResponse> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/profiles/{profile_id}',
-      path: {
-        profile_id: profileId,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Update Profile
-   * Update a voice profile.
-   * @returns VoiceProfileResponse Successful Response
-   * @throws ApiError
-   */
-  public static updateProfileProfilesProfileIdPut({
-    profileId,
-    requestBody,
-  }: {
-    profileId: string;
-    requestBody: VoiceProfileCreate;
-  }): CancelablePromise<VoiceProfileResponse> {
-    return __request(OpenAPI, {
-      method: 'PUT',
-      url: '/profiles/{profile_id}',
-      path: {
-        profile_id: profileId,
-      },
-      body: requestBody,
-      mediaType: 'application/json',
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Delete Profile
-   * Delete a voice profile.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static deleteProfileProfilesProfileIdDelete({
-    profileId,
-  }: {
-    profileId: string;
-  }): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'DELETE',
-      url: '/profiles/{profile_id}',
-      path: {
-        profile_id: profileId,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Add Profile Sample
-   * Add a sample to a voice profile.
-   * @returns ProfileSampleResponse Successful Response
-   * @throws ApiError
-   */
-  public static addProfileSampleProfilesProfileIdSamplesPost({
-    profileId,
-    formData,
-  }: {
-    profileId: string;
-    formData: Body_add_profile_sample_profiles__profile_id__samples_post;
-  }): CancelablePromise<ProfileSampleResponse> {
-    return __request(OpenAPI, {
-      method: 'POST',
-      url: '/profiles/{profile_id}/samples',
-      path: {
-        profile_id: profileId,
-      },
-      formData: formData,
-      mediaType: 'multipart/form-data',
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Get Profile Samples
-   * Get all samples for a profile.
-   * @returns ProfileSampleResponse Successful Response
-   * @throws ApiError
-   */
-  public static getProfileSamplesProfilesProfileIdSamplesGet({
-    profileId,
-  }: {
-    profileId: string;
-  }): CancelablePromise<Array<ProfileSampleResponse>> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/profiles/{profile_id}/samples',
-      path: {
-        profile_id: profileId,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Delete Profile Sample
-   * Delete a profile sample.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static deleteProfileSampleProfilesSamplesSampleIdDelete({
-    sampleId,
-  }: {
-    sampleId: string;
-  }): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'DELETE',
-      url: '/profiles/samples/{sample_id}',
-      path: {
-        sample_id: sampleId,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Generate Speech
-   * Generate speech from text using a voice profile.
-   * @returns GenerationResponse Successful Response
-   * @throws ApiError
-   */
-  public static generateSpeechGeneratePost({
-    requestBody,
-  }: {
-    requestBody: GenerationRequest;
-  }): CancelablePromise<GenerationResponse> {
-    return __request(OpenAPI, {
-      method: 'POST',
-      url: '/generate',
-      body: requestBody,
-      mediaType: 'application/json',
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * List History
-   * List generation history with optional filters.
-   * @returns HistoryListResponse Successful Response
-   * @throws ApiError
-   */
-  public static listHistoryHistoryGet({
-    profileId,
-    search,
-    limit = 50,
-    offset,
-  }: {
-    profileId?: string | null;
-    search?: string | null;
-    limit?: number;
-    offset?: number;
-  }): CancelablePromise<HistoryListResponse> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/history',
-      query: {
-        profile_id: profileId,
-        search: search,
-        limit: limit,
-        offset: offset,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Get Generation
-   * Get a generation by ID.
-   * @returns HistoryResponse Successful Response
-   * @throws ApiError
-   */
-  public static getGenerationHistoryGenerationIdGet({
-    generationId,
-  }: {
-    generationId: string;
-  }): CancelablePromise<HistoryResponse> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/history/{generation_id}',
-      path: {
-        generation_id: generationId,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Delete Generation
-   * Delete a generation.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static deleteGenerationHistoryGenerationIdDelete({
-    generationId,
-  }: {
-    generationId: string;
-  }): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'DELETE',
-      url: '/history/{generation_id}',
-      path: {
-        generation_id: generationId,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Get Stats
-   * Get generation statistics.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static getStatsHistoryStatsGet(): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/history/stats',
-    });
-  }
-  /**
-   * Transcribe Audio
-   * Transcribe audio file to text.
-   * @returns TranscriptionResponse Successful Response
-   * @throws ApiError
-   */
-  public static transcribeAudioTranscribePost({
-    formData,
-  }: {
-    formData: Body_transcribe_audio_transcribe_post;
-  }): CancelablePromise<TranscriptionResponse> {
-    return __request(OpenAPI, {
-      method: 'POST',
-      url: '/transcribe',
-      formData: formData,
-      mediaType: 'multipart/form-data',
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Get Audio
-   * Serve generated audio file.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static getAudioAudioGenerationIdGet({
-    generationId,
-  }: {
-    generationId: string;
-  }): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/audio/{generation_id}',
-      path: {
-        generation_id: generationId,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Load Model
-   * Manually load TTS model.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static loadModelModelsLoadPost({
-    modelSize = '1.7B',
-  }: {
-    modelSize?: string;
-  }): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'POST',
-      url: '/models/load',
-      query: {
-        model_size: modelSize,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Unload Model
-   * Unload TTS model to free memory.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static unloadModelModelsUnloadPost(): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'POST',
-      url: '/models/unload',
-    });
-  }
-  /**
-   * Get Model Progress
-   * Get model download progress via Server-Sent Events.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static getModelProgressModelsProgressModelNameGet({
-    modelName,
-  }: {
-    modelName: string;
-  }): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/models/progress/{model_name}',
-      path: {
-        model_name: modelName,
-      },
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-  /**
-   * Get Model Status
-   * Get status of all available models.
-   * @returns ModelStatusListResponse Successful Response
-   * @throws ApiError
-   */
-  public static getModelStatusModelsStatusGet(): CancelablePromise<ModelStatusListResponse> {
-    return __request(OpenAPI, {
-      method: 'GET',
-      url: '/models/status',
-    });
-  }
-  /**
-   * Trigger Model Download
-   * Trigger download of a specific model.
-   * @returns any Successful Response
-   * @throws ApiError
-   */
-  public static triggerModelDownloadModelsDownloadPost({
-    requestBody,
-  }: {
-    requestBody: ModelDownloadRequest;
-  }): CancelablePromise<any> {
-    return __request(OpenAPI, {
-      method: 'POST',
-      url: '/models/download',
-      body: requestBody,
-      mediaType: 'application/json',
-      errors: {
-        422: `Validation Error`,
-      },
-    });
-  }
-}

app/src/lib/api/types.ts

@@ -213,6 +213,10 @@ export interface CaptureSettings {
   /** Whether the global keyboard hotkey is armed. Off by default — turning
    *  this on triggers the macOS Input Monitoring TCC prompt. */
   hotkey_enabled: boolean;
+  /** Hold the mic open while dictation is enabled so push-to-talk doesn't clip
+   *  the first words. Off by default — when on, the OS mic indicator stays lit
+   *  the whole time dictation is enabled. */
+  keep_mic_warm: boolean;
   /** keytap key names. Defaults are platform-specific right-hand modifiers. */
   chord_push_to_talk_keys: string[];
   /** keytap key names. Toggle adds Space to the platform-specific PTT chord. */
@@ -542,3 +546,18 @@ export interface MCPClientBindingUpsert {
 export interface MCPClientBindingListResponse {
   items: MCPClientBinding[];
 }
+
+/* ─── Cloud (backup & sync) ───────────────────────────────────────────── */
+
+export interface CloudLoginStartResponse {
+  authorize_url: string;
+}
+
+export interface CloudStatus {
+  connected: boolean;
+  device_name: string | null;
+  account_user_id: string | null;
+  key_prefix: string | null;
+  connected_at: string | null;
+  dashboard_url: string;
+}

app/src/lib/constants/languages.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  ALL_LANGUAGES,
+  ENGINE_LANGUAGES,
+  LANGUAGE_CODES,
+  LANGUAGE_OPTIONS,
+  getLanguageOptionsForEngine,
+} from './languages';
+
+describe('ENGINE_LANGUAGES', () => {
+  test('every engine maps only to codes defined in ALL_LANGUAGES', () => {
+    for (const [engine, codes] of Object.entries(ENGINE_LANGUAGES)) {
+      for (const code of codes) {
+        expect(ALL_LANGUAGES[code], `${engine} references unknown code "${code}"`).toBeDefined();
+      }
+    }
+  });
+
+  test('no engine lists a language twice', () => {
+    for (const [engine, codes] of Object.entries(ENGINE_LANGUAGES)) {
+      expect(new Set(codes).size, `${engine} has duplicate codes`).toBe(codes.length);
+    }
+  });
+
+  test('every engine supports at least English', () => {
+    for (const codes of Object.values(ENGINE_LANGUAGES)) {
+      expect(codes).toContain('en');
+    }
+  });
+
+  test('English-only engines list exactly one language', () => {
+    expect(ENGINE_LANGUAGES.luxtts).toEqual(['en']);
+    expect(ENGINE_LANGUAGES.chatterbox_turbo).toEqual(['en']);
+  });
+
+  test('qwen and qwen_custom_voice support the same languages', () => {
+    expect(ENGINE_LANGUAGES.qwen_custom_voice).toEqual(ENGINE_LANGUAGES.qwen);
+  });
+});
+
+describe('getLanguageOptionsForEngine', () => {
+  test('builds value/label pairs from ALL_LANGUAGES', () => {
+    expect(getLanguageOptionsForEngine('luxtts')).toEqual([{ value: 'en', label: 'English' }]);
+  });
+
+  test('preserves the engine declaration order', () => {
+    const values = getLanguageOptionsForEngine('qwen').map((o) => o.value);
+    expect(values).toEqual([...ENGINE_LANGUAGES.qwen]);
+  });
+
+  test('falls back to qwen languages for unknown engines', () => {
+    expect(getLanguageOptionsForEngine('does-not-exist')).toEqual(
+      getLanguageOptionsForEngine('qwen'),
+    );
+  });
+});
+
+describe('language option exports', () => {
+  test('LANGUAGE_CODES covers every ALL_LANGUAGES key exactly once', () => {
+    const codes: string[] = [...LANGUAGE_CODES].sort();
+    expect(codes).toEqual(Object.keys(ALL_LANGUAGES).sort());
+    expect(new Set(LANGUAGE_CODES).size).toBe(LANGUAGE_CODES.length);
+  });
+
+  test('LANGUAGE_OPTIONS labels match ALL_LANGUAGES', () => {
+    for (const option of LANGUAGE_OPTIONS) {
+      expect(option.label).toBe(ALL_LANGUAGES[option.value]);
+    }
+  });
+});

app/src/lib/hooks/useAudioRecording.ts

@@ -4,12 +4,45 @@ import { convertToWav } from '@/lib/utils/audio';
 
 interface UseAudioRecordingOptions {
   maxDurationSeconds?: number;
-  onRecordingComplete?: (blob: Blob, duration?: number) => void;
+  // ``context`` is whatever was handed to ``startRecording`` for this take,
+  // threaded back untouched so callers can correlate the result with the
+  // recording it came from (the dictate window pairs it with the focus
+  // snapshot captured at chord-start).
+  onRecordingComplete?: (blob: Blob, duration?: number, context?: unknown) => void;
+  /**
+   * Keep the microphone ``MediaStream`` open between recordings instead of
+   * tearing it down on every stop. This is what removes the "first words get
+   * clipped" problem on push-to-talk dictation: ``getUserMedia`` on macOS can
+   * take several hundred ms — up to a second cold — to hand back a stream, and
+   * ``MediaRecorder`` only starts capturing *after* it resolves, so everything
+   * spoken in that window is lost. With a warm stream already open, the next
+   * ``startRecording`` skips ``getUserMedia`` entirely.
+   *
+   * Off by default: the voice-clone sample recorders release the device
+   * immediately, and the dictation session only opts in when the user enables
+   * the "keep microphone ready" setting. While on, the warm stream stays open —
+   * and the OS mic-in-use indicator stays lit — until it's explicitly released
+   * (dictation disabled or the setting turned off), so the trade-off is visible
+   * and user-controlled rather than a background mic that's always warm.
+   */
+  keepWarm?: boolean;
 }
 
+// Audio constraints for capture. Kept identical to the previous inline value so
+// this change is purely about *when* the stream is opened, not *how*.
+const AUDIO_CONSTRAINTS: MediaTrackConstraints = {
+  echoCancellation: true,
+  noiseSuppression: true,
+  autoGainControl: true,
+};
+
+const streamHasLiveAudio = (stream: MediaStream | null): stream is MediaStream =>
+  !!stream && stream.getAudioTracks().some((t) => t.readyState === 'live');
+
 export function useAudioRecording({
   maxDurationSeconds,
   onRecordingComplete,
+  keepWarm = false,
 }: UseAudioRecordingOptions = {}) {
   const platform = usePlatform();
   const [isRecording, setIsRecording] = useState(false);
@@ -17,195 +50,392 @@ export function useAudioRecording({
   const [error, setError] = useState<string | null>(null);
   const mediaRecorderRef = useRef<MediaRecorder | null>(null);
   const chunksRef = useRef<Blob[]>([]);
+  // The stream currently backing the MediaRecorder. When ``keepWarm`` is set
+  // this is the same object as ``warmStreamRef`` and is *not* torn down on
+  // stop; otherwise it's stopped as soon as the recording completes.
   const streamRef = useRef<MediaStream | null>(null);
+  // Persistent pre-opened stream reused across recordings when ``keepWarm``.
+  const warmStreamRef = useRef<MediaStream | null>(null);
   const timerRef = useRef<number | null>(null);
   const startTimeRef = useRef<number | null>(null);
   const cancelledRef = useRef<boolean>(false);
+  // Mirror of ``isRecording`` for reads inside callbacks that would otherwise
+  // close over a stale render.
+  const isRecordingRef = useRef(false);
+  // A ``getUserMedia`` call in flight, shared so concurrent acquirers (prewarm
+  // plus an immediate chord) coalesce onto one stream instead of each opening —
+  // and orphaning — their own.
+  const acquiringRef = useRef<Promise<MediaStream> | null>(null);
+  // True from ``startRecording`` entry until the recorder is actually running
+  // (or has failed), so a stop that arrives mid-acquisition can be deferred.
+  const startingRef = useRef(false);
+  // True from MediaRecorder.stop() until onstop has snapshotted the take's
+  // shared refs. React state and MediaRecorder.state both flip before onstop,
+  // so without this gate a rapid next chord can clear chunks/duration/cancel
+  // state out from under the recorder that is still finalising.
+  const finishingRef = useRef(false);
+  const pendingStopRef = useRef(false);
+  // Bumped per recording so a stale recorder's ``onstop`` can tell it's no
+  // longer the active one before it touches the shared stream refs.
+  const recordingCounterRef = useRef(0);
+  // Bumped whenever the warm stream is released/aborted so a ``getUserMedia``
+  // still in flight can tell its result is stale and stop it instead of
+  // adopting a live mic after disable/unmount.
+  const acquireGenRef = useRef(0);
+  // Set when a release is requested mid-recording; the onstop path performs the
+  // deferred release once capture finishes rather than yanking the device now.
+  const releaseAfterStopRef = useRef(false);
 
-  const startRecording = useCallback(async () => {
-    try {
-      setError(null);
-      chunksRef.current = [];
-      cancelledRef.current = false;
-      setDuration(0);
+  // Keeps the ref in lockstep with the state so the synchronous stop path reads
+  // a fresh value without waiting for a rerender.
+  const setRecording = useCallback((next: boolean) => {
+    isRecordingRef.current = next;
+    setIsRecording(next);
+  }, []);
 
-      // Check if getUserMedia is available
-      // In Tauri, navigator.mediaDevices might not be available immediately
-      if (typeof navigator === 'undefined') {
-        const errorMsg =
-          'Navigator API is not available. This might be a Tauri configuration issue.';
-        setError(errorMsg);
-        throw new Error(errorMsg);
-      }
+  const releaseWarmStream = useCallback(() => {
+    // Invalidate any getUserMedia still in flight so its stream is stopped on
+    // resolve rather than adopted as the warm stream.
+    acquireGenRef.current += 1;
+    // Don't tear the device out from under an active/starting recording — the
+    // warm stream is the one backing it; defer to the onstop path instead.
+    if (isRecordingRef.current || startingRef.current) {
+      releaseAfterStopRef.current = true;
+      return;
+    }
+    warmStreamRef.current?.getTracks().forEach((track) => {
+      track.stop();
+    });
+    warmStreamRef.current = null;
+  }, []);
 
+  // Assert that getUserMedia is reachable, mirroring the previous inline guard
+  // (Tauri webviews occasionally expose ``navigator.mediaDevices`` a beat late).
+  const assertMediaDevices = useCallback(async () => {
+    if (typeof navigator === 'undefined') {
+      throw new Error('Navigator API is not available. This might be a Tauri configuration issue.');
+    }
+    if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
       if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
-        // Try waiting a bit for Tauri webview to initialize
-        await new Promise((resolve) => setTimeout(resolve, 100));
-
-        if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
-          console.error('MediaDevices check:', {
-            hasNavigator: typeof navigator !== 'undefined',
-            hasMediaDevices: !!navigator?.mediaDevices,
-            hasGetUserMedia: !!navigator?.mediaDevices?.getUserMedia,
-            isTauri: platform.metadata.isTauri,
-          });
-
-          const errorMsg = platform.metadata.isTauri
+        throw new Error(
+          platform.metadata.isTauri
             ? 'Microphone access is not available. Please ensure:\n1. The app has microphone permissions in System Settings (macOS: System Settings > Privacy & Security > Microphone)\n2. You restart the app after granting permissions\n3. You are using Tauri v2 with a webview that supports getUserMedia'
-            : 'Microphone access is not available. Please ensure you are using a secure context (HTTPS or localhost) and that your browser has microphone permissions enabled.';
-          setError(errorMsg);
-          throw new Error(errorMsg);
-        }
+            : 'Microphone access is not available. Please ensure you are using a secure context (HTTPS or localhost) and that your browser has microphone permissions enabled.',
+        );
       }
+    }
+  }, [platform.metadata.isTauri]);
 
-      // Request microphone access
-      const stream = await navigator.mediaDevices.getUserMedia({
-        audio: {
-          echoCancellation: true,
-          noiseSuppression: true,
-          autoGainControl: true,
-        },
+  // Return a live capture stream, reusing the warm one when available so the
+  // hot path (chord-down → record) never waits on getUserMedia.
+  const acquireStream = useCallback(async (): Promise<MediaStream> => {
+    // Captured separately so it stays typed as the full stream after the live
+    // check narrows ``warmStreamRef.current`` itself.
+    const existing = warmStreamRef.current;
+    if (streamHasLiveAudio(warmStreamRef.current)) {
+      return warmStreamRef.current;
+    }
+    // Coalesce concurrent acquirers onto one getUserMedia call so prewarm and
+    // an immediate chord can't open two streams.
+    if (acquiringRef.current) return acquiringRef.current;
+    // A dead warm stream (device unplugged / tracks ended) — drop it and reopen.
+    if (existing) {
+      existing.getTracks().forEach((track) => {
+        track.stop();
       });
-
-      streamRef.current = stream;
-
-      // Create MediaRecorder with preferred MIME type
-      const options: MediaRecorderOptions = {
-        mimeType: 'audio/webm;codecs=opus',
-      };
-
-      // Fallback to default if webm not supported
-      if (!MediaRecorder.isTypeSupported(options.mimeType!)) {
-        delete options.mimeType;
-      }
-
-      const mediaRecorder = new MediaRecorder(stream, options);
-      mediaRecorderRef.current = mediaRecorder;
-
-      mediaRecorder.ondataavailable = (event) => {
-        if (event.data.size > 0) {
-          chunksRef.current.push(event.data);
-        }
-      };
-
-      mediaRecorder.onstop = async () => {
-        // Snapshot the cancellation flag and recorded duration immediately —
-        // cancelRecording() clears chunks and sets cancelledRef synchronously
-        // before this async handler runs, so we must check it first.
-        const wasCancelled = cancelledRef.current;
-        const recordedDuration = startTimeRef.current
-          ? (Date.now() - startTimeRef.current) / 1000
-          : undefined;
-
-        const webmBlob = new Blob(chunksRef.current, { type: 'audio/webm' });
-
-        // Stop all tracks now that we have the data
-        streamRef.current?.getTracks().forEach((track) => {
+      warmStreamRef.current = null;
+    }
+    const gen = acquireGenRef.current;
+    const acquisition = (async () => {
+      await assertMediaDevices();
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: AUDIO_CONSTRAINTS,
+      });
+      // Released / disabled / unmounted while acquiring — this stream is stale,
+      // so stop it instead of leaving a live mic open, and abort the caller.
+      if (gen !== acquireGenRef.current) {
+        stream.getTracks().forEach((track) => {
           track.stop();
         });
-        streamRef.current = null;
+        throw new Error('microphone acquisition aborted');
+      }
+      if (keepWarm) warmStreamRef.current = stream;
+      return stream;
+    })();
+    acquiringRef.current = acquisition;
+    try {
+      return await acquisition;
+    } finally {
+      if (acquiringRef.current === acquisition) acquiringRef.current = null;
+    }
+  }, [assertMediaDevices, keepWarm]);
 
-        // Don't fire completion callback if the recording was cancelled
-        if (wasCancelled) return;
+  /**
+   * Open the microphone ahead of the first recording so the initial dictation
+   * doesn't clip. No-op unless ``keepWarm`` is set. Safe to call repeatedly and
+   * safe to fail (e.g. permission not yet granted) — ``startRecording`` still
+   * surfaces a real error if capture is genuinely unavailable.
+   */
+  const prewarm = useCallback(async () => {
+    if (!keepWarm) return;
+    try {
+      await acquireStream();
+    } catch {
+      // Permission missing / device busy / aborted — recording will report a
+      // real error if capture is genuinely unavailable.
+    }
+  }, [keepWarm, acquireStream]);
 
-        // Convert to WAV format to avoid needing ffmpeg on backend
-        try {
-          const wavBlob = await convertToWav(webmBlob);
-          onRecordingComplete?.(wavBlob, recordedDuration);
-        } catch (err) {
-          console.error('Error converting audio to WAV:', err);
-          // Fallback to original blob if conversion fails
-          onRecordingComplete?.(webmBlob, recordedDuration);
+  const startRecording = useCallback(
+    async (context?: unknown) => {
+      // A second chord can arrive while the first one is still waiting on
+      // getUserMedia. Never create overlapping MediaRecorders on the same
+      // coalesced stream; the original take will honor any deferred stop.
+      if (
+        startingRef.current ||
+        finishingRef.current ||
+        mediaRecorderRef.current?.state === 'recording'
+      )
+        return;
+      startingRef.current = true;
+      pendingStopRef.current = false;
+      // A new recording supersedes any release deferred from a prior take.
+      releaseAfterStopRef.current = false;
+      const recordingId = ++recordingCounterRef.current;
+      try {
+        setError(null);
+        chunksRef.current = [];
+        cancelledRef.current = false;
+        setDuration(0);
+
+        // Reuse the warm stream when present (instant); otherwise open one now.
+        const stream = await acquireStream();
+        streamRef.current = stream;
+
+        // Create MediaRecorder with preferred MIME type
+        const options: MediaRecorderOptions = {
+          mimeType: 'audio/webm;codecs=opus',
+        };
+
+        // Fallback to default if webm not supported
+        if (!MediaRecorder.isTypeSupported(options.mimeType!)) {
+          delete options.mimeType;
         }
-      };
 
-      mediaRecorder.onerror = (event) => {
-        setError('Recording error occurred');
-        console.error('MediaRecorder error:', event);
-      };
+        const mediaRecorder = new MediaRecorder(stream, options);
+        mediaRecorderRef.current = mediaRecorder;
 
-      // WebKit's MediaRecorder drops the WebM EBML header from chunks when
-      // started with a timeslice, so concatenated blobs fail to parse in
-      // both AudioContext and ffmpeg. Starting with no timeslice produces
-      // exactly one dataavailable on stop() with a valid container.
-      mediaRecorder.start();
-      setIsRecording(true);
-      startTimeRef.current = Date.now();
+        mediaRecorder.ondataavailable = (event) => {
+          if (event.data.size > 0) {
+            chunksRef.current.push(event.data);
+          }
+        };
 
-      // Start timer
-      timerRef.current = window.setInterval(() => {
-        if (startTimeRef.current) {
-          const elapsed = (Date.now() - startTimeRef.current) / 1000;
-          setDuration(elapsed);
+        mediaRecorder.onstop = async () => {
+          // Whether this recorder is still the active one. A stale onstop (an
+          // older recorder stopping after a newer startRecording) must not touch
+          // the shared stream refs.
+          const isCurrent = recordingCounterRef.current === recordingId;
+          // Snapshot the cancellation flag and recorded duration immediately —
+          // cancelRecording() clears chunks and sets cancelledRef synchronously
+          // before this async handler runs, so we must check it first.
+          const wasCancelled = cancelledRef.current;
+          const recordedDuration = startTimeRef.current
+            ? (Date.now() - startTimeRef.current) / 1000
+            : undefined;
 
-          // Auto-stop at max duration when the caller opts in — dictation
-          // sessions pass undefined and run until the user releases the
-          // chord or hits stop; voice-clone sample recorders pass 29s to
-          // keep reference clips short.
-          if (maxDurationSeconds !== undefined && elapsed >= maxDurationSeconds) {
-            if (mediaRecorderRef.current && mediaRecorderRef.current.state !== 'inactive') {
-              mediaRecorderRef.current.stop();
-              setIsRecording(false);
-              if (timerRef.current !== null) {
-                clearInterval(timerRef.current);
-                timerRef.current = null;
+          const webmBlob = new Blob(chunksRef.current, { type: 'audio/webm' });
+
+          // Release the device unless we're keeping it warm for the next capture.
+          // Act on this recorder's own stream; only touch the shared refs when
+          // this is still the current recording.
+          if (keepWarm) {
+            if (isCurrent) {
+              streamRef.current = null;
+              // A release requested mid-recording (dictation disabled) is
+              // honored now that capture has finished; otherwise the warm
+              // stream stays open for the next take.
+              if (releaseAfterStopRef.current) {
+                releaseAfterStopRef.current = false;
+                releaseWarmStream();
+              }
+            }
+          } else {
+            stream.getTracks().forEach((track) => {
+              track.stop();
+            });
+            if (isCurrent) streamRef.current = null;
+          }
+
+          // All shared per-take refs have now been snapshotted and stream
+          // cleanup is complete. A new take may begin while WAV conversion and
+          // upload continue using the local values above.
+          finishingRef.current = false;
+
+          // Don't fire completion callback if the recording was cancelled
+          if (wasCancelled) return;
+
+          // Convert to WAV format to avoid needing ffmpeg on backend
+          try {
+            const wavBlob = await convertToWav(webmBlob);
+            onRecordingComplete?.(wavBlob, recordedDuration, context);
+          } catch (err) {
+            console.error('Error converting audio to WAV:', err);
+            // Fallback to original blob if conversion fails
+            onRecordingComplete?.(webmBlob, recordedDuration, context);
+          }
+        };
+
+        mediaRecorder.onerror = (event) => {
+          setError('Recording error occurred');
+          console.error('MediaRecorder error:', event);
+        };
+
+        // WebKit's MediaRecorder drops the WebM EBML header from chunks when
+        // started with a timeslice, so concatenated blobs fail to parse in
+        // both AudioContext and ffmpeg. Starting with no timeslice produces
+        // exactly one dataavailable on stop() with a valid container.
+        mediaRecorder.start();
+        setRecording(true);
+        startTimeRef.current = Date.now();
+        startingRef.current = false;
+
+        // A stop (chord release) that landed while the mic was still opening —
+        // honor it now that capture has actually begun.
+        if (pendingStopRef.current) {
+          pendingStopRef.current = false;
+          finishingRef.current = true;
+          mediaRecorder.stop();
+          setRecording(false);
+          return;
+        }
+
+        // Start timer
+        timerRef.current = window.setInterval(() => {
+          if (startTimeRef.current) {
+            const elapsed = (Date.now() - startTimeRef.current) / 1000;
+            setDuration(elapsed);
+
+            // Auto-stop at max duration when the caller opts in — dictation
+            // sessions pass undefined and run until the user releases the
+            // chord or hits stop; voice-clone sample recorders pass 29s to
+            // keep reference clips short.
+            if (maxDurationSeconds !== undefined && elapsed >= maxDurationSeconds) {
+              if (mediaRecorderRef.current && mediaRecorderRef.current.state !== 'inactive') {
+                finishingRef.current = true;
+                mediaRecorderRef.current.stop();
+                setRecording(false);
+                if (timerRef.current !== null) {
+                  clearInterval(timerRef.current);
+                  timerRef.current = null;
+                }
               }
             }
           }
+        }, 100);
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error
+            ? err.message
+            : 'Failed to access microphone. Please check permissions.';
+        // A fresh (non-warm) stream opened before the failure must be released
+        // so the mic doesn't stay lit; a warm stream is reusable, so it's kept.
+        if (!keepWarm) {
+          streamRef.current?.getTracks().forEach((track) => {
+            track.stop();
+          });
+          streamRef.current = null;
         }
-      }, 100);
-    } catch (err) {
-      const errorMessage =
-        err instanceof Error
-          ? err.message
-          : 'Failed to access microphone. Please check permissions.';
-      setError(errorMessage);
-      setIsRecording(false);
-    }
-  }, [maxDurationSeconds, onRecordingComplete]);
+        startingRef.current = false;
+        finishingRef.current = false;
+        pendingStopRef.current = false;
+        setError(errorMessage);
+        setRecording(false);
+      }
+    },
+    [
+      maxDurationSeconds,
+      onRecordingComplete,
+      acquireStream,
+      keepWarm,
+      releaseWarmStream,
+      setRecording,
+    ],
+  );
 
   const stopRecording = useCallback(() => {
-    if (mediaRecorderRef.current && isRecording) {
-      mediaRecorderRef.current.stop();
-      setIsRecording(false);
+    // The recorder's own state is the lifecycle authority — React ``isRecording``
+    // lags a render behind ``mediaRecorder.start()``, so a chord release in that
+    // window would otherwise be dropped.
+    const recorder = mediaRecorderRef.current;
+    if (recorder && recorder.state === 'recording') {
+      finishingRef.current = true;
+      recorder.stop();
+      setRecording(false);
 
       if (timerRef.current !== null) {
         clearInterval(timerRef.current);
         timerRef.current = null;
       }
+    } else if (startingRef.current) {
+      // Stop arrived before capture began (mic still opening) — defer it so
+      // startRecording stops as soon as the recorder goes live.
+      pendingStopRef.current = true;
     }
-  }, [isRecording]);
+  }, [setRecording]);
 
   const cancelRecording = useCallback(() => {
-    if (mediaRecorderRef.current) {
-      cancelledRef.current = true; // Must be set before stop() triggers onstop
+    cancelledRef.current = true; // Must be set before stop() triggers onstop
+    const recorder = mediaRecorderRef.current;
+    if (recorder && recorder.state !== 'inactive') {
       chunksRef.current = [];
-      mediaRecorderRef.current.stop();
-      setIsRecording(false);
+      finishingRef.current = true;
+      recorder.stop();
+      setRecording(false);
       setDuration(0);
+    } else if (startingRef.current) {
+      // Cancel during mic acquisition — stop as soon as capture begins; the
+      // cancelled flag suppresses the completion callback.
+      pendingStopRef.current = true;
     }
 
-    // Stop all tracks
-    streamRef.current?.getTracks().forEach((track) => {
-      track.stop();
-    });
-    streamRef.current = null;
+    // Keep the device warm for the next capture when opted in; otherwise stop
+    // the tracks so the mic is released immediately.
+    if (keepWarm) {
+      streamRef.current = null;
+      if (releaseAfterStopRef.current) {
+        releaseAfterStopRef.current = false;
+        releaseWarmStream();
+      }
+    } else {
+      streamRef.current?.getTracks().forEach((track) => {
+        track.stop();
+      });
+      streamRef.current = null;
+    }
 
     if (timerRef.current !== null) {
       clearInterval(timerRef.current);
       timerRef.current = null;
     }
-  }, []);
+  }, [keepWarm, releaseWarmStream, setRecording]);
 
-  // Cleanup on unmount
+  // Cleanup on unmount — always fully release the device, warm or not.
   useEffect(() => {
     return () => {
+      // Invalidate any in-flight acquisition so a stream resolving after unmount
+      // stops itself instead of leaking a live mic.
+      acquireGenRef.current += 1;
       if (timerRef.current !== null) {
         clearInterval(timerRef.current);
       }
       streamRef.current?.getTracks().forEach((track) => {
         track.stop();
       });
+      warmStreamRef.current?.getTracks().forEach((track) => {
+        track.stop();
+      });
     };
   }, []);
 
@@ -216,5 +446,7 @@ export function useAudioRecording({
     startRecording,
     stopRecording,
     cancelRecording,
+    prewarm,
+    releaseWarm: releaseWarmStream,
   };
 }

app/src/lib/hooks/useCaptureRecordingSession.ts

@@ -54,11 +54,15 @@ const SHORT_RECORDING_MESSAGE = 'Recording too short, canceled';
 export type CapturePillState = PillState | 'hidden';
 
 export interface UseCaptureRecordingSessionOptions {
+  /** Keep the microphone stream open between dictations when explicitly
+   * enabled. Off by default so normal recorders release the device. */
+  keepMicWarm?: boolean;
   /**
    * Fired after a capture row is created on the server. Callers can use this
    * to select the new capture or emit a Tauri event to a sibling window.
+   * ``context`` is whatever was passed to ``startRecording`` for this take.
    */
-  onCaptureCreated?: (capture: CaptureResponse) => void;
+  onCaptureCreated?: (capture: CaptureResponse, context?: unknown) => void;
   /**
    * Fired with the final delivered text — refined if ``auto_refine`` was on
    * for this capture, raw transcript otherwise. Used by the floating
@@ -66,12 +70,14 @@ export interface UseCaptureRecordingSessionOptions {
    *
    * ``allowAutoPaste`` snapshots the setting at chord-start so a refine that
    * lands after the user flips the toggle still uses the value the capture
-   * was created under.
+   * was created under. ``context`` is the value passed to ``startRecording``
+   * for this take, so overlapping dictations can't cross their targets.
    */
   onFinalText?: (
     text: string,
     capture: CaptureResponse,
     allowAutoPaste: boolean,
+    context?: unknown,
   ) => void;
 }
 
@@ -82,12 +88,14 @@ export interface UseCaptureRecordingSessionResult {
   isRecording: boolean;
   isUploading: boolean;
   isRefining: boolean;
-  startRecording: () => void;
+  startRecording: (context?: unknown) => void;
   stopRecording: () => void;
   toggleRecording: () => void;
   dismissError: () => void;
   uploadFile: (file: File, source: CaptureSource) => void;
   refine: (captureId: string) => void;
+  prewarm: () => Promise<void>;
+  releaseWarm: () => void;
 }
 
 /**
@@ -123,10 +131,13 @@ export function useCaptureRecordingSession(
   const onFinalTextRef = useRef(options.onFinalText);
   onFinalTextRef.current = options.onFinalText;
 
-  // Snapshot of ``allow_auto_paste`` from the capture-create response —
-  // held so the refine onSuccess (which only sees the plain CaptureResponse)
-  // can still pass the original setting through to onFinalText.
-  const allowAutoPasteRef = useRef<boolean>(true);
+  // Per-capture recording context and its ``allow_auto_paste`` snapshot, keyed
+  // by capture id so a refine that resolves after another dictation started
+  // still delivers to the right target with the setting the capture was created
+  // under. Populated on capture-create and consumed once the final text lands.
+  const captureDeliveryRef = useRef<Map<string, { context: unknown; allowAutoPaste: boolean }>>(
+    new Map(),
+  );
 
   const clearRestTimer = useCallback(() => {
     if (restTimerRef.current !== null) {
@@ -192,20 +203,34 @@ export function useCaptureRecordingSession(
       queryClient.invalidateQueries({ queryKey: ['captures'] });
       broadcastUpdated(captureId);
       if (pillStateRef.current === 'refining') scheduleHidePill();
+      const delivery = captureDeliveryRef.current.get(captureId);
+      captureDeliveryRef.current.delete(captureId);
       const finalText = data.transcript_refined ?? data.transcript_raw;
       if (finalText) {
-        onFinalTextRef.current?.(finalText, data, allowAutoPasteRef.current);
+        onFinalTextRef.current?.(
+          finalText,
+          data,
+          delivery?.allowAutoPaste ?? true,
+          delivery?.context,
+        );
       }
     },
-    onError: (err: Error) => {
+    onError: (err: Error, captureId) => {
+      captureDeliveryRef.current.delete(captureId);
       showError(err.message || 'Refinement failed');
     },
   });
 
   const uploadMutation = useMutation({
-    mutationFn: async ({ file, source }: { file: File; source: CaptureSource }) =>
-      apiClient.createCapture(file, { source }),
-    onSuccess: (capture) => {
+    mutationFn: async ({
+      file,
+      source,
+    }: {
+      file: File;
+      source: CaptureSource;
+      context?: unknown;
+    }) => apiClient.createCapture(file, { source }),
+    onSuccess: (capture, { context }) => {
       queryClient.setQueryData<CaptureListResponse>(['captures'], (prev) => {
         if (!prev) return prev;
         if (prev.items.some((c) => c.id === capture.id)) return prev;
@@ -213,9 +238,12 @@ export function useCaptureRecordingSession(
       });
       queryClient.invalidateQueries({ queryKey: ['captures'] });
       broadcastCreated(capture);
-      onCaptureCreatedRef.current?.(capture);
-      allowAutoPasteRef.current = capture.allow_auto_paste;
+      onCaptureCreatedRef.current?.(capture, context);
       if (capture.auto_refine) {
+        captureDeliveryRef.current.set(capture.id, {
+          context,
+          allowAutoPaste: capture.allow_auto_paste,
+        });
         setPillState('refining');
         refineMutation.mutate(capture.id);
       } else {
@@ -225,6 +253,7 @@ export function useCaptureRecordingSession(
             capture.transcript_raw,
             capture,
             capture.allow_auto_paste,
+            context,
           );
         }
       }
@@ -249,8 +278,11 @@ export function useCaptureRecordingSession(
     startRecording: beginAudioRecording,
     stopRecording,
     error: recordError,
+    prewarm,
+    releaseWarm,
   } = useAudioRecording({
-    onRecordingComplete: (blob, recordedDuration) => {
+    keepWarm: options.keepMicWarm ?? false,
+    onRecordingComplete: (blob, recordedDuration, context) => {
       // Trigger-happy tap — MediaRecorder hasn't emitted a usable chunk yet
       // so the blob is empty or unparseable. Surface it as a transient pill
       // so the user sees their recording was recognised and canceled.
@@ -268,7 +300,7 @@ export function useCaptureRecordingSession(
       const file = new File([blob], `dictation-${Date.now()}.${extension}`, {
         type: blob.type,
       });
-      uploadMutation.mutate({ file, source: 'dictation' });
+      uploadMutation.mutate({ file, source: 'dictation', context });
     },
   });
 
@@ -278,13 +310,16 @@ export function useCaptureRecordingSession(
     }
   }, [recordError, showError]);
 
-  const startRecording = useCallback(() => {
-    if (isRecording) return;
-    clearRestTimer();
-    setFrozenElapsedMs(0);
-    setPillState('recording');
-    beginAudioRecording();
-  }, [isRecording, beginAudioRecording, clearRestTimer]);
+  const startRecording = useCallback(
+    (context?: unknown) => {
+      if (isRecording) return;
+      clearRestTimer();
+      setFrozenElapsedMs(0);
+      setPillState('recording');
+      beginAudioRecording(context);
+    },
+    [isRecording, beginAudioRecording, clearRestTimer],
+  );
 
   const toggleRecording = useCallback(() => {
     if (isRecording) {
@@ -324,5 +359,7 @@ export function useCaptureRecordingSession(
     dismissError,
     uploadFile,
     refine,
+    prewarm,
+    releaseWarm,
   };
 }

app/src/lib/hooks/useChordSync.ts

@@ -1,5 +1,6 @@
 import { invoke } from '@tauri-apps/api/core';
-import { useEffect } from 'react';
+import { emit, listen } from '@tauri-apps/api/event';
+import { useEffect, useRef } from 'react';
 import { useDictationReadiness } from '@/lib/hooks/useDictationReadiness';
 import { useCaptureSettings } from '@/lib/hooks/useSettings';
 import { usePlatform } from '@/platform/PlatformContext';
@@ -30,21 +31,45 @@ export function useChordSync() {
   const { settings } = useCaptureSettings();
   const { canRecord } = useDictationReadiness();
   const enabled = settings?.hotkey_enabled;
+  const keepMicWarm = settings?.keep_mic_warm;
   const pushKeys = settings?.chord_push_to_talk_keys;
   const toggleKeys = settings?.chord_toggle_to_talk_keys;
 
+  // Latest warm state, so the dictate window's mount-time request can be
+  // answered even between the dep-driven emits below.
+  const shouldWarmRef = useRef(false);
+
+  // The floating dictate window holds the mic warm ahead of the first chord to
+  // avoid clipping, but it's a separate webview with no view of settings. Mirror
+  // the decision to it: warm only when dictation is armed AND the user enabled
+  // "keep microphone ready". Gating here is what stops the always-mounted pill
+  // from opening the mic — or prompting for access — when the user hasn't asked.
+  useEffect(() => {
+    if (!platform.metadata.isTauri) return;
+    const unlisten = listen('dictate:warm-request', () => {
+      emit('dictate:warm', shouldWarmRef.current).catch(() => {});
+    });
+    return () => {
+      unlisten.then((fn) => fn()).catch(() => {});
+    };
+  }, [platform.metadata.isTauri]);
+
   useEffect(() => {
     if (!platform.metadata.isTauri) return;
     if (enabled === undefined || !pushKeys || !toggleKeys) return;
     const shouldArm = enabled && canRecord;
+    const shouldWarm = shouldArm && (keepMicWarm ?? false);
+    shouldWarmRef.current = shouldWarm;
     const command = shouldArm ? 'enable_hotkey' : 'disable_hotkey';
     const args = shouldArm ? { pushToTalk: pushKeys, toggleToTalk: toggleKeys } : {};
     invoke(command, args).catch((err) => {
       console.warn(`[chord-sync] ${command} failed:`, err);
     });
+    emit('dictate:warm', shouldWarm).catch(() => {});
   }, [
     platform.metadata.isTauri,
     enabled,
+    keepMicWarm,
     canRecord,
     // Stringify so a referentially-new array with the same content
     // doesn't fire a redundant invoke on every settings refetch.

app/src/lib/hooks/useHistory.ts

@@ -47,12 +47,14 @@ export function useExportGeneration() {
     mutationFn: async ({ generationId, text }: { generationId: string; text: string }) => {
       const blob = await apiClient.exportGeneration(generationId);
 
-      // Create safe filename from text
+      // Create safe filename from text. Append a short id so exports of
+      // similarly-worded generations don't collide on the same filename
+      // (the first 30 chars are frequently identical).
       const safeText = text
         .substring(0, 30)
         .replace(/[^a-z0-9]/gi, '-')
         .toLowerCase();
-      const filename = `generation-${safeText}.voicebox.zip`;
+      const filename = `generation-${safeText}-${generationId.substring(0, 8)}.voicebox.zip`;
 
       await platform.filesystem.saveFile(filename, blob, [
         {
@@ -73,12 +75,14 @@ export function useExportGenerationAudio() {
     mutationFn: async ({ generationId, text }: { generationId: string; text: string }) => {
       const blob = await apiClient.exportGenerationAudio(generationId);
 
-      // Create safe filename from text
+      // Create safe filename from text. Append a short id so exports of
+      // similarly-worded generations don't collide on the same filename
+      // (the first 30 chars are frequently identical).
       const safeText = text
         .substring(0, 30)
         .replace(/[^a-z0-9]/gi, '-')
         .toLowerCase();
-      const filename = `${safeText}.wav`;
+      const filename = `${safeText}-${generationId.substring(0, 8)}.wav`;
 
       await platform.filesystem.saveFile(filename, blob, [
         {

app/src/lib/utils/format.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from 'bun:test';
+import { formatDuration, formatEngineName, formatFileSize } from './format';
+
+describe('formatDuration', () => {
+  test('formats zero', () => {
+    expect(formatDuration(0)).toBe('0:00');
+  });
+
+  test('pads single-digit seconds', () => {
+    expect(formatDuration(65)).toBe('1:05');
+  });
+
+  test('handles the minute boundary', () => {
+    expect(formatDuration(59)).toBe('0:59');
+    expect(formatDuration(60)).toBe('1:00');
+  });
+
+  test('floors fractional seconds', () => {
+    expect(formatDuration(89.9)).toBe('1:29');
+  });
+
+  test('does not roll minutes into hours', () => {
+    expect(formatDuration(3661)).toBe('61:01');
+  });
+});
+
+describe('formatFileSize', () => {
+  test('special-cases zero', () => {
+    expect(formatFileSize(0)).toBe('0 Bytes');
+  });
+
+  test('formats bytes below 1 KB', () => {
+    expect(formatFileSize(512)).toBe('512 Bytes');
+    expect(formatFileSize(1023)).toBe('1023 Bytes');
+  });
+
+  test('formats KB, MB, and GB boundaries', () => {
+    expect(formatFileSize(1024)).toBe('1 KB');
+    expect(formatFileSize(1024 ** 2)).toBe('1 MB');
+    expect(formatFileSize(1024 ** 3)).toBe('1 GB');
+  });
+
+  test('rounds to two decimal places', () => {
+    expect(formatFileSize(1536)).toBe('1.5 KB');
+    expect(formatFileSize(2_684_354_560)).toBe('2.5 GB');
+    expect(formatFileSize(1_234_567)).toBe('1.18 MB');
+  });
+});
+
+describe('formatEngineName', () => {
+  test('maps known engines to display names', () => {
+    expect(formatEngineName('luxtts')).toBe('LuxTTS');
+    expect(formatEngineName('chatterbox')).toBe('Chatterbox');
+    expect(formatEngineName('chatterbox_turbo')).toBe('Chatterbox Turbo');
+  });
+
+  test('defaults to Qwen when engine is undefined', () => {
+    expect(formatEngineName()).toBe('Qwen');
+    expect(formatEngineName(undefined, '1.7B')).toBe('Qwen');
+  });
+
+  test('appends the model size for qwen only', () => {
+    expect(formatEngineName('qwen', '1.7B')).toBe('Qwen 1.7B');
+    expect(formatEngineName('qwen')).toBe('Qwen');
+    expect(formatEngineName('luxtts', '1.7B')).toBe('LuxTTS');
+  });
+
+  test('passes unknown engines through verbatim', () => {
+    expect(formatEngineName('kokoro')).toBe('kokoro');
+  });
+});

app/src/lib/utils/format.ts

@@ -23,27 +23,28 @@ function getDateLocale() {
   }
 }
 
-export function formatDate(date: string | Date): string {
-  let dateObj: Date;
-  if (typeof date === 'string') {
-    const dateStr = date.trim();
-    if (!dateStr.includes('Z') && !dateStr.match(/[+-]\d{2}:\d{2}$/)) {
-      dateObj = new Date(`${dateStr}Z`);
-    } else {
-      dateObj = new Date(dateStr);
-    }
-  } else {
-    dateObj = date;
+// Backend timestamps are naive UTC — append `Z` so JS doesn't parse a
+// timezone-less date-time string as local time.
+function parseServerDate(date: string | Date): Date {
+  if (typeof date !== 'string') {
+    return date;
   }
+  const dateStr = date.trim();
+  if (!dateStr.includes('Z') && !dateStr.match(/[+-]\d{2}:\d{2}$/)) {
+    return new Date(`${dateStr}Z`);
+  }
+  return new Date(dateStr);
+}
 
-  return formatDistance(dateObj, new Date(), {
+export function formatDate(date: string | Date): string {
+  return formatDistance(parseServerDate(date), new Date(), {
     addSuffix: true,
     locale: getDateLocale(),
   }).replace(/^about /i, '');
 }
 
 export function formatAbsoluteDate(date: string | Date): string {
-  const dateObj = typeof date === 'string' ? new Date(date) : date;
+  const dateObj = parseServerDate(date);
   return dateObj.toLocaleString(i18n.language, {
     month: 'short',
     day: 'numeric',

app/src/lib/utils/parseChangelog.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from 'bun:test';
+import { parseChangelog } from './parseChangelog';
+
+const SAMPLE = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.5.0] - 2026-06-01
+
+### Added
+
+- Story track editor
+- Cloud login
+
+## [0.4.1]
+
+### Fixed
+
+- Trim clamping
+
+## [0.4.0] - 2026-04-15
+
+Initial public release.
+
+[0.5.0]: https://example.com/compare/v0.4.1...v0.5.0
+[0.4.1]: https://example.com/compare/v0.4.0...v0.4.1
+`;
+
+describe('parseChangelog', () => {
+  test('splits entries on version headings', () => {
+    const entries = parseChangelog(SAMPLE);
+    expect(entries.map((e) => e.version)).toEqual(['0.5.0', '0.4.1', '0.4.0']);
+  });
+
+  test('extracts the date when present and null otherwise', () => {
+    const entries = parseChangelog(SAMPLE);
+    expect(entries[0].date).toBe('2026-06-01');
+    expect(entries[1].date).toBeNull();
+  });
+
+  test('keeps the markdown body between headings', () => {
+    const entries = parseChangelog(SAMPLE);
+    expect(entries[0].body).toBe('### Added\n\n- Story track editor\n- Cloud login');
+    expect(entries[2].body).toBe('Initial public release.');
+  });
+
+  test('strips trailing link reference definitions from the last body', () => {
+    const entries = parseChangelog(SAMPLE);
+    expect(entries[2].body).toBe('Initial public release.');
+    expect(entries[2].body).not.toContain('example.com');
+  });
+
+  test('returns an empty array when no headings match', () => {
+    expect(parseChangelog('')).toEqual([]);
+    expect(parseChangelog('# Changelog\n\nNothing yet.')).toEqual([]);
+  });
+
+  test('handles a heading with an empty body', () => {
+    const entries = parseChangelog('## [1.0.0] - 2026-01-01\n');
+    expect(entries).toEqual([{ version: '1.0.0', date: '2026-01-01', body: '' }]);
+  });
+
+  test('accepts non-semver headings like Unreleased', () => {
+    const entries = parseChangelog('## [Unreleased]\n\n### Added\n\n- WIP\n');
+    expect(entries[0].version).toBe('Unreleased');
+    expect(entries[0].date).toBeNull();
+    expect(entries[0].body).toBe('### Added\n\n- WIP');
+  });
+});

app/src/lib/utils/trim.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'bun:test';
+import { MIN_CLIP_DURATION_MS, computeTrimValues } from './trim';
+
+// A 10-second clip with no existing trims unless stated otherwise.
+const DURATION = 10_000;
+
+describe('computeTrimValues', () => {
+  describe('start handle', () => {
+    test('dragging right trims from the start', () => {
+      expect(computeTrimValues('start', 500, 0, 0, DURATION)).toEqual({
+        trim_start_ms: 500,
+        trim_end_ms: 0,
+      });
+    });
+
+    test('dragging left restores previously trimmed audio', () => {
+      expect(computeTrimValues('start', -300, 1000, 0, DURATION)).toEqual({
+        trim_start_ms: 700,
+        trim_end_ms: 0,
+      });
+    });
+
+    test('clamps at zero when restoring past the clip start', () => {
+      expect(computeTrimValues('start', -5000, 1000, 0, DURATION)).toEqual({
+        trim_start_ms: 0,
+        trim_end_ms: 0,
+      });
+    });
+
+    test('never trims below the minimum clip duration', () => {
+      const result = computeTrimValues('start', 99_999, 0, 2000, DURATION);
+      // Clamp lands exactly on the minimum, which the guard rejects.
+      expect(result).toBeNull();
+    });
+
+    test('rounds fractional millisecond deltas', () => {
+      expect(computeTrimValues('start', 100.6, 0, 0, DURATION)).toEqual({
+        trim_start_ms: 101,
+        trim_end_ms: 0,
+      });
+    });
+
+    test('preserves the untouched end trim', () => {
+      expect(computeTrimValues('start', 250, 0, 400, DURATION)).toEqual({
+        trim_start_ms: 250,
+        trim_end_ms: 400,
+      });
+    });
+  });
+
+  describe('end handle', () => {
+    test('dragging left trims from the end', () => {
+      expect(computeTrimValues('end', -500, 0, 0, DURATION)).toEqual({
+        trim_start_ms: 0,
+        trim_end_ms: 500,
+      });
+    });
+
+    test('dragging right restores previously trimmed audio', () => {
+      expect(computeTrimValues('end', 300, 0, 1000, DURATION)).toEqual({
+        trim_start_ms: 0,
+        trim_end_ms: 700,
+      });
+    });
+
+    test('clamps at zero when restoring past the clip end', () => {
+      expect(computeTrimValues('end', 5000, 0, 1000, DURATION)).toEqual({
+        trim_start_ms: 0,
+        trim_end_ms: 0,
+      });
+    });
+
+    test('never trims below the minimum clip duration', () => {
+      expect(computeTrimValues('end', -99_999, 3000, 0, DURATION)).toBeNull();
+    });
+  });
+
+  describe('minimum duration guard', () => {
+    test('rejects drags that leave less than the minimum audible clip', () => {
+      // 9.5s already trimmed; taking 450ms more leaves only 50ms.
+      expect(computeTrimValues('start', 450, 5000, 4500, DURATION)).toBeNull();
+    });
+
+    test('allows a drag that leaves just over the minimum', () => {
+      expect(computeTrimValues('start', 399, 5000, 4500, DURATION)).toEqual({
+        trim_start_ms: 5399,
+        trim_end_ms: 4500,
+      });
+    });
+
+    test('boundary: exactly the minimum remaining is rejected', () => {
+      // trim_start + trim_end === duration - MIN_CLIP_DURATION_MS
+      expect(
+        computeTrimValues('start', 400, 5000, 4500, DURATION)?.trim_start_ms ?? null,
+      ).toBeNull();
+      expect(MIN_CLIP_DURATION_MS).toBe(100);
+    });
+  });
+
+  test('zero delta is a no-op that returns the initial trims', () => {
+    expect(computeTrimValues('start', 0, 1200, 800, DURATION)).toEqual({
+      trim_start_ms: 1200,
+      trim_end_ms: 800,
+    });
+  });
+});

app/src/lib/utils/trim.ts

@@ -0,0 +1,57 @@
+import type { StoryItemTrim } from '@/lib/api/types';
+
+/** Clips are never allowed to shrink below this effective duration. */
+export const MIN_CLIP_DURATION_MS = 100;
+
+/**
+ * Computes new trim values for a clip while a trim handle is being dragged.
+ *
+ * `deltaMs` is the signed drag distance converted to milliseconds. Dragging
+ * the start handle right increases `trim_start_ms` (trims more from the
+ * start); dragging it left restores. The end handle mirrors this for
+ * `trim_end_ms`. Both values are clamped so the clip keeps at least
+ * MIN_CLIP_DURATION_MS of audible content.
+ *
+ * Returns null when the drag would leave less than the minimum duration.
+ */
+export function computeTrimValues(
+  side: 'start' | 'end',
+  deltaMs: number,
+  initialTrimStart: number,
+  initialTrimEnd: number,
+  originalDurationMs: number,
+): StoryItemTrim | null {
+  let newTrimStart = initialTrimStart;
+  let newTrimEnd = initialTrimEnd;
+
+  if (side === 'start') {
+    newTrimStart = Math.round(
+      Math.max(
+        0,
+        Math.min(
+          initialTrimStart + deltaMs,
+          originalDurationMs - initialTrimEnd - MIN_CLIP_DURATION_MS,
+        ),
+      ),
+    );
+  } else {
+    newTrimEnd = Math.round(
+      Math.max(
+        0,
+        Math.min(
+          initialTrimEnd - deltaMs,
+          originalDurationMs - initialTrimStart - MIN_CLIP_DURATION_MS,
+        ),
+      ),
+    );
+  }
+
+  if (newTrimStart + newTrimEnd >= originalDurationMs - MIN_CLIP_DURATION_MS) {
+    return null;
+  }
+
+  return {
+    trim_start_ms: newTrimStart,
+    trim_end_ms: newTrimEnd,
+  };
+}

app/tsconfig.json

@@ -25,7 +25,7 @@
     "paths": {
       "@/*": ["./src/*"]
     },
-    "types": ["vite/client"]
+    "types": ["vite/client", "bun"]
   },
   "include": ["src"],
   "references": [{ "path": "./tsconfig.node.json" }]

backend/app.py

@@ -95,18 +95,19 @@ if not os.environ.get("HSA_OVERRIDE_GFX_VERSION"):
 if not os.environ.get("MIOPEN_LOG_LEVEL"):
     os.environ["MIOPEN_LOG_LEVEL"] = "4"
 
+from urllib.parse import quote
+
 import torch
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
-from urllib.parse import quote
 
 from . import __version__, config, database
-from .services import tts, transcribe, llm
 from .database import get_db
+from .routes import register_routers
+from .services import llm, transcribe, tts
+from .services.task_queue import create_background_task, init_queue
 from .utils.platform_detect import get_backend_type
 from .utils.progress import get_progress_manager
-from .services.task_queue import create_background_task, init_queue
-from .routes import register_routers
 
 
 def safe_content_disposition(disposition_type: str, filename: str) -> str:
@@ -122,8 +123,8 @@ def safe_content_disposition(disposition_type: str, filename: str) -> str:
 
 def create_app() -> FastAPI:
     """Create and configure the FastAPI application."""
-    from .mcp_server.server import build_mcp_server, compose_lifespan
     from .mcp_server.context import ClientIdMiddleware
+    from .mcp_server.server import build_mcp_server, compose_lifespan
 
     # Build the MCP app up-front so we can wire its lifespan into FastAPI's —
     # FastMCP's Streamable HTTP transport only works if its session manager
@@ -202,8 +203,8 @@ def _mount_frontend(application: FastAPI) -> None:
     if not frontend_dir.is_dir():
         return
 
-    from fastapi.staticfiles import StaticFiles
     from fastapi.responses import FileResponse
+    from fastapi.staticfiles import StaticFiles
 
     # Mount hashed assets (JS, CSS, images) that Vite places under /assets
     assets_dir = frontend_dir / "assets"
@@ -243,9 +244,9 @@ def _get_gpu_status() -> str:
         if not compatible:
             label += " [UNSUPPORTED - see logs]"
         return label
-    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
         return "MPS (Apple Silicon)"
-    elif backend_type == "mlx":
+    if backend_type == "mlx":
         return "Metal (Apple Silicon via MLX)"
 
     # Intel XPU (Arc / Data Center) via IPEX
@@ -302,7 +303,7 @@ async def _run_startup(application: FastAPI) -> None:
         if result.rowcount > 0:
             logger.info("Marked %d stale generation(s) as failed", result.rowcount)
 
-        from .database import VoiceProfile as DBVoiceProfile, Generation as DBGeneration
+        from .database import Generation as DBGeneration, VoiceProfile as DBVoiceProfile
 
         profile_count = db.query(DBVoiceProfile).count()
         generation_count = db.query(DBGeneration).count()
@@ -353,15 +354,15 @@ async def _run_shutdown() -> None:
     """Unload models on lifespan exit."""
     logger.info("Voicebox server shutting down...")
     try:
-        tts.unload_tts_model()
+        await tts.unload_tts_model()
     except Exception:
         logger.exception("Failed to unload TTS model")
     try:
-        transcribe.unload_whisper_model()
+        await transcribe.unload_whisper_model()
     except Exception:
         logger.exception("Failed to unload Whisper model")
     try:
-        llm.unload_llm_model()
+        await llm.unload_llm_model()
     except Exception:
         logger.exception("Failed to unload LLM model")
 

backend/backends/__init__.py

@@ -10,13 +10,14 @@ and a model config registry that eliminates per-engine dispatch maps.
 # import time, which wraps transformers' tokenizer load against the
 # unconditional HuggingFace metadata call that otherwise raises on
 # HF_HUB_OFFLINE=1 and on network failures.
-from ..utils import hf_offline_patch  # noqa: F401
-
 import threading
 from dataclasses import dataclass, field
-from typing import Protocol, Optional, Tuple, List
-from typing_extensions import runtime_checkable
+from typing import Protocol
+
 import numpy as np
+from typing_extensions import runtime_checkable
+
+from ..utils import hf_offline_patch
 
 DEFAULT_LLM_MAX_TOKENS = 512
 DEFAULT_LLM_TEMPERATURE = 0.7
@@ -56,6 +57,7 @@ class ModelConfig:
     model_size: str = "default"
     size_mb: int = 0
     needs_trim: bool = False
+    retries_runaway: bool = False
     supports_instruct: bool = False
     languages: list[str] = field(default_factory=lambda: ["en"])
 
@@ -76,7 +78,7 @@ class TTSBackend(Protocol):
         audio_path: str,
         reference_text: str,
         use_cache: bool = True,
-    ) -> Tuple[dict, bool]:
+    ) -> tuple[dict, bool]:
         """
         Create voice prompt from reference audio.
 
@@ -87,9 +89,9 @@ class TTSBackend(Protocol):
 
     async def combine_voice_prompts(
         self,
-        audio_paths: List[str],
-        reference_texts: List[str],
-    ) -> Tuple[np.ndarray, str]:
+        audio_paths: list[str],
+        reference_texts: list[str],
+    ) -> tuple[np.ndarray, str]:
         """
         Combine multiple voice prompts.
 
@@ -103,9 +105,9 @@ class TTSBackend(Protocol):
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
-    ) -> Tuple[np.ndarray, int]:
+        seed: int | None = None,
+        instruct: str | None = None,
+    ) -> tuple[np.ndarray, int]:
         """
         Generate audio from text.
 
@@ -143,8 +145,8 @@ class STTBackend(Protocol):
     async def transcribe(
         self,
         audio_path: str,
-        language: Optional[str] = None,
-        model_size: Optional[str] = None,
+        language: str | None = None,
+        model_size: str | None = None,
     ) -> str:
         """
         Transcribe audio to text.
@@ -174,11 +176,11 @@ class LLMBackend(Protocol):
     async def generate(
         self,
         prompt: str,
-        system: Optional[str] = None,
+        system: str | None = None,
         max_tokens: int = DEFAULT_LLM_MAX_TOKENS,
         temperature: float = DEFAULT_LLM_TEMPERATURE,
-        model_size: Optional[str] = None,
-        examples: Optional[list[tuple[str, str]]] = None,
+        model_size: str | None = None,
+        examples: list[tuple[str, str]] | None = None,
     ) -> str:
         """Run a single-turn chat completion and return the assistant reply.
 
@@ -198,10 +200,11 @@ class LLMBackend(Protocol):
 
 
 # Global backend instances
-_tts_backend: Optional[TTSBackend] = None
+_tts_backend: TTSBackend | None = None
 _tts_backends: dict[str, TTSBackend] = {}
 _tts_backends_lock = threading.Lock()
-_stt_backend: Optional[STTBackend] = None
+_stt_backend: STTBackend | None = None
+_stt_backend_lock = threading.Lock()
 _llm_backends: dict[str, LLMBackend] = {}
 _llm_backends_lock = threading.Lock()
 
@@ -232,6 +235,10 @@ def _get_qwen_model_configs() -> list[ModelConfig]:
         repo_1_7b = "Qwen/Qwen3-TTS-12Hz-1.7B-Base"
         repo_0_6b = "Qwen/Qwen3-TTS-12Hz-0.6B-Base"
 
+    # mlx-audio can continue after an EOS miss with silence followed by
+    # codec noise. Retry only the affected text as smaller chunks.
+    retries_runaway = backend_type == "mlx"
+
     return [
         ModelConfig(
             model_name="qwen-tts-1.7B",
@@ -240,6 +247,7 @@ def _get_qwen_model_configs() -> list[ModelConfig]:
             hf_repo_id=repo_1_7b,
             model_size="1.7B",
             size_mb=3500,
+            retries_runaway=retries_runaway,
             supports_instruct=False,  # Base model drops instruct silently
             languages=["zh", "en", "ja", "ko", "de", "fr", "ru", "pt", "es", "it"],
         ),
@@ -250,6 +258,7 @@ def _get_qwen_model_configs() -> list[ModelConfig]:
             hf_repo_id=repo_0_6b,
             model_size="0.6B",
             size_mb=1200,
+            retries_runaway=retries_runaway,
             supports_instruct=False,
             languages=["zh", "en", "ja", "ko", "de", "fr", "ru", "pt", "es", "it"],
         ),
@@ -488,7 +497,7 @@ def get_stt_model_configs() -> list[ModelConfig]:
 # Lookup helpers — these replace the if/elif chains in main.py
 
 
-def get_model_config(model_name: str) -> Optional[ModelConfig]:
+def get_model_config(model_name: str) -> ModelConfig | None:
     """Look up a model config by model_name."""
     for cfg in get_all_model_configs():
         if cfg.model_name == model_name:
@@ -504,6 +513,14 @@ def engine_needs_trim(engine: str) -> bool:
     return False
 
 
+def engine_retries_runaway(engine: str) -> bool:
+    """Whether unstable output should be retried in smaller chunks."""
+    for cfg in get_tts_model_configs():
+        if cfg.engine == engine:
+            return cfg.retries_runaway
+    return False
+
+
 def engine_has_model_sizes(engine: str) -> bool:
     """Whether this engine supports multiple model sizes (only Qwen currently)."""
     configs = [c for c in get_tts_model_configs() if c.engine == engine]
@@ -547,15 +564,29 @@ async def ensure_model_cached_or_raise(engine: str, model_size: str = "default")
             )
 
 
-def unload_model_by_config(config: ModelConfig) -> bool:
+async def unload_backend(backend) -> None:
+    """Free a backend's model, serialized onto the MLX worker when it has one.
+
+    MLX backends expose an async ``unload`` that runs the free on the dedicated
+    MLX thread so it can't collide with an in-flight load/generate. Other
+    backends only carry the synchronous ``unload_model``.
+    """
+    unload = getattr(backend, "unload", None)
+    if unload is not None:
+        await unload()
+    else:
+        backend.unload_model()
+
+
+async def unload_model_by_config(config: ModelConfig) -> bool:
     """Unload a model given its config. Returns True if it was loaded, False otherwise."""
+    from ..services import llm as llm_service, transcribe, tts
     from . import get_tts_backend_for_engine
-    from ..services import tts, transcribe, llm as llm_service
 
     if config.engine == "whisper":
         whisper_model = transcribe.get_whisper_model()
         if whisper_model.is_loaded() and whisper_model.model_size == config.model_size:
-            transcribe.unload_whisper_model()
+            await unload_backend(whisper_model)
             return True
         return False
 
@@ -563,7 +594,7 @@ def unload_model_by_config(config: ModelConfig) -> bool:
         backend = llm_service.get_llm_model()
         loaded_size = getattr(backend, "_current_model_size", None) or getattr(backend, "model_size", None)
         if backend.is_loaded() and loaded_size == config.model_size:
-            backend.unload_model()
+            await unload_backend(backend)
             return True
         return False
 
@@ -571,7 +602,7 @@ def unload_model_by_config(config: ModelConfig) -> bool:
         tts_model = tts.get_tts_model()
         loaded_size = getattr(tts_model, "_current_model_size", None) or getattr(tts_model, "model_size", None)
         if tts_model.is_loaded() and loaded_size == config.model_size:
-            tts.unload_tts_model()
+            await unload_backend(tts_model)
             return True
         return False
 
@@ -579,22 +610,22 @@ def unload_model_by_config(config: ModelConfig) -> bool:
         backend = get_tts_backend_for_engine(config.engine)
         loaded_size = getattr(backend, "_current_model_size", None) or getattr(backend, "model_size", None)
         if backend.is_loaded() and loaded_size == config.model_size:
-            backend.unload_model()
+            await unload_backend(backend)
             return True
         return False
 
     # All other TTS engines
     backend = get_tts_backend_for_engine(config.engine)
     if backend.is_loaded():
-        backend.unload_model()
+        await unload_backend(backend)
         return True
     return False
 
 
 def check_model_loaded(config: ModelConfig) -> bool:
     """Check if a model is currently loaded."""
+    from ..services import llm as llm_service, transcribe, tts
     from . import get_tts_backend_for_engine
-    from ..services import tts, transcribe, llm as llm_service
 
     try:
         if config.engine == "whisper":
@@ -624,8 +655,8 @@ def check_model_loaded(config: ModelConfig) -> bool:
 
 def get_model_load_func(config: ModelConfig):
     """Return a callable that loads/downloads the model."""
+    from ..services import llm as llm_service, transcribe, tts
     from . import get_tts_backend_for_engine
-    from ..services import tts, transcribe, llm as llm_service
 
     if config.engine == "whisper":
         return lambda: transcribe.get_whisper_model().load_model(config.model_size)
@@ -724,7 +755,13 @@ def get_stt_backend() -> STTBackend:
     """
     global _stt_backend
 
-    if _stt_backend is None:
+    if _stt_backend is not None:
+        return _stt_backend
+
+    with _stt_backend_lock:
+        if _stt_backend is not None:
+            return _stt_backend
+
         backend_type = get_backend_type()
 
         if backend_type == "mlx":
@@ -736,7 +773,7 @@ def get_stt_backend() -> STTBackend:
 
             _stt_backend = PyTorchSTTBackend()
 
-    return _stt_backend
+        return _stt_backend
 
 
 def get_llm_backend() -> LLMBackend:

backend/backends/base.py

@@ -9,13 +9,12 @@ import logging
 import platform
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Callable, List, Optional, Tuple
 
 import numpy as np
 
-from ..utils.audio import normalize_audio, load_audio
-from ..utils.progress import get_progress_manager
+from ..utils.audio import load_audio, normalize_audio
 from ..utils.hf_progress import HFProgressTracker, create_hf_progress_callback
+from ..utils.progress import get_progress_manager
 from ..utils.tasks import get_task_manager
 
 logger = logging.getLogger(__name__)
@@ -25,7 +24,7 @@ def is_model_cached(
     hf_repo: str,
     *,
     weight_extensions: tuple[str, ...] = (".safetensors", ".bin"),
-    required_files: Optional[list[str]] = None,
+    required_files: list[str] | None = None,
 ) -> bool:
     """
     Check if a HuggingFace model is fully cached locally.
@@ -201,11 +200,11 @@ def manual_seed(seed: int, device: str) -> None:
 
 
 async def combine_voice_prompts(
-    audio_paths: List[str],
-    reference_texts: List[str],
+    audio_paths: list[str],
+    reference_texts: list[str],
     *,
-    sample_rate: Optional[int] = None,
-) -> Tuple[np.ndarray, str]:
+    sample_rate: int | None = None,
+) -> tuple[np.ndarray, str]:
     """
     Combine multiple reference audio samples into one.
 
@@ -235,7 +234,7 @@ async def combine_voice_prompts(
 def model_load_progress(
     model_name: str,
     is_cached: bool,
-    filter_non_downloads: Optional[bool] = None,
+    filter_non_downloads: bool | None = None,
 ):
     """
     Context manager for model loading with HF download progress tracking.

backend/backends/chatterbox_backend.py

@@ -10,17 +10,16 @@ import asyncio
 import logging
 import threading
 from pathlib import Path
-from typing import ClassVar, List, Optional, Tuple
+from typing import ClassVar
 
 import numpy as np
 
-from . import TTSBackend
 from .base import (
-    is_model_cached,
-    get_torch_device,
-    empty_device_cache,
-    manual_seed,
     combine_voice_prompts as _combine_voice_prompts,
+    empty_device_cache,
+    get_torch_device,
+    is_model_cached,
+    manual_seed,
     model_load_progress,
     patch_chatterbox_f32,
 )
@@ -127,7 +126,7 @@ class ChatterboxTTSBackend:
         audio_path: str,
         reference_text: str,
         use_cache: bool = True,
-    ) -> Tuple[dict, bool]:
+    ) -> tuple[dict, bool]:
         """
         Create voice prompt from reference audio.
 
@@ -143,9 +142,9 @@ class ChatterboxTTSBackend:
 
     async def combine_voice_prompts(
         self,
-        audio_paths: List[str],
-        reference_texts: List[str],
-    ) -> Tuple[np.ndarray, str]:
+        audio_paths: list[str],
+        reference_texts: list[str],
+    ) -> tuple[np.ndarray, str]:
         return await _combine_voice_prompts(audio_paths, reference_texts)
 
     # Per-language generation defaults. Lower temp + higher cfg = clearer speech.
@@ -169,9 +168,9 @@ class ChatterboxTTSBackend:
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
-    ) -> Tuple[np.ndarray, int]:
+        seed: int | None = None,
+        instruct: str | None = None,
+    ) -> tuple[np.ndarray, int]:
         """
         Generate audio using Chatterbox Multilingual TTS.
 

backend/backends/chatterbox_turbo_backend.py

@@ -10,17 +10,16 @@ import asyncio
 import logging
 import threading
 from pathlib import Path
-from typing import ClassVar, List, Optional, Tuple
+from typing import ClassVar
 
 import numpy as np
 
-from . import TTSBackend
 from .base import (
-    is_model_cached,
-    get_torch_device,
-    empty_device_cache,
-    manual_seed,
     combine_voice_prompts as _combine_voice_prompts,
+    empty_device_cache,
+    get_torch_device,
+    is_model_cached,
+    manual_seed,
     model_load_progress,
     patch_chatterbox_f32,
 )
@@ -81,8 +80,8 @@ class ChatterboxTurboTTSBackend:
             logger.info(f"Loading Chatterbox Turbo TTS on {device}...")
 
             import torch
-            from huggingface_hub import snapshot_download
             from chatterbox.tts_turbo import ChatterboxTurboTTS
+            from huggingface_hub import snapshot_download
 
             local_path = snapshot_download(
                 repo_id=CHATTERBOX_TURBO_HF_REPO,
@@ -126,7 +125,7 @@ class ChatterboxTurboTTSBackend:
         audio_path: str,
         reference_text: str,
         use_cache: bool = True,
-    ) -> Tuple[dict, bool]:
+    ) -> tuple[dict, bool]:
         """
         Create voice prompt from reference audio.
 
@@ -141,9 +140,9 @@ class ChatterboxTurboTTSBackend:
 
     async def combine_voice_prompts(
         self,
-        audio_paths: List[str],
-        reference_texts: List[str],
-    ) -> Tuple[np.ndarray, str]:
+        audio_paths: list[str],
+        reference_texts: list[str],
+    ) -> tuple[np.ndarray, str]:
         return await _combine_voice_prompts(audio_paths, reference_texts)
 
     async def generate(
@@ -151,9 +150,9 @@ class ChatterboxTurboTTSBackend:
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
-    ) -> Tuple[np.ndarray, int]:
+        seed: int | None = None,
+        instruct: str | None = None,
+    ) -> tuple[np.ndarray, int]:
         """
         Generate audio using Chatterbox Turbo TTS.
 

backend/backends/hume_backend.py

@@ -16,20 +16,19 @@ causal LM generates speech via flow-matching diffusion.
 import asyncio
 import logging
 import threading
-from typing import ClassVar, List, Optional, Tuple
+from typing import ClassVar
 
 import numpy as np
 
-from . import TTSBackend
+from ..utils.cache import cache_voice_prompt, get_cache_key, get_cached_voice_prompt
 from .base import (
-    is_model_cached,
-    get_torch_device,
-    empty_device_cache,
-    manual_seed,
     combine_voice_prompts as _combine_voice_prompts,
+    empty_device_cache,
+    get_torch_device,
+    is_model_cached,
+    manual_seed,
     model_load_progress,
 )
-from ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_prompt
 
 logger = logging.getLogger(__name__)
 
@@ -182,7 +181,7 @@ class HumeTadaBackend:
             #   getattr(config, "tokenizer_name", "meta-llama/Llama-3.2-1B")
             # which hits the gated repo. Pre-load the config from HF,
             # inject the local tokenizer path, then pass it in.
-            from tada.modules.tada import TadaForCausalLM, TadaConfig
+            from tada.modules.tada import TadaConfig, TadaForCausalLM
 
             logger.info(f"Loading TADA {model_size} model...")
             config = TadaConfig.from_pretrained(repo)
@@ -214,7 +213,7 @@ class HumeTadaBackend:
         audio_path: str,
         reference_text: str,
         use_cache: bool = True,
-    ) -> Tuple[dict, bool]:
+    ) -> tuple[dict, bool]:
         """
         Create voice prompt from reference audio using TADA's encoder.
 
@@ -234,8 +233,8 @@ class HumeTadaBackend:
                 return cached, True
 
         def _encode_sync():
-            import torch
             import soundfile as sf
+            import torch
 
             device = self._device
 
@@ -248,9 +247,13 @@ class HumeTadaBackend:
                 audio = audio.T  # (samples, channels) -> (channels, samples)
             audio = audio.to(device)
 
-            # Encode with forced alignment
+            # Encode with forced alignment.
+            # Must run under inference_mode: encoder params still require
+            # grad by default, and an autograd graph across the DAC/Snake
+            # stack can balloon VRAM far past the model footprint (#890).
             text_arg = [reference_text] if reference_text else None
-            prompt = self.encoder(audio, text=text_arg, sample_rate=sr)
+            with torch.inference_mode():
+                prompt = self.encoder(audio, text=text_arg, sample_rate=sr)
 
             # Serialize EncoderOutput to a dict of CPU tensors for caching
             prompt_dict = {}
@@ -258,9 +261,7 @@ class HumeTadaBackend:
                 val = getattr(prompt, field_name)
                 if isinstance(val, torch.Tensor):
                     prompt_dict[field_name] = val.detach().cpu()
-                elif isinstance(val, list):
-                    prompt_dict[field_name] = val
-                elif isinstance(val, (int, float)):
+                elif isinstance(val, (list, int, float)):
                     prompt_dict[field_name] = val
                 else:
                     prompt_dict[field_name] = val
@@ -275,9 +276,9 @@ class HumeTadaBackend:
 
     async def combine_voice_prompts(
         self,
-        audio_paths: List[str],
-        reference_texts: List[str],
-    ) -> Tuple[np.ndarray, str]:
+        audio_paths: list[str],
+        reference_texts: list[str],
+    ) -> tuple[np.ndarray, str]:
         return await _combine_voice_prompts(audio_paths, reference_texts, sample_rate=24000)
 
     async def generate(
@@ -285,9 +286,9 @@ class HumeTadaBackend:
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
-    ) -> Tuple[np.ndarray, int]:
+        seed: int | None = None,
+        instruct: str | None = None,
+    ) -> tuple[np.ndarray, int]:
         """
         Generate audio from text using HumeAI TADA.
 

backend/backends/kokoro_backend.py

@@ -17,15 +17,12 @@ Languages supported (via misaki G2P):
 
 import asyncio
 import logging
-import os
-from typing import Optional
 
 import numpy as np
 
-from . import TTSBackend
 from .base import (
-    get_torch_device,
     combine_voice_prompts as _combine_voice_prompts,
+    get_torch_device,
     model_load_progress,
 )
 
@@ -122,8 +119,9 @@ class KokoroTTSBackend:
     def __init__(self):
         self._model = None
         self._pipelines: dict = {}  # lang_code -> KPipeline
-        self._device: Optional[str] = None
+        self._device: str | None = None
         self.model_size = "default"
+        self._model_load_lock = asyncio.Lock()
 
     def _get_device(self) -> str:
         """Select device. Kokoro supports CUDA and CPU. MPS needs fallback env var."""
@@ -157,7 +155,10 @@ class KokoroTTSBackend:
         """Load the Kokoro model."""
         if self._model is not None:
             return
-        await asyncio.to_thread(self._load_model_sync)
+        async with self._model_load_lock:
+            if self._model is not None:
+                return
+            await asyncio.to_thread(self._load_model_sync)
 
     def _load_model_sync(self):
         """Synchronous model loading."""
@@ -239,8 +240,8 @@ class KokoroTTSBackend:
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
+        seed: int | None = None,
+        instruct: str | None = None,
     ) -> tuple[np.ndarray, int]:
         """
         Generate audio from text using Kokoro.

backend/backends/luxtts_backend.py

@@ -7,20 +7,18 @@ Wraps the LuxTTS (ZipVoice) model for zero-shot voice cloning.
 
 import asyncio
 import logging
-from typing import Optional, Tuple
 
 import numpy as np
 
-from . import TTSBackend
+from ..utils.cache import cache_voice_prompt, get_cache_key, get_cached_voice_prompt
 from .base import (
-    is_model_cached,
-    get_torch_device,
-    empty_device_cache,
-    manual_seed,
     combine_voice_prompts as _combine_voice_prompts,
+    empty_device_cache,
+    get_torch_device,
+    is_model_cached,
+    manual_seed,
     model_load_progress,
 )
-from ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_prompt
 
 logger = logging.getLogger(__name__)
 
@@ -35,6 +33,7 @@ class LuxTTSBackend:
         self.model = None
         self.model_size = "default"  # LuxTTS has only one model size
         self._device = None
+        self._model_load_lock = asyncio.Lock()
 
     def _get_device(self) -> str:
         return get_torch_device(allow_mps=True, allow_xpu=True)
@@ -61,8 +60,10 @@ class LuxTTSBackend:
         """Load the LuxTTS model."""
         if self.model is not None:
             return
-
-        await asyncio.to_thread(self._load_model_sync)
+        async with self._model_load_lock:
+            if self.model is not None:
+                return
+            await asyncio.to_thread(self._load_model_sync)
 
     def _load_model_sync(self):
         model_name = "luxtts"
@@ -105,7 +106,7 @@ class LuxTTSBackend:
         audio_path: str,
         reference_text: str,
         use_cache: bool = True,
-    ) -> Tuple[dict, bool]:
+    ) -> tuple[dict, bool]:
         """
         Create voice prompt from reference audio.
 
@@ -145,9 +146,9 @@ class LuxTTSBackend:
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
-    ) -> Tuple[np.ndarray, int]:
+        seed: int | None = None,
+        instruct: str | None = None,
+    ) -> tuple[np.ndarray, int]:
         """
         Generate audio from text using LuxTTS.
 

backend/backends/mlx_backend.py

@@ -2,24 +2,24 @@
 MLX backend implementation for TTS and STT using mlx-audio.
 """
 
-from typing import Optional, List, Tuple
-import asyncio
 import logging
-import numpy as np
 from pathlib import Path
 
+import numpy as np
+
 logger = logging.getLogger(__name__)
 
 # PATCH: Import and apply offline patch BEFORE any huggingface_hub usage
 # This prevents mlx_audio from making network requests when models are cached
-from ..utils.hf_offline_patch import patch_huggingface_hub_offline, ensure_original_qwen_config_cached
+from ..utils.hf_offline_patch import ensure_original_qwen_config_cached, patch_huggingface_hub_offline
 
 patch_huggingface_hub_offline()
 ensure_original_qwen_config_cached()
 
-from . import TTSBackend, STTBackend, LANGUAGE_CODE_TO_NAME, WHISPER_HF_REPOS
-from .base import is_model_cached, combine_voice_prompts as _combine_voice_prompts, model_load_progress
-from ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_prompt
+from ..services.mlx_thread import clear_mlx_cache, run_on_mlx_thread
+from ..utils.cache import cache_voice_prompt, get_cache_key, get_cached_voice_prompt
+from . import LANGUAGE_CODE_TO_NAME, WHISPER_HF_REPOS
+from .base import combine_voice_prompts as _combine_voice_prompts, is_model_cached, model_load_progress
 
 
 class MLXTTSBackend:
@@ -63,30 +63,38 @@ class MLXTTSBackend:
             weight_extensions=(".safetensors", ".bin", ".npz"),
         )
 
-    async def load_model_async(self, model_size: Optional[str] = None):
+    def _ensure_loaded_sync(self, model_size: str | None):
+        """Load the model if the requested size isn't already resident.
+
+        Runs on the MLX worker thread so it stays serialized with generation.
+        """
+        if model_size is None:
+            model_size = self.model_size
+
+        if self.model is not None and self._current_model_size == model_size:
+            return
+
+        if self.model is not None and self._current_model_size != model_size:
+            self.unload_model()
+
+        self._load_model_sync(model_size)
+
+    async def load_model_async(self, model_size: str | None = None):
         """
         Lazy load the MLX TTS model.
 
         Args:
             model_size: Model size to load (1.7B or 0.6B)
         """
-        if model_size is None:
-            model_size = self.model_size
-
-        # If already loaded with correct size, return
-        if self.model is not None and self._current_model_size == model_size:
-            return
-
-        # Unload existing model if different size requested
-        if self.model is not None and self._current_model_size != model_size:
-            self.unload_model()
-
-        # Run blocking load in thread pool
-        await asyncio.to_thread(self._load_model_sync, model_size)
+        await run_on_mlx_thread(self._ensure_loaded_sync, model_size)
 
     # Alias for compatibility
     load_model = load_model_async
 
+    async def unload(self):
+        """Free the model, serialized onto the MLX worker thread."""
+        await run_on_mlx_thread(self.unload_model)
+
     def _load_model_sync(self, model_size: str):
         """Synchronous model loading."""
         model_path = self._get_model_path(model_size)
@@ -110,6 +118,7 @@ class MLXTTSBackend:
             del self.model
             self.model = None
             self._current_model_size = None
+            clear_mlx_cache()
             logger.info("MLX TTS model unloaded")
 
     async def create_voice_prompt(
@@ -117,7 +126,7 @@ class MLXTTSBackend:
         audio_path: str,
         reference_text: str,
         use_cache: bool = True,
-    ) -> Tuple[dict, bool]:
+    ) -> tuple[dict, bool]:
         """
         Create voice prompt from reference audio.
 
@@ -145,9 +154,8 @@ class MLXTTSBackend:
                     cached_audio_path = cached_prompt.get("ref_audio") or cached_prompt.get("ref_audio_path")
                     if cached_audio_path and Path(cached_audio_path).exists():
                         return cached_prompt, True
-                    else:
-                        # Cached file no longer exists, invalidate cache
-                        logger.warning("Cached audio file not found: %s, regenerating prompt", cached_audio_path)
+                    # Cached file no longer exists, invalidate cache
+                    logger.warning("Cached audio file not found: %s, regenerating prompt", cached_audio_path)
 
         # MLX voice prompt format - store audio path and text
         # The model will process this during generation
@@ -171,9 +179,9 @@ class MLXTTSBackend:
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
-    ) -> Tuple[np.ndarray, int]:
+        seed: int | None = None,
+        instruct: str | None = None,
+    ) -> tuple[np.ndarray, int]:
         """
         Generate audio from text using voice prompt.
 
@@ -187,8 +195,6 @@ class MLXTTSBackend:
         Returns:
             Tuple of (audio_array, sample_rate)
         """
-        await self.load_model_async(None)
-
         logger.info("Generating audio for text: %s", text)
 
         def _generate_sync():
@@ -221,45 +227,39 @@ class MLXTTSBackend:
             # mlx_audio lookups hanging when the network drops mid-inference,
             # issue #462) regressed online users because libraries make
             # legitimate metadata calls during generation.
-            try:
-                if ref_audio:
-                    # Check if generate accepts ref_audio parameter
-                    import inspect
+            # A cloning failure surfaces as a failed generation; substituting
+            # the model's default voice would silently break the clone the
+            # user asked for.
+            if ref_audio:
+                import inspect
 
-                    sig = inspect.signature(self.model.generate)
-                    if "ref_audio" in sig.parameters:
-                        # Generate with voice cloning
-                        for result in self.model.generate(text, ref_audio=ref_audio, ref_text=ref_text, lang_code=lang):
-                            audio_chunks.append(np.array(result.audio))
-                            sample_rate = result.sample_rate
-                    else:
-                        # Fallback: generate without voice cloning
-                        for result in self.model.generate(text, lang_code=lang):
-                            audio_chunks.append(np.array(result.audio))
-                            sample_rate = result.sample_rate
-                else:
-                    # No voice prompt, generate normally
-                    for result in self.model.generate(text, lang_code=lang):
-                        audio_chunks.append(np.array(result.audio))
-                        sample_rate = result.sample_rate
-            except Exception as e:
-                # If voice cloning fails, try without it
-                logger.warning("Voice cloning failed, generating without voice prompt: %s", e)
+                sig = inspect.signature(self.model.generate)
+                if "ref_audio" not in sig.parameters:
+                    raise RuntimeError(
+                        "Loaded MLX model does not support voice cloning "
+                        "(generate() has no ref_audio parameter)"
+                    )
+                for result in self.model.generate(text, ref_audio=ref_audio, ref_text=ref_text, lang_code=lang):
+                    audio_chunks.append(np.array(result.audio))
+                    sample_rate = result.sample_rate
+            else:
                 for result in self.model.generate(text, lang_code=lang):
                     audio_chunks.append(np.array(result.audio))
                     sample_rate = result.sample_rate
 
-            # Concatenate all chunks
-            if audio_chunks:
-                audio = np.concatenate([np.asarray(chunk, dtype=np.float32) for chunk in audio_chunks])
-            else:
-                # Fallback: empty audio
-                audio = np.array([], dtype=np.float32)
+            if not audio_chunks:
+                raise RuntimeError("Model produced no audio")
 
+            audio = np.concatenate([np.asarray(chunk, dtype=np.float32) for chunk in audio_chunks])
             return audio, sample_rate
 
-        # Run blocking inference in thread pool
-        audio, sample_rate = await asyncio.to_thread(_generate_sync)
+        # Load-if-needed and inference run as one job on the MLX worker so a
+        # concurrent unload or different-size load can't land between them.
+        def _load_and_generate():
+            self._ensure_loaded_sync(None)
+            return _generate_sync()
+
+        audio, sample_rate = await run_on_mlx_thread(_load_and_generate)
 
         return audio, sample_rate
 
@@ -279,12 +279,10 @@ class MLXSTTBackend:
         hf_repo = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
         return is_model_cached(hf_repo, weight_extensions=(".safetensors", ".bin", ".npz"))
 
-    async def load_model_async(self, model_size: Optional[str] = None):
-        """
-        Lazy load the MLX Whisper model.
+    def _ensure_loaded_sync(self, model_size: str | None):
+        """Load the model if the requested size isn't already resident.
 
-        Args:
-            model_size: Model size (tiny, base, small, medium, large)
+        Runs on the MLX worker thread so it stays serialized with transcription.
         """
         if model_size is None:
             model_size = self.model_size
@@ -292,12 +290,24 @@ class MLXSTTBackend:
         if self.model is not None and self.model_size == model_size:
             return
 
-        # Run blocking load in thread pool
-        await asyncio.to_thread(self._load_model_sync, model_size)
+        self._load_model_sync(model_size)
+
+    async def load_model_async(self, model_size: str | None = None):
+        """
+        Lazy load the MLX Whisper model.
+
+        Args:
+            model_size: Model size (tiny, base, small, medium, large)
+        """
+        await run_on_mlx_thread(self._ensure_loaded_sync, model_size)
 
     # Alias for compatibility
     load_model = load_model_async
 
+    async def unload(self):
+        """Free the model, serialized onto the MLX worker thread."""
+        await run_on_mlx_thread(self.unload_model)
+
     def _load_model_sync(self, model_size: str):
         """Synchronous model loading."""
         progress_model_name = f"whisper-{model_size}"
@@ -319,13 +329,14 @@ class MLXSTTBackend:
         if self.model is not None:
             del self.model
             self.model = None
+            clear_mlx_cache()
             logger.info("MLX Whisper model unloaded")
 
     async def transcribe(
         self,
         audio_path: str,
-        language: Optional[str] = None,
-        model_size: Optional[str] = None,
+        language: str | None = None,
+        model_size: str | None = None,
     ) -> str:
         """
         Transcribe audio to text.
@@ -338,8 +349,6 @@ class MLXSTTBackend:
         Returns:
             Transcribed text
         """
-        await self.load_model_async(model_size)
-
         def _transcribe_sync():
             """Run synchronous transcription in thread pool."""
             # MLX Whisper transcription using generate method
@@ -356,12 +365,16 @@ class MLXSTTBackend:
             # Extract text from result
             if isinstance(result, str):
                 return result.strip()
-            elif isinstance(result, dict):
+            if isinstance(result, dict):
                 return result.get("text", "").strip()
-            elif hasattr(result, "text"):
+            if hasattr(result, "text"):
                 return result.text.strip()
-            else:
-                return str(result).strip()
+            return str(result).strip()
 
-        # Run blocking transcription in thread pool
-        return await asyncio.to_thread(_transcribe_sync)
+        # Load-if-needed and transcription run as one job on the MLX worker so
+        # a concurrent unload or load can't land between them.
+        def _load_and_transcribe():
+            self._ensure_loaded_sync(model_size)
+            return _transcribe_sync()
+
+        return await run_on_mlx_thread(_load_and_transcribe)

backend/backends/pytorch_backend.py

@@ -2,25 +2,25 @@
 PyTorch backend implementation for TTS and STT.
 """
 
-from typing import Optional, List, Tuple
 import asyncio
 import logging
-import torch
+
 import numpy as np
+import torch
 
 logger = logging.getLogger(__name__)
 
-from . import TTSBackend, STTBackend, LANGUAGE_CODE_TO_NAME, WHISPER_HF_REPOS
+from ..utils.audio import load_audio
+from ..utils.cache import cache_voice_prompt, get_cache_key, get_cached_voice_prompt
+from . import LANGUAGE_CODE_TO_NAME, WHISPER_HF_REPOS
 from .base import (
-    is_model_cached,
-    get_torch_device,
-    empty_device_cache,
-    manual_seed,
     combine_voice_prompts as _combine_voice_prompts,
+    empty_device_cache,
+    get_torch_device,
+    is_model_cached,
+    manual_seed,
     model_load_progress,
 )
-from ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_prompt
-from ..utils.audio import load_audio
 
 
 class PyTorchTTSBackend:
@@ -63,7 +63,7 @@ class PyTorchTTSBackend:
     def _is_model_cached(self, model_size: str) -> bool:
         return is_model_cached(self._get_model_path(model_size))
 
-    async def load_model_async(self, model_size: Optional[str] = None):
+    async def load_model_async(self, model_size: str | None = None):
         """
         Lazy load the TTS model with automatic downloading from HuggingFace Hub.
 
@@ -140,7 +140,7 @@ class PyTorchTTSBackend:
         audio_path: str,
         reference_text: str,
         use_cache: bool = True,
-    ) -> Tuple[dict, bool]:
+    ) -> tuple[dict, bool]:
         """
         Create voice prompt from reference audio.
 
@@ -165,7 +165,7 @@ class PyTorchTTSBackend:
                     # For PyTorch backend, the dict should contain tensors, not file paths
                     # So we can safely return it
                     return cached_prompt, True
-                elif isinstance(cached_prompt, torch.Tensor):
+                if isinstance(cached_prompt, torch.Tensor):
                     # Legacy cache format - convert to dict
                     # This shouldn't happen in practice, but handle it
                     return {"prompt": cached_prompt}, True
@@ -194,9 +194,9 @@ class PyTorchTTSBackend:
 
     async def combine_voice_prompts(
         self,
-        audio_paths: List[str],
-        reference_texts: List[str],
-    ) -> Tuple[np.ndarray, str]:
+        audio_paths: list[str],
+        reference_texts: list[str],
+    ) -> tuple[np.ndarray, str]:
         return await _combine_voice_prompts(audio_paths, reference_texts)
 
     async def generate(
@@ -204,9 +204,9 @@ class PyTorchTTSBackend:
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
-    ) -> Tuple[np.ndarray, int]:
+        seed: int | None = None,
+        instruct: str | None = None,
+    ) -> tuple[np.ndarray, int]:
         """
         Generate audio from text using voice prompt.
 
@@ -266,7 +266,7 @@ class PyTorchSTTBackend:
         hf_repo = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
         return is_model_cached(hf_repo)
 
-    async def load_model_async(self, model_size: Optional[str] = None):
+    async def load_model_async(self, model_size: str | None = None):
         """
         Lazy load the Whisper model.
 
@@ -290,7 +290,7 @@ class PyTorchSTTBackend:
         is_cached = self._is_model_cached(model_size)
 
         with model_load_progress(progress_model_name, is_cached):
-            from transformers import WhisperProcessor, WhisperForConditionalGeneration
+            from transformers import WhisperForConditionalGeneration, WhisperProcessor
 
             model_name = WHISPER_HF_REPOS.get(model_size, f"openai/whisper-{model_size}")
             logger.info("Loading Whisper model %s on %s...", model_size, self.device)
@@ -317,8 +317,8 @@ class PyTorchSTTBackend:
     async def transcribe(
         self,
         audio_path: str,
-        language: Optional[str] = None,
-        model_size: Optional[str] = None,
+        language: str | None = None,
+        model_size: str | None = None,
     ) -> str:
         """
         Transcribe audio to text.

backend/backends/qwen_custom_voice_backend.py

@@ -16,16 +16,15 @@ Languages supported: zh, en, ja, ko, de, fr, ru, pt, es, it
 
 import asyncio
 import logging
-from typing import Optional
 
 import numpy as np
 import torch
 
-from . import TTSBackend, LANGUAGE_CODE_TO_NAME
+from . import LANGUAGE_CODE_TO_NAME
 from .base import (
-    is_model_cached,
-    get_torch_device,
     combine_voice_prompts as _combine_voice_prompts,
+    get_torch_device,
+    is_model_cached,
     model_load_progress,
 )
 
@@ -62,7 +61,7 @@ class QwenCustomVoiceBackend:
         self.model = None
         self.model_size = model_size
         self.device = self._get_device()
-        self._current_model_size: Optional[str] = None
+        self._current_model_size: str | None = None
 
     def _get_device(self) -> str:
         return get_torch_device(allow_xpu=True, allow_directml=True)
@@ -75,11 +74,11 @@ class QwenCustomVoiceBackend:
             raise ValueError(f"Unknown model size: {model_size}")
         return QWEN_CV_HF_REPOS[model_size]
 
-    def _is_model_cached(self, model_size: Optional[str] = None) -> bool:
+    def _is_model_cached(self, model_size: str | None = None) -> bool:
         size = model_size or self.model_size
         return is_model_cached(self._get_model_path(size))
 
-    async def load_model_async(self, model_size: Optional[str] = None) -> None:
+    async def load_model_async(self, model_size: str | None = None) -> None:
         if model_size is None:
             model_size = self.model_size
 
@@ -164,8 +163,8 @@ class QwenCustomVoiceBackend:
         text: str,
         voice_prompt: dict,
         language: str = "en",
-        seed: Optional[int] = None,
-        instruct: Optional[str] = None,
+        seed: int | None = None,
+        instruct: str | None = None,
     ) -> tuple[np.ndarray, int]:
         """
         Generate audio using Qwen CustomVoice.

backend/backends/qwen_llm_backend.py

@@ -9,17 +9,16 @@ and STT engines.
 
 import asyncio
 import logging
-from typing import Optional
 
-from . import LLMBackend, DEFAULT_LLM_MAX_TOKENS, DEFAULT_LLM_TEMPERATURE
+from ..services.mlx_thread import clear_mlx_cache, run_on_mlx_thread
+from ..utils.hf_offline_patch import force_offline_if_cached
+from . import DEFAULT_LLM_MAX_TOKENS, DEFAULT_LLM_TEMPERATURE
 from .base import (
-    is_model_cached,
-    get_torch_device,
     empty_device_cache,
-    manual_seed,
+    get_torch_device,
+    is_model_cached,
     model_load_progress,
 )
-from ..utils.hf_offline_patch import force_offline_if_cached
 
 logger = logging.getLogger(__name__)
 
@@ -43,8 +42,8 @@ def _progress_name(model_size: str) -> str:
 
 def _build_messages(
     prompt: str,
-    system: Optional[str],
-    examples: Optional[list[tuple[str, str]]] = None,
+    system: str | None,
+    examples: list[tuple[str, str]] | None = None,
 ) -> list[dict]:
     messages: list[dict] = []
     if system:
@@ -64,7 +63,7 @@ class PyTorchQwenLLMBackend:
         self.model = None
         self.tokenizer = None
         self.model_size = model_size
-        self._current_model_size: Optional[str] = None
+        self._current_model_size: str | None = None
         self.device = self._get_device()
 
     def _get_device(self) -> str:
@@ -81,7 +80,7 @@ class PyTorchQwenLLMBackend:
     def _is_model_cached(self, model_size: str) -> bool:
         return is_model_cached(self._get_model_path(model_size))
 
-    async def load_model(self, model_size: Optional[str] = None) -> None:
+    async def load_model(self, model_size: str | None = None) -> None:
         if model_size is None:
             model_size = self.model_size
 
@@ -131,11 +130,11 @@ class PyTorchQwenLLMBackend:
     async def generate(
         self,
         prompt: str,
-        system: Optional[str] = None,
+        system: str | None = None,
         max_tokens: int = DEFAULT_LLM_MAX_TOKENS,
         temperature: float = DEFAULT_LLM_TEMPERATURE,
-        model_size: Optional[str] = None,
-        examples: Optional[list[tuple[str, str]]] = None,
+        model_size: str | None = None,
+        examples: list[tuple[str, str]] | None = None,
     ) -> str:
         await self.load_model(model_size)
         return await asyncio.to_thread(
@@ -145,10 +144,10 @@ class PyTorchQwenLLMBackend:
     def _generate_sync(
         self,
         prompt: str,
-        system: Optional[str],
+        system: str | None,
         max_tokens: int,
         temperature: float,
-        examples: Optional[list[tuple[str, str]]] = None,
+        examples: list[tuple[str, str]] | None = None,
     ) -> str:
         import torch
 
@@ -186,7 +185,7 @@ class MLXQwenLLMBackend:
         self.model = None
         self.tokenizer = None
         self.model_size = model_size
-        self._current_model_size: Optional[str] = None
+        self._current_model_size: str | None = None
 
     def is_loaded(self) -> bool:
         return self.model is not None
@@ -202,7 +201,11 @@ class MLXQwenLLMBackend:
             weight_extensions=(".safetensors", ".bin", ".npz"),
         )
 
-    async def load_model(self, model_size: Optional[str] = None) -> None:
+    def _ensure_loaded_sync(self, model_size: str | None) -> None:
+        """Load the model if the requested size isn't already resident.
+
+        Runs on the MLX worker thread so it stays serialized with generation.
+        """
         if model_size is None:
             model_size = self.model_size
 
@@ -212,7 +215,14 @@ class MLXQwenLLMBackend:
         if self.model is not None and self._current_model_size != model_size:
             self.unload_model()
 
-        await asyncio.to_thread(self._load_model_sync, model_size)
+        self._load_model_sync(model_size)
+
+    async def load_model(self, model_size: str | None = None) -> None:
+        await run_on_mlx_thread(self._ensure_loaded_sync, model_size)
+
+    async def unload(self) -> None:
+        """Free the model, serialized onto the MLX worker thread."""
+        await run_on_mlx_thread(self.unload_model)
 
     def _load_model_sync(self, model_size: str) -> None:
         from mlx_lm import load as mlx_load
@@ -243,29 +253,33 @@ class MLXQwenLLMBackend:
         self.model = None
         self.tokenizer = None
         self._current_model_size = None
+        clear_mlx_cache()
         logger.info("Qwen3 (MLX) unloaded")
 
     async def generate(
         self,
         prompt: str,
-        system: Optional[str] = None,
+        system: str | None = None,
         max_tokens: int = DEFAULT_LLM_MAX_TOKENS,
         temperature: float = DEFAULT_LLM_TEMPERATURE,
-        model_size: Optional[str] = None,
-        examples: Optional[list[tuple[str, str]]] = None,
+        model_size: str | None = None,
+        examples: list[tuple[str, str]] | None = None,
     ) -> str:
-        await self.load_model(model_size)
-        return await asyncio.to_thread(
-            self._generate_sync, prompt, system, max_tokens, temperature, examples
-        )
+        # Load-if-needed and inference run as one job on the MLX worker so a
+        # concurrent unload or different-size load can't land between them.
+        def _load_and_generate() -> str:
+            self._ensure_loaded_sync(model_size)
+            return self._generate_sync(prompt, system, max_tokens, temperature, examples)
+
+        return await run_on_mlx_thread(_load_and_generate)
 
     def _generate_sync(
         self,
         prompt: str,
-        system: Optional[str],
+        system: str | None,
         max_tokens: int,
         temperature: float,
-        examples: Optional[list[tuple[str, str]]] = None,
+        examples: list[tuple[str, str]] | None = None,
     ) -> str:
         from mlx_lm import generate as mlx_generate
         from mlx_lm.sample_utils import make_sampler

backend/config.py

@@ -138,3 +138,17 @@ def get_models_dir() -> Path:
     path = _data_dir / "models"
     path.mkdir(parents=True, exist_ok=True)
     return path
+
+
+# Voicebox Cloud (backup & sync). Two hosts: the web app owns auth + device
+# pairing (voicebox.sh), the API owns sync + account endpoints
+# (api.voicebox.sh). Override both for local development, e.g.
+# VOICEBOX_CLOUD_URL=http://localhost:17592 VOICEBOX_CLOUD_API_URL=http://localhost:17593
+def get_cloud_web_url() -> str:
+    """Base URL of the Voicebox Cloud web app (auth + /connect + exchange)."""
+    return os.environ.get("VOICEBOX_CLOUD_URL", "https://voicebox.sh").rstrip("/")
+
+
+def get_cloud_api_url() -> str:
+    """Base URL of the Voicebox Cloud API (bearer-authenticated sync/account)."""
+    return os.environ.get("VOICEBOX_CLOUD_API_URL", "https://api.voicebox.sh").rstrip("/")

backend/database/__init__.py

@@ -6,11 +6,12 @@ without changing any importers.
 """
 
 from .models import (
-    Base,
     AudioChannel,
+    Base,
     Capture,
     CaptureSettings,
     ChannelDeviceMapping,
+    CloudSettings,
     EffectPreset,
     Generation,
     GenerationSettings,
@@ -23,15 +24,16 @@ from .models import (
     StoryItem,
     VoiceProfile,
 )
-from .session import engine, SessionLocal, _db_path, init_db, get_db
+from .session import SessionLocal, _db_path, engine, get_db, init_db
 
 __all__ = [
+    "AudioChannel",
     # Models
     "Base",
-    "AudioChannel",
     "Capture",
     "CaptureSettings",
     "ChannelDeviceMapping",
+    "CloudSettings",
     "EffectPreset",
     "Generation",
     "GenerationSettings",
@@ -40,13 +42,13 @@ __all__ = [
     "ProfileChannelMapping",
     "ProfileSample",
     "Project",
+    "SessionLocal",
     "Story",
     "StoryItem",
     "VoiceProfile",
+    "_db_path",
     # Session
     "engine",
-    "SessionLocal",
-    "_db_path",
-    "init_db",
     "get_db",
+    "init_db",
 ]

backend/database/migrations.py

@@ -243,6 +243,13 @@ def _migrate_capture_settings(engine, inspector, tables: set[str]) -> None:
             "hotkey_enabled BOOLEAN NOT NULL DEFAULT 0",
             "hotkey_enabled",
         )
+    if "keep_mic_warm" not in columns:
+        _add_column(
+            engine,
+            "capture_settings",
+            "keep_mic_warm BOOLEAN NOT NULL DEFAULT 0",
+            "keep_mic_warm",
+        )
 
 
 def _migrate_mcp_bindings(engine, inspector, tables: set[str]) -> None:
@@ -296,7 +303,7 @@ def _normalize_storage_paths(engine, tables: set[str]) -> None:
     """Normalize stored file paths to be relative to the configured data dir."""
     from pathlib import Path
 
-    from ..config import get_data_dir, to_storage_path, resolve_storage_path
+    from ..config import get_data_dir, resolve_storage_path, to_storage_path
 
     data_dir = get_data_dir()
 

backend/database/models.py

@@ -1,9 +1,9 @@
 """ORM model definitions for the voicebox SQLite database."""
 
-from datetime import datetime
 import uuid
+from datetime import datetime
 
-from sqlalchemy import Column, String, Integer, Float, DateTime, Text, ForeignKey, Boolean, JSON
+from sqlalchemy import JSON, Boolean, Column, DateTime, Float, ForeignKey, Integer, String, Text
 from sqlalchemy.ext.declarative import declarative_base
 
 from ..utils.capture_chords import (
@@ -210,6 +210,10 @@ class CaptureSettings(Base):
     # "Voicebox would like to receive keystrokes from any application" dialog
     # before they've even opened the Captures tab.
     hotkey_enabled = Column(Boolean, nullable=False, default=False)
+    # Hold the microphone open while dictation is enabled so push-to-talk
+    # doesn't clip the first words. Off by default — when on, the OS mic-in-use
+    # indicator stays lit the whole time dictation is enabled.
+    keep_mic_warm = Column(Boolean, nullable=False, default=False)
     # Lists of keytap key names (e.g. "MetaRight", "ControlRight"). Right-hand
     # modifiers by default so they don't collide with left-hand shortcuts.
     chord_push_to_talk_keys = Column(
@@ -234,6 +238,28 @@ class GenerationSettings(Base):
     updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
 
 
+class CloudSettings(Base):
+    """Singleton row holding the link to a Voicebox Cloud account.
+
+    Populated by the "Log in with browser" pairing flow (see services/cloud.py):
+    the browser hands back a one-time code, which the backend exchanges for an
+    ``api_key`` it stores here. The key is a bearer credential for
+    api.voicebox.sh — auth only, never an encryption key (E2E key material lives
+    elsewhere). Stored in the local app database alongside the user's other data;
+    moving it to the OS keychain is a future hardening step. The ``id`` is
+    always 1; a null ``api_key`` means "not connected".
+    """
+
+    __tablename__ = "cloud_settings"
+
+    id = Column(Integer, primary_key=True, default=1)
+    api_key = Column(String, nullable=True)
+    device_name = Column(String, nullable=True)
+    account_user_id = Column(String, nullable=True)
+    connected_at = Column(DateTime, nullable=True)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+
 class MCPClientBinding(Base):
     """Per-MCP-client settings (voice profile, engine, personality default).
 

backend/database/session.py

@@ -3,20 +3,20 @@
 import logging
 import uuid
 
-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, event
 from sqlalchemy.orm import sessionmaker
 
 from .. import config
+from .migrations import run_migrations
 from .models import (
-    Base,
     AudioChannel,
+    Base,
     EffectPreset,
     Generation,
     GenerationVersion,
     ProfileChannelMapping,
     VoiceProfile,
 )
-from .migrations import run_migrations
 from .seed import backfill_generation_versions, seed_builtin_presets
 
 logger = logging.getLogger(__name__)
@@ -36,9 +36,22 @@ def init_db() -> None:
 
     engine = create_engine(
         f"sqlite:///{_db_path}",
-        connect_args={"check_same_thread": False},
+        # timeout is sqlite3's busy handler: wait up to 30s on a locked
+        # database instead of raising "database is locked" immediately.
+        connect_args={"check_same_thread": False, "timeout": 30},
     )
 
+    @event.listens_for(engine, "connect")
+    def _set_sqlite_pragmas(dbapi_connection, _connection_record):
+        # WAL lets readers proceed while a writer holds the lock, which is
+        # the main source of lock racing between the generation worker and
+        # request handlers. synchronous=NORMAL is the recommended pairing
+        # (durable across app crashes, fsyncs only on checkpoint).
+        cursor = dbapi_connection.cursor()
+        cursor.execute("PRAGMA journal_mode=WAL")
+        cursor.execute("PRAGMA synchronous=NORMAL")
+        cursor.close()
+
     SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 
     run_migrations(engine)
@@ -47,7 +60,7 @@ def init_db() -> None:
     # Create default audio channel if it doesn't exist
     db = SessionLocal()
     try:
-        default_channel = db.query(AudioChannel).filter(AudioChannel.is_default == True).first()
+        default_channel = db.query(AudioChannel).filter(AudioChannel.is_default).first()
         if not default_channel:
             default_channel = AudioChannel(
                 id=str(uuid.uuid4()),

backend/main.py

@@ -5,10 +5,11 @@ entry point for development.
 """
 
 import argparse
+
 import uvicorn
 
-from .app import app  # noqa: F401 -- re-export for uvicorn "backend.main:app"
 from . import config, database
+from .app import app  # noqa: F401 -- re-export for uvicorn "backend.main:app"
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="voicebox backend server")

backend/mcp_server/context.py

@@ -11,14 +11,13 @@ import asyncio
 import ipaddress
 import logging
 from contextvars import ContextVar
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.requests import Request
 from starlette.responses import Response
 from starlette.types import ASGIApp
 
-
 logger = logging.getLogger(__name__)
 
 # Strong refs to in-flight stamp tasks so asyncio.create_task results
@@ -141,7 +140,7 @@ def _stamp_last_seen(client_id: str) -> None:
         if row is None:
             row = MCPClientBinding(client_id=client_id)
             db.add(row)
-        row.last_seen_at = datetime.now(timezone.utc)
+        row.last_seen_at = datetime.now(UTC)
         db.commit()
     except Exception:
         logger.debug(

backend/mcp_server/events.py

@@ -8,7 +8,6 @@ floating pill surfaces whenever an agent is speaking.
 import asyncio
 from typing import Any
 
-
 # Each subscriber gets its own queue. Bounded to drop oldest if a client lags.
 _subscribers: set[asyncio.Queue[dict[str, Any]]] = set()
 

backend/mcp_server/resolve.py

@@ -30,7 +30,7 @@ def resolve_profile(
     if client_id:
         # Per-client binding. Imported lazily so this module stays importable
         # even before the migration adds the table on first boot.
-        from ..database.models import MCPClientBinding  # noqa: WPS433
+        from ..database.models import MCPClientBinding
 
         binding = (
             db.query(MCPClientBinding)

backend/mcp_server/server.py

@@ -9,8 +9,8 @@ binary bundled with the desktop app.
 from __future__ import annotations
 
 import logging
-from contextlib import AsyncExitStack, asynccontextmanager
 from collections.abc import Callable
+from contextlib import AsyncExitStack, asynccontextmanager
 
 from fastapi import FastAPI
 from fastmcp import FastMCP
@@ -18,7 +18,6 @@ from fastmcp import FastMCP
 from .context import ClientIdMiddleware
 from .tools import register_tools
 
-
 logger = logging.getLogger(__name__)
 
 

backend/mcp_server/tools.py

@@ -12,19 +12,17 @@ import base64 as b64
 import logging
 import tempfile
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from fastmcp import FastMCP
 
 from .. import models
 from ..database import get_db
-from ..services import captures as captures_service
-from ..services import profiles as profiles_service
+from ..services import captures as captures_service, profiles as profiles_service
 from . import events as mcp_events
 from .context import current_client_id, request_is_loopback
 from .resolve import resolve_profile
 
-
 logger = logging.getLogger(__name__)
 
 # Absolute-path transcribes are bounded to keep a bad client from
@@ -49,6 +47,7 @@ def register_tools(mcp: FastMCP) -> None:
         engine: str | None = None,
         personality: bool | None = None,
         language: str | None = None,
+        model_size: Literal["1.7B", "0.6B", "1B", "3B"] | None = None,
     ) -> dict[str, Any]:
         """Speak ``text`` in a voice profile.
 
@@ -61,6 +60,12 @@ def register_tools(mcp: FastMCP) -> None:
         LLM before TTS. When omitted, the per-client binding's
         ``default_personality`` flag decides; when that is unset, the
         default is plain TTS.
+
+        ``model_size`` selects a model variant for engines that ship more
+        than one — ``qwen`` and ``qwen_custom_voice`` accept "1.7B" (default)
+        or "0.6B"; ``tada`` accepts "1B" or "3B". Other engines ignore it.
+        Omit to use the engine default. Requesting a smaller variant (e.g.
+        "0.6B") is faster and avoids reloading a heavier model between calls.
         """
         from ..database.models import MCPClientBinding
 
@@ -99,6 +104,7 @@ def register_tools(mcp: FastMCP) -> None:
                 engine=resolved_engine,
                 language=language,
                 personality=use_persona,
+                model_size=model_size,
                 db=db,
             )
         finally:
@@ -228,18 +234,23 @@ async def _speak(
     engine: str | None,
     language: str | None,
     personality: bool,
+    model_size: str | None = None,
     db,
 ) -> dict[str, Any]:
     """Delegate to POST /generate — the route handles personality-rewrite
     internally when ``personality=true`` and the profile has a prompt."""
     from ..routes.generations import generate_speech
 
+    # model_size=None is intentional: generate_speech normalizes it to the
+    # engine default (see routes/generations.py), so an omitted size behaves
+    # exactly like the REST /generate endpoint with no model_size in the body.
     req = models.GenerationRequest(
         profile_id=profile_id,
         text=text,
         language=language or "en",
         engine=engine,
         personality=personality,
+        model_size=model_size,
     )
     generation = await generate_speech(req, db)
     return _speak_response(generation, profile_name, source="mcp")

backend/mcp_shim/__main__.py

@@ -23,7 +23,6 @@ from typing import Any
 
 import httpx
 
-
 CLIENT_ID_HEADER = "X-Voicebox-Client-Id"
 SESSION_HEADER = "mcp-session-id"
 HEALTH_TIMEOUT_S = 30.0

backend/models.py

@@ -2,10 +2,10 @@
 Pydantic models for request/response validation.
 """
 
-from pydantic import BaseModel, Field
-from typing import Optional, List
 from datetime import datetime
 
+from pydantic import BaseModel, Field
+
 from .utils.capture_chords import (
     default_push_to_talk_chord,
     default_toggle_to_talk_chord,
@@ -16,16 +16,16 @@ class VoiceProfileCreate(BaseModel):
     """Request model for creating a voice profile."""
 
     name: str = Field(..., min_length=1, max_length=100)
-    description: Optional[str] = Field(None, max_length=500)
+    description: str | None = Field(None, max_length=500)
     language: str = Field(
         default="en", pattern="^(zh|en|ja|ko|de|fr|ru|pt|es|it|he|ar|da|el|fi|hi|ms|nl|no|pl|sv|sw|tr)$"
     )
-    voice_type: Optional[str] = Field(default="cloned", pattern="^(cloned|preset|designed)$")
-    preset_engine: Optional[str] = Field(None, max_length=50)
-    preset_voice_id: Optional[str] = Field(None, max_length=100)
-    design_prompt: Optional[str] = Field(None, max_length=2000)
-    default_engine: Optional[str] = Field(None, max_length=50)
-    personality: Optional[str] = Field(None, max_length=2000)
+    voice_type: str | None = Field(default="cloned", pattern="^(cloned|preset|designed)$")
+    preset_engine: str | None = Field(None, max_length=50)
+    preset_voice_id: str | None = Field(None, max_length=100)
+    design_prompt: str | None = Field(None, max_length=2000)
+    default_engine: str | None = Field(None, max_length=50)
+    personality: str | None = Field(None, max_length=2000)
 
 
 class VoiceProfileResponse(BaseModel):
@@ -33,16 +33,16 @@ class VoiceProfileResponse(BaseModel):
 
     id: str
     name: str
-    description: Optional[str]
+    description: str | None
     language: str
-    avatar_path: Optional[str] = None
-    effects_chain: Optional[List["EffectConfig"]] = None
+    avatar_path: str | None = None
+    effects_chain: list["EffectConfig"] | None = None
     voice_type: str = "cloned"
-    preset_engine: Optional[str] = None
-    preset_voice_id: Optional[str] = None
-    design_prompt: Optional[str] = None
-    default_engine: Optional[str] = None
-    personality: Optional[str] = None
+    preset_engine: str | None = None
+    preset_voice_id: str | None = None
+    design_prompt: str | None = None
+    default_engine: str | None = None
+    personality: str | None = None
     generation_count: int = 0
     sample_count: int = 0
     created_at: datetime
@@ -82,10 +82,10 @@ class GenerationRequest(BaseModel):
     profile_id: str
     text: str = Field(..., min_length=1, max_length=50000)
     language: str = Field(default="en", pattern="^(zh|en|ja|ko|de|fr|ru|pt|es|it|he|ar|da|el|fi|hi|ms|nl|no|pl|sv|sw|tr)$")
-    seed: Optional[int] = Field(None, ge=0)
-    model_size: Optional[str] = Field(default="1.7B", pattern="^(1\\.7B|0\\.6B|1B|3B)$")
-    instruct: Optional[str] = Field(None, max_length=500)
-    engine: Optional[str] = Field(default="qwen", pattern="^(qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro)$")
+    seed: int | None = Field(None, ge=0)
+    model_size: str | None = Field(default="1.7B", pattern="^(1\\.7B|0\\.6B|1B|3B)$")
+    instruct: str | None = Field(None, max_length=500)
+    engine: str | None = Field(default="qwen", pattern="^(qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro)$")
     personality: bool = Field(
         default=False,
         description="When true and the profile has a personality prompt, the input text is rewritten in-character before TTS.",
@@ -97,7 +97,7 @@ class GenerationRequest(BaseModel):
         default=50, ge=0, le=500, description="Crossfade duration in ms between chunks (0 for hard cut)"
     )
     normalize: bool = Field(default=True, description="Normalize output audio volume")
-    effects_chain: Optional[List["EffectConfig"]] = Field(
+    effects_chain: list["EffectConfig"] | None = Field(
         None, description="Effects chain to apply after generation (overrides profile default)"
     )
 
@@ -109,19 +109,19 @@ class GenerationResponse(BaseModel):
     profile_id: str
     text: str
     language: str
-    audio_path: Optional[str] = None
-    duration: Optional[float] = None
-    seed: Optional[int] = None
-    instruct: Optional[str] = None
-    engine: Optional[str] = "qwen"
-    model_size: Optional[str] = None
+    audio_path: str | None = None
+    duration: float | None = None
+    seed: int | None = None
+    instruct: str | None = None
+    engine: str | None = "qwen"
+    model_size: str | None = None
     status: str = "completed"
-    error: Optional[str] = None
+    error: str | None = None
     is_favorited: bool = False
     source: str = "manual"
     created_at: datetime
-    versions: Optional[List["GenerationVersionResponse"]] = None
-    active_version_id: Optional[str] = None
+    versions: list["GenerationVersionResponse"] | None = None
+    active_version_id: str | None = None
 
     class Config:
         from_attributes = True
@@ -130,8 +130,8 @@ class GenerationResponse(BaseModel):
 class HistoryQuery(BaseModel):
     """Query model for generation history."""
 
-    profile_id: Optional[str] = None
-    search: Optional[str] = None
+    profile_id: str | None = None
+    search: str | None = None
     limit: int = Field(default=50, ge=1, le=100)
     offset: int = Field(default=0, ge=0)
 
@@ -144,18 +144,18 @@ class HistoryResponse(BaseModel):
     profile_name: str
     text: str
     language: str
-    audio_path: Optional[str] = None
-    duration: Optional[float] = None
-    seed: Optional[int] = None
-    instruct: Optional[str] = None
-    engine: Optional[str] = "qwen"
-    model_size: Optional[str] = None
+    audio_path: str | None = None
+    duration: float | None = None
+    seed: int | None = None
+    instruct: str | None = None
+    engine: str | None = "qwen"
+    model_size: str | None = None
     status: str = "completed"
-    error: Optional[str] = None
+    error: str | None = None
     is_favorited: bool = False
     created_at: datetime
-    versions: Optional[List["GenerationVersionResponse"]] = None
-    active_version_id: Optional[str] = None
+    versions: list["GenerationVersionResponse"] | None = None
+    active_version_id: str | None = None
 
     class Config:
         from_attributes = True
@@ -164,15 +164,15 @@ class HistoryResponse(BaseModel):
 class HistoryListResponse(BaseModel):
     """Response model for history list."""
 
-    items: List[HistoryResponse]
+    items: list[HistoryResponse]
     total: int
 
 
 class TranscriptionRequest(BaseModel):
     """Request model for audio transcription."""
 
-    language: Optional[str] = Field(None, pattern="^(en|zh|ja|ko|de|fr|ru|pt|es|it)$")
-    model: Optional[str] = Field(None, pattern="^(base|small|medium|large|turbo)$")
+    language: str | None = Field(None, pattern="^(en|zh|ja|ko|de|fr|ru|pt|es|it)$")
+    model: str | None = Field(None, pattern="^(base|small|medium|large|turbo)$")
 
 
 class TranscriptionResponse(BaseModel):
@@ -196,13 +196,13 @@ class CaptureResponse(BaseModel):
     id: str
     audio_path: str
     source: str
-    language: Optional[str] = None
-    duration_ms: Optional[int] = None
+    language: str | None = None
+    duration_ms: int | None = None
     transcript_raw: str
-    transcript_refined: Optional[str] = None
-    stt_model: Optional[str] = None
-    llm_model: Optional[str] = None
-    refinement_flags: Optional[RefinementFlagsModel] = None
+    transcript_refined: str | None = None
+    stt_model: str | None = None
+    llm_model: str | None = None
+    refinement_flags: RefinementFlagsModel | None = None
     created_at: datetime
 
     class Config:
@@ -212,7 +212,7 @@ class CaptureResponse(BaseModel):
 class CaptureListResponse(BaseModel):
     """Response model for paginated capture list."""
 
-    items: List[CaptureResponse]
+    items: list[CaptureResponse]
     total: int
 
 
@@ -234,15 +234,15 @@ class CaptureCreateResponse(CaptureResponse):
 class CaptureRefineRequest(BaseModel):
     """Request to refine a capture's transcript via the LLM."""
 
-    flags: Optional[RefinementFlagsModel] = None
-    model_size: Optional[str] = Field(default=None, pattern="^(0\\.6B|1\\.7B|4B)$")
+    flags: RefinementFlagsModel | None = None
+    model_size: str | None = Field(default=None, pattern="^(0\\.6B|1\\.7B|4B)$")
 
 
 class CaptureRetranscribeRequest(BaseModel):
     """Request to re-run STT on a capture's audio with a different model."""
 
-    model: Optional[str] = Field(None, pattern="^(base|small|medium|large|turbo)$")
-    language: Optional[str] = Field(None, pattern="^(en|zh|ja|ko|de|fr|ru|pt|es|it)$")
+    model: str | None = Field(None, pattern="^(base|small|medium|large|turbo)$")
+    language: str | None = Field(None, pattern="^(en|zh|ja|ko|de|fr|ru|pt|es|it)$")
 
 
 class CaptureSettingsResponse(BaseModel):
@@ -256,12 +256,13 @@ class CaptureSettingsResponse(BaseModel):
     self_correction: bool = True
     preserve_technical: bool = True
     allow_auto_paste: bool = True
-    default_playback_voice_id: Optional[str] = None
+    default_playback_voice_id: str | None = None
     hotkey_enabled: bool = False
-    chord_push_to_talk_keys: List[str] = Field(
+    keep_mic_warm: bool = False
+    chord_push_to_talk_keys: list[str] = Field(
         default_factory=default_push_to_talk_chord
     )
-    chord_toggle_to_talk_keys: List[str] = Field(
+    chord_toggle_to_talk_keys: list[str] = Field(
         default_factory=default_toggle_to_talk_chord
     )
 
@@ -272,18 +273,19 @@ class CaptureSettingsResponse(BaseModel):
 class CaptureSettingsUpdate(BaseModel):
     """Partial update for capture settings — every field is optional."""
 
-    stt_model: Optional[str] = Field(default=None, pattern="^(base|small|medium|large|turbo)$")
-    language: Optional[str] = None
-    auto_refine: Optional[bool] = None
-    llm_model: Optional[str] = Field(default=None, pattern="^(0\\.6B|1\\.7B|4B)$")
-    smart_cleanup: Optional[bool] = None
-    self_correction: Optional[bool] = None
-    preserve_technical: Optional[bool] = None
-    allow_auto_paste: Optional[bool] = None
-    default_playback_voice_id: Optional[str] = None
-    hotkey_enabled: Optional[bool] = None
-    chord_push_to_talk_keys: Optional[List[str]] = Field(default=None, min_length=1, max_length=6)
-    chord_toggle_to_talk_keys: Optional[List[str]] = Field(default=None, min_length=1, max_length=6)
+    stt_model: str | None = Field(default=None, pattern="^(base|small|medium|large|turbo)$")
+    language: str | None = None
+    auto_refine: bool | None = None
+    llm_model: str | None = Field(default=None, pattern="^(0\\.6B|1\\.7B|4B)$")
+    smart_cleanup: bool | None = None
+    self_correction: bool | None = None
+    preserve_technical: bool | None = None
+    allow_auto_paste: bool | None = None
+    default_playback_voice_id: str | None = None
+    hotkey_enabled: bool | None = None
+    keep_mic_warm: bool | None = None
+    chord_push_to_talk_keys: list[str] | None = Field(default=None, min_length=1, max_length=6)
+    chord_toggle_to_talk_keys: list[str] | None = Field(default=None, min_length=1, max_length=6)
 
 
 class GenerationSettingsResponse(BaseModel):
@@ -301,10 +303,10 @@ class GenerationSettingsResponse(BaseModel):
 class GenerationSettingsUpdate(BaseModel):
     """Partial update for generation settings — every field is optional."""
 
-    max_chunk_chars: Optional[int] = Field(default=None, ge=100, le=5000)
-    crossfade_ms: Optional[int] = Field(default=None, ge=0, le=500)
-    normalize_audio: Optional[bool] = None
-    autoplay_on_generate: Optional[bool] = None
+    max_chunk_chars: int | None = Field(default=None, ge=100, le=5000)
+    crossfade_ms: int | None = Field(default=None, ge=0, le=500)
+    normalize_audio: bool | None = None
+    autoplay_on_generate: bool | None = None
 
 
 class MCPClientBindingResponse(BaseModel):
@@ -313,14 +315,14 @@ class MCPClientBindingResponse(BaseModel):
     opt-in personality-rewrite default."""
 
     client_id: str
-    label: Optional[str] = None
-    profile_id: Optional[str] = None
-    default_engine: Optional[str] = Field(
+    label: str | None = None
+    profile_id: str | None = None
+    default_engine: str | None = Field(
         None,
         pattern="^(qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro)$",
     )
     default_personality: bool = False
-    last_seen_at: Optional[datetime] = None
+    last_seen_at: datetime | None = None
     created_at: datetime
     updated_at: datetime
 
@@ -332,9 +334,9 @@ class MCPClientBindingUpsert(BaseModel):
     """Create or update a binding. Matched by ``client_id``."""
 
     client_id: str = Field(..., min_length=1, max_length=64)
-    label: Optional[str] = Field(None, max_length=128)
-    profile_id: Optional[str] = None
-    default_engine: Optional[str] = Field(
+    label: str | None = Field(None, max_length=128)
+    profile_id: str | None = None
+    default_engine: str | None = Field(
         None,
         pattern="^(qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro)$",
     )
@@ -342,26 +344,26 @@ class MCPClientBindingUpsert(BaseModel):
 
 
 class MCPClientBindingListResponse(BaseModel):
-    items: List[MCPClientBindingResponse]
+    items: list[MCPClientBindingResponse]
 
 
 class SpeakRequest(BaseModel):
     """Body for POST /speak — non-MCP REST surface that mirrors voicebox.speak."""
 
     text: str = Field(..., min_length=1, max_length=10000)
-    profile: Optional[str] = Field(
+    profile: str | None = Field(
         None,
         description="Voice profile name or id. Falls back to per-client binding, then default.",
     )
-    engine: Optional[str] = Field(
+    engine: str | None = Field(
         None,
         pattern="^(qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro)$",
     )
-    personality: Optional[bool] = Field(
+    personality: bool | None = Field(
         None,
         description="When true and the profile has a personality prompt, the input text is rewritten in-character before TTS. When null, the per-client binding's default_personality flag decides.",
     )
-    language: Optional[str] = Field(
+    language: str | None = Field(
         None,
         pattern="^(zh|en|ja|ko|de|fr|ru|pt|es|it|he|ar|da|el|fi|hi|ms|nl|no|pl|sv|sw|tr)$",
     )
@@ -371,15 +373,15 @@ class LLMGenerateRequest(BaseModel):
     """Request model for LLM text generation."""
 
     prompt: str = Field(..., min_length=1, max_length=50000)
-    system: Optional[str] = Field(None, max_length=4000)
-    model_size: Optional[str] = Field(default="0.6B", pattern="^(0\\.6B|1\\.7B|4B)$")
+    system: str | None = Field(None, max_length=4000)
+    model_size: str | None = Field(default="0.6B", pattern="^(0\\.6B|1\\.7B|4B)$")
     max_tokens: int = Field(default=512, ge=1, le=4096)
     temperature: float = Field(default=0.7, ge=0.0, le=2.0)
     # Few-shot (user, assistant) pairs prepended as real chat turns.
     # Used by the refinement service to pin tricky rules (imperatives
     # staying imperatives, technical-term punctuation) that small models
     # lose when the examples live inline in the system prompt.
-    examples: Optional[List[List[str]]] = Field(default=None, max_length=8)
+    examples: list[list[str]] | None = Field(default=None, max_length=8)
 
 
 class LLMGenerateResponse(BaseModel):
@@ -416,7 +418,7 @@ class ModelReadiness(BaseModel):
     model_name: str
     display_name: str
     size: str
-    size_mb: Optional[int] = None
+    size_mb: int | None = None
 
 
 class CaptureReadinessResponse(BaseModel):
@@ -436,15 +438,15 @@ class HealthResponse(BaseModel):
 
     status: str
     model_loaded: bool
-    model_downloaded: Optional[bool] = None  # Whether model is cached/downloaded
-    model_size: Optional[str] = None  # Current model size if loaded
+    model_downloaded: bool | None = None  # Whether model is cached/downloaded
+    model_size: str | None = None  # Current model size if loaded
     gpu_available: bool
-    gpu_type: Optional[str] = None  # GPU type (CUDA, MPS, or None)
-    vram_used_mb: Optional[float] = None
-    backend_type: Optional[str] = None  # Backend type (mlx or pytorch)
-    backend_variant: Optional[str] = None  # Binary variant (cpu, cuda, or rocm)
+    gpu_type: str | None = None  # GPU type (CUDA, MPS, or None)
+    vram_used_mb: float | None = None
+    backend_type: str | None = None  # Backend type (mlx or pytorch)
+    backend_variant: str | None = None  # Binary variant (cpu, cuda, or rocm)
     supports_rocm: bool = False  # AMD GPU on Windows — the ROCm backend is applicable
-    gpu_compatibility_warning: Optional[str] = None  # Warning if GPU arch unsupported
+    gpu_compatibility_warning: str | None = None  # Warning if GPU arch unsupported
 
 
 class DirectoryCheck(BaseModel):
@@ -453,16 +455,16 @@ class DirectoryCheck(BaseModel):
     path: str
     exists: bool
     writable: bool
-    error: Optional[str] = None
+    error: str | None = None
 
 
 class FilesystemHealthResponse(BaseModel):
     """Response model for filesystem health check."""
 
     healthy: bool
-    disk_free_mb: Optional[float] = None
-    disk_total_mb: Optional[float] = None
-    directories: List[DirectoryCheck]
+    disk_free_mb: float | None = None
+    disk_total_mb: float | None = None
+    directories: list[DirectoryCheck]
 
 
 class ModelStatus(BaseModel):
@@ -470,17 +472,17 @@ class ModelStatus(BaseModel):
 
     model_name: str
     display_name: str
-    hf_repo_id: Optional[str] = None  # HuggingFace repository ID
+    hf_repo_id: str | None = None  # HuggingFace repository ID
     downloaded: bool
     downloading: bool = False  # True if download is in progress
-    size_mb: Optional[float] = None
+    size_mb: float | None = None
     loaded: bool = False
 
 
 class ModelStatusListResponse(BaseModel):
     """Response model for model status list."""
 
-    models: List[ModelStatus]
+    models: list[ModelStatus]
 
 
 class ModelDownloadRequest(BaseModel):
@@ -501,11 +503,11 @@ class ActiveDownloadTask(BaseModel):
     model_name: str
     status: str
     started_at: datetime
-    error: Optional[str] = None
-    progress: Optional[float] = None  # 0-100 percentage
-    current: Optional[int] = None  # bytes downloaded
-    total: Optional[int] = None  # total bytes
-    filename: Optional[str] = None  # current file being downloaded
+    error: str | None = None
+    progress: float | None = None  # 0-100 percentage
+    current: int | None = None  # bytes downloaded
+    total: int | None = None  # total bytes
+    filename: str | None = None  # current file being downloaded
 
 
 class ActiveGenerationTask(BaseModel):
@@ -520,22 +522,22 @@ class ActiveGenerationTask(BaseModel):
 class ActiveTasksResponse(BaseModel):
     """Response model for active tasks."""
 
-    downloads: List[ActiveDownloadTask]
-    generations: List[ActiveGenerationTask]
+    downloads: list[ActiveDownloadTask]
+    generations: list[ActiveGenerationTask]
 
 
 class AudioChannelCreate(BaseModel):
     """Request model for creating an audio channel."""
 
     name: str = Field(..., min_length=1, max_length=100)
-    device_ids: List[str] = Field(default_factory=list)
+    device_ids: list[str] = Field(default_factory=list)
 
 
 class AudioChannelUpdate(BaseModel):
     """Request model for updating an audio channel."""
 
-    name: Optional[str] = Field(None, min_length=1, max_length=100)
-    device_ids: Optional[List[str]] = None
+    name: str | None = Field(None, min_length=1, max_length=100)
+    device_ids: list[str] | None = None
 
 
 class AudioChannelResponse(BaseModel):
@@ -544,7 +546,7 @@ class AudioChannelResponse(BaseModel):
     id: str
     name: str
     is_default: bool
-    device_ids: List[str]
+    device_ids: list[str]
     created_at: datetime
 
     class Config:
@@ -554,20 +556,20 @@ class AudioChannelResponse(BaseModel):
 class ChannelVoiceAssignment(BaseModel):
     """Request model for assigning voices to a channel."""
 
-    profile_ids: List[str]
+    profile_ids: list[str]
 
 
 class ProfileChannelAssignment(BaseModel):
     """Request model for assigning channels to a profile."""
 
-    channel_ids: List[str]
+    channel_ids: list[str]
 
 
 class StoryCreate(BaseModel):
     """Request model for creating a story."""
 
     name: str = Field(..., min_length=1, max_length=100)
-    description: Optional[str] = Field(None, max_length=500)
+    description: str | None = Field(None, max_length=500)
 
 
 class StoryResponse(BaseModel):
@@ -575,7 +577,7 @@ class StoryResponse(BaseModel):
 
     id: str
     name: str
-    description: Optional[str]
+    description: str | None
     created_at: datetime
     updated_at: datetime
     item_count: int = 0
@@ -590,7 +592,7 @@ class StoryItemDetail(BaseModel):
     id: str
     story_id: str
     generation_id: str
-    version_id: Optional[str] = None
+    version_id: str | None = None
     start_time_ms: int
     track: int = 0
     trim_start_ms: int = 0
@@ -603,14 +605,14 @@ class StoryItemDetail(BaseModel):
     language: str
     audio_path: str
     duration: float
-    seed: Optional[int]
-    instruct: Optional[str]
-    engine: Optional[str] = None
+    seed: int | None
+    instruct: str | None
+    engine: str | None = None
     volume: float = 1.0
     generation_created_at: datetime
     # Versions available for this generation
-    versions: Optional[List["GenerationVersionResponse"]] = None
-    active_version_id: Optional[str] = None
+    versions: list["GenerationVersionResponse"] | None = None
+    active_version_id: str | None = None
 
     class Config:
         from_attributes = True
@@ -621,10 +623,10 @@ class StoryDetailResponse(BaseModel):
 
     id: str
     name: str
-    description: Optional[str]
+    description: str | None
     created_at: datetime
     updated_at: datetime
-    items: List[StoryItemDetail] = []
+    items: list[StoryItemDetail] = []
 
     class Config:
         from_attributes = True
@@ -634,8 +636,8 @@ class StoryItemCreate(BaseModel):
     """Request model for adding a generation to a story."""
 
     generation_id: str
-    start_time_ms: Optional[int] = None  # If not provided, will be calculated automatically
-    track: Optional[int] = 0  # Track number (0 = main track)
+    start_time_ms: int | None = None  # If not provided, will be calculated automatically
+    track: int | None = 0  # Track number (0 = main track)
 
 
 class StoryItemUpdateTime(BaseModel):
@@ -648,13 +650,13 @@ class StoryItemUpdateTime(BaseModel):
 class StoryItemBatchUpdate(BaseModel):
     """Request model for batch updating story item timecodes."""
 
-    updates: List[StoryItemUpdateTime]
+    updates: list[StoryItemUpdateTime]
 
 
 class StoryItemReorder(BaseModel):
     """Request model for reordering story items."""
 
-    generation_ids: List[str] = Field(..., min_length=1)
+    generation_ids: list[str] = Field(..., min_length=1)
 
 
 class StoryItemMove(BaseModel):
@@ -680,7 +682,7 @@ class StoryItemSplit(BaseModel):
 class StoryItemVersionUpdate(BaseModel):
     """Request model for setting a story item's pinned version."""
 
-    version_id: Optional[str] = None  # null = use generation default
+    version_id: str | None = None  # null = use generation default
 
 
 class StoryItemVolumeUpdate(BaseModel):
@@ -705,23 +707,23 @@ class EffectConfig(BaseModel):
 class EffectsChain(BaseModel):
     """An ordered list of effects to apply."""
 
-    effects: List[EffectConfig] = Field(default_factory=list)
+    effects: list[EffectConfig] = Field(default_factory=list)
 
 
 class EffectPresetCreate(BaseModel):
     """Request model for creating an effect preset."""
 
     name: str = Field(..., min_length=1, max_length=100)
-    description: Optional[str] = Field(None, max_length=500)
-    effects_chain: List[EffectConfig]
+    description: str | None = Field(None, max_length=500)
+    effects_chain: list[EffectConfig]
 
 
 class EffectPresetUpdate(BaseModel):
     """Request model for updating an effect preset."""
 
-    name: Optional[str] = Field(None, min_length=1, max_length=100)
-    description: Optional[str] = None
-    effects_chain: Optional[List[EffectConfig]] = None
+    name: str | None = Field(None, min_length=1, max_length=100)
+    description: str | None = None
+    effects_chain: list[EffectConfig] | None = None
 
 
 class EffectPresetResponse(BaseModel):
@@ -729,8 +731,8 @@ class EffectPresetResponse(BaseModel):
 
     id: str
     name: str
-    description: Optional[str] = None
-    effects_chain: List[EffectConfig]
+    description: str | None = None
+    effects_chain: list[EffectConfig]
     is_builtin: bool = False
     created_at: datetime
 
@@ -745,8 +747,8 @@ class GenerationVersionResponse(BaseModel):
     generation_id: str
     label: str
     audio_path: str
-    effects_chain: Optional[List[EffectConfig]] = None
-    source_version_id: Optional[str] = None
+    effects_chain: list[EffectConfig] | None = None
+    source_version_id: str | None = None
     is_default: bool
     created_at: datetime
 
@@ -757,18 +759,18 @@ class GenerationVersionResponse(BaseModel):
 class ApplyEffectsRequest(BaseModel):
     """Request to apply effects to an existing generation."""
 
-    effects_chain: List[EffectConfig]
-    source_version_id: Optional[str] = Field(
+    effects_chain: list[EffectConfig]
+    source_version_id: str | None = Field(
         None, description="Version to use as source audio (defaults to clean/original)"
     )
-    label: Optional[str] = Field(None, max_length=100, description="Label for this version (auto-generated if omitted)")
+    label: str | None = Field(None, max_length=100, description="Label for this version (auto-generated if omitted)")
     set_as_default: bool = Field(default=True, description="Set this version as the default")
 
 
 class ProfileEffectsUpdate(BaseModel):
     """Request to update the default effects chain on a profile."""
 
-    effects_chain: Optional[List[EffectConfig]] = Field(None, description="Effects chain (null to remove)")
+    effects_chain: list[EffectConfig] | None = Field(None, description="Effects chain (null to remove)")
 
 
 class AvailableEffectParam(BaseModel):
@@ -793,4 +795,25 @@ class AvailableEffect(BaseModel):
 class AvailableEffectsResponse(BaseModel):
     """Response listing all available effect types."""
 
-    effects: List[AvailableEffect]
+    effects: list[AvailableEffect]
+
+
+# ─── Cloud (backup & sync) ──────────────────────────────────────────────
+
+
+class CloudLoginStartResponse(BaseModel):
+    """Returned when the desktop kicks off browser login. The backend has
+    already opened the browser; the URL is included for fallback/debugging."""
+
+    authorize_url: str
+
+
+class CloudStatusResponse(BaseModel):
+    """Current link between this device and a Voicebox Cloud account."""
+
+    connected: bool
+    device_name: str | None = None
+    account_user_id: str | None = None
+    key_prefix: str | None = None
+    connected_at: datetime | None = None
+    dashboard_url: str

backend/pyi_rth_numpy_compat.py

@@ -44,6 +44,7 @@ def _patch_torch_from_numpy():
             return
         try:
             import ctypes
+
             import numpy as np
 
             _orig = torch.from_numpy
@@ -53,17 +54,17 @@ def _patch_torch_from_numpy():
             # silently corrupt data (e.g. fp16 tensors from some TTS engines),
             # so we raise instead.
             dtype_map = {
-                "float16": _t.float16,
-                "float32": _t.float32,
-                "float64": _t.float64,
-                "int8": _t.int8,
-                "int16": _t.int16,
-                "int32": _t.int32,
-                "int64": _t.int64,
-                "uint8": _t.uint8,
-                "bool": _t.bool,
-                "complex64": _t.complex64,
-                "complex128": _t.complex128,
+                "float16": torch.float16,
+                "float32": torch.float32,
+                "float64": torch.float64,
+                "int8": torch.int8,
+                "int16": torch.int16,
+                "int32": torch.int32,
+                "int64": torch.int64,
+                "uint8": torch.uint8,
+                "bool": torch.bool,
+                "complex64": torch.complex64,
+                "complex128": torch.complex128,
             }
 
             def _safe_from_numpy(

backend/pyi_rth_torch_compiler_disable.py

@@ -56,7 +56,6 @@ import sys
 import tempfile
 import types
 
-
 # Diagnostics — log hook activity to a file alongside the bundle so we can
 # see what's happening when the server is run as a sidecar (no stdout for
 # runtime hook prints). Safe no-op if the file can't be written.

backend/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "voicebox-backend"
-version = "0.2.3"
+version = "0.5.0"
 requires-python = ">=3.12"
 
 # ---------------------------------------------------------------------------
@@ -49,19 +49,43 @@ ignore = [
     "SIM108", # use ternary operator (sometimes less readable)
     "B008",   # function call in default argument (FastAPI Depends() pattern)
     "UP007",  # use X | Y for union (auto-fixed by UP, but noisy on big diffs)
+
+    # Existing-violation baseline so ruff can gate CI. Remove entries from
+    # this list as the remaining occurrences are fixed; counts are as of
+    # 2026-07-26 after the auto-fix pass.
+    "B904",   # raise without `from` inside except (49) -- needs per-site from err/from None
+    "SIM105", # try/except/pass instead of contextlib.suppress (14)
+    "N806",   # non-lowercase variable in function (9)
+    "RUF002", # ambiguous unicode in docstring (6)
+    "F841",   # unused variable (5)
+    "N803",   # invalid argument name (5)
+    "B007",   # unused loop control variable (4)
+    "ERA001", # commented-out code (4)
+    "SIM102", # collapsible if (4)
+    "SIM117", # multiple with statements (4)
+    "SIM115", # open() without context manager (3)
+    "RUF001", # ambiguous unicode in string (2)
+    "RUF012", # mutable class default (2)
+    "SIM110", # reimplemented builtin (2)
+    "RUF006", # asyncio dangling task (1)
+    "RUF034", # useless if-else (1)
 ]
 
 # Per-file rule overrides.
 [tool.ruff.lint.per-file-ignores]
-# Tests can use assert, print, and magic values freely.
-"tests/**" = ["S101", "T201", "PLR2004", "ERA001"]
+# Tests can use assert, print, magic values, and script-style setup freely.
+"tests/**" = ["S101", "T201", "PLR2004", "ERA001", "E402", "PT011", "PT018", "PT019"]
 # __init__.py re-exports are expected to have unused imports.
 "**/__init__.py" = ["F401"]
 # Entry points and scripts legitimately use print.
-"server.py" = ["T201"]
 "main.py" = ["T201"]
 # AMD GPU env vars must be set before torch import.
 "app.py" = ["E402"]
+# Environment and stdout hardening must run before heavy imports.
+"server.py" = ["T201", "E402"]
+"backends/__init__.py" = ["E402"]
+"backends/mlx_backend.py" = ["E402"]
+"backends/pytorch_backend.py" = ["E402"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["backend"]
@@ -81,3 +105,7 @@ docstring-code-format = true
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+markers = [
+    "slow: long-running tests, deselect with '-m \"not slow\"'",
+    "timeout: per-test timeout in seconds (enforced only when pytest-timeout is installed)",
+]