fix(paths): strip legacy "data/" prefix when resolving stored paths

0.3.0 sometimes stored relative media paths with the data-dir name baked in (e.g. "data/profiles/<uuid>/sample.wav"). resolve_storage_path joined those directly with _data_dir, producing "<data_dir>/data/profiles/..." — a spurious double nest that breaks file reads after upgrading to 0.4.0. The 0.4.0 startup migration didn't catch it because resolve_storage_path produced the buggy double-nested path, to_storage_path saw "data" at the first (legitimate) index, and the normalized value matched the stored value so the row was skipped. Strip any leading "data/" component before joining. This unblocks runtime reads and lets _normalize_storage_paths rewrite the affected rows on next startup — no manual migration needed. Fixes "No such file or directory: '<data_dir>/data/profiles/...'" and associated 404s on GET /audio/<id> after upgrading from 0.3.0 to 0.4.0. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
docs/landing: update for 0.4.0 — new engines, GPU docs, donate button, voice docs restructure
2026-09-26 21:55:15 -07:00 · 2026-04-16 20:18:31 -07:00 · 2026-04-16 19:51:43 -07:00 · 2026-04-16 03:16:06 -07:00 · 2026-04-16 03:13:45 -07:00 · 2026-04-16 03:12:09 -07:00
106 changed files with 4549 additions and 820 deletions
@@ -0,0 +1,299 @@
+---
+name: triage-prs
+description: Use this skill to triage the open PR queue before a release. Classifies every open PR into must-merge, candidate, superseded, or deferred; writes a working triage doc; and runs the merge loop end-to-end. Designed for the pre-release "PR speedrun" pass where a solo maintainer wants to clear the inbound backlog in a single session.
+---
+
+# Triage PRs
+
+## Goal
+
+Turn a backlog of open PRs into a shipped set of merges in a single focused session. Produce a tracked, resumable plan (`<VERSION>_PR_TRIAGE.md`), then work it — rebasing where needed, merging in isolation-safe batches, applying post-merge follow-ups, and closing superseded or partially-applicable PRs with credit to their authors.
+
+This skill pairs with `draft-release-notes` and `release-bump`: triage first, then draft notes against the new main, then cut the release.
+
+## When to use
+
+- Before a minor or major release when 10+ open PRs have accumulated
+- When you want to unblock merging without losing the narrative of what's landing
+- When you know you can't personally review every PR deeply, but need to land the critical subset fast
+
+## Prerequisites
+
+- `gh` CLI authenticated against the repo
+- A dedicated worktree for PR review (avoid contaminating `main` with checkouts of contributor branches)
+- Clarity on the target version — the triage doc is named after it (e.g. `0.4.0_PR_TRIAGE.md`)
+
+## Workflow
+
+### 1. Set up an isolated PR-review worktree
+
+```bash
+git worktree list  # check for stale ones first
+git worktree prune
+git worktree add ../voicebox-pr-review -b pr-review-<VERSION> main
+```
+
+Keep the main worktree for release-prep work (changelog drafts, direct-to-main follow-ups). Keep the review worktree for `gh pr checkout` — each checkout moves HEAD to a contributor branch, which you don't want to do in the main worktree.
+
+### 2. Gather metadata for every open PR
+
+```bash
+gh pr list --state open --limit 50 --json \
+  number,title,author,isDraft,mergeable,mergeStateStatus,files,additions,deletions,reviewDecision,statusCheckRollup,maintainerCanModify \
+  --jq '.[] | {num: .number, title, author: .author.login, mergeable, state: .mergeStateStatus, canModify: .maintainerCanModify, changes: "+\(.additions)/-\(.deletions)", files: [.files[].path]}'
+```
+
+You want, for each PR:
+- Size (`+additions/-deletions`)
+- Mergeable state (`CLEAN`, `UNSTABLE`, `DIRTY` = conflicts, `UNKNOWN` = GitHub still computing)
+- Whether maintainer edits are allowed on the branch (needed later if you rebase for the author)
+- File paths touched (helps spot overlaps between PRs)
+
+`UNKNOWN` is common right after a push to main — just try the merge and see.
+
+### 3. Classify into tiers
+
+Sort each PR into exactly one bucket:
+
+**Tier 1 — Merge:** small, mergeable, fixes a real bug, clean CI, low review cost. One-liners, dependency relaxations, targeted safety hardening. These are the easy wins.
+
+**Tier 2 — Candidate, review:** medium size (50-200 lines), touches more surface area, looks sound but needs a closer read. New user-facing features that fit the product direction.
+
+**Supersede:** the fix or feature is already covered by something merged. Close with a comment pointing to the superseding PR. Check carefully — "similar title" isn't proof; compare the actual diffs.
+
+**Defer to next release:** big features, dirty conflicts, draft PRs, anything touching the release pipeline in ways that would introduce risk. Don't merge these in a speedrun — they need dedicated focus.
+
+### 4. Write the triage doc
+
+Create `<VERSION>_PR_TRIAGE.md` in the PR-review worktree root. Structure:
+
+```markdown
+# <Repo> <VERSION> — PR Triage
+
+Working doc for tracking which open PRs land in <VERSION>. Delete after release cut.
+
+Last updated: <DATE>
+
+## Progress
+
+**Tier 1: 0 / N merged**
+**Tier 2: 0 / M handled**
+**Supersede triage: pending**
+
+---
+
+## Merge for <VERSION> — critical bug fixes
+
+| PR | Status | Size | What it fixes | Why must-have |
+|---|---|---|---|---|
+| [#123](url) | [ ] | +5/-0 | ... | ... |
+
+## Strong candidate — needs a quick review
+
+| PR | Status | Size | Summary |
+|---|---|---|---|
+
+## Close as superseded
+
+| PR | Status | Reason |
+|---|---|---|
+
+## Defer to <NEXT_VERSION>
+
+- [#xxx](url) ... — reason
+
+---
+
+## Order of attack
+
+1. Close superseded PRs (one-liner comments)
+2. Merge tier-1 in dependency-free batches — check file paths don't overlap
+3. Review tier-2 individually
+4. Rerun `draft-release-notes` to pick up everything
+5. Run `release-bump`
+```
+
+The **Progress** header is the most important part — it's your scoreboard and lets you resume cleanly if the session gets interrupted.
+
+### 5. Work the loop — per PR
+
+For each PR in the tier-1 / tier-2 list:
+
+**a. Checkout in the review worktree:**
+```bash
+cd ../voicebox-pr-review
+git checkout pr-review-<VERSION>  # reset to neutral base
+gh pr checkout <N>
+```
+
+**b. Read the *actual* commit, not `main..HEAD`:**
+
+```bash
+git show HEAD                    # the PR's actual changes
+git show --stat HEAD             # files touched + line counts
+```
+
+**Do NOT review via `git diff main..HEAD`** if the PR branch is older than main. That diff includes *every commit that landed on main after the PR was forked* as `-` (deletion) lines. A 3-line PR can look like a 700-line revert. This is the single easiest way to misjudge a PR.
+
+**c. Evaluate concerns:** correctness, scope, interaction with already-merged work, version compatibility (e.g. can't use an API that requires a dependency version we don't yet pin).
+
+**d. Rebase if the branch is behind main:**
+```bash
+git fetch origin main
+git rebase origin/main
+```
+
+This is **essential** before squash-merging. GitHub's squash computes `diff(PR-head, merge-base)` — on a stale branch, that diff includes reverting every in-between commit. Rebasing moves the merge-base forward so the squash is clean.
+
+**e. If maintainer edits are allowed, push the rebase back to the contributor's fork:**
+```bash
+git remote add <author> https://github.com/<author>/<repo>.git
+git fetch <author> <branch>              # get their ref first
+git push <author> HEAD:<branch> --force-with-lease
+```
+
+This keeps GitHub's PR UI in sync with the rebased state and makes the merge clean from the GitHub side.
+
+**f. Merge:**
+```bash
+gh pr merge <N> --squash
+```
+
+**g. Update the triage doc** — flip the checkbox to `✅ merged <sha>` (use the short SHA from `gh pr view <N> --json mergeCommit --jq '.mergeCommit.oid[0:7]'`). Update the Progress header.
+
+### 6. Batch tiny fixes
+
+PRs with ≤5 line changes, clean CI, non-overlapping file paths, and obviously-correct intent (e.g. one-line dependency relax, env var add, import path fix) can be merged in a single loop without the review-per-PR ceremony:
+
+```bash
+for pr in 425 384 416 429; do
+  echo "=== Merging PR $pr ==="
+  gh pr merge $pr --squash
+done
+```
+
+Verify afterward that each landed cleanly:
+```bash
+for pr in 425 384 416 429; do
+  gh pr view $pr --json state,mergeCommit --jq "{pr: $pr, state, sha: .mergeCommit.oid[0:7]}"
+done
+```
+
+### 7. Post-merge follow-ups
+
+Sometimes a PR is worth merging despite a known minor issue (e.g. incomplete dtype map, stale sentinel cleanup). Don't block the merge; apply the follow-up as a normal branch + PR right after:
+
+```bash
+cd <main-worktree>
+git pull --ff-only origin main
+git checkout -b fix/<short-name>
+# edit...
+git commit -m "fix(<area>): <one-liner>"
+git push -u origin fix/<short-name>
+gh pr create --title "..." --body "Follow-up to #<N>. ..."
+```
+
+Record both SHAs in the triage doc (`✅ merged <pr-sha> + follow-up <pr>`).
+
+**Direct-to-main exception:** only under an explicit, scoped policy (e.g. "release speedrun"). Don't default to it.
+
+### 8. Supersede: close with a credit-pointing comment
+
+```bash
+gh pr close <N> --comment "Closing — superseded by merged #<M> which landed <brief description>. Thanks!"
+```
+
+Check the diffs first — "similar title" is not enough. If the PR is *partially* superseded (the diagnosis is right but only half the changes are still needed), do a partial-apply instead.
+
+### 9. Partial-apply pattern
+
+When a PR has both valuable and questionable changes bundled:
+
+```bash
+cd <main-worktree>
+git pull --ff-only origin main
+
+# Cherry-pick specific files from the PR branch
+git checkout <pr-commit-sha> -- <file1> <file2>
+
+# Review the staged changes, adjust as needed
+git diff --cached
+
+# Apply any surgical edits to files you don't want to bulk-replace
+# (e.g. the PR's file predates a recent main commit you need to preserve)
+
+# Commit with a trailer crediting the original author
+git commit -m "$(cat <<'EOF'
+<subject>
+
+<body explaining what was kept vs dropped>
+
+Co-Authored-By: <author> <[email protected]>
+EOF
+)"
+git push ...  # branch + PR, unless under the direct-to-main exception
+```
+
+Then close the PR with a comment explaining what was applied and what was dropped, referencing the commit SHA.
+
+### 10. Keep the doc current
+
+Every merge, every close, every follow-up → update `<VERSION>_PR_TRIAGE.md`. The doc is your session log. If you're interrupted and resume tomorrow, the doc is the only source of truth for "where am I."
+
+### 11. When triage is done
+
+- Every PR in the doc has a terminal status (✅ merged / ✅ closed / deferred)
+- Progress header shows N/N for each tier
+- Next skill to run is `draft-release-notes` (to regenerate `[Unreleased]` against the new main), then `release-bump`
+
+You can delete the triage doc after the release ships, or keep it in version history as a record.
+
+## Gotchas
+
+- **`main..HEAD` on a stale branch lies.** It shows everything main gained since the branch split as deletions. Always review via `git show HEAD` for the PR's actual commit.
+- **Squash-merging an unrebased branch reverts in-between work.** The squash computes `diff(PR-head, merge-base)`. Rebase moves the merge-base forward.
+- **`mergeable=UNKNOWN`** is transient — GitHub is recomputing after a push. Just try the merge.
+- **Route ordering matters (FastAPI and similar):** `DELETE /history/failed` must be registered *before* `DELETE /history/{id}`, or the parameterized path will consume `"failed"` as an ID.
+- **Apple's `-weak_framework` overrides `-framework`** for the same framework, regardless of order — use it via `cargo:rustc-link-arg=-Wl,-weak_framework,Name` when a dependency hard-links something optional.
+- **Dependency version floors constrain what you can apply.** Before accepting a kwarg rename like `torch_dtype=` → `dtype=`, check the min-version pin supports it. Sometimes the right move is to cherry-pick half the PR.
+- **`cpal::Stream` and similar `!Send` audio types** can't cross `await` points or `spawn_blocking`. Sometimes a "not-ideal but correct" sync wait is the best available fix; flag but don't block.
+- **PyTorch nightly builds are not shippable for releases** — non-deterministic, can regress between runs. If a PR suggests switching to nightly to fix a GPU issue, prefer `TORCH_CUDA_ARCH_LIST=...+PTX` or wait for stable support instead.
+
+## Canonical commands reference
+
+```bash
+# Bulk PR metadata
+gh pr list --state open --limit 50 --json number,title,author,mergeable,mergeStateStatus,additions,deletions,maintainerCanModify,files
+
+# Detailed single-PR view
+gh pr view <N> --json body,author,headRefName,baseRefName,mergeable,maintainerCanModify,files,statusCheckRollup
+
+# The actual commit, not the branch-vs-main diff
+git show HEAD
+git show --stat HEAD
+gh pr diff <N>
+
+# Rebase contributor branch onto current main
+git fetch origin main && git rebase origin/main
+
+# Push rebase back to contributor fork (maintainerCanModify=true required)
+git remote add <author> https://github.com/<author>/<repo>.git
+git fetch <author> <branch>
+git push <author> HEAD:<branch> --force-with-lease
+
+# Merge
+gh pr merge <N> --squash
+
+# Confirm merge SHA for triage doc
+gh pr view <N> --json state,mergeCommit --jq '{state, sha: .mergeCommit.oid[0:7]}'
+
+# Close superseded
+gh pr close <N> --comment "Closing — superseded by merged #<M>. Thanks!"
+```
+
+## Notes
+
+- **Never review a stale branch via `main..HEAD`.** This is the single most important line in this skill.
+- **The triage doc is the session state.** Lose the doc, lose the session. Update it after every action.
+- **Credit contributors even on partial-applies.** Use `Co-Authored-By:` trailers and close comments that link to the applied commit.
+- **Don't let perfect be the enemy of shipped.** A fix that goes from "broken" to "works with a minor known issue" is a strict improvement. Flag the issue, file a follow-up, merge the fix.
@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.3.1
+current_version = 0.4.0
 commit = True
 tag = True
 tag_name = v{new_version}
@@ -38,7 +38,6 @@ biome.json
 .bumpversion.cfg
 .npmrc
 Makefile
-CHANGELOG.md
 CONTRIBUTING.md
 SECURITY.md
 LICENSE
@@ -203,6 +203,12 @@ jobs:
      - name: Build CUDA server binary (onedir)
        shell: bash
        working-directory: backend
+        env:
+          # Include Blackwell (sm_120) via PTX forward compatibility.
+          # Pre-built PyTorch cu128 wheels ship native kernels for sm_80/86/89/90
+          # but not sm_120. Setting this env var causes torch.utils.cpp_extension
+          # (and any JIT-compiled kernels) to target Blackwell GPUs as well.
+          TORCH_CUDA_ARCH_LIST: "8.0;8.6;8.9;9.0;12.0+PTX"
        run: python build_binary.py --cuda

      - name: Package into server core + CUDA libs archives
@@ -7,6 +7,117 @@

 ## [Unreleased]

+## [0.4.0] - 2026-04-16
+
+The biggest Voicebox release yet. Three new TTS engines bring the lineup to **seven** — HumeAI TADA, Kokoro 82M, and Qwen CustomVoice join Qwen3-TTS, LuxTTS, Chatterbox Multilingual, and Chatterbox Turbo. GPU support broadens to Intel Arc (XPU) and NVIDIA Blackwell (RTX 50-series), with runtime diagnostics that warn when your PyTorch build doesn't match your GPU. The CUDA backend is now split into independently versioned server and library archives, so upgrading no longer redownloads 4 GB of PyTorch/CUDA DLLs.
+
+This release also marks a big community moment: **13 new contributors** shipped fixes and features in 0.4.0. Thirty-plus bug fixes target the most-reported issues in the tracker — numpy 2.x TTS crashes, Windows background-server reliability, macOS 11 launch failures, audio playback silence, Stories clip-splitting races, history status staleness, and more.
+
+### New TTS Engines
+
+#### HumeAI TADA — Expressive English & Multilingual ([#296](https://github.com/jamiepine/voicebox/pull/296))
+- Added `tada-1b` (English) and `tada-3b-ml` (multilingual) backends
+- Replaced `descript-audio-codec` with a lightweight DAC shim to cut dependencies
+- Switched audio decoding to `soundfile` to sidestep `torchcodec` bundling issues
+- Redirected gated Llama tokenizer lookups to an ungated mirror so model loading works out of the box
+- Fixed tokenizer patch that was corrupting `AutoTokenizer` for other engines
+- Fixed TorchScript error in frozen builds
+
+#### Kokoro 82M — Fast Lightweight TTS ([#325](https://github.com/jamiepine/voicebox/pull/325))
+- Added Kokoro 82M engine with a new voice profile type system that distinguishes preset voices from cloned profiles
+- Profile grid now handles engine compatibility directly — removed redundant dropdown filtering
+- Tightened Kokoro profile handling so preset voices can't be edited like cloned profiles
+
+#### Qwen CustomVoice ([#328](https://github.com/jamiepine/voicebox/pull/328))
+- Added `qwen-custom-voice` preset engine backed by Qwen3-TTS
+- Enforced preset/profile engine compatibility across the generation flow
+- Floating generator now shows all engines instead of silently filtering
+
+### Voice Profile UX
+
+Until 0.4, every engine in Voicebox was a cloning model, so every voice profile was usable with every engine and the profile grid just showed them all. Introducing Kokoro and Qwen CustomVoice — which work from preset voices rather than cloned samples — broke that assumption for the first time. An early cut on `main` filtered the grid by the selected engine, which left users running pre-release builds thinking their cloned voices had vanished whenever they switched to a preset-only engine.
+
+This release ships the resolution before it ever reaches a tagged version:
+
+- **Grey-out instead of filter** — all profiles are always visible; unsupported ones render dimmed with a compatibility hint at the bottom of the grid
+- **Auto-switch on selection** — clicking a greyed-out profile selects it AND switches the engine to a compatible one, instead of silently doing nothing
+- **Instruct toggle restored for Qwen CustomVoice** — the floating generate box now reveals a delivery-instructions input (tone, emotion, pace) when CustomVoice is selected. Hidden across the board while the new multi-engine lineup was stabilizing because most engines don't honor the kwarg; now conditionally exposed only for the one engine that was actually trained for instruction-based style control
+- Supported profiles sort first; the grid scrolls the selected profile into view after engine/sort changes
+- Fixed engine desync on tab navigation — the form now initializes its engine from the store
+- Fixed the disabled-and-selected card click edge case by bouncing selection to re-trigger the auto-switch
+- Cleaned up scroll effect timers (requestAnimationFrame + setTimeout) to prevent stale DOM writes on unmount or rapid selection changes
+
+### GPU & Platform
+
+#### Intel Arc (XPU) Support ([#320](https://github.com/jamiepine/voicebox/pull/320))
+- First-class Intel Arc support across all PyTorch-based backends
+- Device-aware seeding, XPU detection in the GPU status panel, and setup flow detection
+- Reports correct device name and VRAM in settings
+
+#### Blackwell / RTX 50-series Support ([#316](https://github.com/jamiepine/voicebox/pull/316), [#401](https://github.com/jamiepine/voicebox/pull/401))
+- Upgraded the CUDA backend from cu126 → cu128 for RTX 50-series support
+- Added `sm_120+PTX` to the CUDA build via `TORCH_CUDA_ARCH_LIST` for forward-compatibility with Blackwell architectures (closes 5 open reports: #386, #395, #396, #399, #400)
+- GPU settings UI fixes around install/uninstall state
+
+#### GPU Compatibility Diagnostics ([#367](https://github.com/jamiepine/voicebox/pull/367), adapted)
+- New `check_cuda_compatibility()` compares the current device's compute capability against the bundled PyTorch's architecture list
+- Health endpoint exposes a `gpu_compatibility_warning` field so the UI can surface mismatches
+- Startup logs a `WARN` when the installed PyTorch build doesn't support the detected GPU
+- GPU status label shows `[UNSUPPORTED - see logs]` — no more silent "no kernel image" failures
+
+#### Split CUDA Backend ([#298](https://github.com/jamiepine/voicebox/pull/298))
+- CUDA backend now ships as two independently versioned archives: a small server binary and a large libs archive (the ~4 GB of PyTorch/CUDA DLLs)
+- Upgrading Voicebox no longer redownloads the libs archive when only the server binary changed
+- Added `asyncio.Lock` around `download_cuda_binary()` so auto-update and manual download can't race on the same temp file ([#428](https://github.com/jamiepine/voicebox/pull/428))
+- Updated `package_cuda.py` for PyInstaller 6.18 onedir layout
+- Temp archives are always cleaned up on failure, even when the install aborts mid-extract
+
+### Bug Fixes
+
+#### Critical: TTS Generation
+- **numpy 2.x `torch.from_numpy` crash** ([#361](https://github.com/jamiepine/voicebox/pull/361)) — torch compiled against numpy 1.x ABI fails silently when paired with numpy 2.x, causing `RuntimeError: Numpy is not available` / `Unable to create tensor` on every TTS request in bundled macOS Intel / Rosetta builds. Pinned `numpy<2.0` in requirements and added a PyInstaller runtime hook with a `ctypes.memmove` fallback as belt-and-suspenders. Hardened afterward to raise on unknown dtypes instead of silently reinterpreting bytes as float32.
+
+#### Platform Reliability
+- **Windows background server** ([#402](https://github.com/jamiepine/voicebox/pull/402)) — "keep server running after close" now actually keeps the server running. The HTTP `/watchdog/disable` request could lose the race against process exit on Windows; added a `.keep-running` sentinel file as a synchronous fallback, with stale-sentinel cleanup on startup to avoid orphan server processes
+- **macOS 11 launch crash** ([#424](https://github.com/jamiepine/voicebox/pull/424)) — weak-linked ScreenCaptureKit so the app can launch on macOS < 12.3 instead of crashing at dyld resolution. Gated system audio capture behind a real `sw_vers` version check so unsupported systems cleanly advertise "not available" rather than crashing at runtime
+- **macOS Intel (x86_64) setup** ([#416](https://github.com/jamiepine/voicebox/pull/416)) — relaxed `torch>=2.7.0` → `torch>=2.2.0`. PyTorch dropped pre-built x86_64 wheels after 2.2.2, so Intel Mac devs could no longer `pip install`. Now resolves to the latest compatible torch per platform
+- **Offline model loading** ([#318](https://github.com/jamiepine/voicebox/pull/318)) — Qwen TTS and Whisper force offline mode when loading cached models, so startup works without network access
+- **GUI startup with external server** ([#319](https://github.com/jamiepine/voicebox/pull/319)) — fixed GUI launch when pointed at a remote/external server, and added data refresh on server switch; hardened health validation and error handling
+- **Qwen3-TTS cache split on Windows** (adapted from [#218](https://github.com/jamiepine/voicebox/pull/218)) — route `Qwen3TTSModel.from_pretrained` through `hf_constants.HF_HUB_CACHE` so the speech tokenizer and `preprocessor_config.json` resolve from a single cache root
+- **Qwen3-TTS bundling** ([#305](https://github.com/jamiepine/voicebox/pull/305)) — bundle `qwen_tts` source files in the PyInstaller build to fix `inspect.getsource` errors in frozen builds
+- **Backend import paths** ([#345](https://github.com/jamiepine/voicebox/pull/345)) — moved lazy imports to top-level with absolute paths to resolve the "Failed to Save" preset error caused by `ModuleNotFoundError` in production builds
+- **Effects service import** ([#384](https://github.com/jamiepine/voicebox/pull/384)) — fixed `ModuleNotFoundError` on preset create/update by switching to relative imports (#349)
+
+#### Audio & Playback
+- **cpal stream silent playback** ([#405](https://github.com/jamiepine/voicebox/pull/405)) — `cpal::Stream` was dropped on function return immediately after `play()`, causing every playback to fall silent. Now holds the stream until either the buffer drains or the stop flag fires (#404)
+
+#### Stories & History
+- **Clip-splitting race** ([#403](https://github.com/jamiepine/voicebox/pull/403)) — rapid double-clicks on split could race through `split_story_item` with inconsistent state. Added `with_for_update()` row locking on the backend and an `isPending` guard on the frontend (#366)
+- **History `status` staleness** ([#394](https://github.com/jamiepine/voicebox/pull/394)) — `GET /history/{id}` was hardcoding `status="completed"` regardless of the DB row, breaking any client polling for job completion. Now returns `status`, `error`, `engine`, `model_size`, and `is_favorited` from the actual row
+- **"Clear failed" bulk button** ([#412](https://github.com/jamiepine/voicebox/pull/412)) — new `DELETE /history/failed` endpoint and a header strip showing `"N failed generations"` with a Clear button, complementing the per-row trash icon added in #321 (#410)
+- **Delete failed generations** ([#321](https://github.com/jamiepine/voicebox/pull/321)) — added a trash icon next to the retry button so failed entries can be cleaned up without having to retry first
+
+#### Security & Safety
+- **Voice prompt cache hardening** ([#429](https://github.com/jamiepine/voicebox/pull/429)) — `torch.load(weights_only=True)` on cached voice prompts per PyTorch 2.6 recommendation; replaced string-based SPA path guard with `Path.is_relative_to()` for more robust path-traversal protection
+
+#### Infrastructure & Docker
+- **Docker web build** ([#344](https://github.com/jamiepine/voicebox/pull/344)) — include `CHANGELOG.md` in the Docker web build so the in-app changelog page works in Docker deployments
+- **Docker numba cache** ([#425](https://github.com/jamiepine/voicebox/pull/425)) — set `NUMBA_CACHE_DIR` in docker-compose so numba can write its JIT cache in container runtime (#308)
+- **Relative media paths** ([#332](https://github.com/jamiepine/voicebox/pull/332)) — media paths now stored relative to the configured data dir rather than resolved against CWD, so the data directory is portable between installs
+
+### Developer Tooling
+
+- New `triage-prs` agent skill — encodes the end-to-end PR-speedrun workflow (classification → triage doc → rebase → squash-merge → follow-ups) so future release cycles can reproduce it
+- Rewrote the TTS engine guide with the patterns learned from adding TADA and Kokoro
+- Added the API refactor plan and CUDA libs addon design doc
+- Fixed broken links in the Get Started section ([#332](https://github.com/jamiepine/voicebox/pull/332))
+
+### New Contributors
+
+Huge thank you to everyone who contributed their first PR to Voicebox in this release:
+
+[@liorshahverdi](https://github.com/liorshahverdi), [@nicoschtein](https://github.com/nicoschtein), [@ArfianID](https://github.com/ArfianID), [@aimaaaimaa](https://github.com/aimaaaimaa), [@maxmcoding](https://github.com/maxmcoding), [@Khalodddd](https://github.com/Khalodddd), [@LuisSambrano](https://github.com/LuisSambrano), [@shaun0927](https://github.com/shaun0927), [@malletfils](https://github.com/malletfils), [@mvanhorn](https://github.com/mvanhorn), [@kuishou68](https://github.com/kuishou68), [@txhno](https://github.com/txhno), [@MukundaKatta](https://github.com/MukundaKatta)
+
 ## [0.3.0] - 2026-03-17

 This release rewrites the backend into a modular architecture, overhauls the settings UI into routed sub-pages, fixes audio player freezing, migrates documentation to Fumadocs, and ships a batch of bug fixes targeting the most-reported issues from the tracker.
@@ -444,7 +555,9 @@ The first public release of Voicebox — an open-source voice synthesis studio p

 Tauri v2, React, TypeScript, Tailwind CSS, FastAPI, Qwen3-TTS, Whisper, SQLite

-[Unreleased]: https://github.com/jamiepine/voicebox/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/jamiepine/voicebox/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/jamiepine/voicebox/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/jamiepine/voicebox/compare/v0.2.3...v0.3.0
 [0.2.3]: https://github.com/jamiepine/voicebox/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/jamiepine/voicebox/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/jamiepine/voicebox/compare/v0.1.13...v0.2.1
@@ -9,7 +9,7 @@ FROM oven/bun:1 AS frontend
 WORKDIR /build

 # Copy workspace config and frontend source
-COPY package.json bun.lock ./
+COPY package.json bun.lock CHANGELOG.md ./
 COPY app/ ./app/
 COPY web/ ./web/

@@ -1,6 +1,6 @@
 {
  "name": "@voicebox/app",
-  "version": "0.3.1",
+  "version": "0.4.0",
  "private": true,
  "type": "module",
  "scripts": {
@@ -4,6 +4,8 @@ import voiceboxLogo from '@/assets/voicebox-logo.png';
 import ShinyText from '@/components/ShinyText';
 import { TitleBarDragRegion } from '@/components/TitleBarDragRegion';
 import { useAutoUpdater } from '@/hooks/useAutoUpdater';
+import { apiClient } from '@/lib/api/client';
+import type { HealthResponse } from '@/lib/api/types';
 import { TOP_SAFE_AREA_PADDING } from '@/lib/constants/ui';
 import { cn } from '@/lib/utils/cn';
 import { usePlatform } from '@/platform/PlatformContext';
@@ -11,6 +13,33 @@ import { router } from '@/router';
 import { useLogStore } from '@/stores/logStore';
 import { useServerStore } from '@/stores/serverStore';

+/**
+ * Validate that a health response has the expected Voicebox-specific shape.
+ * Prevents misidentifying an unrelated service on the same port.
+ */
+function isVoiceboxHealthResponse(health: HealthResponse): boolean {
+  return (
+    health?.status === 'healthy' &&
+    typeof health.model_loaded === 'boolean' &&
+    typeof health.gpu_available === 'boolean'
+  );
+}
+
+/**
+ * Check whether a startup error indicates the port is occupied by an external
+ * server (which we should try to reuse via health-check polling) vs. a real
+ * failure (missing sidecar, signing issue, etc.) that should surface immediately.
+ */
+function isPortInUseError(error: unknown): boolean {
+  const msg = error instanceof Error ? error.message : String(error);
+  return (
+    msg.includes('already in use') ||
+    msg.includes('port') ||
+    msg.includes('EADDRINUSE') ||
+    msg.includes('address already in use')
+  );
+}
+
 const LOADING_MESSAGES = [
  'Warming up tensors...',
  'Calibrating synthesizer engine...',
@@ -37,6 +66,7 @@ const LOADING_MESSAGES = [
 function App() {
  const platform = usePlatform();
  const [serverReady, setServerReady] = useState(false);
+  const [startupError, setStartupError] = useState<string | null>(null);
  const [loadingMessageIndex, setLoadingMessageIndex] = useState(0);
  const serverStartingRef = useRef(false);

@@ -122,6 +152,46 @@ function App() {
        serverStartingRef.current = false;
        // @ts-expect-error - adding property to window
        window.__voiceboxServerStartedByApp = false;
+
+        // Only fall back to health-check polling when the error indicates the
+        // port is occupied (likely an external server). For real failures
+        // (missing sidecar, signing issues, etc.) surface the error immediately.
+        if (!isPortInUseError(error)) {
+          const msg = error instanceof Error ? error.message : String(error);
+          console.error('Real startup failure — not polling:', msg);
+          setStartupError(msg);
+          return;
+        }
+
+        // Fall back to polling: the server may already be running externally
+        // (e.g. started via python/uvicorn/Docker). Poll the health endpoint
+        // until it responds with a valid Voicebox payload, then transition to
+        // the main UI.
+        console.log('Falling back to health-check polling...');
+        const pollInterval = setInterval(async () => {
+          try {
+            const health = await apiClient.getHealth();
+            if (!isVoiceboxHealthResponse(health)) {
+              console.log('Health response is not from a Voicebox server, keep polling...');
+              return;
+            }
+            console.log('External Voicebox server detected via health check');
+            clearInterval(pollInterval);
+            setServerReady(true);
+          } catch {
+            // Server not ready yet, keep polling
+          }
+        }, 2000);
+
+        // Stop polling after 2 minutes and surface the failure
+        setTimeout(() => {
+          clearInterval(pollInterval);
+          serverStartingRef.current = false;
+          setStartupError(
+            'Could not connect to a Voicebox server within 2 minutes. ' +
+              'Please check that the server is running and try again.',
+          );
+        }, 120_000);
      });

    // Cleanup: stop server on actual unmount (not StrictMode remount)
@@ -168,15 +238,34 @@ function App() {
              className="w-48 h-48 object-contain animate-fade-in-scale relative z-10"
            />
          </div>
-          <div className="animate-fade-in-delayed">
-            <ShinyText
-              text={LOADING_MESSAGES[loadingMessageIndex]}
-              className="text-lg font-medium text-muted-foreground"
-              speed={2}
-              color="hsl(var(--muted-foreground))"
-              shineColor="hsl(var(--foreground))"
-            />
-          </div>
+          {startupError ? (
+            <div className="animate-fade-in-delayed max-w-md mx-auto space-y-3">
+              <p className="text-lg font-medium text-destructive">Server startup failed</p>
+              <p className="text-sm text-muted-foreground">{startupError}</p>
+              <button
+                type="button"
+                className="mt-2 px-4 py-2 text-sm rounded-md bg-primary text-primary-foreground hover:bg-primary/90 transition-colors"
+                onClick={() => {
+                  setStartupError(null);
+                  serverStartingRef.current = false;
+                  // Trigger a re-mount of the effect by toggling state
+                  window.location.reload();
+                }}
+              >
+                Retry
+              </button>
+            </div>
+          ) : (
+            <div className="animate-fade-in-delayed">
+              <ShinyText
+                text={LOADING_MESSAGES[loadingMessageIndex]}
+                className="text-lg font-medium text-muted-foreground"
+                speed={2}
+                color="hsl(var(--muted-foreground))"
+                shineColor="hsl(var(--foreground))"
+              />
+            </div>
+          )}
        </div>
      </div>
    );
@@ -14,15 +14,17 @@ interface AppFrameProps {
 export function AppFrame({ children }: AppFrameProps) {
  const routerState = useRouterState();
  const isStoriesRoute = routerState.location.pathname === '/stories';
-  
+
  const selectedStoryId = useStoryStore((state) => state.selectedStoryId);
  const { data: story } = useStory(selectedStoryId);
-  
+
  // Show track editor when on stories route with a selected story that has items
  const showTrackEditor = isStoriesRoute && selectedStoryId && story && story.items.length > 0;

  return (
-    <div className={cn('h-screen bg-background flex flex-col overflow-hidden', TOP_SAFE_AREA_PADDING)}>
+    <div
+      className={cn('h-screen bg-background flex flex-col overflow-hidden', TOP_SAFE_AREA_PADDING)}
+    >
      <TitleBarDragRegion />
      {children}
      {showTrackEditor ? (
@@ -1,20 +1,20 @@
-import {EffectsDetail} from "./EffectsDetail";
-import {EffectsList} from "./EffectsList";
+import { EffectsDetail } from './EffectsDetail';
+import { EffectsList } from './EffectsList';

 export function EffectsTab() {
-	return (
-		<div className="flex flex-col h-full min-h-0 overflow-hidden">
-			<div className="flex-1 min-h-0 flex gap-6 overflow-hidden">
-				{/* Left - Presets list */}
-				<div className="w-full max-w-[360px] shrink-0 flex flex-col min-h-0">
-					<EffectsList />
-				</div>
+  return (
+    <div className="flex flex-col h-full min-h-0 overflow-hidden">
+      <div className="flex-1 min-h-0 flex gap-6 overflow-hidden">
+        {/* Left - Presets list */}
+        <div className="w-full max-w-[360px] shrink-0 flex flex-col min-h-0">
+          <EffectsList />
+        </div>

-				{/* Right - Detail / editor */}
-				<div className="flex-1 min-h-0 flex flex-col">
-					<EffectsDetail />
-				</div>
-			</div>
-		</div>
-	);
+        {/* Right - Detail / editor */}
+        <div className="flex-1 min-h-0 flex flex-col">
+          <EffectsDetail />
+        </div>
+      </div>
+    </div>
+  );
 }
@@ -1,3 +1,4 @@
+import { useEffect } from 'react';
 import type { UseFormReturn } from 'react-hook-form';
 import { FormControl } from '@/components/ui/form';
 import {
@@ -7,6 +8,7 @@ import {
  SelectTrigger,
  SelectValue,
 } from '@/components/ui/select';
+import type { VoiceProfileResponse } from '@/lib/api/types';
 import { getLanguageOptionsForEngine } from '@/lib/constants/languages';
 import type { GenerationFormValues } from '@/lib/hooks/useGenerationForm';

@@ -15,34 +17,57 @@ import type { GenerationFormValues } from '@/lib/hooks/useGenerationForm';
 * Adding a new engine means adding one entry here.
 */
 const ENGINE_OPTIONS = [
-  { value: 'qwen:1.7B', label: 'Qwen3-TTS 1.7B' },
-  { value: 'qwen:0.6B', label: 'Qwen3-TTS 0.6B' },
-  { value: 'luxtts', label: 'LuxTTS' },
-  { value: 'chatterbox', label: 'Chatterbox' },
-  { value: 'chatterbox_turbo', label: 'Chatterbox Turbo' },
-  { value: 'tada:1B', label: 'TADA 1B' },
-  { value: 'tada:3B', label: 'TADA 3B Multilingual' },
+  { value: 'qwen:1.7B', label: 'Qwen3-TTS 1.7B', engine: 'qwen' },
+  { value: 'qwen:0.6B', label: 'Qwen3-TTS 0.6B', engine: 'qwen' },
+  { value: 'qwen_custom_voice:1.7B', label: 'Qwen CustomVoice 1.7B', engine: 'qwen_custom_voice' },
+  { value: 'qwen_custom_voice:0.6B', label: 'Qwen CustomVoice 0.6B', engine: 'qwen_custom_voice' },
+  { value: 'luxtts', label: 'LuxTTS', engine: 'luxtts' },
+  { value: 'chatterbox', label: 'Chatterbox', engine: 'chatterbox' },
+  { value: 'chatterbox_turbo', label: 'Chatterbox Turbo', engine: 'chatterbox_turbo' },
+  { value: 'tada:1B', label: 'TADA 1B', engine: 'tada' },
+  { value: 'tada:3B', label: 'TADA 3B Multilingual', engine: 'tada' },
+  { value: 'kokoro', label: 'Kokoro 82M', engine: 'kokoro' },
 ] as const;

 const ENGINE_DESCRIPTIONS: Record<string, string> = {
  qwen: 'Multi-language, two sizes',
+  qwen_custom_voice: '9 preset voices, instruct control',
  luxtts: 'Fast, English-focused',
  chatterbox: '23 languages, incl. Hebrew',
  chatterbox_turbo: 'English, [laugh] [cough] tags',
  tada: 'HumeAI, 700s+ coherent audio',
+  kokoro: '82M params, CPU realtime, 8 langs',
 };

 /** Engines that only support English and should force language to 'en' on select. */
 const ENGLISH_ONLY_ENGINES = new Set(['luxtts', 'chatterbox_turbo']);

+/** Engines that support cloned (reference audio) profiles. */
+const CLONING_ENGINES = new Set(['qwen', 'luxtts', 'chatterbox', 'chatterbox_turbo', 'tada']);
+
+function getAvailableOptions(selectedProfile?: VoiceProfileResponse | null) {
+  if (!selectedProfile) return ENGINE_OPTIONS;
+  return ENGINE_OPTIONS.filter((opt) => isProfileCompatibleWithEngine(selectedProfile, opt.engine));
+}
+
 function getSelectValue(engine: string, modelSize?: string): string {
  if (engine === 'qwen') return `qwen:${modelSize || '1.7B'}`;
+  if (engine === 'qwen_custom_voice') return `qwen_custom_voice:${modelSize || '1.7B'}`;
  if (engine === 'tada') return `tada:${modelSize || '1B'}`;
  return engine;
 }

-function handleEngineChange(form: UseFormReturn<GenerationFormValues>, value: string) {
-  if (value.startsWith('qwen:')) {
+export function applyEngineSelection(form: UseFormReturn<GenerationFormValues>, value: string) {
+  if (value.startsWith('qwen_custom_voice:')) {
+    const [, modelSize] = value.split(':');
+    form.setValue('engine', 'qwen_custom_voice');
+    form.setValue('modelSize', modelSize as '1.7B' | '0.6B');
+    const currentLang = form.getValues('language');
+    const available = getLanguageOptionsForEngine('qwen_custom_voice');
+    if (!available.some((l) => l.value === currentLang)) {
+      form.setValue('language', available[0]?.value ?? 'en');
+    }
+  } else if (value.startsWith('qwen:')) {
    const [, modelSize] = value.split(':');
    form.setValue('engine', 'qwen');
    form.setValue('modelSize', modelSize as '1.7B' | '0.6B');
@@ -85,12 +110,22 @@ function handleEngineChange(form: UseFormReturn<GenerationFormValues>, value: st
 interface EngineModelSelectorProps {
  form: UseFormReturn<GenerationFormValues>;
  compact?: boolean;
+  selectedProfile?: VoiceProfileResponse | null;
 }

-export function EngineModelSelector({ form, compact }: EngineModelSelectorProps) {
+export function EngineModelSelector({ form, compact, selectedProfile }: EngineModelSelectorProps) {
  const engine = form.watch('engine') || 'qwen';
  const modelSize = form.watch('modelSize');
  const selectValue = getSelectValue(engine, modelSize);
+  const availableOptions = getAvailableOptions(selectedProfile);
+
+  const currentEngineAvailable = availableOptions.some((opt) => opt.value === selectValue);
+
+  useEffect(() => {
+    if (!currentEngineAvailable && availableOptions.length > 0) {
+      applyEngineSelection(form, availableOptions[0].value);
+    }
+  }, [availableOptions, currentEngineAvailable, form]);

  const itemClass = compact ? 'text-xs text-muted-foreground' : undefined;
  const triggerClass = compact
@@ -98,14 +133,14 @@ export function EngineModelSelector({ form, compact }: EngineModelSelectorProps)
    : undefined;

  return (
-    <Select value={selectValue} onValueChange={(v) => handleEngineChange(form, v)}>
+    <Select value={selectValue} onValueChange={(v) => applyEngineSelection(form, v)}>
      <FormControl>
        <SelectTrigger className={triggerClass}>
          <SelectValue />
        </SelectTrigger>
      </FormControl>
      <SelectContent>
-        {ENGINE_OPTIONS.map((opt) => (
+        {availableOptions.map((opt) => (
          <SelectItem key={opt.value} value={opt.value} className={itemClass}>
            {opt.label}
          </SelectItem>
@@ -119,3 +154,17 @@ export function EngineModelSelector({ form, compact }: EngineModelSelectorProps)
 export function getEngineDescription(engine: string): string {
  return ENGINE_DESCRIPTIONS[engine] ?? '';
 }
+
+/**
+ * Check if a profile is compatible with the currently selected engine.
+ * Useful for UI hints.
+ */
+export function isProfileCompatibleWithEngine(
+  profile: VoiceProfileResponse,
+  engine: string,
+): boolean {
+  const voiceType = profile.voice_type || 'cloned';
+  if (voiceType === 'preset') return profile.preset_engine === engine;
+  if (voiceType === 'cloned') return CLONING_ENGINES.has(engine);
+  return true; // designed — future
+}
@@ -1,7 +1,7 @@
 import { useQuery } from '@tanstack/react-query';
 import { useMatchRoute } from '@tanstack/react-router';
 import { AnimatePresence, motion } from 'framer-motion';
-import { Loader2, Sparkles } from 'lucide-react';
+import { Loader2, SlidersHorizontal, Sparkles } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
 import { Button } from '@/components/ui/button';
 import { Form, FormControl, FormField, FormItem, FormMessage } from '@/components/ui/form';
@@ -36,9 +36,11 @@ export function FloatingGenerateBox({
 }: FloatingGenerateBoxProps) {
  const selectedProfileId = useUIStore((state) => state.selectedProfileId);
  const setSelectedProfileId = useUIStore((state) => state.setSelectedProfileId);
+  const setSelectedEngine = useUIStore((state) => state.setSelectedEngine);
  const { data: selectedProfile } = useProfile(selectedProfileId || '');
  const { data: profiles } = useProfiles();
  const [isExpanded, setIsExpanded] = useState(false);
+  const [isInstructExpanded, setIsInstructExpanded] = useState(false);
  const [selectedPresetId, setSelectedPresetId] = useState<string | null>(null);
  const containerRef = useRef<HTMLDivElement>(null);
  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
@@ -67,7 +69,12 @@ export function FloatingGenerateBox({
      }
    },
    getEffectsChain: () => {
-      if (!selectedPresetId || !effectPresets) return undefined;
+      if (!selectedPresetId) return undefined;
+      // Profile's own effects chain (no matching preset)
+      if (selectedPresetId === '_profile') {
+        return selectedProfile?.effects_chain ?? undefined;
+      }
+      if (!effectPresets) return undefined;
      const preset = effectPresets.find((p) => p.id === selectedPresetId);
      return preset?.effects_chain;
    },
@@ -110,12 +117,63 @@ export function FloatingGenerateBox({
    }
  }, [selectedProfileId, profiles, setSelectedProfileId]);

-  // Sync generation form language with selected profile's language
+  // Sync engine selection to global store so ProfileList can filter
+  const watchedEngine = form.watch('engine');
+  useEffect(() => {
+    if (watchedEngine) {
+      setSelectedEngine(watchedEngine);
+    }
+  }, [watchedEngine, setSelectedEngine]);
+
+  // Sync generation form language, engine, and effects with selected profile
+  type EngineValue =
+    | 'qwen'
+    | 'luxtts'
+    | 'chatterbox'
+    | 'chatterbox_turbo'
+    | 'tada'
+    | 'kokoro'
+    | 'qwen_custom_voice';
  useEffect(() => {
    if (selectedProfile?.language) {
      form.setValue('language', selectedProfile.language as LanguageCode);
    }
-  }, [selectedProfile, form]);
+    // Auto-switch engine to match the profile
+    const engine = selectedProfile?.default_engine ?? selectedProfile?.preset_engine;
+    if (engine) {
+      form.setValue('engine', engine as EngineValue);
+    } else if (selectedProfile && selectedProfile.voice_type !== 'preset') {
+      // Cloned/designed profile with no default — ensure a compatible (non-preset) engine
+      const currentEngine = form.getValues('engine');
+      const presetEngines = new Set(['kokoro', 'qwen_custom_voice']);
+      if (presetEngines.has(currentEngine)) {
+        form.setValue('engine', 'qwen');
+      }
+    }
+    // Pre-fill effects from profile defaults
+    if (
+      selectedProfile?.effects_chain &&
+      selectedProfile.effects_chain.length > 0 &&
+      effectPresets
+    ) {
+      // Try to match against a known preset
+      const profileChainJson = JSON.stringify(selectedProfile.effects_chain);
+      const matchingPreset = effectPresets.find(
+        (p) => JSON.stringify(p.effects_chain) === profileChainJson,
+      );
+      if (matchingPreset) {
+        setSelectedPresetId(matchingPreset.id);
+      } else {
+        // No matching preset — use special value to pass profile chain directly
+        setSelectedPresetId('_profile');
+      }
+    } else if (
+      selectedProfile &&
+      (!selectedProfile.effects_chain || selectedProfile.effects_chain.length === 0)
+    ) {
+      setSelectedPresetId(null);
+    }
+  }, [selectedProfile, effectPresets, form]);

  // Auto-resize textarea based on content (only when expanded)
  useEffect(() => {
@@ -296,9 +354,80 @@ export function FloatingGenerateBox({
                        : 'Generate speech'}
                  </span>
                </div>
+
+                {/* Instruct toggle — only for Qwen CustomVoice, which actually honors the kwarg */}
+                <AnimatePresence>
+                  {isExpanded && form.watch('engine') === 'qwen_custom_voice' && (
+                    <motion.div
+                      initial={{ opacity: 0, scale: 0.8 }}
+                      animate={{ opacity: 1, scale: 1 }}
+                      exit={{ opacity: 0, scale: 0.8 }}
+                      transition={{ duration: 0.2 }}
+                      className="absolute top-0 right-[calc(100%+0.5rem)]"
+                    >
+                      <div className="group relative">
+                        <Button
+                          type="button"
+                          variant="ghost"
+                          size="icon"
+                          onClick={() => setIsInstructExpanded((prev) => !prev)}
+                          className={cn(
+                            'h-10 w-10 rounded-full transition-all duration-200',
+                            isInstructExpanded
+                              ? 'bg-accent text-accent-foreground border border-accent hover:bg-accent/90'
+                              : 'bg-card border border-border hover:bg-background/50',
+                          )}
+                          aria-label={
+                            isInstructExpanded
+                              ? 'Hide delivery instructions'
+                              : 'Show delivery instructions'
+                          }
+                          aria-pressed={isInstructExpanded}
+                        >
+                          <SlidersHorizontal className="h-4 w-4" />
+                        </Button>
+                        <span className="pointer-events-none absolute bottom-full left-1/2 -translate-x-1/2 mb-2 whitespace-nowrap rounded-md bg-popover px-3 py-1.5 text-xs text-popover-foreground border border-border opacity-0 transition-opacity group-hover:opacity-100 z-[9999]">
+                          Delivery instructions (tone, emotion, pace)
+                        </span>
+                      </div>
+                    </motion.div>
+                  )}
+                </AnimatePresence>
              </div>
            </div>

+            {/* Additive instruct textarea — shown below main text when toggle is on and engine supports it */}
+            <AnimatePresence>
+              {isInstructExpanded && form.watch('engine') === 'qwen_custom_voice' && (
+                <motion.div
+                  initial={{ opacity: 0, height: 0 }}
+                  animate={{ opacity: 1, height: 'auto' }}
+                  exit={{ opacity: 0, height: 0 }}
+                  transition={{ duration: 0.2, ease: 'easeOut' }}
+                  className="overflow-hidden"
+                >
+                  <FormField
+                    control={form.control}
+                    name="instruct"
+                    render={({ field }) => (
+                      <FormItem className="mt-2">
+                        <FormControl>
+                          <Textarea
+                            {...field}
+                            placeholder="Delivery instructions — e.g. Speak slowly with warmth, Authoritative and clear..."
+                            className="resize-none bg-transparent border border-accent/20 focus-visible:ring-1 focus-visible:ring-accent/40 rounded-2xl text-sm placeholder:text-muted-foreground/60 w-full px-3 py-2"
+                            style={{ minHeight: '60px', maxHeight: '160px' }}
+                            maxLength={500}
+                          />
+                        </FormControl>
+                        <FormMessage className="text-xs" />
+                      </FormItem>
+                    )}
+                  />
+                </motion.div>
+              )}
+            </AnimatePresence>
+
            <AnimatePresence>
              <motion.div
                initial={{ height: 0, opacity: 0 }}
@@ -375,6 +504,12 @@ export function FloatingGenerateBox({
                        <SelectItem value="none" className="text-xs">
                          No effects
                        </SelectItem>
+                        {selectedProfile?.effects_chain &&
+                          selectedProfile.effects_chain.length > 0 && (
+                            <SelectItem value="_profile" className="text-xs">
+                              Profile default
+                            </SelectItem>
+                          )}
                        {effectPresets?.map((preset) => (
                          <SelectItem key={preset.id} value={preset.id} className="text-xs">
                            {preset.name}
@@ -1,4 +1,5 @@
 import { Loader2, Mic } from 'lucide-react';
+import { useEffect } from 'react';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import {
@@ -19,19 +20,45 @@ import {
  SelectValue,
 } from '@/components/ui/select';
 import { Textarea } from '@/components/ui/textarea';
-import { getLanguageOptionsForEngine } from '@/lib/constants/languages';
+import { getLanguageOptionsForEngine, type LanguageCode } from '@/lib/constants/languages';
 import { useGenerationForm } from '@/lib/hooks/useGenerationForm';
 import { useProfile } from '@/lib/hooks/useProfiles';
 import { useUIStore } from '@/stores/uiStore';
-import { EngineModelSelector, getEngineDescription } from './EngineModelSelector';
+import {
+  applyEngineSelection,
+  EngineModelSelector,
+  getEngineDescription,
+} from './EngineModelSelector';
 import { ParalinguisticInput } from './ParalinguisticInput';

+function getEngineSelectValue(engine: string): string {
+  if (engine === 'qwen') return 'qwen:1.7B';
+  if (engine === 'qwen_custom_voice') return 'qwen_custom_voice:1.7B';
+  if (engine === 'tada') return 'tada:1B';
+  return engine;
+}
+
 export function GenerationForm() {
  const selectedProfileId = useUIStore((state) => state.selectedProfileId);
  const { data: selectedProfile } = useProfile(selectedProfileId || '');

  const { form, handleSubmit, isPending } = useGenerationForm();

+  useEffect(() => {
+    if (!selectedProfile) {
+      return;
+    }
+
+    if (selectedProfile.language) {
+      form.setValue('language', selectedProfile.language as LanguageCode);
+    }
+
+    const preferredEngine = selectedProfile.default_engine || selectedProfile.preset_engine;
+    if (preferredEngine) {
+      applyEngineSelection(form, getEngineSelectValue(preferredEngine));
+    }
+  }, [form, selectedProfile]);
+
  async function onSubmit(data: Parameters<typeof handleSubmit>[0]) {
    await handleSubmit(data, selectedProfileId);
  }
@@ -91,7 +118,7 @@ export function GenerationForm() {
              )}
            />

-            {form.watch('engine') === 'qwen' && (
+            {form.watch('engine') === 'qwen_custom_voice' && (
              <FormField
                control={form.control}
                name="instruct"
@@ -118,7 +145,7 @@ export function GenerationForm() {
            <div className="grid gap-4 md:grid-cols-3">
              <FormItem>
                <FormLabel>Model</FormLabel>
-                <EngineModelSelector form={form} />
+                <EngineModelSelector form={form} selectedProfile={selectedProfile} />
                <FormDescription>
                  {getEngineDescription(form.watch('engine') || 'qwen')}
                </FormDescription>
@@ -45,6 +45,7 @@ import { apiClient } from '@/lib/api/client';
 import type { EffectConfig, GenerationVersionResponse, HistoryResponse } from '@/lib/api/types';
 import { BOTTOM_SAFE_AREA_PADDING } from '@/lib/constants/ui';
 import {
+  useClearFailedGenerations,
  useDeleteGeneration,
  useExportGeneration,
  useExportGenerationAudio,
@@ -124,6 +125,8 @@ export function HistoryTable() {
  });

  const deleteGeneration = useDeleteGeneration();
+  const clearFailed = useClearFailedGenerations();
+  const [clearFailedDialogOpen, setClearFailedDialogOpen] = useState(false);
  const exportGeneration = useExportGeneration();
  const exportGenerationAudio = useExportGenerationAudio();
  const importGeneration = useImportGeneration();
@@ -157,11 +160,11 @@ export function HistoryTable() {
  const pendingCount = useGenerationStore((state) => state.pendingGenerationIds.size);
  const prevPendingCountRef = useRef(pendingCount);
  useEffect(() => {
-    if (deleteGeneration.isSuccess || importGeneration.isSuccess) {
+    if (deleteGeneration.isSuccess || importGeneration.isSuccess || clearFailed.isSuccess) {
      setPage(0);
      setAllHistory([]);
    }
-  }, [deleteGeneration.isSuccess, importGeneration.isSuccess]);
+  }, [deleteGeneration.isSuccess, importGeneration.isSuccess, clearFailed.isSuccess]);

  useEffect(() => {
    // A generation finished (pending count decreased) — scroll back to show it
@@ -415,6 +418,27 @@ export function HistoryTable() {

  const history = allHistory;
  const hasMore = allHistory.length < total;
+  const failedCount = history.filter((g) => g.status === 'failed').length;
+
+  const handleClearFailedConfirm = () => {
+    clearFailed.mutate(undefined, {
+      onSuccess: (data) => {
+        setClearFailedDialogOpen(false);
+        toast({
+          title: 'Cleared failed generations',
+          description: `${data.deleted} failed ${data.deleted === 1 ? 'generation' : 'generations'} removed.`,
+        });
+      },
+      onError: (error) => {
+        setClearFailedDialogOpen(false);
+        toast({
+          title: 'Failed to clear',
+          description: error instanceof Error ? error.message : 'Unknown error',
+          variant: 'destructive',
+        });
+      },
+    });
+  };

  return (
    <div className="flex flex-col h-full min-h-0 relative">
@@ -424,6 +448,23 @@ export function HistoryTable() {
        </div>
      ) : (
        <>
+          {failedCount > 0 && (
+            <div className="flex items-center justify-between px-1 pb-2">
+              <span className="text-xs text-muted-foreground">
+                {failedCount} failed {failedCount === 1 ? 'generation' : 'generations'}
+              </span>
+              <Button
+                variant="ghost"
+                size="sm"
+                className="h-7 text-xs text-muted-foreground hover:text-destructive"
+                onClick={() => setClearFailedDialogOpen(true)}
+                disabled={clearFailed.isPending}
+              >
+                <Trash2 className="h-3 w-3 mr-1.5" />
+                {clearFailed.isPending ? 'Clearing...' : 'Clear failed'}
+              </Button>
+            </div>
+          )}
          {isScrolled && (
            <div className="absolute top-0 left-0 right-0 h-16 bg-gradient-to-b from-background to-transparent z-10 pointer-events-none" />
          )}
@@ -569,15 +610,27 @@ export function HistoryTable() {
                      )}

                      {isFailed ? (
-                        <Button
-                          variant="ghost"
-                          size="icon"
-                          className="h-6 w-6 text-muted-foreground/50 hover:bg-muted-foreground/20 hover:text-muted-foreground"
-                          aria-label="Retry generation"
-                          onClick={() => handleRetry(gen.id)}
-                        >
-                          <RotateCcw className="h-2 w-2" />
-                        </Button>
+                        <>
+                          <Button
+                            variant="ghost"
+                            size="icon"
+                            className="h-6 w-6 text-muted-foreground/50 hover:bg-muted-foreground/20 hover:text-muted-foreground"
+                            aria-label="Retry generation"
+                            onClick={() => handleRetry(gen.id)}
+                          >
+                            <RotateCcw className="h-2 w-2" />
+                          </Button>
+                          <Button
+                            variant="ghost"
+                            size="icon"
+                            className="h-6 w-6 text-muted-foreground/50 hover:bg-muted-foreground/20 hover:text-muted-foreground"
+                            aria-label="Delete generation"
+                            disabled={deleteGeneration.isPending}
+                            onClick={() => handleDeleteClick(gen.id, gen.profile_name)}
+                          >
+                            <Trash2 className="h-2 w-2" />
+                          </Button>
+                        </>
                      ) : (
                        <>
                          <DropdownMenu>
@@ -747,6 +800,31 @@ export function HistoryTable() {
        </DialogContent>
      </Dialog>

+      <Dialog open={clearFailedDialogOpen} onOpenChange={setClearFailedDialogOpen}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Clear failed generations</DialogTitle>
+            <DialogDescription>
+              This will permanently delete {failedCount} failed{' '}
+              {failedCount === 1 ? 'generation' : 'generations'} from your history. This cannot be
+              undone.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setClearFailedDialogOpen(false)}>
+              Cancel
+            </Button>
+            <Button
+              variant="destructive"
+              onClick={handleClearFailedConfirm}
+              disabled={clearFailed.isPending}
+            >
+              {clearFailed.isPending ? 'Clearing...' : 'Clear all'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
      <Dialog open={importDialogOpen} onOpenChange={setImportDialogOpen}>
        <DialogContent>
          <DialogHeader>
@@ -66,6 +66,12 @@ const MODEL_DESCRIPTIONS: Record<string, string> = {
    'HumeAI TADA 1B — English speech-language model built on Llama 3.2 1B. Generates 700s+ of coherent audio with synchronized text-acoustic alignment.',
  'tada-3b-ml':
    'HumeAI TADA 3B Multilingual — built on Llama 3.2 3B. Supports 10 languages with high-fidelity voice cloning via text-acoustic dual alignment.',
+  kokoro:
+    'Kokoro 82M by hexgrad. Tiny 82M-parameter TTS that runs at CPU realtime. Supports 8 languages with pre-built voice styles. Apache 2.0 licensed.',
+  'qwen-custom-voice-1.7B':
+    'Qwen3-TTS CustomVoice 1.7B by Alibaba. 9 premium preset voices with instruct-based style control for tone, emotion, and prosody. Supports 10 languages.',
+  'qwen-custom-voice-0.6B':
+    'Qwen3-TTS CustomVoice 0.6B by Alibaba. Lightweight version with the same 9 preset voices and instruct control. Faster inference for lower-end hardware.',
  'whisper-base':
    'Smallest Whisper model (74M parameters). Fast transcription with moderate accuracy.',
  'whisper-small':
@@ -394,9 +400,11 @@ export function ModelManagement() {
    modelStatus?.models.filter(
      (m) =>
        m.model_name.startsWith('qwen-tts') ||
+        m.model_name.startsWith('qwen-custom-voice') ||
        m.model_name.startsWith('luxtts') ||
        m.model_name.startsWith('chatterbox') ||
-        m.model_name.startsWith('tada'),
+        m.model_name.startsWith('tada') ||
+        m.model_name.startsWith('kokoro'),
    ) ?? [];
  const whisperModels = modelStatus?.models.filter((m) => m.model_name.startsWith('whisper')) ?? [];

@@ -12,7 +12,11 @@ interface ModelProgressProps {
  isDownloading?: boolean;
 }

-export function ModelProgress({ modelName, displayName, isDownloading = false }: ModelProgressProps) {
+export function ModelProgress({
+  modelName,
+  displayName,
+  isDownloading = false,
+}: ModelProgressProps) {
  const [progress, setProgress] = useState<ModelProgressType | null>(null);
  const serverUrl = useServerStore((state) => state.serverUrl);

@@ -182,8 +182,8 @@ function ChangelogEntryCard({ entry }: { entry: ChangelogEntry }) {

  return (
    <div className="border-b border-border/50 pb-6">
-      <div className="flex items-baseline gap-3 mb-1">
-        <h3 className="text-sm font-medium">{entry.version}</h3>
+      <div className="flex items-baseline gap-3 mb-3">
+        <h3 className="text-xl font-semibold tracking-tight">{entry.version}</h3>
        {entry.date && <span className="text-xs text-muted-foreground">{entry.date}</span>}
        {entry.version === 'Unreleased' && <Badge variant="outline">dev</Badge>}
      </div>
@@ -87,7 +87,7 @@ export function StoryChatItem({
              alt={`${item.profile_name} avatar`}
              className={cn(
                'h-full w-full object-cover transition-all duration-200',
-                !isCurrentlyPlaying && 'grayscale'
+                !isCurrentlyPlaying && 'grayscale',
              )}
              onError={() => setAvatarError(true)}
            />
@@ -127,7 +127,10 @@ export function StoryChatItem({
              <Play className="mr-2 h-4 w-4" />
              Play from here
            </DropdownMenuItem>
-            <DropdownMenuItem onClick={onRemove} className="text-destructive focus:text-destructive">
+            <DropdownMenuItem
+              onClick={onRemove}
+              className="text-destructive focus:text-destructive"
+            >
              <Trash2 className="mr-2 h-4 w-4" />
              Remove from Story
            </DropdownMenuItem>
@@ -139,15 +142,12 @@ export function StoryChatItem({
 }

 // Sortable wrapper component
-export function SortableStoryChatItem(props: Omit<StoryChatItemProps, 'dragHandleProps' | 'isDragging'>) {
-  const {
-    attributes,
-    listeners,
-    setNodeRef,
-    transform,
-    transition,
-    isDragging,
-  } = useSortable({ id: props.item.generation_id });
+export function SortableStoryChatItem(
+  props: Omit<StoryChatItemProps, 'dragHandleProps' | 'isDragging'>,
+) {
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: props.item.generation_id,
+  });

  const style = {
    transform: CSS.Transform.toString(transform),
@@ -156,11 +156,7 @@ export function SortableStoryChatItem(props: Omit<StoryChatItemProps, 'dragHandl

  return (
    <div ref={setNodeRef} style={style} {...attributes}>
-      <StoryChatItem
-        {...props}
-        dragHandleProps={listeners}
-        isDragging={isDragging}
-      />
+      <StoryChatItem {...props} dragHandleProps={listeners} isDragging={isDragging} />
    </div>
  );
 }
@@ -500,7 +500,7 @@ export function StoryTrackEditor({ storyId, items }: StoryTrackEditorProps) {
  }, [trimmingItem, trimSide, tempTrimValues, storyId, trimItem, toast]);

  const handleSplit = useCallback(() => {
-    if (!selectedClipId) return;
+    if (!selectedClipId || splitItem.isPending) return;

    const item = items.find((i) => i.id === selectedClipId);
    if (!item) return;
@@ -14,12 +14,7 @@ const MemoizedWaveform = memo(function MemoizedWaveform({
    <div className="absolute inset-0 pointer-events-none flex items-center justify-center opacity-30">
      <Visualizer audio={audioStream} autoStart strokeColor="#b39a3d">
        {({ canvasRef }) => (
-          <canvas
-            ref={canvasRef}
-            width={500}
-            height={150}
-            className="w-full h-full"
-          />
+          <canvas ref={canvasRef} width={500} height={150} className="w-full h-full" />
        )}
      </Visualizer>
    </div>
@@ -87,9 +82,7 @@ export function AudioSampleRecording({
        <div className="space-y-4">
          {!isRecording && !file && (
            <div className="relative flex flex-col items-center justify-center gap-4 p-4 border-2 border-dashed rounded-lg min-h-[180px] overflow-hidden">
-              {showWaveform && audioStream && (
-                <MemoizedWaveform audioStream={audioStream} />
-              )}
+              {showWaveform && audioStream && <MemoizedWaveform audioStream={audioStream} />}
              <Button
                type="button"
                onClick={onStart}
@@ -107,9 +100,7 @@ export function AudioSampleRecording({

          {isRecording && (
            <div className="relative flex flex-col items-center justify-center gap-4 p-4 border-2 border-accent rounded-lg bg-accent/5 min-h-[180px] overflow-hidden">
-              {showWaveform && audioStream && (
-                <MemoizedWaveform audioStream={audioStream} />
-              )}
+              {showWaveform && audioStream && <MemoizedWaveform audioStream={audioStream} />}
              <div className="relative z-10 flex items-center gap-4">
                <div className="flex items-center gap-2">
                  <div className="h-3 w-3 rounded-full bg-accent animate-pulse" />
@@ -17,11 +17,18 @@ import { useDeleteProfile, useExportProfile } from '@/lib/hooks/useProfiles';
 import { cn } from '@/lib/utils/cn';
 import { useUIStore } from '@/stores/uiStore';

+/** Human-readable display names for preset engine badges. */
+const ENGINE_DISPLAY_NAMES: Record<string, string> = {
+  kokoro: 'Kokoro',
+  qwen_custom_voice: 'CustomVoice',
+};
+
 interface ProfileCardProps {
  profile: VoiceProfileResponse;
+  disabled?: boolean;
 }

-export function ProfileCard({ profile }: ProfileCardProps) {
+export function ProfileCard({ profile, disabled }: ProfileCardProps) {
  const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);

  const deleteProfile = useDeleteProfile();
@@ -34,6 +41,12 @@ export function ProfileCard({ profile }: ProfileCardProps) {
  const isSelected = selectedProfileId === profile.id;

  const handleSelect = () => {
+    // If disabled but already selected, bounce the selection to re-trigger engine auto-switch
+    if (disabled && isSelected) {
+      setSelectedProfileId(null);
+      setTimeout(() => setSelectedProfileId(profile.id), 0);
+      return;
+    }
    setSelectedProfileId(isSelected ? null : profile.id);
  };

@@ -74,8 +87,9 @@ export function ProfileCard({ profile }: ProfileCardProps) {
    <>
      <Card
        className={cn(
-          'cursor-pointer hover:shadow-md transition-all flex flex-col h-[162px]',
-          isSelected && 'ring-2 ring-accent shadow-md',
+          'cursor-pointer transition-all flex flex-col h-[162px]',
+          disabled ? 'opacity-40 hover:opacity-60' : 'hover:shadow-md',
+          isSelected && !disabled && 'ring-2 ring-accent shadow-md',
        )}
        onClick={handleSelect}
        tabIndex={0}
@@ -97,6 +111,16 @@ export function ProfileCard({ profile }: ProfileCardProps) {
            <Badge variant="outline" className="text-xs h-5 px-1.5 text-muted-foreground">
              {profile.language}
            </Badge>
+            {profile.voice_type === 'preset' && (
+              <Badge variant="secondary" className="text-xs h-5 px-1.5">
+                {ENGINE_DISPLAY_NAMES[profile.preset_engine ?? ''] ?? profile.preset_engine}
+              </Badge>
+            )}
+            {profile.voice_type === 'designed' && (
+              <Badge variant="secondary" className="text-xs h-5 px-1.5">
+                designed
+              </Badge>
+            )}
            {profile.effects_chain && profile.effects_chain.length > 0 && (
              <Sparkles className="h-3.5 w-3.5 text-accent fill-accent" />
            )}
@@ -1,9 +1,11 @@
 import { zodResolver } from '@hookform/resolvers/zod';
-import { Edit2, Mic, Monitor, Upload, X } from 'lucide-react';
+import { useQuery } from '@tanstack/react-query';
+import { Edit2, Mic, Monitor, Music, Upload, X } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
 import { useForm } from 'react-hook-form';
 import * as z from 'zod';
 import { EffectsChainEditor } from '@/components/Effects/EffectsChainEditor';
+import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import {
  Dialog,
@@ -15,6 +17,7 @@ import {
 import {
  Form,
  FormControl,
+  FormDescription,
  FormField,
  FormItem,
  FormLabel,
@@ -32,7 +35,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { Textarea } from '@/components/ui/textarea';
 import { useToast } from '@/components/ui/use-toast';
 import { apiClient } from '@/lib/api/client';
-import type { EffectConfig } from '@/lib/api/types';
+import type { EffectConfig, PresetVoice, VoiceType } from '@/lib/api/types';
 import { LANGUAGE_CODES, LANGUAGE_OPTIONS, type LanguageCode } from '@/lib/constants/languages';
 import { useAudioPlayer } from '@/lib/hooks/useAudioPlayer';
 import { useAudioRecording } from '@/lib/hooks/useAudioRecording';
@@ -40,6 +43,7 @@ import {
  useAddSample,
  useCreateProfile,
  useDeleteAvatar,
+  useDeleteProfile,
  useProfile,
  useUpdateProfile,
  useUploadAvatar,
@@ -56,6 +60,16 @@ import { AudioSampleUpload } from './AudioSampleUpload';
 import { SampleList } from './SampleList';

 const MAX_AUDIO_DURATION_SECONDS = 30;
+const PRESET_ONLY_ENGINES = new Set(['kokoro', 'qwen_custom_voice']);
+const DEFAULT_ENGINE_OPTIONS = [
+  { value: 'qwen', label: 'Qwen3-TTS' },
+  { value: 'qwen_custom_voice', label: 'Qwen CustomVoice' },
+  { value: 'luxtts', label: 'LuxTTS' },
+  { value: 'chatterbox', label: 'Chatterbox' },
+  { value: 'chatterbox_turbo', label: 'Chatterbox Turbo' },
+  { value: 'tada', label: 'TADA' },
+  { value: 'kokoro', label: 'Kokoro 82M' },
+] as const;

 const baseProfileSchema = z.object({
  name: z.string().min(1, 'Name is required').max(100),
@@ -116,20 +130,25 @@ export function ProfileForm() {
  const createProfile = useCreateProfile();
  const updateProfile = useUpdateProfile();
  const addSample = useAddSample();
+  const deleteProfile = useDeleteProfile();
  const uploadAvatar = useUploadAvatar();
  const deleteAvatar = useDeleteAvatar();
  const transcribe = useTranscription();
  const { toast } = useToast();
+  const [voiceSource, setVoiceSource] = useState<'clone' | 'builtin'>('clone');
  const [sampleMode, setSampleMode] = useState<'upload' | 'record' | 'system'>('record');
  const [audioDuration, setAudioDuration] = useState<number | null>(null);
  const [isValidatingAudio, setIsValidatingAudio] = useState(false);
  const [avatarPreview, setAvatarPreview] = useState<string | null>(null);
+  const [selectedPresetEngine, setSelectedPresetEngine] = useState<string>('kokoro');
+  const [selectedPresetVoiceId, setSelectedPresetVoiceId] = useState<string>('');
  const avatarInputRef = useRef<HTMLInputElement>(null);
  const { isPlaying, playPause, cleanup: cleanupAudio } = useAudioPlayer();
  const isCreating = !editingProfileId;
  const serverUrl = useServerStore((state) => state.serverUrl);
  const [profileEffectsChain, setProfileEffectsChain] = useState<EffectConfig[]>([]);
  const [effectsDirty, setEffectsDirty] = useState(false);
+  const [defaultEngine, setDefaultEngine] = useState<string>('');

  const form = useForm<ProfileFormValues>({
    resolver: zodResolver(profileSchema),
@@ -239,6 +258,26 @@ export function ProfileForm() {
    },
  });

+  // Fetch available preset voices for the selected engine
+  const presetEngineToQuery = isCreating
+    ? selectedPresetEngine
+    : (editingProfile?.preset_engine ?? '');
+  const { data: presetVoicesData } = useQuery({
+    queryKey: ['presetVoices', presetEngineToQuery],
+    queryFn: () => apiClient.listPresetVoices(presetEngineToQuery),
+    enabled:
+      !!presetEngineToQuery &&
+      ((voiceSource === 'builtin' && isCreating) ||
+        (!isCreating && editingProfile?.voice_type === 'preset')),
+  });
+  const presetVoices = presetVoicesData?.voices ?? [];
+  const isSampleBasedProfile = isCreating
+    ? voiceSource === 'clone'
+    : editingProfile?.voice_type !== 'preset';
+  const availableDefaultEngines = DEFAULT_ENGINE_OPTIONS.filter(
+    (option) => !isSampleBasedProfile || !PRESET_ONLY_ENGINES.has(option.value),
+  );
+
  // Show recording errors
  useEffect(() => {
    if (recordingError) {
@@ -287,6 +326,7 @@ export function ProfileForm() {
      });
      setProfileEffectsChain(editingProfile.effects_chain ?? []);
      setEffectsDirty(false);
+      setDefaultEngine(editingProfile.default_engine ?? '');
    } else if (profileFormDraft && open) {
      // Restore from draft when opening in create mode
      form.reset({
@@ -326,6 +366,24 @@ export function ProfileForm() {
    }
  }, [editingProfile, profileFormDraft, open, form]);

+  useEffect(() => {
+    if (
+      defaultEngine &&
+      !availableDefaultEngines.some((option) => option.value === defaultEngine)
+    ) {
+      setDefaultEngine('');
+    }
+  }, [availableDefaultEngines, defaultEngine]);
+
+  useEffect(() => {
+    if (!selectedPresetVoiceId) {
+      return;
+    }
+
+    if (!presetVoices.some((voice: PresetVoice) => voice.voice_id === selectedPresetVoiceId)) {
+      setSelectedPresetVoiceId('');
+    }
+  }, [presetVoices, selectedPresetVoiceId]);
  async function handleTranscribe() {
    const file = form.getValues('sampleFile');
    if (!file) {
@@ -415,13 +473,14 @@ export function ProfileForm() {
  async function onSubmit(data: ProfileFormValues) {
    try {
      if (editingProfileId) {
-        // Editing: just update profile
+        // Editing: update profile
        await updateProfile.mutateAsync({
          profileId: editingProfileId,
          data: {
            name: data.name,
            description: data.description,
            language: data.language,
+            default_engine: defaultEngine || undefined,
          },
        });

@@ -464,8 +523,50 @@ export function ProfileForm() {
          title: 'Voice updated',
          description: `"${data.name}" has been updated successfully.`,
        });
+      } else if (voiceSource === 'builtin') {
+        // Creating preset profile from built-in voice
+        if (!selectedPresetVoiceId) {
+          toast({
+            title: 'No voice selected',
+            description: 'Please select a built-in voice.',
+            variant: 'destructive',
+          });
+          return;
+        }
+
+        const profile = await createProfile.mutateAsync({
+          name: data.name,
+          description: data.description,
+          language: data.language,
+          voice_type: 'preset' as VoiceType,
+          preset_engine: selectedPresetEngine,
+          preset_voice_id: selectedPresetVoiceId,
+          default_engine: selectedPresetEngine,
+        });
+
+        // Handle avatar upload if provided
+        if (data.avatarFile) {
+          try {
+            await uploadAvatar.mutateAsync({
+              profileId: profile.id,
+              file: data.avatarFile,
+            });
+          } catch (avatarError) {
+            toast({
+              title: 'Avatar upload failed',
+              description:
+                avatarError instanceof Error ? avatarError.message : 'Failed to upload avatar',
+              variant: 'destructive',
+            });
+          }
+        }
+
+        toast({
+          title: 'Profile created',
+          description: `"${data.name}" has been created with a built-in voice.`,
+        });
      } else {
-        // Creating: require sample file and reference text
+        // Creating cloned profile: require sample file and reference text
        const sampleFile = form.getValues('sampleFile');
        const referenceText = form.getValues('referenceText');

@@ -528,6 +629,7 @@ export function ProfileForm() {
          name: data.name,
          description: data.description,
          language: data.language,
+          default_engine: defaultEngine || undefined,
        });

        // Convert non-WAV uploads to WAV so the backend can always use soundfile.
@@ -572,12 +674,32 @@ export function ProfileForm() {
            description: `"${data.name}" has been created with a sample.`,
          });
        } catch (sampleError) {
-          // Profile was created but sample failed - still show error
+          let rollbackSucceeded = false;
+          try {
+            await deleteProfile.mutateAsync(profile.id);
+            rollbackSucceeded = true;
+          } catch (rollbackError) {
+            toast({
+              title: 'Rollback failed',
+              description:
+                rollbackError instanceof Error
+                  ? rollbackError.message
+                  : 'Created profile could not be removed after sample upload failure.',
+              variant: 'destructive',
+            });
+          }
+
          toast({
            title: 'Failed to add sample',
-            description: `Profile "${data.name}" was created, but failed to add sample: ${sampleError instanceof Error ? sampleError.message : 'Unknown error'}`,
+            description:
+              sampleError instanceof Error
+                ? `${sampleError.message}${rollbackSucceeded ? ' The profile was rolled back.' : ''}`
+                : rollbackSucceeded
+                  ? 'Failed to add sample. The profile was rolled back.'
+                  : 'Failed to add sample.',
            variant: 'destructive',
          });
+          return;
        }
      }

@@ -642,16 +764,16 @@ export function ProfileForm() {

  return (
    <Dialog open={open} onOpenChange={handleOpenChange}>
-      <DialogContent className="max-w-none w-screen h-screen left-0 top-0 translate-x-0 translate-y-0 rounded-none p-6 overflow-y-auto">
-        <div className="max-w-5xl max-h-[85vh] mx-auto my-auto w-full flex flex-col">
+      <DialogContent className="max-w-none w-screen h-screen left-0 top-0 translate-x-0 translate-y-0 rounded-none p-6 overflow-hidden">
+        <div className="max-w-5xl h-[85vh] mx-auto my-auto w-full flex flex-col overflow-hidden">
          <DialogHeader>
            <DialogTitle className="text-2xl">
-              {editingProfileId ? 'Edit Voice' : 'Clone voice'}
+              {editingProfileId ? 'Edit Voice' : 'Create Voice'}
            </DialogTitle>
            <DialogDescription>
              {editingProfileId
                ? 'Update your voice profile details and manage samples.'
-                : 'Create a new voice profile with an audio sample to clone the voice.'}
+                : 'Create a new voice profile from an audio sample or a built-in voice.'}
            </DialogDescription>
            {isCreating && profileFormDraft && (
              <div className="flex items-center gap-2 pt-2">
@@ -682,143 +804,276 @@ export function ProfileForm() {

          <Form {...form}>
            <form onSubmit={form.handleSubmit(onSubmit)} className="flex-1 min-h-0 flex flex-col">
-              <div className="grid gap-6 grid-cols-2 flex-1 overflow-y-auto min-h-0">
+              <div className="grid gap-6 grid-cols-2 flex-1 min-h-0 overflow-hidden">
                {/* Left column: Sample management */}
-                <div className="space-y-4 border-r pr-6">
+                <div className="space-y-4 border-r pr-6 overflow-y-auto min-h-0">
                  {isCreating ? (
                    <>
-                      <Tabs
-                        className="pt-4"
-                        value={sampleMode}
-                        onValueChange={(v) => {
-                          const newMode = v as 'upload' | 'record' | 'system';
-                          // Cancel any active recordings when switching modes
-                          if (isRecording && newMode !== 'record') {
-                            cancelRecording();
-                          }
-                          if (isSystemRecording && newMode !== 'system') {
-                            cancelSystemRecording();
-                          }
-                          setSampleMode(newMode);
-                        }}
-                      >
-                        <TabsList
-                          className={`grid w-full ${platform.metadata.isTauri && isSystemAudioSupported ? 'grid-cols-3' : 'grid-cols-2'}`}
-                        >
-                          <TabsTrigger value="upload" className="flex items-center gap-2">
-                            <Upload className="h-4 w-4 shrink-0" />
-                            Upload
-                          </TabsTrigger>
-                          <TabsTrigger value="record" className="flex items-center gap-2">
-                            <Mic className="h-4 w-4 shrink-0" />
-                            Record
-                          </TabsTrigger>
-                          {platform.metadata.isTauri && isSystemAudioSupported && (
-                            <TabsTrigger value="system" className="flex items-center gap-2">
-                              <Monitor className="h-4 w-4 shrink-0" />
-                              System Audio
-                            </TabsTrigger>
-                          )}
-                        </TabsList>
+                      {/* Voice source selector */}
+                      <div className="flex pt-4 pb-2">
+                        <div className="inline-flex rounded-lg border border-border p-0.5 bg-muted/50">
+                          <button
+                            type="button"
+                            onClick={() => setVoiceSource('clone')}
+                            className={`inline-flex items-center gap-2 px-3 py-1.5 text-sm rounded-md transition-colors ${
+                              voiceSource === 'clone'
+                                ? 'bg-accent text-accent-foreground shadow-sm'
+                                : 'text-muted-foreground hover:text-foreground'
+                            }`}
+                          >
+                            <Mic className="h-3.5 w-3.5" />
+                            Clone from audio
+                          </button>
+                          <button
+                            type="button"
+                            onClick={() => setVoiceSource('builtin')}
+                            className={`inline-flex items-center gap-2 px-3 py-1.5 text-sm rounded-md transition-colors ${
+                              voiceSource === 'builtin'
+                                ? 'bg-accent text-accent-foreground shadow-sm'
+                                : 'text-muted-foreground hover:text-foreground'
+                            }`}
+                          >
+                            <Music className="h-3.5 w-3.5" />
+                            Built-in voice
+                          </button>
+                        </div>
+                      </div>

-                        <TabsContent value="upload" className="space-y-4">
-                          <FormField
-                            control={form.control}
-                            name="sampleFile"
-                            render={({ field: { onChange, name } }) => (
-                              <AudioSampleUpload
-                                file={selectedFile}
-                                onFileChange={onChange}
-                                onTranscribe={handleTranscribe}
-                                onPlayPause={handlePlayPause}
-                                isPlaying={isPlaying}
-                                isValidating={isValidatingAudio}
-                                isTranscribing={transcribe.isPending}
-                                isDisabled={
-                                  audioDuration !== null &&
-                                  audioDuration > MAX_AUDIO_DURATION_SECONDS
-                                }
-                                fieldName={name}
-                              />
-                            )}
-                          />
-                        </TabsContent>
+                      {voiceSource === 'builtin' ? (
+                        <div className="space-y-4">
+                          <FormDescription>
+                            Choose a pre-built voice. These don't require an audio sample.
+                          </FormDescription>

-                        <TabsContent value="record" className="space-y-4">
-                          <FormField
-                            control={form.control}
-                            name="sampleFile"
-                            render={() => (
-                              <AudioSampleRecording
-                                file={selectedFile}
-                                isRecording={isRecording}
-                                duration={duration}
-                                onStart={startRecording}
-                                onStop={stopRecording}
-                                onCancel={handleCancelRecording}
-                                onTranscribe={handleTranscribe}
-                                onPlayPause={handlePlayPause}
-                                isPlaying={isPlaying}
-                                isTranscribing={transcribe.isPending}
-                              />
-                            )}
-                          />
-                        </TabsContent>
-
-                        {platform.metadata.isTauri && isSystemAudioSupported && (
-                          <TabsContent value="system" className="space-y-4">
-                            <FormField
-                              control={form.control}
-                              name="sampleFile"
-                              render={() => (
-                                <AudioSampleSystem
-                                  file={selectedFile}
-                                  isRecording={isSystemRecording}
-                                  duration={systemDuration}
-                                  onStart={startSystemRecording}
-                                  onStop={stopSystemRecording}
-                                  onCancel={handleCancelRecording}
-                                  onTranscribe={handleTranscribe}
-                                  onPlayPause={handlePlayPause}
-                                  isPlaying={isPlaying}
-                                  isTranscribing={transcribe.isPending}
-                                />
-                              )}
-                            />
-                          </TabsContent>
-                        )}
-                      </Tabs>
-
-                      <FormField
-                        control={form.control}
-                        name="referenceText"
-                        render={({ field }) => (
+                          {/* Engine selector */}
                          <FormItem>
-                            <FormLabel>Reference Text</FormLabel>
-                            <FormControl>
-                              <Textarea
-                                placeholder="Enter the exact text spoken in the audio..."
-                                className="min-h-[100px]"
-                                {...field}
-                              />
-                            </FormControl>
-                            <FormMessage />
+                            <FormLabel>Engine</FormLabel>
+                            <Select
+                              value={selectedPresetEngine}
+                              onValueChange={setSelectedPresetEngine}
+                            >
+                              <FormControl>
+                                <SelectTrigger>
+                                  <SelectValue />
+                                </SelectTrigger>
+                              </FormControl>
+                              <SelectContent>
+                                <SelectItem value="kokoro">Kokoro 82M</SelectItem>
+                                <SelectItem value="qwen_custom_voice">Qwen CustomVoice</SelectItem>
+                              </SelectContent>
+                            </Select>
                          </FormItem>
-                        )}
-                      />
+
+                          {/* Voice picker */}
+                          <FormItem>
+                            <FormLabel>Voice</FormLabel>
+                            <div className="grid grid-cols-2 gap-1.5 max-h-[340px] overflow-y-auto pr-1">
+                              {presetVoices.map((voice: PresetVoice) => (
+                                <button
+                                  key={voice.voice_id}
+                                  type="button"
+                                  onClick={() => {
+                                    setSelectedPresetVoiceId(voice.voice_id);
+                                    // Auto-set language from voice
+                                    if (voice.language) {
+                                      form.setValue('language', voice.language as LanguageCode);
+                                    }
+                                  }}
+                                  className={`text-left px-3 py-2 rounded-md border text-sm transition-colors ${
+                                    selectedPresetVoiceId === voice.voice_id
+                                      ? 'border-accent bg-accent/10 text-accent-foreground'
+                                      : 'border-border hover:bg-muted'
+                                  }`}
+                                >
+                                  <div className="font-medium">{voice.name}</div>
+                                  <div className="flex gap-1.5 mt-0.5">
+                                    <Badge variant="outline" className="text-[10px] h-4 px-1">
+                                      {voice.gender}
+                                    </Badge>
+                                    <Badge variant="outline" className="text-[10px] h-4 px-1">
+                                      {voice.language}
+                                    </Badge>
+                                  </div>
+                                </button>
+                              ))}
+                            </div>
+                          </FormItem>
+                        </div>
+                      ) : (
+                        <>
+                          <Tabs
+                            className="pt-0"
+                            value={sampleMode}
+                            onValueChange={(v) => {
+                              const newMode = v as 'upload' | 'record' | 'system';
+                              // Cancel any active recordings when switching modes
+                              if (isRecording && newMode !== 'record') {
+                                cancelRecording();
+                              }
+                              if (isSystemRecording && newMode !== 'system') {
+                                cancelSystemRecording();
+                              }
+                              setSampleMode(newMode);
+                            }}
+                          >
+                            <TabsList
+                              className={`grid w-full ${platform.metadata.isTauri && isSystemAudioSupported ? 'grid-cols-3' : 'grid-cols-2'}`}
+                            >
+                              <TabsTrigger value="upload" className="flex items-center gap-2">
+                                <Upload className="h-4 w-4 shrink-0" />
+                                Upload
+                              </TabsTrigger>
+                              <TabsTrigger value="record" className="flex items-center gap-2">
+                                <Mic className="h-4 w-4 shrink-0" />
+                                Record
+                              </TabsTrigger>
+                              {platform.metadata.isTauri && isSystemAudioSupported && (
+                                <TabsTrigger value="system" className="flex items-center gap-2">
+                                  <Monitor className="h-4 w-4 shrink-0" />
+                                  System Audio
+                                </TabsTrigger>
+                              )}
+                            </TabsList>
+
+                            <TabsContent value="upload" className="space-y-4">
+                              <FormField
+                                control={form.control}
+                                name="sampleFile"
+                                render={({ field: { onChange, name } }) => (
+                                  <AudioSampleUpload
+                                    file={selectedFile}
+                                    onFileChange={onChange}
+                                    onTranscribe={handleTranscribe}
+                                    onPlayPause={handlePlayPause}
+                                    isPlaying={isPlaying}
+                                    isValidating={isValidatingAudio}
+                                    isTranscribing={transcribe.isPending}
+                                    isDisabled={
+                                      audioDuration !== null &&
+                                      audioDuration > MAX_AUDIO_DURATION_SECONDS
+                                    }
+                                    fieldName={name}
+                                  />
+                                )}
+                              />
+                            </TabsContent>
+
+                            <TabsContent value="record" className="space-y-4">
+                              <FormField
+                                control={form.control}
+                                name="sampleFile"
+                                render={() => (
+                                  <AudioSampleRecording
+                                    file={selectedFile}
+                                    isRecording={isRecording}
+                                    duration={duration}
+                                    onStart={startRecording}
+                                    onStop={stopRecording}
+                                    onCancel={handleCancelRecording}
+                                    onTranscribe={handleTranscribe}
+                                    onPlayPause={handlePlayPause}
+                                    isPlaying={isPlaying}
+                                    isTranscribing={transcribe.isPending}
+                                  />
+                                )}
+                              />
+                            </TabsContent>
+
+                            {platform.metadata.isTauri && isSystemAudioSupported && (
+                              <TabsContent value="system" className="space-y-4">
+                                <FormField
+                                  control={form.control}
+                                  name="sampleFile"
+                                  render={() => (
+                                    <AudioSampleSystem
+                                      file={selectedFile}
+                                      isRecording={isSystemRecording}
+                                      duration={systemDuration}
+                                      onStart={startSystemRecording}
+                                      onStop={stopSystemRecording}
+                                      onCancel={handleCancelRecording}
+                                      onTranscribe={handleTranscribe}
+                                      onPlayPause={handlePlayPause}
+                                      isPlaying={isPlaying}
+                                      isTranscribing={transcribe.isPending}
+                                    />
+                                  )}
+                                />
+                              </TabsContent>
+                            )}
+                          </Tabs>
+
+                          <FormField
+                            control={form.control}
+                            name="referenceText"
+                            render={({ field }) => (
+                              <FormItem>
+                                <FormLabel>Reference Text</FormLabel>
+                                <FormControl>
+                                  <Textarea
+                                    placeholder="Enter the exact text spoken in the audio..."
+                                    className="min-h-[100px]"
+                                    {...field}
+                                  />
+                                </FormControl>
+                                <FormMessage />
+                              </FormItem>
+                            )}
+                          />
+                        </>
+                      )}
                    </>
                  ) : (
-                    // Show sample list when editing
-                    editingProfileId && (
+                    // Editing mode
+                    editingProfileId &&
+                    editingProfile &&
+                    (editingProfile.voice_type === 'preset' ? (
+                      <div className="space-y-4 pt-4">
+                        <div className="rounded-lg border border-border p-4 space-y-3">
+                          <div className="text-sm font-medium text-muted-foreground">
+                            Built-in Voice
+                          </div>
+                          <div className="flex items-center gap-3">
+                            <div className="text-lg font-semibold">
+                              {presetVoices.find(
+                                (v: PresetVoice) => v.voice_id === editingProfile.preset_voice_id,
+                              )?.name ?? editingProfile.preset_voice_id}
+                            </div>
+                            <Badge variant="secondary" className="text-xs">
+                              {editingProfile.preset_engine}
+                            </Badge>
+                          </div>
+                          {(() => {
+                            const voice = presetVoices.find(
+                              (v: PresetVoice) => v.voice_id === editingProfile.preset_voice_id,
+                            );
+                            return voice ? (
+                              <div className="flex gap-1.5">
+                                <Badge variant="outline" className="text-xs">
+                                  {voice.gender}
+                                </Badge>
+                                <Badge variant="outline" className="text-xs">
+                                  {voice.language}
+                                </Badge>
+                              </div>
+                            ) : null;
+                          })()}
+                        </div>
+                        <p className="text-xs text-muted-foreground">
+                          This profile uses a built-in voice. The voice cannot be changed after
+                          creation.
+                        </p>
+                      </div>
+                    ) : (
                      <div>
                        <SampleList profileId={editingProfileId} />
                      </div>
-                    )
+                    ))
                  )}
                </div>

                {/* Right column: Profile info */}
-                <div className="space-y-4">
+                <div className="space-y-4 overflow-y-auto min-h-0">
                  {/* Avatar Upload */}
                  <FormField
                    control={form.control}
@@ -924,6 +1179,36 @@ export function ProfileForm() {
                    )}
                  />

+                  <FormItem>
+                    <FormLabel>Default Engine</FormLabel>
+                    <Select
+                      value={defaultEngine || '_none'}
+                      onValueChange={(v) => {
+                        setDefaultEngine(v === '_none' ? '' : v);
+                      }}
+                      disabled={
+                        voiceSource === 'builtin' || editingProfile?.voice_type === 'preset'
+                      }
+                    >
+                      <FormControl>
+                        <SelectTrigger>
+                          <SelectValue placeholder="No preference" />
+                        </SelectTrigger>
+                      </FormControl>
+                      <SelectContent>
+                        <SelectItem value="_none">No preference</SelectItem>
+                        {availableDefaultEngines.map((option) => (
+                          <SelectItem key={option.value} value={option.value}>
+                            {option.label}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                    <p className="text-xs text-muted-foreground">
+                      Auto-selects this engine when the profile is chosen.
+                    </p>
+                  </FormItem>
+
                  {editingProfileId && (
                    <div className="space-y-2">
                      <FormLabel>Default Effects</FormLabel>
@@ -1,4 +1,5 @@
-import { Mic, Sparkles } from 'lucide-react';
+import { Info, Mic, Sparkles } from 'lucide-react';
+import { useEffect, useRef } from 'react';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
 import { useProfiles } from '@/lib/hooks/useProfiles';
@@ -6,9 +7,36 @@ import { useUIStore } from '@/stores/uiStore';
 import { ProfileCard } from './ProfileCard';
 import { ProfileForm } from './ProfileForm';

+/** Engines that use preset (built-in) voices instead of cloned profiles. */
+const PRESET_ENGINES = new Set(['kokoro', 'qwen_custom_voice']);
+
 export function ProfileList() {
  const { data: profiles, isLoading, error } = useProfiles();
  const setDialogOpen = useUIStore((state) => state.setProfileDialogOpen);
+  const selectedEngine = useUIStore((state) => state.selectedEngine);
+  const selectedProfileId = useUIStore((state) => state.selectedProfileId);
+  const cardRefs = useRef<Map<string, HTMLDivElement>>(new Map());
+
+  // Scroll to the selected profile after engine/sort changes
+  useEffect(() => {
+    if (!selectedProfileId) return;
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+    const rafId = requestAnimationFrame(() => {
+      const el = cardRefs.current.get(selectedProfileId);
+      if (!el) return;
+
+      // Temporarily apply scroll-margin so it doesn't land flush at the top
+      el.style.scrollMarginTop = '180px';
+      el.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+      timeoutId = setTimeout(() => {
+        el.style.scrollMarginTop = '';
+      }, 500);
+    });
+    return () => {
+      cancelAnimationFrame(rafId);
+      if (timeoutId) clearTimeout(timeoutId);
+    };
+  }, [selectedProfileId, selectedEngine]);

  if (isLoading) {
    return null;
@@ -23,6 +51,20 @@ export function ProfileList() {
  }

  const allProfiles = profiles || [];
+  const isPresetEngine = PRESET_ENGINES.has(selectedEngine);
+
+  /** Whether a profile is supported by the currently selected engine. */
+  const isSupported = (p: (typeof allProfiles)[number]) =>
+    isPresetEngine
+      ? p.voice_type === 'preset' && p.preset_engine === selectedEngine
+      : p.voice_type !== 'preset';
+
+  // Sort so supported profiles come first
+  const sortedProfiles = [...allProfiles].sort(
+    (a, b) => (isSupported(a) ? 0 : 1) - (isSupported(b) ? 0 : 1),
+  );
+
+  const hasUnsupported = sortedProfiles.some((p) => !isSupported(p));

  return (
    <div className="flex flex-col">
@@ -42,11 +84,24 @@ export function ProfileList() {
          </Card>
        ) : (
          <div className="flex gap-4 overflow-x-auto p-1 pb-1 lg:grid lg:grid-cols-3 lg:auto-rows-auto lg:overflow-x-visible lg:pb-[150px]">
-            {allProfiles.map((profile) => (
-              <div key={profile.id} className="shrink-0 w-[200px] lg:w-auto lg:shrink">
-                <ProfileCard profile={profile} />
+            {sortedProfiles.map((profile) => (
+              <div
+                key={profile.id}
+                className="shrink-0 w-[200px] lg:w-auto lg:shrink"
+                ref={(el) => {
+                  if (el) cardRefs.current.set(profile.id, el);
+                  else cardRefs.current.delete(profile.id);
+                }}
+              >
+                <ProfileCard profile={profile} disabled={!isSupported(profile)} />
              </div>
            ))}
+            {hasUnsupported && (
+              <div className="col-span-full flex items-center gap-2 text-xs text-muted-foreground py-2">
+                <Info className="h-3.5 w-3.5 shrink-0" />
+                <span>Only supported voice profiles can be selected for the current model.</span>
+              </div>
+            )}
          </div>
        )}
      </div>
@@ -111,4 +111,4 @@ export {
  AlertDialogDescription,
  AlertDialogAction,
  AlertDialogCancel,
-};
+};
@@ -17,6 +17,7 @@ import type {
  HistoryResponse,
  ModelDownloadRequest,
  ModelStatusListResponse,
+  PresetVoice,
  ProfileSampleResponse,
  StoryCreate,
  StoryDetailResponse,
@@ -97,6 +98,10 @@ class ApiClient {
    return this.request<VoiceProfileResponse>(`/profiles/${profileId}`);
  }

+  async listPresetVoices(engine: string): Promise<{ engine: string; voices: PresetVoice[] }> {
+    return this.request<{ engine: string; voices: PresetVoice[] }>(`/profiles/presets/${engine}`);
+  }
+
  async updateProfile(profileId: string, data: VoiceProfileCreate): Promise<VoiceProfileResponse> {
    return this.request<VoiceProfileResponse>(`/profiles/${profileId}`, {
      method: 'PUT',
@@ -265,6 +270,12 @@ class ApiClient {
    });
  }

+  async clearFailedGenerations(): Promise<{ deleted: number }> {
+    return this.request<{ deleted: number }>(`/history/failed`, {
+      method: 'DELETE',
+    });
+  }
+
  async exportGeneration(generationId: string): Promise<Blob> {
    const url = `${this.getBaseUrl()}/history/${generationId}/export`;
    const response = await fetch(url);
@@ -1,10 +1,17 @@
 // API Types matching backend Pydantic models
 import type { LanguageCode } from '@/lib/constants/languages';

+export type VoiceType = 'cloned' | 'preset' | 'designed';
+
 export interface VoiceProfileCreate {
  name: string;
  description?: string;
  language: LanguageCode;
+  voice_type?: VoiceType;
+  preset_engine?: string;
+  preset_voice_id?: string;
+  design_prompt?: string;
+  default_engine?: string;
 }

 export interface VoiceProfileResponse {
@@ -14,12 +21,24 @@ export interface VoiceProfileResponse {
  language: string;
  avatar_path?: string;
  effects_chain?: EffectConfig[];
+  voice_type: VoiceType;
+  preset_engine?: string;
+  preset_voice_id?: string;
+  design_prompt?: string;
+  default_engine?: string;
  generation_count: number;
  sample_count: number;
  created_at: string;
  updated_at: string;
 }

+export interface PresetVoice {
+  voice_id: string;
+  name: string;
+  gender: 'male' | 'female';
+  language: string;
+}
+
 export interface ProfileSampleCreate {
  reference_text: string;
 }
@@ -43,7 +62,14 @@ export interface GenerationRequest {
  language: LanguageCode;
  seed?: number;
  model_size?: '1.7B' | '0.6B' | '1B' | '3B';
-  engine?: 'qwen' | 'luxtts' | 'chatterbox' | 'chatterbox_turbo' | 'tada';
+  engine?:
+    | 'qwen'
+    | 'qwen_custom_voice'
+    | 'luxtts'
+    | 'chatterbox'
+    | 'chatterbox_turbo'
+    | 'tada'
+    | 'kokoro';
  instruct?: string;
  max_chunk_chars?: number;
  crossfade_ms?: number;
@@ -5,6 +5,7 @@
 * LuxTTS is English-only.
 * Chatterbox Multilingual supports 23 languages.
 * Chatterbox Turbo is English-only.
+ * Kokoro supports 8 languages.
 */

 /** All languages that any engine supports. */
@@ -67,6 +68,8 @@ export const ENGINE_LANGUAGES: Record<string, readonly LanguageCode[]> = {
  ],
  chatterbox_turbo: ['en'],
  tada: ['en', 'ar', 'zh', 'de', 'es', 'fr', 'it', 'ja', 'pl', 'pt'],
+  kokoro: ['en', 'es', 'fr', 'hi', 'it', 'pt', 'ja', 'zh'],
+  qwen_custom_voice: ['zh', 'en', 'ja', 'ko', 'de', 'fr', 'ru', 'pt', 'es', 'it'],
 } as const;

 /** Helper: get language options for a given engine. */
@@ -10,6 +10,7 @@ import { useGeneration } from '@/lib/hooks/useGeneration';
 import { useModelDownloadToast } from '@/lib/hooks/useModelDownloadToast';
 import { useGenerationStore } from '@/stores/generationStore';
 import { useServerStore } from '@/stores/serverStore';
+import { useUIStore } from '@/stores/uiStore';

 const generationSchema = z.object({
  text: z.string().min(1, '').max(50000),
@@ -17,7 +18,17 @@ const generationSchema = z.object({
  seed: z.number().int().optional(),
  modelSize: z.enum(['1.7B', '0.6B', '1B', '3B']).optional(),
  instruct: z.string().max(500).optional(),
-  engine: z.enum(['qwen', 'luxtts', 'chatterbox', 'chatterbox_turbo', 'tada']).optional(),
+  engine: z
+    .enum([
+      'qwen',
+      'qwen_custom_voice',
+      'luxtts',
+      'chatterbox',
+      'chatterbox_turbo',
+      'tada',
+      'kokoro',
+    ])
+    .optional(),
 });

 export type GenerationFormValues = z.infer<typeof generationSchema>;
@@ -35,6 +46,7 @@ export function useGenerationForm(options: UseGenerationFormOptions = {}) {
  const maxChunkChars = useServerStore((state) => state.maxChunkChars);
  const crossfadeMs = useServerStore((state) => state.crossfadeMs);
  const normalizeAudio = useServerStore((state) => state.normalizeAudio);
+  const selectedEngine = useUIStore((state) => state.selectedEngine);
  const [downloadingModelName, setDownloadingModelName] = useState<string | null>(null);
  const [downloadingDisplayName, setDownloadingDisplayName] = useState<string | null>(null);

@@ -52,7 +64,7 @@ export function useGenerationForm(options: UseGenerationFormOptions = {}) {
      seed: undefined,
      modelSize: '1.7B',
      instruct: '',
-      engine: 'qwen',
+      engine: (selectedEngine as GenerationFormValues['engine']) || 'qwen',
      ...options.defaultValues,
    },
  });
@@ -83,7 +95,11 @@ export function useGenerationForm(options: UseGenerationFormOptions = {}) {
                ? data.modelSize === '3B'
                  ? 'tada-3b-ml'
                  : 'tada-1b'
-                : `qwen-tts-${data.modelSize}`;
+                : engine === 'kokoro'
+                  ? 'kokoro'
+                  : engine === 'qwen_custom_voice'
+                    ? `qwen-custom-voice-${data.modelSize}`
+                    : `qwen-tts-${data.modelSize}`;
      const displayName =
        engine === 'luxtts'
          ? 'LuxTTS'
@@ -95,9 +111,15 @@ export function useGenerationForm(options: UseGenerationFormOptions = {}) {
                ? data.modelSize === '3B'
                  ? 'TADA 3B Multilingual'
                  : 'TADA 1B'
-                : data.modelSize === '1.7B'
-                  ? 'Qwen TTS 1.7B'
-                  : 'Qwen TTS 0.6B';
+                : engine === 'kokoro'
+                  ? 'Kokoro 82M'
+                  : engine === 'qwen_custom_voice'
+                    ? data.modelSize === '1.7B'
+                      ? 'Qwen CustomVoice 1.7B'
+                      : 'Qwen CustomVoice 0.6B'
+                    : data.modelSize === '1.7B'
+                      ? 'Qwen TTS 1.7B'
+                      : 'Qwen TTS 0.6B';

      // Check if model needs downloading
      try {
@@ -112,7 +134,11 @@ export function useGenerationForm(options: UseGenerationFormOptions = {}) {
        console.error('Failed to check model status:', error);
      }

-      const hasModelSizes = engine === 'qwen' || engine === 'tada';
+      const hasModelSizes =
+        engine === 'qwen' || engine === 'qwen_custom_voice' || engine === 'tada';
+      // Only Qwen CustomVoice actually honors the instruct kwarg at model level.
+      // Base Qwen3-TTS accepts the kwarg but ignores it.
+      const supportsInstruct = engine === 'qwen_custom_voice';
      const effectsChain = options.getEffectsChain?.();
      // This now returns immediately with status="generating"
      const result = await generation.mutateAsync({
@@ -122,7 +148,7 @@ export function useGenerationForm(options: UseGenerationFormOptions = {}) {
        seed: data.seed,
        model_size: hasModelSizes ? data.modelSize : undefined,
        engine,
-        instruct: engine === 'qwen' ? data.instruct || undefined : undefined,
+        instruct: supportsInstruct ? data.instruct || undefined : undefined,
        max_chunk_chars: maxChunkChars,
        crossfade_ms: crossfadeMs,
        normalize: normalizeAudio,
@@ -29,6 +29,17 @@ export function useDeleteGeneration() {
  });
 }

+export function useClearFailedGenerations() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: () => apiClient.clearFailedGenerations(),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['history'] });
+    },
+  });
+}
+
 export function useExportGeneration() {
  const platform = usePlatform();

@@ -131,7 +131,8 @@ export function useModelDownloadToast({
                )}
              </div>
            ),
-            duration: progress.status === 'complete' || progress.status === 'error' ? 5000 : Infinity,
+            duration:
+              progress.status === 'complete' || progress.status === 'error' ? 5000 : Infinity,
          });

          // Close connection and dismiss toast on completion or error
@@ -26,8 +26,24 @@ export function useSystemAudioCapture({

  // Check if system audio capture is supported
  useEffect(() => {
-    const supported = platform.audio.isSystemAudioSupported();
-    setIsSupported(supported);
+    let isActive = true;
+
+    void platform.audio
+      .isSystemAudioSupported()
+      .then((supported) => {
+        if (isActive) {
+          setIsSupported(supported);
+        }
+      })
+      .catch(() => {
+        if (isActive) {
+          setIsSupported(false);
+        }
+      });
+
+    return () => {
+      isActive = false;
+    };
  }, [platform]);

  const startRecording = useCallback(async () => {
@@ -0,0 +1,19 @@
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * Shared QueryClient instance used across the app.
+ *
+ * Extracted into its own side-effect-free module so it can be imported from
+ * both the React bootstrap (main.tsx) and non-React code (stores, utilities)
+ * without pulling in ReactDOM or other bootstrap side effects.
+ */
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      gcTime: 1000 * 60 * 10, // 10 minutes (formerly cacheTime)
+      retry: 1,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
@@ -1,20 +1,10 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { QueryClientProvider } from '@tanstack/react-query';
 // import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import App from './App';
 import './index.css';
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1000 * 60 * 5, // 5 minutes
-      gcTime: 1000 * 60 * 10, // 10 minutes (formerly cacheTime)
-      retry: 1,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
+import { queryClient } from './lib/queryClient';

 ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
@@ -9,11 +9,7 @@ export interface PlatformProviderProps {
 }

 export function PlatformProvider({ platform, children }: PlatformProviderProps) {
-  return (
-    <PlatformContext.Provider value={platform}>
-      {children}
-    </PlatformContext.Provider>
-  );
+  return <PlatformContext.Provider value={platform}>{children}</PlatformContext.Provider>;
 }

 export function usePlatform(): Platform {
@@ -42,7 +42,7 @@ export interface AudioDevice {
 }

 export interface PlatformAudio {
-  isSystemAudioSupported(): boolean;
+  isSystemAudioSupported(): Promise<boolean>;
  startSystemAudioCapture(maxDurationSecs: number): Promise<void>;
  stopSystemAudioCapture(): Promise<Blob>;
  listOutputDevices(): Promise<AudioDevice[]>;
@@ -1,5 +1,6 @@
 import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
+import { queryClient } from '@/lib/queryClient';

 interface ServerStore {
  serverUrl: string;
@@ -30,11 +31,25 @@ interface ServerStore {
  setCustomModelsDir: (dir: string | null) => void;
 }

+/**
+ * Invalidate all React Query caches so stale data from the previous
+ * server is not shown. Called when the server URL changes.
+ */
+function invalidateAllServerData() {
+  queryClient.invalidateQueries();
+}
+
 export const useServerStore = create<ServerStore>()(
  persist(
-    (set) => ({
+    (set, get) => ({
      serverUrl: 'http://127.0.0.1:17493',
-      setServerUrl: (url) => set({ serverUrl: url }),
+      setServerUrl: (url) => {
+        const prev = get().serverUrl;
+        set({ serverUrl: url });
+        if (url !== prev) {
+          invalidateAllServerData();
+        }
+      },

      isConnected: false,
      setIsConnected: (connected) => set({ isConnected: connected }),
@@ -31,6 +31,10 @@ interface UIStore {
  selectedProfileId: string | null;
  setSelectedProfileId: (id: string | null) => void;

+  // Currently selected engine (synced from generation form)
+  selectedEngine: string;
+  setSelectedEngine: (engine: string) => void;
+
  // Selected voice in Voices tab inspector
  selectedVoiceId: string | null;
  setSelectedVoiceId: (id: string | null) => void;
@@ -59,6 +63,9 @@ export const useUIStore = create<UIStore>((set) => ({
  selectedProfileId: null,
  setSelectedProfileId: (id) => set({ selectedProfileId: id }),

+  selectedEngine: 'qwen',
+  setSelectedEngine: (engine) => set({ selectedEngine: engine }),
+
  selectedVoiceId: null,
  setSelectedVoiceId: (id) => set({ selectedVoiceId: id }),

@@ -1,3 +1,3 @@
 # Backend package

-__version__ = "0.3.1"
+__version__ = "0.4.0"
@@ -135,7 +135,7 @@ def _mount_frontend(application: FastAPI) -> None:
    async def serve_spa(full_path: str):
        file_path = (frontend_dir / full_path).resolve()
        # Guard against path traversal — only serve files inside frontend_dir
-        if full_path and file_path.is_file() and str(file_path).startswith(str(frontend_dir)):
+        if full_path and file_path.is_file() and file_path.is_relative_to(frontend_dir):
            return FileResponse(file_path)
        return FileResponse(frontend_dir / "index.html", media_type="text/html")

@@ -146,15 +146,36 @@ def _get_gpu_status() -> str:
    """Return a human-readable string describing GPU availability."""
    backend_type = get_backend_type()
    if torch.cuda.is_available():
+        from .backends.base import check_cuda_compatibility
+
        device_name = torch.cuda.get_device_name(0)
+        compatible, _warning = check_cuda_compatibility()
        is_rocm = hasattr(torch.version, "hip") and torch.version.hip is not None
        if is_rocm:
-            return f"ROCm ({device_name})"
-        return f"CUDA ({device_name})"
+            label = f"ROCm ({device_name})"
+        else:
+            label = f"CUDA ({device_name})"
+        if not compatible:
+            label += " [UNSUPPORTED - see logs]"
+        return label
    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
        return "MPS (Apple Silicon)"
    elif backend_type == "mlx":
        return "Metal (Apple Silicon via MLX)"
+
+    # Intel XPU (Arc / Data Center) via IPEX
+    try:
+        import intel_extension_for_pytorch  # noqa: F401
+
+        if hasattr(torch, "xpu") and torch.xpu.is_available():
+            try:
+                xpu_name = torch.xpu.get_device_name(0)
+            except Exception:
+                xpu_name = "Intel GPU"
+            return f"XPU ({xpu_name})"
+    except ImportError:
+        pass
+
    return "None (CPU only)"


@@ -216,6 +237,13 @@ def _register_lifecycle(application: FastAPI) -> None:
        logger.info("Backend: %s", backend_type.upper())
        logger.info("GPU: %s", _get_gpu_status())

+        # Warn if GPU architecture is not supported by this PyTorch build
+        from .backends.base import check_cuda_compatibility
+
+        _compatible, _cuda_warning = check_cuda_compatibility()
+        if not _compatible:
+            logger.warning("GPU COMPATIBILITY: %s", _cuda_warning)
+
        from .services.cuda import check_and_update_cuda_binary

        create_background_task(check_and_update_cuda_binary())
@@ -163,10 +163,12 @@ _stt_backend: Optional[STTBackend] = None
 # The factory function uses this for the if/elif chain; the model configs live on the backend classes.
 TTS_ENGINES = {
    "qwen": "Qwen TTS",
+    "qwen_custom_voice": "Qwen CustomVoice",
    "luxtts": "LuxTTS",
    "chatterbox": "Chatterbox TTS",
    "chatterbox_turbo": "Chatterbox Turbo",
    "tada": "TADA",
+    "kokoro": "Kokoro",
 }


@@ -204,6 +206,32 @@ def _get_qwen_model_configs() -> list[ModelConfig]:
    ]


+def _get_qwen_custom_voice_configs() -> list[ModelConfig]:
+    """Return Qwen CustomVoice model configs."""
+    return [
+        ModelConfig(
+            model_name="qwen-custom-voice-1.7B",
+            display_name="Qwen CustomVoice 1.7B",
+            engine="qwen_custom_voice",
+            hf_repo_id="Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
+            model_size="1.7B",
+            size_mb=3500,
+            supports_instruct=True,
+            languages=["zh", "en", "ja", "ko", "de", "fr", "ru", "pt", "es", "it"],
+        ),
+        ModelConfig(
+            model_name="qwen-custom-voice-0.6B",
+            display_name="Qwen CustomVoice 0.6B",
+            engine="qwen_custom_voice",
+            hf_repo_id="Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice",
+            model_size="0.6B",
+            size_mb=1200,
+            supports_instruct=True,
+            languages=["zh", "en", "ja", "ko", "de", "fr", "ru", "pt", "es", "it"],
+        ),
+    ]
+
+
 def _get_non_qwen_tts_configs() -> list[ModelConfig]:
    """Return model configs for non-Qwen TTS engines.

@@ -278,6 +306,14 @@ def _get_non_qwen_tts_configs() -> list[ModelConfig]:
            size_mb=8000,
            languages=["en", "ar", "zh", "de", "es", "fr", "it", "ja", "pl", "pt"],
        ),
+        ModelConfig(
+            model_name="kokoro",
+            display_name="Kokoro 82M",
+            engine="kokoro",
+            hf_repo_id="hexgrad/Kokoro-82M",
+            size_mb=350,
+            languages=["en", "es", "fr", "hi", "it", "pt", "ja", "zh"],
+        ),
    ]


@@ -324,12 +360,12 @@ def _get_whisper_configs() -> list[ModelConfig]:

 def get_all_model_configs() -> list[ModelConfig]:
    """Return the full list of model configs (TTS + STT)."""
-    return _get_qwen_model_configs() + _get_non_qwen_tts_configs() + _get_whisper_configs()
+    return _get_qwen_model_configs() + _get_qwen_custom_voice_configs() + _get_non_qwen_tts_configs() + _get_whisper_configs()


 def get_tts_model_configs() -> list[ModelConfig]:
    """Return only TTS model configs."""
-    return _get_qwen_model_configs() + _get_non_qwen_tts_configs()
+    return _get_qwen_model_configs() + _get_qwen_custom_voice_configs() + _get_non_qwen_tts_configs()


 # Lookup helpers — these replace the if/elif chains in main.py
@@ -360,7 +396,7 @@ def engine_has_model_sizes(engine: str) -> bool:
 async def load_engine_model(engine: str, model_size: str = "default") -> None:
    """Load a model for the given engine, handling engines with multiple model sizes."""
    backend = get_tts_backend_for_engine(engine)
-    if engine == "qwen":
+    if engine in ("qwen", "qwen_custom_voice"):
        await backend.load_model_async(model_size)
    elif engine == "tada":
        await backend.load_model(model_size)
@@ -379,7 +415,7 @@ async def ensure_model_cached_or_raise(engine: str, model_size: str = "default")
            cfg = c
            break

-    if engine in ("qwen", "tada"):
+    if engine in ("qwen", "qwen_custom_voice", "tada"):
        if not backend._is_model_cached(model_size):
            raise HTTPException(
                status_code=400,
@@ -414,6 +450,14 @@ def unload_model_by_config(config: ModelConfig) -> bool:
            return True
        return False

+    if config.engine == "qwen_custom_voice":
+        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()
+            return True
+        return False
+
    # All other TTS engines
    backend = get_tts_backend_for_engine(config.engine)
    if backend.is_loaded():
@@ -437,6 +481,11 @@ def check_model_loaded(config: ModelConfig) -> bool:
            loaded_size = getattr(tts_model, "_current_model_size", None) or getattr(tts_model, "model_size", None)
            return tts_model.is_loaded() and loaded_size == config.model_size

+        if config.engine == "qwen_custom_voice":
+            backend = get_tts_backend_for_engine(config.engine)
+            loaded_size = getattr(backend, "_current_model_size", None) or getattr(backend, "model_size", None)
+            return backend.is_loaded() and loaded_size == config.model_size
+
        backend = get_tts_backend_for_engine(config.engine)
        return backend.is_loaded()
    except Exception:
@@ -454,6 +503,9 @@ def get_model_load_func(config: ModelConfig):
    if config.engine == "qwen":
        return lambda: tts.get_tts_model().load_model(config.model_size)

+    if config.engine == "qwen_custom_voice":
+        return lambda: get_tts_backend_for_engine(config.engine).load_model(config.model_size)
+
    return lambda: get_tts_backend_for_engine(config.engine).load_model()


@@ -515,6 +567,14 @@ def get_tts_backend_for_engine(engine: str) -> TTSBackend:
            from .hume_backend import HumeTadaBackend

            backend = HumeTadaBackend()
+        elif engine == "kokoro":
+            from .kokoro_backend import KokoroTTSBackend
+
+            backend = KokoroTTSBackend()
+        elif engine == "qwen_custom_voice":
+            from .qwen_custom_voice_backend import QwenCustomVoiceBackend
+
+            backend = QwenCustomVoiceBackend()
        else:
            raise ValueError(f"Unknown TTS engine: {engine}. Supported: {list(TTS_ENGINES.keys())}")

@@ -126,6 +126,75 @@ def get_torch_device(
    return "cpu"


+def check_cuda_compatibility() -> tuple[bool, str | None]:
+    """Check if the installed PyTorch supports the current GPU's compute capability.
+
+    Returns:
+        (compatible, warning_message) — compatible is True if OK or no CUDA GPU,
+        warning_message is a human-readable string if there's a problem.
+    """
+    import torch
+
+    if not torch.cuda.is_available():
+        return True, None
+
+    major, minor = torch.cuda.get_device_capability(0)
+    capability = f"{major}.{minor}"
+    device_name = torch.cuda.get_device_name(0)
+    sm_tag = f"sm_{major}{minor}"
+
+    # torch.cuda._get_arch_list() returns the SM architectures this build
+    # was compiled for (e.g. ["sm_50", "sm_60", ..., "sm_90"]).
+    try:
+        arch_list = torch.cuda._get_arch_list()
+        if arch_list:
+            # Check for both sm_XX and compute_XX (JIT-compiled) entries
+            compute_tag = f"compute_{major}{minor}"
+            if sm_tag not in arch_list and compute_tag not in arch_list:
+                return False, (
+                    f"{device_name} (compute capability {capability} / {sm_tag}) "
+                    f"is not supported by this PyTorch build. "
+                    f"Supported architectures: {', '.join(arch_list)}. "
+                    f"Install PyTorch nightly (cu128) for newer GPU support: "
+                    f"pip install torch --index-url https://download.pytorch.org/whl/nightly/cu128"
+                )
+    except AttributeError:
+        pass
+
+    return True, None
+
+
+def empty_device_cache(device: str) -> None:
+    """
+    Free cached memory on the given device (CUDA or XPU).
+
+    Backends should call this after unloading models so VRAM is returned
+    to the OS.
+    """
+    import torch
+
+    if device == "cuda" and torch.cuda.is_available():
+        torch.cuda.empty_cache()
+    elif device == "xpu" and hasattr(torch, "xpu"):
+        torch.xpu.empty_cache()
+
+
+def manual_seed(seed: int, device: str) -> None:
+    """
+    Set the random seed on both CPU and the active accelerator.
+
+    Covers CUDA and Intel XPU so that generation is reproducible
+    regardless of which GPU backend is in use.
+    """
+    import torch
+
+    torch.manual_seed(seed)
+    if device == "cuda" and torch.cuda.is_available():
+        torch.cuda.manual_seed(seed)
+    elif device == "xpu" and hasattr(torch, "xpu"):
+        torch.xpu.manual_seed(seed)
+
+
 async def combine_voice_prompts(
    audio_paths: List[str],
    reference_texts: List[str],
@@ -18,6 +18,8 @@ from . import TTSBackend
 from .base import (
    is_model_cached,
    get_torch_device,
+    empty_device_cache,
+    manual_seed,
    combine_voice_prompts as _combine_voice_prompts,
    model_load_progress,
    patch_chatterbox_f32,
@@ -48,7 +50,7 @@ class ChatterboxTTSBackend:
        self._model_load_lock = asyncio.Lock()

    def _get_device(self) -> str:
-        return get_torch_device(force_cpu_on_mac=True)
+        return get_torch_device(force_cpu_on_mac=True, allow_xpu=True)

    def is_loaded(self) -> bool:
        return self.model is not None
@@ -117,10 +119,7 @@ class ChatterboxTTSBackend:
            del self.model
            self.model = None
            self._device = None
-            if device == "cuda":
-                import torch
-
-                torch.cuda.empty_cache()
+            empty_device_cache(device)
            logger.info("Chatterbox unloaded")

    async def create_voice_prompt(
@@ -200,7 +199,7 @@ class ChatterboxTTSBackend:
            import torch

            if seed is not None:
-                torch.manual_seed(seed)
+                manual_seed(seed, self._device)

            logger.info(f"[Chatterbox] Generating: lang={language}")

@@ -220,10 +219,7 @@ class ChatterboxTTSBackend:
            else:
                audio = np.asarray(wav, dtype=np.float32)

-            sample_rate = (
-                getattr(self.model, "sr", None)
-                or getattr(self.model, "sample_rate", 24000)
-            )
+            sample_rate = getattr(self.model, "sr", None) or getattr(self.model, "sample_rate", 24000)

            return audio, sample_rate

@@ -18,6 +18,8 @@ from . import TTSBackend
 from .base import (
    is_model_cached,
    get_torch_device,
+    empty_device_cache,
+    manual_seed,
    combine_voice_prompts as _combine_voice_prompts,
    model_load_progress,
    patch_chatterbox_f32,
@@ -48,7 +50,7 @@ class ChatterboxTurboTTSBackend:
        self._model_load_lock = asyncio.Lock()

    def _get_device(self) -> str:
-        return get_torch_device(force_cpu_on_mac=True)
+        return get_torch_device(force_cpu_on_mac=True, allow_xpu=True)

    def is_loaded(self) -> bool:
        return self.model is not None
@@ -116,10 +118,7 @@ class ChatterboxTurboTTSBackend:
            del self.model
            self.model = None
            self._device = None
-            if device == "cuda":
-                import torch
-
-                torch.cuda.empty_cache()
+            empty_device_cache(device)
            logger.info("Chatterbox Turbo unloaded")

    async def create_voice_prompt(
@@ -181,7 +180,7 @@ class ChatterboxTurboTTSBackend:
            import torch

            if seed is not None:
-                torch.manual_seed(seed)
+                manual_seed(seed, self._device)

            logger.info("[Chatterbox Turbo] Generating (English)")

@@ -200,10 +199,7 @@ class ChatterboxTurboTTSBackend:
            else:
                audio = np.asarray(wav, dtype=np.float32)

-            sample_rate = (
-                getattr(self.model, "sr", None)
-                or getattr(self.model, "sample_rate", 24000)
-            )
+            sample_rate = getattr(self.model, "sr", None) or getattr(self.model, "sample_rate", 24000)

            return audio, sample_rate

@@ -24,6 +24,8 @@ from . import TTSBackend
 from .base import (
    is_model_cached,
    get_torch_device,
+    empty_device_cache,
+    manual_seed,
    combine_voice_prompts as _combine_voice_prompts,
    model_load_progress,
 )
@@ -66,7 +68,7 @@ class HumeTadaBackend:
    def _get_device(self) -> str:
        # Force CPU on macOS — MPS has issues with flow matching
        # and large vocab lm_head (>65536 output channels)
-        return get_torch_device(force_cpu_on_mac=True)
+        return get_torch_device(force_cpu_on_mac=True, allow_xpu=True)

    def is_loaded(self) -> bool:
        return self.model is not None
@@ -105,6 +107,7 @@ class HumeTadaBackend:
            # package.  The real package pulls in onnx/tensorboard/matplotlib via
            # descript-audiotools, so we use a lightweight shim instead.
            from ..utils.dac_shim import install_dac_shim
+
            install_dac_shim()

            import torch
@@ -142,9 +145,12 @@ class HumeTadaBackend:
                allow_patterns=["tokenizer*", "special_tokens*"],
            )

-            # Determine dtype — use bf16 on CUDA for ~50% memory savings
+            # Determine dtype — use bf16 on CUDA/XPU for ~50% memory savings
            if device == "cuda" and torch.cuda.is_bf16_supported():
                model_dtype = torch.bfloat16
+            elif device == "xpu":
+                # Intel Arc (Alchemist+) supports bf16 natively
+                model_dtype = torch.bfloat16
            else:
                model_dtype = torch.float32

@@ -153,14 +159,14 @@ class HumeTadaBackend:
            # This avoids monkey-patching AutoTokenizer.from_pretrained
            # which corrupts the classmethod descriptor for other engines.
            from tada.modules.aligner import AlignerConfig
+
            AlignerConfig.tokenizer_name = tokenizer_path

            # Load encoder (only needed for voice prompt encoding)
            from tada.modules.encoder import Encoder
+
            logger.info("Loading TADA encoder...")
-            self.encoder = Encoder.from_pretrained(
-                TADA_CODEC_REPO, subfolder="encoder"
-            ).to(device)
+            self.encoder = Encoder.from_pretrained(TADA_CODEC_REPO, subfolder="encoder").to(device)
            self.encoder.eval()

            # Load the causal LM (includes decoder for wav generation).
@@ -169,12 +175,11 @@ class HumeTadaBackend:
            # 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
+
            logger.info(f"Loading TADA {model_size} model...")
            config = TadaConfig.from_pretrained(repo)
            config.tokenizer_name = tokenizer_path
-            self.model = TadaForCausalLM.from_pretrained(
-                repo, config=config, torch_dtype=model_dtype
-            ).to(device)
+            self.model = TadaForCausalLM.from_pretrained(repo, config=config, torch_dtype=model_dtype).to(device)
            self.model.eval()

        logger.info(f"HumeAI TADA {model_size} loaded successfully on {device}")
@@ -188,11 +193,11 @@ class HumeTadaBackend:
            del self.encoder
            self.encoder = None

+        device = self._device
        self._device = None

-        import torch
-        if torch.cuda.is_available():
-            torch.cuda.empty_cache()
+        if device:
+            empty_device_cache(device)

        logger.info("HumeAI TADA unloaded")

@@ -213,9 +218,7 @@ class HumeTadaBackend:
        """
        await self.load_model(self.model_size)

-        cache_key = (
-            "tada_" + get_cache_key(audio_path, reference_text)
-        ) if use_cache else None
+        cache_key = ("tada_" + get_cache_key(audio_path, reference_text)) if use_cache else None

        if cache_key:
            cached = get_cached_voice_prompt(cache_key)
@@ -239,9 +242,7 @@ class HumeTadaBackend:

            # Encode with forced alignment
            text_arg = [reference_text] if reference_text else None
-            prompt = self.encoder(
-                audio, text=text_arg, sample_rate=sr
-            )
+            prompt = self.encoder(audio, text=text_arg, sample_rate=sr)

            # Serialize EncoderOutput to a dict of CPU tensors for caching
            prompt_dict = {}
@@ -299,9 +300,7 @@ class HumeTadaBackend:
            from tada.modules.encoder import EncoderOutput

            if seed is not None:
-                torch.manual_seed(seed)
-                if torch.cuda.is_available():
-                    torch.cuda.manual_seed(seed)
+                manual_seed(seed, self._device)

            device = self._device

@@ -0,0 +1,288 @@
+"""
+Kokoro TTS backend implementation.
+
+Wraps the Kokoro-82M model for fast, lightweight text-to-speech.
+82M parameters, CPU realtime, 24kHz output, Apache 2.0 license.
+
+Kokoro uses pre-built voice style vectors (not traditional zero-shot cloning
+from arbitrary audio). Voice prompts are stored as deferred references to
+HF-hosted voice .pt files.
+
+Languages supported (via misaki G2P):
+  - American English (a), British English (b)
+  - Spanish (e), French (f), Hindi (h), Italian (i), Portuguese (p)
+  - Japanese (j) — requires misaki[ja]
+  - Chinese (z) — requires misaki[zh]
+"""
+
+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,
+    model_load_progress,
+)
+
+logger = logging.getLogger(__name__)
+
+# HuggingFace repo for model + voice detection
+KOKORO_HF_REPO = "hexgrad/Kokoro-82M"
+KOKORO_SAMPLE_RATE = 24000
+
+# Default voice if none specified
+KOKORO_DEFAULT_VOICE = "af_heart"
+
+# All available Kokoro voices: (voice_id, display_name, gender, lang_code)
+KOKORO_VOICES = [
+    # American English female
+    ("af_alloy", "Alloy", "female", "en"),
+    ("af_aoede", "Aoede", "female", "en"),
+    ("af_bella", "Bella", "female", "en"),
+    ("af_heart", "Heart", "female", "en"),
+    ("af_jessica", "Jessica", "female", "en"),
+    ("af_kore", "Kore", "female", "en"),
+    ("af_nicole", "Nicole", "female", "en"),
+    ("af_nova", "Nova", "female", "en"),
+    ("af_river", "River", "female", "en"),
+    ("af_sarah", "Sarah", "female", "en"),
+    ("af_sky", "Sky", "female", "en"),
+    # American English male
+    ("am_adam", "Adam", "male", "en"),
+    ("am_echo", "Echo", "male", "en"),
+    ("am_eric", "Eric", "male", "en"),
+    ("am_fenrir", "Fenrir", "male", "en"),
+    ("am_liam", "Liam", "male", "en"),
+    ("am_michael", "Michael", "male", "en"),
+    ("am_onyx", "Onyx", "male", "en"),
+    ("am_puck", "Puck", "male", "en"),
+    ("am_santa", "Santa", "male", "en"),
+    # British English female
+    ("bf_alice", "Alice", "female", "en"),
+    ("bf_emma", "Emma", "female", "en"),
+    ("bf_isabella", "Isabella", "female", "en"),
+    ("bf_lily", "Lily", "female", "en"),
+    # British English male
+    ("bm_daniel", "Daniel", "male", "en"),
+    ("bm_fable", "Fable", "male", "en"),
+    ("bm_george", "George", "male", "en"),
+    ("bm_lewis", "Lewis", "male", "en"),
+    # Spanish
+    ("ef_dora", "Dora", "female", "es"),
+    ("em_alex", "Alex", "male", "es"),
+    ("em_santa", "Santa", "male", "es"),
+    # French
+    ("ff_siwis", "Siwis", "female", "fr"),
+    # Hindi
+    ("hf_alpha", "Alpha", "female", "hi"),
+    ("hf_beta", "Beta", "female", "hi"),
+    ("hm_omega", "Omega", "male", "hi"),
+    ("hm_psi", "Psi", "male", "hi"),
+    # Italian
+    ("if_sara", "Sara", "female", "it"),
+    ("im_nicola", "Nicola", "male", "it"),
+    # Japanese
+    ("jf_alpha", "Alpha", "female", "ja"),
+    ("jf_gongitsune", "Gongitsune", "female", "ja"),
+    ("jf_nezumi", "Nezumi", "female", "ja"),
+    ("jf_tebukuro", "Tebukuro", "female", "ja"),
+    ("jm_kumo", "Kumo", "male", "ja"),
+    # Portuguese
+    ("pf_dora", "Dora", "female", "pt"),
+    ("pm_alex", "Alex", "male", "pt"),
+    ("pm_santa", "Santa", "male", "pt"),
+    # Chinese
+    ("zf_xiaobei", "Xiaobei", "female", "zh"),
+    ("zf_xiaoni", "Xiaoni", "female", "zh"),
+    ("zf_xiaoxiao", "Xiaoxiao", "female", "zh"),
+    ("zf_xiaoyi", "Xiaoyi", "female", "zh"),
+]
+
+# Map our ISO language codes to Kokoro lang_code characters
+LANG_CODE_MAP = {
+    "en": "a",  # American English
+    "es": "e",
+    "fr": "f",
+    "hi": "h",
+    "it": "i",
+    "pt": "p",
+    "ja": "j",
+    "zh": "z",
+}
+
+
+class KokoroTTSBackend:
+    """Kokoro-82M TTS backend — tiny, fast, CPU-friendly."""
+
+    def __init__(self):
+        self._model = None
+        self._pipelines: dict = {}  # lang_code -> KPipeline
+        self._device: Optional[str] = None
+        self.model_size = "default"
+
+    def _get_device(self) -> str:
+        """Select device. Kokoro supports CUDA and CPU. MPS needs fallback env var."""
+        device = get_torch_device(allow_mps=False)
+        # Kokoro can use MPS but requires PYTORCH_ENABLE_MPS_FALLBACK=1
+        # For now, skip MPS to avoid user confusion — CPU is already realtime
+        return device
+
+    @property
+    def device(self) -> str:
+        if self._device is None:
+            self._device = self._get_device()
+        return self._device
+
+    def is_loaded(self) -> bool:
+        return self._model is not None
+
+    def _get_model_path(self, model_size: str) -> str:
+        return KOKORO_HF_REPO
+
+    def _is_model_cached(self, model_size: str = "default") -> bool:
+        """Check if Kokoro model files are cached locally."""
+        from .base import is_model_cached
+
+        return is_model_cached(
+            KOKORO_HF_REPO,
+            required_files=["config.json", "kokoro-v1_0.pth"],
+        )
+
+    async def load_model(self, model_size: str = "default") -> None:
+        """Load the Kokoro model."""
+        if self._model is not None:
+            return
+        await asyncio.to_thread(self._load_model_sync)
+
+    def _load_model_sync(self):
+        """Synchronous model loading."""
+        model_name = "kokoro"
+        is_cached = self._is_model_cached()
+
+        with model_load_progress(model_name, is_cached):
+            from kokoro import KModel
+
+            device = self.device
+            logger.info(f"Loading Kokoro-82M on {device}...")
+
+            self._model = KModel(repo_id=KOKORO_HF_REPO).to(device).eval()
+
+        logger.info("Kokoro-82M loaded successfully")
+
+    def _get_pipeline(self, lang_code: str):
+        """Get or create a KPipeline for the given language code."""
+        kokoro_lang = LANG_CODE_MAP.get(lang_code, "a")
+
+        if kokoro_lang not in self._pipelines:
+            from kokoro import KPipeline
+
+            # Create pipeline with our existing model (no redundant model loading)
+            self._pipelines[kokoro_lang] = KPipeline(
+                lang_code=kokoro_lang,
+                repo_id=KOKORO_HF_REPO,
+                model=self._model,
+            )
+
+        return self._pipelines[kokoro_lang]
+
+    def unload_model(self) -> None:
+        """Unload model to free memory."""
+        if self._model is not None:
+            del self._model
+            self._model = None
+            self._pipelines.clear()
+
+            import torch
+
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+
+            logger.info("Kokoro unloaded")
+
+    async def create_voice_prompt(
+        self,
+        audio_path: str,
+        reference_text: str,
+        use_cache: bool = True,
+    ) -> tuple[dict, bool]:
+        """
+        Create voice prompt for Kokoro.
+
+        Kokoro doesn't do traditional voice cloning from arbitrary audio.
+        When called for a cloned profile (fallback), uses the default voice.
+        For preset profiles, the voice_prompt dict is built by the profile
+        service and bypasses this method entirely.
+        """
+        return {
+            "voice_type": "preset",
+            "preset_engine": "kokoro",
+            "preset_voice_id": KOKORO_DEFAULT_VOICE,
+        }, False
+
+    async def combine_voice_prompts(
+        self,
+        audio_paths: list[str],
+        reference_texts: list[str],
+    ) -> tuple[np.ndarray, str]:
+        """Combine voice prompts — uses base implementation for audio concatenation."""
+        return await _combine_voice_prompts(
+            audio_paths, reference_texts, sample_rate=KOKORO_SAMPLE_RATE
+        )
+
+    async def generate(
+        self,
+        text: str,
+        voice_prompt: dict,
+        language: str = "en",
+        seed: Optional[int] = None,
+        instruct: Optional[str] = None,
+    ) -> tuple[np.ndarray, int]:
+        """
+        Generate audio from text using Kokoro.
+
+        Args:
+            text: Text to synthesize
+            voice_prompt: Dict with kokoro_voice key
+            language: Language code
+            seed: Random seed for reproducibility
+            instruct: Not supported by Kokoro (ignored)
+
+        Returns:
+            Tuple of (audio_array, sample_rate)
+        """
+        await self.load_model()
+
+        voice_name = voice_prompt.get("preset_voice_id") or voice_prompt.get("kokoro_voice") or KOKORO_DEFAULT_VOICE
+
+        def _generate_sync():
+            import torch
+
+            if seed is not None:
+                torch.manual_seed(seed)
+                if torch.cuda.is_available():
+                    torch.cuda.manual_seed(seed)
+
+            pipeline = self._get_pipeline(language)
+
+            # Generate all chunks and concatenate
+            audio_chunks = []
+            for result in pipeline(text, voice=voice_name, speed=1.0):
+                if result.audio is not None:
+                    chunk = result.audio
+                    if isinstance(chunk, torch.Tensor):
+                        chunk = chunk.detach().cpu().numpy()
+                    audio_chunks.append(chunk.squeeze())
+
+            if not audio_chunks:
+                # Return 1 second of silence as fallback
+                return np.zeros(KOKORO_SAMPLE_RATE, dtype=np.float32), KOKORO_SAMPLE_RATE
+
+            audio = np.concatenate(audio_chunks)
+            return audio.astype(np.float32), KOKORO_SAMPLE_RATE
+
+        return await asyncio.to_thread(_generate_sync)
@@ -12,7 +12,14 @@ from typing import Optional, Tuple
 import numpy as np

 from . import TTSBackend
-from .base import is_model_cached, get_torch_device, combine_voice_prompts as _combine_voice_prompts, model_load_progress
+from .base import (
+    is_model_cached,
+    get_torch_device,
+    empty_device_cache,
+    manual_seed,
+    combine_voice_prompts as _combine_voice_prompts,
+    model_load_progress,
+)
 from ..utils.cache import get_cache_key, get_cached_voice_prompt, cache_voice_prompt

 logger = logging.getLogger(__name__)
@@ -30,7 +37,7 @@ class LuxTTSBackend:
        self._device = None

    def _get_device(self) -> str:
-        return get_torch_device(allow_mps=True)
+        return get_torch_device(allow_mps=True, allow_xpu=True)

    def is_loaded(self) -> bool:
        return self.model is not None
@@ -69,9 +76,12 @@ class LuxTTSBackend:

            if device == "cpu":
                import os
+
                threads = os.cpu_count() or 4
                self.model = LuxTTS(
-                    model_path=LUXTTS_HF_REPO, device="cpu", threads=min(threads, 8),
+                    model_path=LUXTTS_HF_REPO,
+                    device="cpu",
+                    threads=min(threads, 8),
                )
            else:
                self.model = LuxTTS(model_path=LUXTTS_HF_REPO, device=device)
@@ -81,12 +91,12 @@ class LuxTTSBackend:
    def unload_model(self) -> None:
        """Unload model to free memory."""
        if self.model is not None:
+            device = self.device
            del self.model
            self.model = None
+            self._device = None

-            import torch
-            if torch.cuda.is_available():
-                torch.cuda.empty_cache()
+            empty_device_cache(device)

            logger.info("LuxTTS unloaded")

@@ -154,12 +164,8 @@ class LuxTTSBackend:
        await self.load_model()

        def _generate_sync():
-            import torch
-
            if seed is not None:
-                torch.manual_seed(seed)
-                if torch.cuda.is_available():
-                    torch.cuda.manual_seed(seed)
+                manual_seed(seed, self.device)

            wav = self.model.generate_speech(
                text=text,
@@ -14,6 +14,8 @@ from . import TTSBackend, STTBackend, 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,
    model_load_progress,
 )
@@ -97,16 +99,25 @@ class PyTorchTTSBackend:
            model_path = self._get_model_path(model_size)
            logger.info("Loading TTS model %s on %s...", model_size, self.device)

+            # Route both HF Hub and Transformers through a single cache root.
+            # On Windows local setups, model assets can otherwise split between
+            # .hf-cache/hub and .hf-cache/transformers, causing speech_tokenizer
+            # and preprocessor_config.json to fail to resolve during load.
+            from huggingface_hub import constants as hf_constants
+            tts_cache_dir = hf_constants.HF_HUB_CACHE
+
            with force_offline_if_cached(is_cached, model_name):
                if self.device == "cpu":
                    self.model = Qwen3TTSModel.from_pretrained(
                        model_path,
+                        cache_dir=tts_cache_dir,
                        torch_dtype=torch.float32,
                        low_cpu_mem_usage=False,
                    )
                else:
                    self.model = Qwen3TTSModel.from_pretrained(
                        model_path,
+                        cache_dir=tts_cache_dir,
                        device_map=self.device,
                        torch_dtype=torch.bfloat16,
                    )
@@ -122,8 +133,7 @@ class PyTorchTTSBackend:
            self.model = None
            self._current_model_size = None

-            if torch.cuda.is_available():
-                torch.cuda.empty_cache()
+            empty_device_cache(self.device)

            logger.info("TTS model unloaded")

@@ -215,9 +225,7 @@ class PyTorchTTSBackend:
            """Run synchronous generation in thread pool."""
            # Set seed if provided
            if seed is not None:
-                torch.manual_seed(seed)
-                if torch.cuda.is_available():
-                    torch.cuda.manual_seed(seed)
+                manual_seed(seed, self.device)

            # Generate audio - this is the blocking operation
            wavs, sample_rate = self.model.generate_voice_clone(
@@ -300,8 +308,7 @@ class PyTorchSTTBackend:
            self.model = None
            self.processor = None

-            if torch.cuda.is_available():
-                torch.cuda.empty_cache()
+            empty_device_cache(self.device)

            logger.info("Whisper model unloaded")

@@ -0,0 +1,210 @@
+"""
+Qwen3-TTS CustomVoice backend implementation.
+
+Wraps the Qwen3-TTS-12Hz CustomVoice model for preset-speaker TTS with
+instruction-based style control. Uses the same qwen_tts library as the
+Base model (pytorch_backend.py) but loads a different checkpoint and
+calls generate_custom_voice() instead of generate_voice_clone().
+
+Key differences from the Base engine:
+  - Uses preset speakers (9 built-in voices) instead of zero-shot cloning
+  - Supports instruct parameter for tone/emotion/prosody control
+  - Two model sizes: 1.7B and 0.6B
+
+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 .base import (
+    is_model_cached,
+    get_torch_device,
+    combine_voice_prompts as _combine_voice_prompts,
+    model_load_progress,
+)
+
+logger = logging.getLogger(__name__)
+
+# ── Preset speakers ──────────────────────────────────────────────────
+
+# (speaker_id, display_name, gender, native_language_code, description)
+QWEN_CUSTOM_VOICES = [
+    ("Vivian", "Vivian", "female", "zh", "Bright, slightly edgy young female voice"),
+    ("Serena", "Serena", "female", "zh", "Warm, gentle young female voice"),
+    ("Uncle_Fu", "Uncle Fu", "male", "zh", "Seasoned male voice with a low, mellow timbre"),
+    ("Dylan", "Dylan", "male", "zh", "Youthful Beijing male voice with a clear, natural timbre"),
+    ("Eric", "Eric", "male", "zh", "Lively Chengdu male voice with a slightly husky brightness"),
+    ("Ryan", "Ryan", "male", "en", "Dynamic male voice with strong rhythmic drive"),
+    ("Aiden", "Aiden", "male", "en", "Sunny American male voice with a clear midrange"),
+    ("Ono_Anna", "Ono Anna", "female", "ja", "Playful Japanese female voice with a light, nimble timbre"),
+    ("Sohee", "Sohee", "female", "ko", "Warm Korean female voice with rich emotion"),
+]
+
+QWEN_CV_DEFAULT_SPEAKER = "Ryan"
+
+# HuggingFace repo IDs per model size
+QWEN_CV_HF_REPOS = {
+    "1.7B": "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
+    "0.6B": "Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice",
+}
+
+
+class QwenCustomVoiceBackend:
+    """Qwen3-TTS CustomVoice backend — preset speakers with instruct control."""
+
+    def __init__(self, model_size: str = "1.7B"):
+        self.model = None
+        self.model_size = model_size
+        self.device = self._get_device()
+        self._current_model_size: Optional[str] = None
+
+    def _get_device(self) -> str:
+        return get_torch_device(allow_xpu=True, allow_directml=True)
+
+    def is_loaded(self) -> bool:
+        return self.model is not None
+
+    def _get_model_path(self, model_size: str) -> str:
+        if model_size not in QWEN_CV_HF_REPOS:
+            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:
+        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:
+        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()
+
+        await asyncio.to_thread(self._load_model_sync, model_size)
+
+    # Alias for compatibility with the TTSBackend protocol
+    load_model = load_model_async
+
+    def _load_model_sync(self, model_size: str) -> None:
+        model_name = f"qwen-custom-voice-{model_size}"
+        is_cached = self._is_model_cached(model_size)
+
+        with model_load_progress(model_name, is_cached):
+            from qwen_tts import Qwen3TTSModel
+
+            model_path = self._get_model_path(model_size)
+            logger.info("Loading Qwen CustomVoice %s on %s...", model_size, self.device)
+
+            if self.device == "cpu":
+                self.model = Qwen3TTSModel.from_pretrained(
+                    model_path,
+                    torch_dtype=torch.float32,
+                    low_cpu_mem_usage=False,
+                )
+            else:
+                self.model = Qwen3TTSModel.from_pretrained(
+                    model_path,
+                    device_map=self.device,
+                    torch_dtype=torch.bfloat16,
+                )
+
+        self._current_model_size = model_size
+        self.model_size = model_size
+        logger.info("Qwen CustomVoice %s loaded successfully", model_size)
+
+    def unload_model(self) -> None:
+        if self.model is not None:
+            del self.model
+            self.model = None
+            self._current_model_size = None
+
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+
+            logger.info("Qwen CustomVoice unloaded")
+
+    async def create_voice_prompt(
+        self,
+        audio_path: str,
+        reference_text: str,
+        use_cache: bool = True,
+    ) -> tuple[dict, bool]:
+        """
+        Create voice prompt for CustomVoice.
+
+        CustomVoice doesn't use reference audio — it uses preset speakers.
+        When called for a cloned profile (fallback), uses the default speaker.
+        For preset profiles, the voice_prompt dict is built by the profile
+        service and bypasses this method entirely.
+        """
+        return {
+            "voice_type": "preset",
+            "preset_engine": "qwen_custom_voice",
+            "preset_voice_id": QWEN_CV_DEFAULT_SPEAKER,
+        }, False
+
+    async def combine_voice_prompts(
+        self,
+        audio_paths: list[str],
+        reference_texts: list[str],
+    ) -> tuple[np.ndarray, str]:
+        return await _combine_voice_prompts(audio_paths, reference_texts)
+
+    async def generate(
+        self,
+        text: str,
+        voice_prompt: dict,
+        language: str = "en",
+        seed: Optional[int] = None,
+        instruct: Optional[str] = None,
+    ) -> tuple[np.ndarray, int]:
+        """
+        Generate audio using Qwen CustomVoice.
+
+        Args:
+            text: Text to synthesize
+            voice_prompt: Dict with preset_voice_id (speaker name)
+            language: Language code (zh, en, ja, ko, etc.)
+            seed: Random seed for reproducibility
+            instruct: Natural language instruction for style control
+                      (e.g. "Speak in an angry tone", "Very happy")
+
+        Returns:
+            Tuple of (audio_array, sample_rate)
+        """
+        await self.load_model_async(None)
+
+        speaker = voice_prompt.get("preset_voice_id") or QWEN_CV_DEFAULT_SPEAKER
+
+        def _generate_sync():
+            if seed is not None:
+                torch.manual_seed(seed)
+                if torch.cuda.is_available():
+                    torch.cuda.manual_seed(seed)
+
+            lang_name = LANGUAGE_CODE_TO_NAME.get(language, "auto")
+
+            kwargs = {
+                "text": text,
+                "language": lang_name.capitalize() if lang_name != "auto" else "Auto",
+                "speaker": speaker,
+            }
+
+            # Only pass instruct if non-empty
+            if instruct:
+                kwargs["instruct"] = instruct
+
+            wavs, sample_rate = self.model.generate_custom_voice(**kwargs)
+            return wavs[0], sample_rate
+
+        audio, sample_rate = await asyncio.to_thread(_generate_sync)
+        return audio, sample_rate
@@ -52,6 +52,16 @@ def build_server(cuda=False):
    if platform.system() == "Windows":
        args.append("--noconsole")

+    # numpy 2.x / torch ABI mismatch fix: install memmove fallback for
+    # torch.from_numpy() before the app starts. Runtime hooks run after
+    # FrozenImporter is registered so frozen torch/numpy are importable.
+    args.extend(
+        [
+            "--runtime-hook",
+            str(backend_dir / "pyi_rth_numpy_compat.py"),
+        ]
+    )
+
    # Add local qwen_tts path if specified (for editable installs)
    qwen_tts_path = os.getenv("QWEN_TTS_PATH")
    if qwen_tts_path and Path(qwen_tts_path).exists():
@@ -86,6 +96,8 @@ def build_server(cuda=False):
            "--hidden-import",
            "backend.backends.pytorch_backend",
            "--hidden-import",
+            "backend.backends.qwen_custom_voice_backend",
+            "--hidden-import",
            "backend.utils.audio",
            "--hidden-import",
            "backend.utils.cache",
@@ -228,6 +240,44 @@ def build_server(cuda=False):
            "torchaudio",
            "--collect-submodules",
            "tada",
+            # Kokoro 82M — lightweight TTS engine using misaki G2P
+            "--hidden-import",
+            "backend.backends.kokoro_backend",
+            "--hidden-import",
+            "kokoro",
+            "--hidden-import",
+            "kokoro.pipeline",
+            "--hidden-import",
+            "kokoro.model",
+            "--hidden-import",
+            "kokoro.istftnet",
+            "--hidden-import",
+            "kokoro.modules",
+            "--hidden-import",
+            "kokoro.custom_stft",
+            # misaki ships G2P data files (dictionaries, phoneme tables)
+            # that must be bundled for espeak/en/ja/zh G2P to work
+            "--collect-all",
+            "misaki",
+            # language_tags ships JSON data files (index.json etc.) loaded at
+            # runtime via: misaki → phonemizer → segments → csvw → language_tags
+            "--collect-all",
+            "language_tags",
+            # espeakng_loader ships the entire espeak-ng-data directory (369 files)
+            # loaded at import time by misaki.espeak via get_data_path()
+            "--collect-all",
+            "espeakng_loader",
+            # spacy en_core_web_sm model — misaki.en tries to spacy.cli.download()
+            # at runtime if not found, which calls pip as a subprocess and crashes
+            # the frozen binary. Bundle the model so spacy.util.is_package() passes.
+            "--collect-all",
+            "en_core_web_sm",
+            "--copy-metadata",
+            "en_core_web_sm",
+            "--hidden-import",
+            "en_core_web_sm",
+            "--hidden-import",
+            "loguru",
        ]
    )

@@ -19,7 +19,22 @@ if _custom_models_dir:
    logger.info("Model download path set to: %s", _custom_models_dir)

 # Default data directory (used in development)
-_data_dir = Path("data")
+_data_dir = Path("data").resolve()
+
+
+def _path_relative_to_any_data_dir(path: Path) -> Path | None:
+    """Extract the path within a data dir from an absolute or relative path."""
+    parts = path.parts
+    for idx, part in enumerate(parts):
+        if part != "data":
+            continue
+
+        tail = parts[idx + 1 :]
+        if tail:
+            return Path(*tail)
+        return Path()
+
+    return None


 def set_data_dir(path: str | Path):
@@ -30,9 +45,9 @@ def set_data_dir(path: str | Path):
        path: Path to the data directory
    """
    global _data_dir
-    _data_dir = Path(path)
+    _data_dir = Path(path).resolve()
    _data_dir.mkdir(parents=True, exist_ok=True)
-    logger.info("Data directory set to: %s", _data_dir.absolute())
+    logger.info("Data directory set to: %s", _data_dir)


 def get_data_dir() -> Path:
@@ -45,6 +60,46 @@ def get_data_dir() -> Path:
    return _data_dir


+def to_storage_path(path: str | Path) -> str:
+    """Convert a filesystem path to a DB-safe path relative to the data dir."""
+    resolved_path = Path(path).resolve()
+
+    relative_to_any_data_dir = _path_relative_to_any_data_dir(resolved_path)
+    if relative_to_any_data_dir is not None:
+        return str(relative_to_any_data_dir)
+
+    try:
+        return str(resolved_path.relative_to(_data_dir))
+    except ValueError:
+        return str(resolved_path)
+
+
+def resolve_storage_path(path: str | Path | None) -> Path | None:
+    """Resolve a DB-stored path against the configured data dir."""
+    if path is None:
+        return None
+
+    stored_path = Path(path)
+    if stored_path.is_absolute():
+        rebased_path = _path_relative_to_any_data_dir(stored_path)
+        if rebased_path is not None:
+            candidate = (_data_dir / rebased_path).resolve()
+            if candidate.exists() or not stored_path.exists():
+                return candidate
+
+        return stored_path
+
+    # 0.3.0 records sometimes stored relative paths with the data-dir name
+    # baked in (e.g. "data/profiles/..."). Joining those directly with
+    # _data_dir produces a spurious "<data_dir>/data/profiles/..." nest.
+    if stored_path.parts and stored_path.parts[0] == "data":
+        stored_path = (
+            Path(*stored_path.parts[1:]) if len(stored_path.parts) > 1 else Path()
+        )
+
+    return (_data_dir / stored_path).resolve()
+
+
 def get_db_path() -> Path:
    """Get database file path."""
    return _data_dir / "voicebox.db"
@@ -34,6 +34,7 @@ def run_migrations(engine) -> None:
    _migrate_generations(engine, inspector, tables)
    _migrate_effect_presets(engine, inspector, tables)
    _migrate_generation_versions(engine, inspector, tables)
+    _normalize_storage_paths(engine, tables)


 # -- helpers ---------------------------------------------------------------
@@ -134,6 +135,17 @@ def _migrate_profiles(engine, inspector, tables: set[str]) -> None:
        _add_column(engine, "profiles", "avatar_path VARCHAR", "avatar_path")
    if "effects_chain" not in columns:
        _add_column(engine, "profiles", "effects_chain TEXT", "effects_chain")
+    # Voice type system — v0.3.x
+    if "voice_type" not in columns:
+        _add_column(engine, "profiles", "voice_type VARCHAR DEFAULT 'cloned'", "voice_type")
+    if "preset_engine" not in columns:
+        _add_column(engine, "profiles", "preset_engine VARCHAR", "preset_engine")
+    if "preset_voice_id" not in columns:
+        _add_column(engine, "profiles", "preset_voice_id VARCHAR", "preset_voice_id")
+    if "design_prompt" not in columns:
+        _add_column(engine, "profiles", "design_prompt TEXT", "design_prompt")
+    if "default_engine" not in columns:
+        _add_column(engine, "profiles", "default_engine VARCHAR", "default_engine")


 def _migrate_generations(engine, inspector, tables: set[str]) -> None:
@@ -168,3 +180,47 @@ def _migrate_generation_versions(engine, inspector, tables: set[str]) -> None:
    columns = _get_columns(inspector, "generation_versions")
    if "source_version_id" not in columns:
        _add_column(engine, "generation_versions", "source_version_id VARCHAR", "source_version_id")
+
+
+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
+
+    data_dir = get_data_dir()
+
+    path_columns = [
+        ("generations", "audio_path"),
+        ("generation_versions", "audio_path"),
+        ("profile_samples", "audio_path"),
+        ("profiles", "avatar_path"),
+    ]
+
+    total_fixed = 0
+    with engine.connect() as conn:
+        for table, column in path_columns:
+            if table not in tables:
+                continue
+            rows = conn.execute(
+                text(f"SELECT id, {column} FROM {table} WHERE {column} IS NOT NULL")
+            ).fetchall()
+            for row_id, path_val in rows:
+                if not path_val:
+                    continue
+                p = Path(path_val)
+                resolved = resolve_storage_path(p)
+                if resolved is None:
+                    continue
+
+                normalized = to_storage_path(resolved)
+
+                if normalized != path_val:
+                    conn.execute(
+                        text(f"UPDATE {table} SET {column} = :path WHERE id = :id"),
+                        {"path": normalized, "id": row_id},
+                    )
+                    total_fixed += 1
+        if total_fixed > 0:
+            conn.commit()
+            logger.info("Normalized %d stored file paths", total_fixed)
@@ -10,7 +10,13 @@ Base = declarative_base()


 class VoiceProfile(Base):
-    """Voice profile."""
+    """Voice profile.
+
+    voice_type discriminates three flavours:
+      - "cloned"   — traditional reference-audio profiles (all cloning engines)
+      - "preset"   — engine-specific pre-built voice (e.g. Kokoro voices)
+      - "designed"  — text-described voice (e.g. Qwen CustomVoice, future)
+    """

    __tablename__ = "profiles"

@@ -20,6 +26,14 @@ class VoiceProfile(Base):
    language = Column(String, default="en")
    avatar_path = Column(String, nullable=True)
    effects_chain = Column(Text, nullable=True)
+
+    # Voice type system — added v0.3.x
+    voice_type = Column(String, default="cloned")  # "cloned" | "preset" | "designed"
+    preset_engine = Column(String, nullable=True)   # e.g. "kokoro" — only for preset
+    preset_voice_id = Column(String, nullable=True)  # e.g. "am_adam" — only for preset
+    design_prompt = Column(Text, nullable=True)      # text description — only for designed
+    default_engine = Column(String, nullable=True)   # auto-selected engine, locked for preset
+
    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

@@ -3,7 +3,8 @@
 import json
 import logging
 import uuid
-from pathlib import Path
+
+from .. import config

 logger = logging.getLogger(__name__)

@@ -25,7 +26,8 @@ def backfill_generation_versions(SessionLocal, Generation, GenerationVersion) ->
        for gen in generations:
            if gen.id in existing_version_gen_ids:
                continue
-            if not Path(gen.audio_path).exists():
+            resolved_audio_path = config.resolve_storage_path(gen.audio_path)
+            if resolved_audio_path is None or not resolved_audio_path.exists():
                continue
            version = GenerationVersion(
                id=str(uuid.uuid4()),
@@ -15,6 +15,11 @@ class VoiceProfileCreate(BaseModel):
    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)


 class VoiceProfileResponse(BaseModel):
@@ -26,6 +31,11 @@ class VoiceProfileResponse(BaseModel):
    language: str
    avatar_path: Optional[str] = None
    effects_chain: Optional[List["EffectConfig"]] = 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
    generation_count: int = 0
    sample_count: int = 0
    created_at: datetime
@@ -68,7 +78,7 @@ class GenerationRequest(BaseModel):
    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|luxtts|chatterbox|chatterbox_turbo|tada)$")
+    engine: Optional[str] = Field(default="qwen", pattern="^(qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro)$")
    max_chunk_chars: int = Field(
        default=800, ge=100, le=5000, description="Max characters per chunk for long text splitting"
    )
@@ -172,6 +182,7 @@ class HealthResponse(BaseModel):
    vram_used_mb: Optional[float] = None
    backend_type: Optional[str] = None  # Backend type (mlx or pytorch)
    backend_variant: Optional[str] = None  # Binary variant (cpu or cuda)
+    gpu_compatibility_warning: Optional[str] = None  # Warning if GPU arch unsupported


 class DirectoryCheck(BaseModel):
@@ -0,0 +1,95 @@
+"""
+PyInstaller runtime hook: numpy 2.x / torch ABI mismatch fix.
+
+Problem
+-------
+torch is compiled against numpy 1.x headers. numpy 2.x changed the version
+number returned by PyArray_GetNDArrayCVersion() (0x01000009 → 0x02000000),
+so torch's is_numpy_available() returns False and every torch.from_numpy()
+call raises:
+
+    RuntimeError: Numpy is not available
+
+This surfaces as:
+
+    ValueError: Unable to create tensor, you should probably activate
+    padding with 'padding=True'
+
+during TTS generation (EncodecFeatureExtractor → BatchFeature.convert_to_tensors).
+
+Fix
+---
+Runtime hooks execute after PyInstaller's FrozenImporter is registered, so
+frozen torch/numpy are importable here. We start a background thread that
+waits for torch to finish loading then wraps torch.from_numpy with a ctypes
+memmove fallback that bypasses the C-level numpy ABI check entirely.
+
+This approach works with any numpy version and is safer than binary-patching
+libtorch_python.dylib (which risks PyArray_Descr struct layout mismatches).
+"""
+
+import sys
+import threading
+
+
+def _patch_torch_from_numpy():
+    import time
+
+    for _ in range(7200):  # poll up to 360 s at 50 ms intervals
+        time.sleep(0.05)
+        torch = sys.modules.get("torch")
+        if torch is None or not hasattr(torch, "from_numpy"):
+            continue
+        if getattr(torch, "_vb_from_numpy_patched", False):
+            return
+        try:
+            import ctypes
+            import numpy as np
+
+            _orig = torch.from_numpy
+
+            # Explicit numpy → torch dtype map. Silent fallback to float32 on
+            # unknown dtypes would reinterpret the memcpy'd bytes as fp32 and
+            # 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,
+            }
+
+            def _safe_from_numpy(
+                arr, _orig=_orig, _c=ctypes, _np=np, _t=torch, _map=dtype_map
+            ):
+                try:
+                    return _orig(arr)
+                except RuntimeError:
+                    a = _np.ascontiguousarray(arr)
+                    key = str(a.dtype)
+                    if key not in _map:
+                        raise TypeError(
+                            f"pyi_rth_numpy_compat: unsupported numpy dtype "
+                            f"{key!r} in torch.from_numpy fallback; add an "
+                            f"explicit mapping rather than silently copying "
+                            f"bytes into the wrong dtype."
+                        )
+                    out = _t.empty(list(a.shape), dtype=_map[key])
+                    _c.memmove(out.data_ptr(), a.ctypes.data, a.nbytes)
+                    return out
+
+            torch.from_numpy = _safe_from_numpy
+            torch._vb_from_numpy_patched = True
+        except Exception:
+            pass
+        return
+
+
+threading.Thread(target=_patch_torch_from_numpy, daemon=True).start()
@@ -8,7 +8,7 @@ sqlalchemy>=2.0.0
 alembic>=1.13.0

 # ML models
-torch>=2.7.0
+torch>=2.2.0
 transformers>=4.36.0,<=4.57.6
 accelerate>=0.26.0
 huggingface_hub>=0.20.0
@@ -40,10 +40,17 @@ pyloudnorm
 # provides the only class TADA uses: Snake1d.)
 torchaudio

+# Kokoro TTS (lightweight 82M-param engine)
+kokoro>=0.9.4
+misaki[en,ja,zh]>=0.9.4
+# spacy model for misaki English G2P — must be pre-installed or misaki
+# tries spacy.cli.download() at runtime which crashes frozen builds
+en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
+
 # Audio processing
 librosa>=0.10.0
 soundfile>=0.12.0
-numpy>=1.24.0
+numpy>=1.24.0,<2.0
 numba>=0.60.0,<0.61.0
 pedalboard>=0.9.0

@@ -1,12 +1,10 @@
 """Audio file serving endpoints."""

-from pathlib import Path
-
 from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import FileResponse
 from sqlalchemy.orm import Session

-from .. import models
+from .. import config, models
 from ..services import history
 from ..database import get_db

@@ -22,8 +20,8 @@ async def get_version_audio(version_id: str, db: Session = Depends(get_db)):
    if not version:
        raise HTTPException(status_code=404, detail="Version not found")

-    audio_path = Path(version.audio_path)
-    if not audio_path.exists():
+    audio_path = config.resolve_storage_path(version.audio_path)
+    if audio_path is None or not audio_path.exists():
        raise HTTPException(status_code=404, detail="Audio file not found")

    return FileResponse(
@@ -40,8 +38,8 @@ async def get_audio(generation_id: str, db: Session = Depends(get_db)):
    if not generation:
        raise HTTPException(status_code=404, detail="Generation not found")

-    audio_path = Path(generation.audio_path)
-    if not audio_path.exists():
+    audio_path = config.resolve_storage_path(generation.audio_path)
+    if audio_path is None or not audio_path.exists():
        raise HTTPException(status_code=404, detail="Audio file not found")

    return FileResponse(
@@ -60,8 +58,8 @@ async def get_sample_audio(sample_id: str, db: Session = Depends(get_db)):
    if not sample:
        raise HTTPException(status_code=404, detail="Sample not found")

-    audio_path = Path(sample.audio_path)
-    if not audio_path.exists():
+    audio_path = config.resolve_storage_path(sample.audio_path)
+    if audio_path is None or not audio_path.exists():
        raise HTTPException(status_code=404, detail="Audio file not found")

    return FileResponse(
@@ -3,7 +3,6 @@
 import asyncio
 import io
 import uuid
-from pathlib import Path

 from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import StreamingResponse
@@ -41,10 +40,11 @@ async def preview_effects(
    all_versions = versions_mod.list_versions(generation_id, db)
    clean_version = next((v for v in all_versions if v.effects_chain is None), None)
    source_path = clean_version.audio_path if clean_version else gen.audio_path
-    if not source_path or not Path(source_path).exists():
+    resolved_source_path = config.resolve_storage_path(source_path)
+    if resolved_source_path is None or not resolved_source_path.exists():
        raise HTTPException(status_code=404, detail="Source audio file not found")

-    audio, sample_rate = await asyncio.to_thread(load_audio, source_path)
+    audio, sample_rate = await asyncio.to_thread(load_audio, str(resolved_source_path))
    processed = await asyncio.to_thread(apply_effects, audio, sample_rate, chain_dicts)

    import soundfile as sf
@@ -193,10 +193,11 @@ async def apply_effects_to_generation(
            source_path = clean_version.audio_path
            source_version_id = clean_version.id

-    if not source_path or not Path(source_path).exists():
+    resolved_source_path = config.resolve_storage_path(source_path)
+    if resolved_source_path is None or not resolved_source_path.exists():
        raise HTTPException(status_code=404, detail="Source audio file not found")

-    audio, sample_rate = await asyncio.to_thread(load_audio, source_path)
+    audio, sample_rate = await asyncio.to_thread(load_audio, str(resolved_source_path))
    processed_audio = await asyncio.to_thread(apply_effects, audio, sample_rate, chain_dicts)

    version_id = str(uuid.uuid4())
@@ -208,7 +209,7 @@ async def apply_effects_to_generation(
    version = versions_mod.create_version(
        generation_id=generation_id,
        label=label,
-        audio_path=str(processed_path),
+        audio_path=config.to_storage_path(processed_path),
        db=db,
        effects_chain=chain_dicts,
        is_default=data.set_as_default,
@@ -20,6 +20,10 @@ from ..utils.tasks import get_task_manager
 router = APIRouter()


+def _resolve_generation_engine(data: models.GenerationRequest, profile) -> str:
+    return data.engine or getattr(profile, "default_engine", None) or getattr(profile, "preset_engine", None) or "qwen"
+
+
@router.post("/generate", response_model=models.GenerationResponse)
 async def generate_speech(
    data: models.GenerationRequest,
@@ -35,7 +39,12 @@ async def generate_speech(

    from ..backends import engine_has_model_sizes

-    engine = data.engine or "qwen"
+    engine = _resolve_generation_engine(data, profile)
+    try:
+        profiles.validate_profile_engine(profile, engine)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
    model_size = (data.model_size or "1.7B") if engine_has_model_sizes(engine) else None

    generation = await history.create_generation(
@@ -230,7 +239,11 @@ async def stream_speech(
    if not profile:
        raise HTTPException(status_code=404, detail="Profile not found")

-    engine = data.engine or "qwen"
+    engine = _resolve_generation_engine(data, profile)
+    try:
+        profiles.validate_profile_engine(profile, engine)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
    tts_model = get_tts_backend_for_engine(engine)
    model_size = data.model_size or "1.7B"

@@ -263,6 +276,22 @@ async def stream_speech(
        trim_fn=trim_fn,
    )

+    effects_chain_config = None
+    if data.effects_chain is not None:
+        effects_chain_config = [e.model_dump() for e in data.effects_chain]
+    elif profile.effects_chain:
+        import json as _json
+
+        try:
+            effects_chain_config = _json.loads(profile.effects_chain)
+        except Exception:
+            effects_chain_config = None
+
+    if effects_chain_config:
+        from ..utils.effects import apply_effects
+
+        audio = apply_effects(audio, sample_rate, effects_chain_config)
+
    if data.normalize:
        from ..utils.audio import normalize_audio

@@ -93,6 +93,12 @@ async def health():
    except ImportError:
        pass

+    gpu_compat_warning = None
+    if has_cuda:
+        from ..backends.base import check_cuda_compatibility
+
+        _compatible, gpu_compat_warning = check_cuda_compatibility()
+
    gpu_available = has_cuda or has_mps or has_xpu or has_directml or backend_type == "mlx"

    gpu_type = None
@@ -110,6 +116,11 @@ async def health():
    vram_used = None
    if has_cuda:
        vram_used = torch.cuda.memory_allocated() / 1024 / 1024
+    elif has_xpu:
+        try:
+            vram_used = torch.xpu.memory_allocated() / 1024 / 1024
+        except Exception:
+            pass  # memory_allocated() may not be available on all IPEX versions

    model_loaded = False
    model_size = None
@@ -162,7 +173,11 @@ async def health():
        gpu_type=gpu_type,
        vram_used_mb=vram_used,
        backend_type=backend_type,
-        backend_variant=os.environ.get("VOICEBOX_BACKEND_VARIANT", "cuda" if torch.cuda.is_available() else "cpu"),
+        backend_variant=os.environ.get(
+            "VOICEBOX_BACKEND_VARIANT",
+            "cuda" if torch.cuda.is_available() else ("xpu" if has_xpu else "cpu"),
+        ),
+        gpu_compatibility_warning=gpu_compat_warning,
    )


@@ -1,13 +1,12 @@
 """Generation history endpoints."""

 import io
-from pathlib import Path

 from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
 from fastapi.responses import FileResponse, StreamingResponse
 from sqlalchemy.orm import Session

-from .. import models
+from .. import config, models
 from ..services import export_import, history
 from ..app import safe_content_disposition
 from ..database import Generation as DBGeneration, VoiceProfile as DBVoiceProfile, get_db
@@ -63,6 +62,13 @@ async def import_generation(
        raise HTTPException(status_code=500, detail=str(e))


+@router.delete("/history/failed")
+async def clear_failed_generations(db: Session = Depends(get_db)):
+    """Delete every generation with status='failed'. Used by the UI's 'Clear failed' button (#410)."""
+    count = await history.delete_failed_generations(db)
+    return {"deleted": count}
+
+
@router.get("/history/{generation_id}", response_model=models.HistoryResponse)
 async def get_generation(
    generation_id: str,
@@ -90,6 +96,11 @@ async def get_generation(
        duration=gen.duration,
        seed=gen.seed,
        instruct=gen.instruct,
+        engine=gen.engine or "qwen",
+        model_size=gen.model_size,
+        status=gen.status or "completed",
+        error=gen.error,
+        is_favorited=bool(gen.is_favorited),
        created_at=gen.created_at,
    )

@@ -162,8 +173,8 @@ async def export_generation_audio(
    if not generation.audio_path:
        raise HTTPException(status_code=404, detail="Generation has no audio file")

-    audio_path = Path(generation.audio_path)
-    if not audio_path.is_file():
+    audio_path = config.resolve_storage_path(generation.audio_path)
+    if audio_path is None or not audio_path.is_file():
        raise HTTPException(status_code=404, detail="Audio file not found")

    safe_text = "".join(c for c in generation.text[:30] if c.isalnum() or c in (" ", "-", "_")).strip()
@@ -1,6 +1,8 @@
 """Voice profile endpoints."""

 import io
+import json as _json
+import logging
 import tempfile
 from datetime import datetime
 from pathlib import Path
@@ -15,6 +17,8 @@ from ..database import VoiceProfile as DBVoiceProfile, get_db
 from ..services import channels, export_import, profiles
 from ..services.profiles import _profile_to_response

+logger = logging.getLogger(__name__)
+
 router = APIRouter()


@@ -62,6 +66,46 @@ async def import_profile(
        raise HTTPException(status_code=500, detail=str(e))


+# ── Preset Voice Endpoints ───────────────────────────────────────────
+# These MUST be declared before /profiles/{profile_id} to avoid the
+# wildcard swallowing "presets" as a profile_id.
+
+
+@router.get("/profiles/presets/{engine}")
+async def list_preset_voices(engine: str):
+    """List available preset voices for an engine."""
+    if engine == "kokoro":
+        from ..backends.kokoro_backend import KOKORO_VOICES
+
+        return {
+            "engine": engine,
+            "voices": [
+                {
+                    "voice_id": vid,
+                    "name": name,
+                    "gender": gender,
+                    "language": lang,
+                }
+                for vid, name, gender, lang in KOKORO_VOICES
+            ],
+        }
+    if engine == "qwen_custom_voice":
+        from ..backends.qwen_custom_voice_backend import QWEN_CUSTOM_VOICES
+
+        return {
+            "engine": engine,
+            "voices": [
+                {
+                    "voice_id": speaker_id,
+                    "name": display_name,
+                    "gender": gender,
+                    "language": lang,
+                }
+                for speaker_id, display_name, gender, lang, _desc in QWEN_CUSTOM_VOICES
+            ],
+        }
+    return {"engine": engine, "voices": []}
+
@router.get("/profiles/{profile_id}", response_model=models.VoiceProfileResponse)
 async def get_profile(
    profile_id: str,
@@ -215,8 +259,8 @@ async def get_profile_avatar(
    if not profile.avatar_path:
        raise HTTPException(status_code=404, detail="No avatar found for this profile")

-    avatar_path = Path(profile.avatar_path)
-    if not avatar_path.exists():
+    avatar_path = config.resolve_storage_path(profile.avatar_path)
+    if avatar_path is None or not avatar_path.exists():
        raise HTTPException(status_code=404, detail="Avatar file not found")

    return FileResponse(avatar_path)
@@ -297,8 +341,6 @@ async def update_profile_effects(
    db: Session = Depends(get_db),
 ):
    """Set or clear the default effects chain for a voice profile."""
-    import json as _json
-
    profile = db.query(DBVoiceProfile).filter_by(id=profile_id).first()
    if not profile:
        raise HTTPException(status_code=404, detail="Profile not found")
@@ -105,6 +105,11 @@ def _start_parent_watchdog(parent_pid, data_dir=None):
    This is the clean shutdown mechanism: instead of the Tauri app trying to
    forcefully kill the server (which spawns console windows on Windows),
    the server monitors its parent and shuts itself down gracefully.
+
+    The Tauri app writes a .keep-running sentinel file to data_dir before
+    exiting when "remain running after close" is enabled. This is a reliable
+    fallback for the HTTP /watchdog/disable request, which can race with
+    process exit on Windows.
    """
    import os
    import signal
@@ -164,6 +169,19 @@ def _start_parent_watchdog(parent_pid, data_dir=None):
        if not alive:
            watchdog_logger.warning(f"Parent PID {parent_pid} not found on first check — disabling watchdog")
            return
+        # Clear any stale .keep-running sentinel from a previous session. The
+        # sentinel is only removed by the watchdog when it's consumed during a
+        # grace period; if the HTTP /watchdog/disable path wins the race on a
+        # "keep running" exit, the sentinel is left on disk. Wipe it here so a
+        # future session can't inherit that stale signal.
+        if data_dir:
+            stale = os.path.join(data_dir, ".keep-running")
+            if os.path.exists(stale):
+                try:
+                    os.remove(stale)
+                    watchdog_logger.info("Removed stale .keep-running sentinel from previous session")
+                except OSError as e:
+                    watchdog_logger.warning(f"Failed to remove stale sentinel: {e}")
        while True:
            if _watchdog_disabled:
                watchdog_logger.info("Watchdog disabled (keep server running), stopping monitor")
@@ -178,6 +196,18 @@ def _start_parent_watchdog(parent_pid, data_dir=None):
                if _watchdog_disabled:
                    watchdog_logger.info("Watchdog was disabled during grace period, keeping server alive")
                    return
+                # Check for sentinel file written by Tauri before exit.
+                # This catches the case where the HTTP disable request
+                # didn't arrive before the parent process died (common
+                # on Windows where process teardown is fast).
+                sentinel = os.path.join(data_dir, ".keep-running") if data_dir else None
+                if sentinel and os.path.exists(sentinel):
+                    watchdog_logger.info("Found .keep-running sentinel file, keeping server alive")
+                    try:
+                        os.remove(sentinel)
+                    except OSError:
+                        pass
+                    return
                watchdog_logger.info("Watchdog still enabled after grace period, shutting down server...")
                if sys.platform == "win32":
                    # sys.exit triggers SystemExit, allowing uvicorn to run
@@ -11,6 +11,7 @@ Both archives are extracted into {data_dir}/backends/cuda/ which forms the
 complete PyInstaller --onedir directory structure that torch expects.
 """

+import asyncio
 import hashlib
 import json
 import logging
@@ -34,6 +35,12 @@ PROGRESS_KEY = "cuda-backend"
 # CUDA toolkit version or torch's CUDA dependency changes (e.g. cu126 -> cu128).
 CUDA_LIBS_VERSION = "cu128-v1"

+# Prevents concurrent download_cuda_binary() calls from racing on the same
+# temp file.  The auto-update background task and the manual HTTP endpoint
+# can both invoke download_cuda_binary(); without this lock the progress-
+# manager status check is a TOCTOU race.
+_download_lock = asyncio.Lock()
+

 def get_backends_dir() -> Path:
    """Directory where downloaded backend binaries are stored."""
@@ -241,6 +248,15 @@ async def download_cuda_binary(version: Optional[str] = None):
    Args:
        version: Version tag (e.g. "v0.3.0"). Defaults to current app version.
    """
+    if _download_lock.locked():
+        logger.info("CUDA download already in progress, skipping duplicate request")
+        return
+    async with _download_lock:
+        await _download_cuda_binary_locked(version)
+
+
+async def _download_cuda_binary_locked(version: Optional[str] = None):
+    """Inner implementation of download_cuda_binary, called under _download_lock."""
    import httpx

    if version is None:
@@ -11,6 +11,8 @@ from typing import List, Optional
 from sqlalchemy.orm import Session
 from sqlalchemy.exc import IntegrityError

+from ..utils.effects import validate_effects_chain
+
 from ..database import EffectPreset as DBEffectPreset
 from ..models import EffectPresetResponse, EffectPresetCreate, EffectPresetUpdate, EffectConfig

@@ -52,7 +54,6 @@ def get_preset_by_name(name: str, db: Session) -> Optional[EffectPresetResponse]

 def create_preset(data: EffectPresetCreate, db: Session) -> EffectPresetResponse:
    """Create a new user effect preset."""
-    from .utils.effects import validate_effects_chain

    chain_dicts = [e.model_dump() for e in data.effects_chain]
    error = validate_effects_chain(chain_dicts)
@@ -94,7 +95,6 @@ def update_preset(preset_id: str, data: EffectPresetUpdate, db: Session) -> Opti
    if data.description is not None:
        preset.description = data.description
    if data.effects_chain is not None:
-        from .utils.effects import validate_effects_chain

        chain_dicts = [e.model_dump() for e in data.effects_chain]
        error = validate_effects_chain(chain_dicts)
@@ -73,8 +73,8 @@ def export_profile_to_zip(profile_id: str, db: Session) -> bytes:
        # Check if profile has avatar
        has_avatar = False
        if profile.avatar_path:
-            avatar_path = Path(profile.avatar_path)
-            if avatar_path.exists():
+            avatar_path = config.resolve_storage_path(profile.avatar_path)
+            if avatar_path is not None and avatar_path.exists():
                has_avatar = True
                # Add avatar to ZIP root with original extension
                avatar_ext = avatar_path.suffix
@@ -98,7 +98,9 @@ def export_profile_to_zip(profile_id: str, db: Session) -> bytes:

        for sample in samples:
            # Get filename from audio_path (should be {sample_id}.wav)
-            audio_path = Path(sample.audio_path)
+            audio_path = config.resolve_storage_path(sample.audio_path)
+            if audio_path is None:
+                raise ValueError(f"Audio file not found: {sample.audio_path}")
            filename = audio_path.name

            # Read audio file
@@ -279,7 +281,7 @@ def export_generation_to_zip(generation_id: str, db: Session) -> bytes:
        # Build version manifest entries
        version_entries = []
        for v in versions:
-            v_path = Path(v.audio_path)
+            v_path = config.resolve_storage_path(v.audio_path)
            effects_chain = None
            if v.effects_chain:
                effects_chain = json.loads(v.effects_chain)
@@ -314,14 +316,14 @@ def export_generation_to_zip(generation_id: str, db: Session) -> bytes:
        
        # Add all version audio files
        for v in versions:
-            v_path = Path(v.audio_path)
-            if v_path.exists():
+            v_path = config.resolve_storage_path(v.audio_path)
+            if v_path is not None and v_path.exists():
                zip_file.write(v_path, f"audio/{v_path.name}")

        # Fallback: if no versions exist, include the generation's main audio
        if not versions:
-            audio_path = Path(generation.audio_path)
-            if audio_path.exists():
+            audio_path = config.resolve_storage_path(generation.audio_path)
+            if audio_path is not None and audio_path.exists():
                zip_file.write(audio_path, f"audio/{audio_path.name}")
    
    zip_buffer.seek(0)
@@ -426,7 +428,7 @@ async def import_generation_from_zip(file_bytes: bytes, db: Session) -> dict:
                    profile_id=profile_id,
                    text=generation_data["text"],
                    language=generation_data["language"],
-                    audio_path=str(audio_dest),
+                    audio_path=config.to_storage_path(audio_dest),
                    duration=generation_data["duration"],
                    seed=generation_data.get("seed"),
                    instruct=generation_data.get("instruct"),
@@ -163,7 +163,7 @@ def _save_generate(
    versions_mod.create_version(
        generation_id=generation_id,
        label="original",
-        audio_path=str(clean_audio_path),
+        audio_path=config.to_storage_path(clean_audio_path),
        db=db,
        effects_chain=None,
        is_default=not has_effects,
@@ -174,6 +174,8 @@ def _save_generate(
    if has_effects:
        from ..utils.effects import apply_effects, validate_effects_chain

+        assert effects_chain is not None
+
        error_msg = validate_effects_chain(effects_chain)
        if error_msg:
            import logging
@@ -189,13 +191,13 @@ def _save_generate(
            versions_mod.create_version(
                generation_id=generation_id,
                label="version-2",
-                audio_path=str(processed_path),
+                audio_path=config.to_storage_path(processed_path),
                db=db,
                effects_chain=effects_chain,
                is_default=True,
            )

-    return final_audio_path
+    return config.to_storage_path(final_audio_path)


 def _save_retry(
@@ -211,7 +213,7 @@ def _save_retry(
    """
    audio_path = config.get_generations_dir() / f"{generation_id}.wav"
    save_audio(audio, str(audio_path), sample_rate)
-    return str(audio_path)
+    return config.to_storage_path(audio_path)


 def _save_regenerate(
@@ -244,10 +246,10 @@ def _save_regenerate(
    versions_mod.create_version(
        generation_id=generation_id,
        label=label,
-        audio_path=str(audio_path),
+        audio_path=config.to_storage_path(audio_path),
        db=db,
        effects_chain=None,
        is_default=True,
    )

-    return str(audio_path)
+    return config.to_storage_path(audio_path)
@@ -253,8 +253,8 @@ async def delete_generation(

    # Delete main audio file (if not already removed by version cleanup)
    if generation.audio_path:
-        audio_path = Path(generation.audio_path)
-        if audio_path.exists():
+        audio_path = config.resolve_storage_path(generation.audio_path)
+        if audio_path is not None and audio_path.exists():
            audio_path.unlink()

    # Delete from database
@@ -264,6 +264,43 @@ async def delete_generation(
    return True


+async def delete_failed_generations(db: Session) -> int:
+    """
+    Delete every generation whose status is 'failed'.
+
+    Used by the "Clear failed" action in the UI so users can tidy up
+    history after the model wasn't loaded, the app was closed mid-run,
+    or a generation otherwise errored out (see issue #410).
+
+    Returns:
+        Number of generations deleted.
+    """
+    from . import versions as versions_mod
+
+    failed = db.query(DBGeneration).filter(DBGeneration.status == "failed").all()
+    count = 0
+    for generation in failed:
+        # Clean up version files/rows first.
+        versions_mod.delete_versions_for_generation(generation.id, db)
+
+        # Remove the main audio file if it somehow made it to disk.
+        if generation.audio_path:
+            audio_path = config.resolve_storage_path(generation.audio_path)
+            if audio_path is not None and audio_path.exists():
+                try:
+                    audio_path.unlink()
+                except OSError:
+                    # Best-effort cleanup — don't abort the whole sweep
+                    # if a single file can't be removed.
+                    pass
+
+        db.delete(generation)
+        count += 1
+
+    db.commit()
+    return count
+
+
 async def delete_generations_by_profile(
    profile_id: str,
    db: Session,
@@ -283,8 +320,8 @@ async def delete_generations_by_profile(
    count = 0
    for generation in generations:
        # Delete audio file
-        audio_path = Path(generation.audio_path)
-        if audio_path.exists():
+        audio_path = config.resolve_storage_path(generation.audio_path)
+        if audio_path is not None and audio_path.exists():
            audio_path.unlink()
        
        # Delete from database
@@ -1,33 +1,30 @@
-"""
-Voice profile management module.
-"""
+"""Voice profile management module."""

-from typing import List, Optional
-from datetime import datetime
-import uuid
+import json as _json
+import logging
 import shutil
+import uuid
+from datetime import datetime
 from pathlib import Path
-from sqlalchemy.orm import Session
-from sqlalchemy import func, select

+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from .. import config
+from ..database import Generation as DBGeneration, ProfileSample as DBProfileSample, VoiceProfile as DBVoiceProfile
 from ..models import (
+    EffectConfig,
+    ProfileSampleResponse,
    VoiceProfileCreate,
    VoiceProfileResponse,
-    ProfileSampleCreate,
-    ProfileSampleResponse,
 )
-from ..database import (
-    VoiceProfile as DBVoiceProfile,
-    ProfileSample as DBProfileSample,
-    Generation as DBGeneration,
-)
-from ..models import EffectConfig
-from ..utils.audio import validate_reference_audio, validate_and_load_reference_audio, load_audio, save_audio
-from ..utils.images import validate_image, process_avatar
+from ..utils.audio import save_audio, validate_and_load_reference_audio
 from ..utils.cache import _get_cache_dir, clear_profile_cache
-from .tts import get_tts_model
-from .. import config
-import json as _json
+from ..utils.images import process_avatar, validate_image
+
+logger = logging.getLogger(__name__)
+
+CLONING_ENGINES = {"qwen", "luxtts", "chatterbox", "chatterbox_turbo", "tada"}


 def _profile_to_response(
@@ -52,6 +49,11 @@ def _profile_to_response(
        language=profile.language,
        avatar_path=profile.avatar_path,
        effects_chain=effects_chain,
+        voice_type=getattr(profile, "voice_type", None) or "cloned",
+        preset_engine=getattr(profile, "preset_engine", None),
+        preset_voice_id=getattr(profile, "preset_voice_id", None),
+        design_prompt=getattr(profile, "design_prompt", None),
+        default_engine=getattr(profile, "default_engine", None),
        generation_count=generation_count,
        sample_count=sample_count,
        created_at=profile.created_at,
@@ -59,6 +61,79 @@ def _profile_to_response(
    )


+def _get_preset_voice_ids(engine: str) -> set[str]:
+    if engine == "kokoro":
+        from ..backends.kokoro_backend import KOKORO_VOICES
+
+        return {voice_id for voice_id, _name, _gender, _lang in KOKORO_VOICES}
+
+    if engine == "qwen_custom_voice":
+        from ..backends.qwen_custom_voice_backend import QWEN_CUSTOM_VOICES
+
+        return {voice_id for voice_id, _name, _gender, _lang, _desc in QWEN_CUSTOM_VOICES}
+
+    return set()
+
+
+def _validate_profile_fields(
+    *,
+    voice_type: str,
+    preset_engine: str | None,
+    preset_voice_id: str | None,
+    design_prompt: str | None,
+    default_engine: str | None,
+) -> str | None:
+    if voice_type == "preset":
+        if not preset_engine or not preset_voice_id:
+            return "Preset profiles require both preset_engine and preset_voice_id"
+        if default_engine and default_engine != preset_engine:
+            return "Preset profiles must use their preset_engine as default_engine"
+
+        available_voice_ids = _get_preset_voice_ids(preset_engine)
+        if available_voice_ids and preset_voice_id not in available_voice_ids:
+            return f"Preset voice '{preset_voice_id}' is not valid for engine '{preset_engine}'"
+        return None
+
+    if voice_type == "designed":
+        if not design_prompt or not design_prompt.strip():
+            return "Designed profiles require a design_prompt"
+        if preset_engine or preset_voice_id:
+            return "Designed profiles cannot set preset_engine or preset_voice_id"
+        return None
+
+    if preset_engine or preset_voice_id:
+        return "Cloned profiles cannot set preset_engine or preset_voice_id"
+    if design_prompt:
+        return "Cloned profiles cannot set design_prompt"
+    if default_engine and default_engine not in CLONING_ENGINES:
+        return f"Cloned profiles cannot use default engine '{default_engine}'"
+    return None
+
+
+def validate_profile_engine(profile, engine: str) -> None:
+    voice_type = getattr(profile, "voice_type", None) or "cloned"
+
+    if voice_type == "preset":
+        preset_engine = getattr(profile, "preset_engine", None)
+        preset_voice_id = getattr(profile, "preset_voice_id", None)
+        if not preset_engine or not preset_voice_id:
+            raise ValueError(f"Preset profile {profile.id} is missing preset engine metadata")
+        if preset_engine != engine:
+            raise ValueError(
+                f"Preset profile {profile.id} only supports engine '{preset_engine}', not '{engine}'"
+            )
+        return
+
+    if voice_type == "designed":
+        design_prompt = getattr(profile, "design_prompt", None)
+        if not design_prompt or not design_prompt.strip():
+            raise ValueError(f"Designed profile {profile.id} is missing design_prompt")
+        return
+
+    if engine not in CLONING_ENGINES:
+        raise ValueError(f"Engine '{engine}' does not support cloned voice profiles")
+
+
 async def create_profile(
    data: VoiceProfileCreate,
    db: Session,
@@ -80,11 +155,32 @@ async def create_profile(
    if existing_profile:
        raise ValueError(f"A profile with the name '{data.name}' already exists. Please choose a different name.")

+    # Auto-set default_engine for preset profiles
+    default_engine = data.default_engine
+    voice_type = data.voice_type or "cloned"
+    if voice_type == "preset" and data.preset_engine and not default_engine:
+        default_engine = data.preset_engine
+
+    validation_error = _validate_profile_fields(
+        voice_type=voice_type,
+        preset_engine=data.preset_engine,
+        preset_voice_id=data.preset_voice_id,
+        design_prompt=data.design_prompt,
+        default_engine=default_engine,
+    )
+    if validation_error:
+        raise ValueError(validation_error)
+
    db_profile = DBVoiceProfile(
        id=str(uuid.uuid4()),
        name=data.name,
        description=data.description,
        language=data.language,
+        voice_type=voice_type,
+        preset_engine=data.preset_engine,
+        preset_voice_id=data.preset_voice_id,
+        design_prompt=data.design_prompt,
+        default_engine=default_engine,
        created_at=datetime.utcnow(),
        updated_at=datetime.utcnow(),
    )
@@ -140,7 +236,7 @@ async def add_profile_sample(
    db_sample = DBProfileSample(
        id=sample_id,
        profile_id=profile_id,
-        audio_path=str(dest_path),
+        audio_path=config.to_storage_path(dest_path),
        reference_text=reference_text,
    )

@@ -161,7 +257,7 @@ async def add_profile_sample(
 async def get_profile(
    profile_id: str,
    db: Session,
-) -> Optional[VoiceProfileResponse]:
+) -> VoiceProfileResponse | None:
    """
    Get a voice profile by ID.

@@ -182,7 +278,7 @@ async def get_profile(
 async def get_profile_samples(
    profile_id: str,
    db: Session,
-) -> List[ProfileSampleResponse]:
+) -> list[ProfileSampleResponse]:
    """
    Get all samples for a profile.

@@ -197,7 +293,7 @@ async def get_profile_samples(
    return [ProfileSampleResponse.model_validate(s) for s in samples]


-async def list_profiles(db: Session) -> List[VoiceProfileResponse]:
+async def list_profiles(db: Session) -> list[VoiceProfileResponse]:
    """
    List all voice profiles with generation and sample counts.

@@ -238,7 +334,7 @@ async def update_profile(
    profile_id: str,
    data: VoiceProfileCreate,
    db: Session,
-) -> Optional[VoiceProfileResponse]:
+) -> VoiceProfileResponse | None:
    """
    Update a voice profile.

@@ -262,9 +358,27 @@ async def update_profile(
        if existing_profile:
            raise ValueError(f"A profile with the name '{data.name}' already exists. Please choose a different name.")

+    voice_type = getattr(profile, "voice_type", None) or "cloned"
+    preset_engine = getattr(profile, "preset_engine", None)
+    preset_voice_id = getattr(profile, "preset_voice_id", None)
+    design_prompt = getattr(profile, "design_prompt", None)
+    default_engine = data.default_engine if data.default_engine is not None else getattr(profile, "default_engine", None)
+
+    validation_error = _validate_profile_fields(
+        voice_type=voice_type,
+        preset_engine=preset_engine,
+        preset_voice_id=preset_voice_id,
+        design_prompt=design_prompt,
+        default_engine=default_engine,
+    )
+    if validation_error:
+        raise ValueError(validation_error)
+
    profile.name = data.name
    profile.description = data.description
    profile.language = data.language
+    if data.default_engine is not None:
+        profile.default_engine = data.default_engine or None  # empty string → NULL
    profile.updated_at = datetime.utcnow()

    db.commit()
@@ -327,8 +441,8 @@ async def delete_profile_sample(
    # Store profile_id before deleting
    profile_id = sample.profile_id

-    audio_path = Path(sample.audio_path)
-    if audio_path.exists():
+    audio_path = config.resolve_storage_path(sample.audio_path)
+    if audio_path is not None and audio_path.exists():
        audio_path.unlink()

    db.delete(sample)
@@ -345,7 +459,7 @@ async def update_profile_sample(
    sample_id: str,
    reference_text: str,
    db: Session,
-) -> Optional[ProfileSampleResponse]:
+) -> ProfileSampleResponse | None:
    """
    Update a profile sample's reference text.

@@ -382,19 +496,57 @@ async def create_voice_prompt_for_profile(
    engine: str = "qwen",
 ) -> dict:
    """
-    Create a combined voice prompt from all samples in a profile.
+    Create a voice prompt from a profile.
+
+    For cloned profiles: combines all audio samples into a voice prompt.
+    For preset profiles: returns the engine-specific preset voice reference.
+    For designed profiles: returns the text design prompt (future).

    Args:
        profile_id: Profile ID
        db: Database session
        use_cache: Whether to use cached prompts
-        engine: TTS engine to create prompt for ("qwen" or "luxtts")
+        engine: TTS engine to create prompt for

    Returns:
        Voice prompt dictionary
    """
    from ..backends import get_tts_backend_for_engine

+    profile = db.query(DBVoiceProfile).filter_by(id=profile_id).first()
+    if not profile:
+        raise ValueError(f"Profile not found: {profile_id}")
+
+    voice_type = getattr(profile, "voice_type", None) or "cloned"
+    validate_profile_engine(profile, engine)
+
+    # ── Preset profiles: return engine-specific voice reference ──
+    if voice_type == "preset":
+        if not profile.preset_engine or not profile.preset_voice_id:
+            raise ValueError(f"Preset profile {profile_id} is missing preset engine metadata")
+        if profile.preset_engine != engine:
+            raise ValueError(
+                f"Preset profile {profile_id} only supports engine '{profile.preset_engine}', not '{engine}'"
+            )
+        return {
+            "voice_type": "preset",
+            "preset_engine": profile.preset_engine,
+            "preset_voice_id": profile.preset_voice_id,
+        }
+
+    # ── Designed profiles: return text description (future) ──
+    if voice_type == "designed":
+        if not profile.design_prompt or not profile.design_prompt.strip():
+            raise ValueError(f"Designed profile {profile_id} is missing design_prompt")
+        return {
+            "voice_type": "designed",
+            "design_prompt": profile.design_prompt,
+        }
+
+    if engine not in CLONING_ENGINES:
+        raise ValueError(f"Engine '{engine}' does not support cloned voice profiles")
+
+    # ── Cloned profiles: create from audio samples ──
    samples = db.query(DBProfileSample).filter_by(profile_id=profile_id).all()

    if not samples:
@@ -404,40 +556,48 @@ async def create_voice_prompt_for_profile(

    if len(samples) == 1:
        sample = samples[0]
+        sample_audio_path = config.resolve_storage_path(sample.audio_path)
+        if sample_audio_path is None:
+            raise ValueError(f"Sample audio not found for profile {profile_id}")
        voice_prompt, _ = await tts_model.create_voice_prompt(
-            sample.audio_path,
+            str(sample_audio_path),
            sample.reference_text,
            use_cache=use_cache,
        )
        return voice_prompt
-    else:
-        audio_paths = [s.audio_path for s in samples]
-        reference_texts = [s.reference_text for s in samples]

-        combined_audio, combined_text = await tts_model.combine_voice_prompts(
-            audio_paths,
-            reference_texts,
-        )
+    audio_paths = []
+    for sample in samples:
+        sample_audio_path = config.resolve_storage_path(sample.audio_path)
+        if sample_audio_path is None:
+            raise ValueError(f"Sample audio not found for profile {profile_id}")
+        audio_paths.append(str(sample_audio_path))
+    reference_texts = [s.reference_text for s in samples]

-        # Save combined audio to cache directory (persistent)
-        # Create a hash of sample IDs to identify this specific combination
-        import hashlib
+    combined_audio, combined_text = await tts_model.combine_voice_prompts(
+        audio_paths,
+        reference_texts,
+    )

-        sample_ids_str = "-".join(sorted([s.id for s in samples]))
-        combination_hash = hashlib.md5(sample_ids_str.encode()).hexdigest()[:12]
+    # Save combined audio to cache directory (persistent)
+    # Create a hash of sample IDs to identify this specific combination
+    import hashlib

-        cache_dir = _get_cache_dir()
-        cache_dir.mkdir(parents=True, exist_ok=True)
-        combined_path = cache_dir / f"combined_{profile_id}_{combination_hash}.wav"
+    sample_ids_str = "-".join(sorted([s.id for s in samples]))
+    combination_hash = hashlib.md5(sample_ids_str.encode()).hexdigest()[:12]

-        save_audio(combined_audio, str(combined_path), 24000)
+    cache_dir = _get_cache_dir()
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    combined_path = cache_dir / f"combined_{profile_id}_{combination_hash}.wav"

-        voice_prompt, _ = await tts_model.create_voice_prompt(
-            str(combined_path),
-            combined_text,
-            use_cache=use_cache,
-        )
-        return voice_prompt
+    save_audio(combined_audio, str(combined_path), 24000)
+
+    voice_prompt, _ = await tts_model.create_voice_prompt(
+        str(combined_path),
+        combined_text,
+        use_cache=use_cache,
+    )
+    return voice_prompt


 async def upload_avatar(
@@ -465,8 +625,8 @@ async def upload_avatar(
        raise ValueError(error_msg)

    if profile.avatar_path:
-        old_avatar = Path(profile.avatar_path)
-        if old_avatar.exists():
+        old_avatar = config.resolve_storage_path(profile.avatar_path)
+        if old_avatar is not None and old_avatar.exists():
            old_avatar.unlink()

    # Determine file extension from uploaded file
@@ -487,7 +647,7 @@ async def upload_avatar(

    process_avatar(image_path, str(output_path))

-    profile.avatar_path = str(output_path)
+    profile.avatar_path = config.to_storage_path(output_path)
    profile.updated_at = datetime.utcnow()

    db.commit()
@@ -514,8 +674,8 @@ async def delete_avatar(
    if not profile or not profile.avatar_path:
        return False

-    avatar_path = Path(profile.avatar_path)
-    if avatar_path.exists():
+    avatar_path = config.resolve_storage_path(profile.avatar_path)
+    if avatar_path is not None and avatar_path.exists():
        avatar_path.unlink()

    profile.avatar_path = None
@@ -10,6 +10,7 @@ from pathlib import Path
 from sqlalchemy.orm import Session
 from sqlalchemy import func

+from .. import config
 from ..models import (
    StoryCreate,
    StoryResponse,
@@ -483,13 +484,15 @@ async def split_story_item(
    Returns:
        List of two updated item details (original and new) or None if not found/invalid
    """
-    # Get the item
+    # Get the item with a row lock to prevent concurrent splits on the
+    # same clip (e.g. from rapid double-clicks racing each other).
    item = (
        db.query(DBStoryItem)
        .filter_by(
            id=item_id,
            story_id=story_id,
        )
+        .with_for_update()
        .first()
    )
    if not item:
@@ -826,8 +829,8 @@ async def export_story_audio(
            if version:
                resolved_audio_path = version.audio_path

-        audio_path = Path(resolved_audio_path)
-        if not audio_path.exists():
+        audio_path = config.resolve_storage_path(resolved_audio_path)
+        if audio_path is None or not audio_path.exists():
            continue

        try:
@@ -158,8 +158,8 @@ def delete_version(version_id: str, db: Session) -> bool:
    gen_id = version.generation_id

    # Delete audio file
-    audio_path = Path(version.audio_path)
-    if audio_path.exists():
+    audio_path = config.resolve_storage_path(version.audio_path)
+    if audio_path is not None and audio_path.exists():
        audio_path.unlink()

    db.delete(version)
@@ -193,8 +193,8 @@ def delete_versions_for_generation(generation_id: str, db: Session) -> int:
    )
    count = 0
    for v in versions:
-        audio_path = Path(v.audio_path)
-        if audio_path.exists():
+        audio_path = config.resolve_storage_path(v.audio_path)
+        if audio_path is not None and audio_path.exists():
            audio_path.unlink()
        db.delete(v)
        count += 1
@@ -64,7 +64,7 @@ def get_cached_voice_prompt(
    cache_file = _get_cache_dir() / f"{cache_key}.prompt"
    if cache_file.exists():
        try:
-            prompt = torch.load(cache_file)
+            prompt = torch.load(cache_file, weights_only=True)
            _memory_cache[cache_key] = prompt
            return prompt
        except Exception:
@@ -1,13 +1,11 @@
 # -*- mode: python ; coding: utf-8 -*-
-from PyInstaller.utils.hooks import collect_data_files
 from PyInstaller.utils.hooks import collect_submodules
 from PyInstaller.utils.hooks import collect_all
 from PyInstaller.utils.hooks import copy_metadata

 datas = []
 binaries = []
-hiddenimports = ['backend', 'backend.main', 'backend.config', 'backend.database', 'backend.models', 'backend.services.profiles', 'backend.services.history', 'backend.services.tts', 'backend.services.transcribe', 'backend.utils.platform_detect', 'backend.backends', 'backend.backends.pytorch_backend', 'backend.utils.audio', 'backend.utils.cache', 'backend.utils.progress', 'backend.utils.hf_progress', 'backend.services.cuda', 'backend.services.effects', 'backend.utils.effects', 'backend.services.versions', 'pedalboard', 'chatterbox', 'chatterbox.tts_turbo', 'chatterbox.mtl_tts', 'backend.backends.chatterbox_backend', 'backend.backends.chatterbox_turbo_backend', 'backend.backends.luxtts_backend', 'zipvoice', 'zipvoice.luxvoice', 'torch', 'transformers', 'fastapi', 'uvicorn', 'sqlalchemy', 'soundfile', 'qwen_tts', 'qwen_tts.inference', 'qwen_tts.inference.qwen3_tts_model', 'qwen_tts.inference.qwen3_tts_tokenizer', 'qwen_tts.core', 'qwen_tts.cli', 'requests', 'pkg_resources.extern', 'backend.backends.mlx_backend', 'mlx', 'mlx.core', 'mlx.nn', 'mlx_audio', 'mlx_audio.tts', 'mlx_audio.stt']
-datas += collect_data_files('qwen_tts')
+hiddenimports = ['backend', 'backend.main', 'backend.config', 'backend.database', 'backend.models', 'backend.services.profiles', 'backend.services.history', 'backend.services.tts', 'backend.services.transcribe', 'backend.utils.platform_detect', 'backend.backends', 'backend.backends.pytorch_backend', 'backend.backends.qwen_custom_voice_backend', 'backend.utils.audio', 'backend.utils.cache', 'backend.utils.progress', 'backend.utils.hf_progress', 'backend.services.cuda', 'backend.services.effects', 'backend.utils.effects', 'backend.services.versions', 'pedalboard', 'chatterbox', 'chatterbox.tts_turbo', 'chatterbox.mtl_tts', 'backend.backends.chatterbox_backend', 'backend.backends.chatterbox_turbo_backend', 'backend.backends.luxtts_backend', 'zipvoice', 'zipvoice.luxvoice', 'torch', 'transformers', 'fastapi', 'uvicorn', 'sqlalchemy', 'soundfile', 'qwen_tts', 'qwen_tts.inference', 'qwen_tts.inference.qwen3_tts_model', 'qwen_tts.inference.qwen3_tts_tokenizer', 'qwen_tts.core', 'qwen_tts.cli', 'requests', 'pkg_resources.extern', 'backend.backends.hume_backend', 'tada', 'tada.modules', 'tada.modules.tada', 'tada.modules.encoder', 'tada.modules.decoder', 'tada.modules.aligner', 'tada.modules.acoustic_spkr_verf', 'tada.nn', 'tada.nn.vibevoice', 'tada.utils', 'tada.utils.gray_code', 'tada.utils.text', 'backend.utils.dac_shim', 'torchaudio', 'backend.backends.kokoro_backend', 'kokoro', 'kokoro.pipeline', 'kokoro.model', 'kokoro.istftnet', 'kokoro.modules', 'kokoro.custom_stft', 'en_core_web_sm', 'loguru', 'backend.backends.mlx_backend', 'mlx', 'mlx.core', 'mlx.nn', 'mlx_audio', 'mlx_audio.tts', 'mlx_audio.stt']
 datas += copy_metadata('qwen-tts')
 datas += copy_metadata('requests')
 datas += copy_metadata('transformers')
@@ -15,8 +13,9 @@ datas += copy_metadata('huggingface-hub')
 datas += copy_metadata('tokenizers')
 datas += copy_metadata('safetensors')
 datas += copy_metadata('tqdm')
-hiddenimports += collect_submodules('qwen_tts')
+datas += copy_metadata('en_core_web_sm')
 hiddenimports += collect_submodules('jaraco')
+hiddenimports += collect_submodules('tada')
 hiddenimports += collect_submodules('mlx')
 hiddenimports += collect_submodules('mlx_audio')
 tmp_ret = collect_all('zipvoice')
@@ -27,12 +26,22 @@ tmp_ret = collect_all('lazy_loader')
 datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
 tmp_ret = collect_all('librosa')
 datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
+tmp_ret = collect_all('qwen_tts')
+datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
 tmp_ret = collect_all('inflect')
 datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
 tmp_ret = collect_all('perth')
 datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
 tmp_ret = collect_all('piper_phonemize')
 datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
+tmp_ret = collect_all('misaki')
+datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
+tmp_ret = collect_all('language_tags')
+datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
+tmp_ret = collect_all('espeakng_loader')
+datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
+tmp_ret = collect_all('en_core_web_sm')
+datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
 tmp_ret = collect_all('mlx')
 datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
 tmp_ret = collect_all('mlx_audio')
@@ -22,6 +22,7 @@ services:

    environment:
      - LOG_LEVEL=info
+      - NUMBA_CACHE_DIR=/tmp/numba_cache

    networks:
      - voicebox-net
@@ -1,7 +1,7 @@
-@import 'tailwindcss';
-@import 'fumadocs-ui/css/neutral.css';
-@import 'fumadocs-ui/css/preset.css';
-@import 'fumadocs-openapi/css/preset.css';
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";
+@import "fumadocs-openapi/css/preset.css";

 :root {
  --color-fd-primary: hsl(43, 50%, 50%);
@@ -5,22 +5,13 @@ import { generate as DefaultImage } from 'fumadocs-ui/og';

 export const revalidate = false;

-export async function GET(
-  _req: Request,
-  { params }: RouteContext<'/og/docs/[...slug]'>,
-) {
+export async function GET(_req: Request, { params }: RouteContext<'/og/docs/[...slug]'>) {
  const { slug } = await params;
  const page = source.getPage(slug.slice(0, -1));
  if (!page) notFound();

  return new ImageResponse(
-    (
-      <DefaultImage
-        title={page.data.title}
-        description={page.data.description}
-        site="My App"
-      />
-    ),
+    <DefaultImage title={page.data.title} description={page.data.description} site="My App" />,
    {
      width: 1200,
      height: 630,
@@ -285,6 +285,34 @@ In `app/src/lib/hooks/useGenerationForm.ts`:

 In `app/src/components/ServerSettings/ModelManagement.tsx`:
 - Add description to `MODEL_DESCRIPTIONS` record
+- Add model name to `voiceModels` filter condition
+
+### 3.6 Non-Cloning Engines (Preset Voices)
+
+If your engine uses **pre-built voices** instead of zero-shot cloning from reference audio (e.g. Kokoro), additional integration is needed:
+
+**Backend:**
+- In `kokoro_backend.py` (or your engine), define a `VOICES` list of `(voice_id, display_name, gender, language)` tuples
+- `create_voice_prompt()` should return `{"voice_type": "preset", "preset_engine": "<engine>", "preset_voice_id": "<id>"}`
+- `generate()` should read `voice_prompt.get("preset_voice_id")` to select the voice
+- Add a `seed_preset_profiles("<engine>")` call in `backend/routes/models.py` after model download completes
+- The `seed_preset_profiles()` function in `backend/services/profiles.py` creates DB profiles with `voice_type="preset"`
+
+**Frontend:**
+- The `EngineModelSelector` filters options based on `selectedProfile.voice_type`:
+  - `"cloned"` profiles → only cloning engines shown (Kokoro hidden)
+  - `"preset"` profiles → only the preset's engine shown
+- Profile cards show the engine name as a badge for preset profiles
+- When a preset profile is selected, the engine auto-switches
+
+**Profile schema fields for presets:**
+- `voice_type: "preset"` (vs `"cloned"` for traditional profiles)
+- `preset_engine: "<engine>"` — which engine owns this voice
+- `preset_voice_id: "<id>"` — the engine-specific voice identifier
+
+**For future "designed" voices** (text description instead of audio, e.g. Qwen CustomVoice):
+- Use `voice_type: "designed"` with `design_prompt` field
+- `create_voice_prompt_for_profile()` already returns the design prompt for this type

 ## Phase 4: Dependencies

@@ -5,17 +5,22 @@ description: "How voice profile management works in Voicebox"

 ## Overview

-Voice profiles are the foundation of Voicebox's voice cloning capability. Each profile stores reference audio samples and metadata that the TTS model uses to clone a voice.
+Voice profiles are the unit of "a saved voice" in Voicebox. As of 0.4 they support two flavors backed by the same `profiles` table:
+
+- **Cloned profiles** — store one or more reference audio samples; the cloning engine generates a voice embedding at use time
+- **Preset profiles** — store no audio; just a pointer to an engine-specific pre-built voice (e.g. Kokoro's `am_adam`, Qwen CustomVoice's `Ryan`)
+
+The schema also reserves a third type, `designed`, for future text-described voices. Not currently used by any shipped engine.

 ## Architecture

 The voice profile system consists of three main components:

-**Database Layer:** SQLite tables store profile metadata and sample references.
+**Database Layer:** SQLite tables store profile metadata, sample references (cloned), and engine + voice ID (preset).

-**File Storage:** Audio samples are stored on disk in a structured directory format.
+**File Storage:** Audio samples are stored on disk in a structured directory format. Preset profiles have no on-disk audio.

-**Profile Module:** The `profiles.py` module provides the business logic for CRUD operations.
+**Profile Module:** `backend/services/profiles.py` provides the business logic for CRUD operations and dispatches to the appropriate engine based on `voice_type`.

 ## Data Model

@@ -24,27 +29,49 @@ The voice profile system consists of three main components:
 ```python
 class VoiceProfile(Base):
    __tablename__ = "profiles"
-    
-    id = Column(String, primary_key=True)
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
    name = Column(String, unique=True, nullable=False)
    description = Column(Text)
    language = Column(String, default="en")
-    created_at = Column(DateTime)
-    updated_at = Column(DateTime)
+    avatar_path = Column(String, nullable=True)
+    effects_chain = Column(Text, nullable=True)
+
+    # Voice type system — added v0.3.x
+    voice_type = Column(String, default="cloned")    # "cloned" | "preset" | "designed"
+    preset_engine = Column(String, nullable=True)    # e.g. "kokoro" — only for preset
+    preset_voice_id = Column(String, nullable=True)  # e.g. "am_adam" — only for preset
+    design_prompt = Column(Text, nullable=True)      # text description — only for designed (reserved)
+    default_engine = Column(String, nullable=True)   # auto-selected engine, locked for preset
+
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
 ```

+The `voice_type` column discriminates the three flavors:
+
+| `voice_type` | `preset_engine` | `preset_voice_id` | Samples in `profile_samples` |
+| ------------ | --------------- | ----------------- | ---------------------------- |
+| `cloned`     | NULL            | NULL              | Required (≥1 row)            |
+| `preset`     | engine name     | voice ID string   | None                         |
+| `designed`   | NULL            | NULL              | None (uses `design_prompt`)  |
+
+The `default_engine` column is set automatically when the profile is created. For preset profiles it's locked to the source engine — switching engines at generation time will skip the profile (and the UI auto-switches back when the user clicks a greyed-out card; see the floating generate box and profile grid).
+
 ### ProfileSample Table

 ```python
 class ProfileSample(Base):
    __tablename__ = "profile_samples"
-    
-    id = Column(String, primary_key=True)
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
    profile_id = Column(String, ForeignKey("profiles.id"))
    audio_path = Column(String, nullable=False)
    reference_text = Column(Text, nullable=False)
 ```

+Only populated for cloned profiles. Preset and designed profiles have zero rows in this table.
+
 ## File Structure

 Profiles are stored in the data directory:
@@ -31,6 +31,6 @@ Voicebox is a **local-first voice cloning studio** -- a free and open-source alt

 ## Get Started

- [Installation](/docs/overview/installation) -- download and install Voicebox
- [Quick Start](/docs/overview/quick-start) -- get up and running in 5 minutes
- [API Reference](/docs/api-reference) -- integrate voice synthesis into your apps
+- [Installation](/overview/installation) -- download and install Voicebox
+- [Quick Start](/overview/quick-start) -- get up and running in 5 minutes
+- [API Reference](/api-reference) -- integrate voice synthesis into your apps
@@ -1,32 +1,43 @@
 ---
 title: "Creating Voice Profiles"
-description: "Advanced guide to creating high-quality voice profiles"
+description: "How to create voice profiles, both cloning-based and preset-based"
 ---

 ## Overview

-Voice profiles are the foundation of voice cloning in Voicebox. This guide covers best practices for creating professional-quality voice profiles.
+A **voice profile** is a saved voice you can reuse across generations, stories, and the API. As of 0.4, Voicebox profiles come in two flavors that map to two different ways of getting a voice:

-## Quick Start
+| Profile type   | What it stores                                       | Use when…                                                |
+| -------------- | ---------------------------------------------------- | -------------------------------------------------------- |
+| **Cloned**     | One or more reference audio samples + a voice embedding | You want to replicate a specific person's voice          |
+| **Preset**     | A reference to a pre-built voice in a specific engine | You want a curated, production-ready voice with no audio prep |
+
+Both types live in the same Profiles tab and behave the same way at generation time — pick the type that matches your goal and follow the workflow below.
+
+<Callout type="info">
+  Not sure which to use? Cloning gives you a *specific* voice but needs clean audio. Preset gives you *good* voices instantly but you don't get to choose who they sound like.
+</Callout>
+
+## Workflow A — Cloned Profiles
+
+Use this when you want to replicate a specific person's voice from a recording.

 <Steps>
  <Step title="Prepare Audio">
-    10-30 seconds of clear speech
+    10-30 seconds of clear speech, minimal background noise. See [Voice Cloning](/overview/voice-cloning) for the engine catalog.
  </Step>
  <Step title="Create Profile">
-    **Profiles** → **+ New Profile**
+    **Profiles** → **+ New Profile** → choose a cloning engine (Qwen3-TTS, Chatterbox, LuxTTS, or TADA)
  </Step>
-  <Step title="Upload Sample">
-    Add your audio file
+  <Step title="Upload or Record Sample">
+    Drag in an audio file, or record directly with the in-app recorder
  </Step>
-  <Step title="Generate">
-    Use the profile to generate speech
+  <Step title="Generate to Test">
+    Use the profile to generate a test phrase. If quality is poor, add more samples
  </Step>
 </Steps>

-## Audio Requirements
-
-### Ideal Sample Characteristics
+### Audio Requirements (Cloning Only)

 <Cards>
  <Card title="Duration">
@@ -44,7 +55,7 @@ Voice profiles are the foundation of voice cloning in Voicebox. This guide cover
  <Card title="Quality">
    **High fidelity**

-    44.1kHz or 48kHz sample rate
+    44.1 kHz or 48 kHz sample rate
    Minimal compression
  </Card>
  <Card title="Content">
@@ -58,18 +69,16 @@ Voice profiles are the foundation of voice cloning in Voicebox. This guide cover
 ### File Formats

 Supported formats:
- **WAV** (recommended) - Lossless quality
- **MP3** - Acceptable, minimal compression
- **M4A** - Acceptable
- **FLAC** - Lossless alternative
+- **WAV** (recommended) — Lossless quality
+- **MP3** — Acceptable, minimal compression
+- **M4A** — Acceptable
+- **FLAC** — Lossless alternative

 <Callout type="info">
  Use WAV for best results. Avoid heavily compressed formats.
 </Callout>

-## Recording Tips
-
-### Environment
+### Recording Tips

 <AccordionGroup>
  <Accordion title="Quiet Space">
@@ -87,27 +96,25 @@ Supported formats:
  </Accordion>

  <Accordion title="Recording Settings">
-    - 44.1kHz or 48kHz sample rate
+    - 44.1 kHz or 48 kHz sample rate
    - 16-bit or 24-bit depth
    - Mono is fine (stereo will be converted)
    - Avoid automatic gain control
  </Accordion>
 </AccordionGroup>

-### Speaking
+### Speaking Style

- **Natural pace** - Don't rush or speak too slowly
- **Clear articulation** - Pronounce words clearly
- **Consistent volume** - Maintain steady loudness
- **Normal tone** - Speak as you normally would
- **Complete sentences** - Avoid fragments or "ums"
+- **Natural pace** — Don't rush or speak too slowly
+- **Clear articulation** — Pronounce words clearly
+- **Consistent volume** — Maintain steady loudness
+- **Normal tone** — Speak as you normally would
+- **Complete sentences** — Avoid fragments or "ums"

-## Multiple Samples
+### Multiple Samples

 Adding multiple samples can significantly improve quality:

-### Why Multiple Samples?
-
 <Cards>
  <Card title="Robustness">
    Model learns a more complete representation
@@ -123,110 +130,57 @@ Adding multiple samples can significantly improve quality:
  </Card>
 </Cards>

-### Sample Variety
-
 Consider adding samples with:

-1. **Different tones**
-   - Casual conversation
-   - Professional/formal
-   - Excited/enthusiastic
-   - Calm/serious
-
-2. **Different content**
-   - Narratives
-   - Questions
-   - Statements
-   - Emotions (happy, sad, neutral)
-
-3. **Different recording conditions**
-   - Studio quality
-   - Phone call quality (if needed)
-   - Room acoustics
+1. **Different tones** — casual, formal, excited, calm
+2. **Different content** — narratives, questions, statements
+3. **Different recording conditions** — studio quality, room acoustics

 <Callout type="warn">
  All samples should be from the **same speaker**. Mixing voices will produce poor results.
 </Callout>

-## Processing Existing Audio
+### Processing Existing Audio

 If you have existing audio (podcasts, videos, etc.):

-### Extracting Clean Segments
-
 <Steps>
  <Step title="Find Clean Speech">
-    Look for segments with:
-    - Just the target speaker
-    - No background music
-    - Minimal noise
+    Look for segments with just the target speaker, no background music, minimal noise
  </Step>
-
  <Step title="Use Audio Editor">
-    Tools like Audacity or Adobe Audition:
-    - Cut out clean 10-30s segments
-    - Remove silence at start/end
-    - Normalize volume if needed
+    Tools like Audacity or Adobe Audition: cut clean 10-30s segments, remove silence at start/end, normalize volume
  </Step>
-
  <Step title="Export as WAV">
    Save as high-quality WAV file
  </Step>
 </Steps>

-### Noise Reduction
+For light background noise, use Audacity's noise reduction (gentle settings — over-processing introduces artifacts).

-If you have light background noise:
+### Testing & Iteration

-```
-1. Use noise reduction in Audacity:
-   - Select noise-only section
-   - Get Noise Profile
-   - Select full audio
-   - Apply noise reduction (gentle settings)
-
-2. Avoid over-processing:
-   - Can introduce artifacts
-   - May reduce voice quality
-```
-
-## Testing & Iteration
-
-### Test Your Profile
-
-After creating a profile:
+After creating a cloned profile:

 <Steps>
  <Step title="Generate Test">
-    Generate a simple phrase:
-    ```
-    "Hello, this is a test of my voice profile."
-    ```
+    Try a simple phrase: `"Hello, this is a test of my voice profile."`
  </Step>
-
  <Step title="Evaluate Quality">
-    Listen for:
-    - Natural tone
-    - Clear pronunciation
-    - Proper prosody
-    - Lack of artifacts
+    Listen for natural tone, clear pronunciation, proper prosody, lack of artifacts
  </Step>
-
  <Step title="Iterate">
-    If quality is poor:
-    - Add more samples
-    - Try different source audio
-    - Check sample quality
+    If quality is poor: add more samples, try different source audio, check sample quality
  </Step>
 </Steps>

-### Common Issues
+#### Common Issues

 <AccordionGroup>
  <Accordion title="Robotic Voice">
    **Cause**: Poor quality samples or too short

-    **Fix**: Use longer, higher quality samples
+    **Fix**: Use longer, higher-quality samples
  </Accordion>

  <Accordion title="Wrong Tone">
@@ -242,51 +196,89 @@ After creating a profile:
  </Accordion>
 </AccordionGroup>

+## Workflow B — Preset Profiles
+
+Use this when you want a ready-made voice without recording anything. Available engines: **Kokoro 82M** (50 voices) and **Qwen CustomVoice** (9 voices). See [Preset Voices](/overview/preset-voices) for the full catalog.
+
+<Steps>
+  <Step title="Create Profile">
+    **Profiles** → **+ New Profile** → choose **Kokoro** or **Qwen CustomVoice** as the engine
+  </Step>
+  <Step title="Pick a Voice">
+    The engine's voice catalog appears. Click any voice to preview it
+  </Step>
+  <Step title="Name and Save">
+    Give the profile a name. No audio sample required
+  </Step>
+  <Step title="Generate">
+    The profile is ready immediately — use it in the floating generate box or Generate page
+  </Step>
+</Steps>
+
+<Callout type="info">
+  Preset profiles are **locked to their source engine**. Switching to a different engine in the floating generate box greys out the profile, since the voice only exists in that engine. Clicking a greyed profile auto-switches the engine back.
+</Callout>
+
+### Qwen CustomVoice + Instruct
+
+Preset voices in Qwen CustomVoice support **delivery instructions** — natural-language style control over tone, pace, and emotion. The floating generate box shows a slider icon next to the generate button when a Qwen CustomVoice profile is selected; click it to reveal the instruct textarea.
+
+See [Preset Voices → Using Instruct Mode](/overview/preset-voices#using-instruct-mode) for examples.
+
 ## Advanced Tips

-### Celebrity/Character Voices
+### Celebrity / Character Voices (Cloning)

 For cloning public figures or characters:

-1. **Legal considerations** - Ensure you have rights or it's fair use
-2. **Source quality** - Find high-quality interview audio or clean clips
-3. **Consistency** - Use clips where they speak similarly
-4. **Multiple samples** - Very important for recognizable voices
+1. **Legal considerations** — Ensure you have rights or it's clearly fair use
+2. **Source quality** — Find high-quality interview audio or clean clips
+3. **Consistency** — Use clips where they speak similarly
+4. **Multiple samples** — Very important for recognizable voices

-### Accent & Dialect
+### Accent & Dialect (Cloning)

-The model will preserve accent and dialect:
+Cloning models preserve accent and dialect:

- British English will generate British English
- Southern accent will produce Southern accent
- Regional pronunciations will be maintained
+- British English samples generate British English output
+- Southern accent samples produce Southern accent output
+- Regional pronunciations are maintained

-### Emotion Transfer
+### Emotion Transfer (Cloning)

 The emotional tone of samples affects generation:

- Energetic samples → Energetic output
- Calm samples → Calm output
- Mix samples for versatile profile
+- Energetic samples → energetic output
+- Calm samples → calm output
+- Mix samples for a more versatile profile
+
+For Qwen CustomVoice presets, use the **instruct** field instead of relying on sample emotion — that's exactly what it controls.

 ## Managing Profiles

 ### Organization

- **Descriptive names** - "John Smith - Professional Narrator"
- **Add descriptions** - Note recording conditions, use cases
- **Language tags** - Mark the primary language
- **Archive unused** - Keep profile list manageable
+- **Descriptive names** — "John Smith - Professional Narrator"
+- **Add descriptions** — Note recording conditions, use cases, or which preset voice
+- **Language tags** — Mark the primary language
+- **Archive unused** — Keep profile list manageable

-### Export/Import
+### Export / Import

 - **Export** profiles to share or backup
 - **Import** from colleagues or teammates
- Profiles include voice embeddings, not original audio
+- **Cloned profiles** export with their voice embeddings (not the original audio)
+- **Preset profiles** export as engine + voice ID metadata only — the importer must have that engine's model installed

 ## Next Steps

 <Cards>
+  <Card title="Voice Cloning" href="/overview/voice-cloning">
+    Engine catalog and best practices for cloning
+  </Card>
+  <Card title="Preset Voices" href="/overview/preset-voices">
+    Full catalog of Kokoro and Qwen CustomVoice voices
+  </Card>
  <Card title="Generate Speech" href="/overview/generating-speech">
    Use your profile to generate speech
  </Card>
@@ -0,0 +1,236 @@
+---
+title: "GPU Acceleration"
+description: "How Voicebox uses your GPU — auto-detection, manual setup, troubleshooting"
+---
+
+## Overview
+
+Voicebox auto-detects available accelerators on first launch and picks the fastest backend it can use. For most people this just works — open the app and you're already on the right backend.
+
+This page is for the cases where it doesn't:
+
+- You have a GPU but Voicebox is running on CPU
+- You upgraded GPUs (especially to RTX 50-series / Blackwell) and generation broke
+- You want to switch backends manually (e.g. force MLX over PyTorch on Apple Silicon)
+- You see `[UNSUPPORTED - see logs]` next to your GPU in Settings
+
+## Backend Matrix
+
+| Platform                    | Auto-selected backend     | Notes                                                |
+| --------------------------- | ------------------------- | ---------------------------------------------------- |
+| **macOS Apple Silicon**     | MLX (Metal)               | 4-5x faster than PyTorch via Apple Neural Engine     |
+| **macOS Intel**             | PyTorch CPU               | No GPU acceleration available; PyTorch ≥ 2.2 only    |
+| **Windows + NVIDIA**        | PyTorch CUDA (cu128)      | Auto-downloads the CUDA backend binary on first use  |
+| **Windows + Intel Arc**     | PyTorch XPU (IPEX)        | New in 0.4 — works with Arc A-series and B-series    |
+| **Windows generic GPU**     | DirectML                  | Universal Windows GPU support; slower than CUDA      |
+| **Linux + NVIDIA**          | PyTorch CUDA (cu128)      | Same auto-download flow as Windows                   |
+| **Linux + AMD**             | PyTorch ROCm              | Auto-configures `HSA_OVERRIDE_GFX_VERSION`           |
+| **Linux + Intel Arc**       | PyTorch XPU (IPEX)        |                                                      |
+| **Any (no GPU)**            | PyTorch CPU               | Works everywhere; expect 5-50x slower than GPU       |
+
+The detected backend is shown in Settings → GPU. Logs at startup also print the chosen backend and the device name.
+
+## Apple Silicon — MLX vs PyTorch
+
+On M-series Macs, Voicebox ships an MLX-optimized backend that uses the Apple Neural Engine. It's **4-5x faster** than the PyTorch (CPU/Metal) path for supported engines.
+
+| Engine               | MLX support | Notes                                       |
+| -------------------- | ----------- | ------------------------------------------- |
+| Qwen3-TTS            | ✅ Native   | Uses MLX exclusively when available         |
+| Chatterbox / Turbo   | PyTorch MPS | Falls back to Metal via PyTorch             |
+| LuxTTS               | PyTorch MPS |                                             |
+| TADA                 | PyTorch MPS |                                             |
+| Kokoro               | PyTorch MPS | Requires `PYTORCH_ENABLE_MPS_FALLBACK=1`    |
+| Qwen CustomVoice     | PyTorch MPS |                                             |
+| Whisper (transcribe) | ✅ Native   | MLX-Whisper is the default on Apple Silicon |
+
+The Whisper Turbo + MLX combo dropped transcription latency from ~20s to ~2-3s on M-series chips (see CHANGELOG entry for v0.1.10).
+
+## Windows / Linux + NVIDIA — The CUDA Backend Swap
+
+Voicebox doesn't bundle CUDA into the main installer (it would balloon downloads to multi-gigabyte territory for users who don't have an NVIDIA GPU). Instead, when you first need it, the app downloads a separate **CUDA backend binary** that contains the PyTorch + CUDA runtime.
+
+<Steps>
+  <Step title="Open Settings → GPU">
+    If an NVIDIA GPU is detected, you'll see "Install CUDA backend" in the GPU panel
+  </Step>
+  <Step title="Click Install">
+    The app downloads two archives separately:
+    - **Server core** (~200-400 MB) — versioned with each Voicebox release
+    - **CUDA libs** (~4 GB) — the heavy PyTorch + CUDA DLLs, versioned independently
+  </Step>
+  <Step title="Restart">
+    Voicebox restarts to swap in the CUDA backend
+  </Step>
+</Steps>
+
+<Callout type="info">
+  The split-archive design (added in v0.4) means most Voicebox upgrades only redownload the small server-core archive. The 4 GB libs archive is only refreshed when the underlying CUDA toolkit or torch major version changes.
+</Callout>
+
+### Auto-update
+
+When a new Voicebox release ships, the GPU panel checks if the bundled server-core matches the installed CUDA version. If only the core changed (typical), it pulls the new core in the background. If the libs version changed (rare — only happens on cu126 → cu128 type bumps), you'll be prompted to confirm the larger download.
+
+## RTX 50-series / Blackwell
+
+Voicebox 0.4 added explicit RTX 50-series support:
+
+- CUDA toolkit upgraded to **cu128** (previous releases used cu126 which lacks Blackwell kernels)
+- Build pinned with `TORCH_CUDA_ARCH_LIST=...12.0+PTX` for forward-compatibility
+
+If you're on an RTX 5070 / 5080 / 5090 and you see "no kernel image is available" errors:
+
+1. Make sure you're on Voicebox **≥ 0.4.0** (Settings → About)
+2. Reinstall the CUDA backend (Settings → GPU → Reinstall CUDA backend) — older installs may have stale cu126 libs
+3. If errors persist, see the GPU compatibility warnings section below
+
+## Intel Arc (XPU)
+
+New in 0.4. Works with both Arc A-series (Alchemist: A380, A580, A750, A770) and B-series (Battlemage).
+
+### Setup
+
+Voicebox auto-detects Arc GPUs and routes through Intel's PyTorch XPU backend (powered by IPEX — Intel Extension for PyTorch). No extra installation step beyond the standard Voicebox install.
+
+Verify it's working:
+- Settings → GPU should show **XPU** followed by your Arc model name (e.g. `XPU (Intel Arc A770)`)
+- Startup logs print `Backend: PYTORCH` and `GPU: XPU (Intel Arc ...)`
+
+### Engines on XPU
+
+All PyTorch-based engines work on XPU. Performance is generally between CPU and CUDA — expect ~2-3x speedup over CPU for the larger models.
+
+## DirectML
+
+The fallback for Windows users with non-NVIDIA, non-Intel-Arc GPUs (older AMD discrete, integrated GPUs, etc.). Slower than CUDA and XPU but provides some acceleration over CPU.
+
+Auto-selected when no other GPU backend is available.
+
+## AMD ROCm (Linux)
+
+ROCm provides PyTorch GPU acceleration on AMD discrete GPUs. Voicebox auto-configures `HSA_OVERRIDE_GFX_VERSION` for common cards that need the override.
+
+### Verifying
+
+```bash
+# In a terminal
+echo $HSA_OVERRIDE_GFX_VERSION
+# Should show e.g. 10.3.0 for RX 6000 series
+```
+
+If detection fails, set the variable manually before launching Voicebox:
+
+```bash
+export HSA_OVERRIDE_GFX_VERSION=10.3.0
+voicebox
+```
+
+Common values:
+- `10.3.0` — RX 6000 series (RDNA 2)
+- `11.0.0` — RX 7000 series (RDNA 3)
+- `9.0.0` — Older Vega cards
+
+## GPU Compatibility Warnings
+
+Voicebox 0.4 added a runtime check that compares your GPU's compute capability against the architectures the bundled PyTorch was compiled for. If they don't match, you'll see:
+
+- A startup log line: `WARNING: GPU COMPATIBILITY: <your GPU> is not supported by this PyTorch build...`
+- The GPU label in Settings shows `[UNSUPPORTED - see logs]`
+- The `/health` API returns a populated `gpu_compatibility_warning` field
+
+### What to do
+
+The most common trigger is a brand-new GPU architecture that pre-built PyTorch wheels don't yet cover natively. In order of preference:
+
+1. **Update Voicebox** — newer releases ship newer PyTorch with broader arch support
+2. **Reinstall the CUDA backend** — Settings → GPU → Reinstall CUDA backend
+3. **For bleeding-edge GPUs (newer than current Blackwell):** install PyTorch nightly manually:
+   ```bash
+   pip install torch --index-url https://download.pytorch.org/whl/nightly/cu128 --force-reinstall
+   ```
+   Then point Voicebox at that environment via [Remote Mode](/overview/remote-mode) until stable PyTorch catches up.
+4. **Fall back to CPU** temporarily — set `VOICEBOX_FORCE_CPU=1` before launching
+
+## CPU-Only Fallback
+
+When no GPU is available (or you've forced it off), Voicebox runs the PyTorch CPU backend. Expect:
+
+- 5-50x slower generation depending on engine and text length
+- Heavy CPU usage during generation
+- Some engines work better than others on CPU:
+  - **Kokoro 82M** — runs at realtime on modern CPUs
+  - **LuxTTS** — exceeds 150x realtime on CPU
+  - **Chatterbox Turbo (350M)** — usable but slow
+  - Larger models (Qwen 1.7B, Chatterbox Multilingual, TADA 3B) — painful
+
+For CPU-bound use cases, prefer the smaller, lighter engines.
+
+## Verifying Your Setup
+
+Three places to check that the right backend is being used:
+
+<Steps>
+  <Step title="Settings → GPU">
+    Shows the detected backend, GPU model, and VRAM (when applicable). Look for the `[UNSUPPORTED - see logs]` suffix
+  </Step>
+  <Step title="Settings → Logs">
+    The "Server logs" tab shows the startup banner with `Backend: <type>` and `GPU: <name>`
+  </Step>
+  <Step title="Health endpoint">
+    `curl http://localhost:17493/health` returns a JSON payload with `backend_type`, `backend_variant`, and `gpu_compatibility_warning` (when applicable)
+  </Step>
+</Steps>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Settings shows CPU instead of my GPU">
+    - On NVIDIA: install the CUDA backend (Settings → GPU)
+    - On Intel Arc: confirm IPEX detection in startup logs; restart the app after a driver update
+    - On AMD Linux: check `HSA_OVERRIDE_GFX_VERSION` is set
+  </Accordion>
+
+  <Accordion title="'no kernel image is available' / 'CUDA error'">
+    Almost always means the bundled PyTorch doesn't have kernels for your GPU's compute capability.
+
+    1. Update to Voicebox ≥ 0.4.0 (Blackwell support added there)
+    2. Reinstall the CUDA backend
+    3. If still broken, install PyTorch nightly via Remote Mode
+  </Accordion>
+
+  <Accordion title="Out of memory (CUDA)">
+    - Switch to a smaller model size (e.g. Qwen3 0.6B instead of 1.7B)
+    - Use Settings → Models to unload other engines you're not using
+    - Enable `low_cpu_mem_usage` is already on for CPU; for CUDA, the engine's `device_map` handles offload automatically
+    - Close other GPU applications
+  </Accordion>
+
+  <Accordion title="MPS fallback errors on macOS">
+    Some operations don't have a Metal implementation. Voicebox sets `PYTORCH_ENABLE_MPS_FALLBACK=1` for engines that need it (notably Kokoro), but if you launch from a custom env, set it manually:
+    ```bash
+    export PYTORCH_ENABLE_MPS_FALLBACK=1
+    ```
+  </Accordion>
+
+  <Accordion title="Generation works but is slow on my GPU">
+    - Check Settings → GPU shows your GPU (not CPU)
+    - Check VRAM usage — you may be paging to system memory
+    - Try a smaller model
+    - For NVIDIA: confirm cu128 is installed (Settings → GPU → version)
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+<Cards>
+  <Card title="Remote Mode" href="/overview/remote-mode">
+    Run the backend on a different machine with a stronger GPU
+  </Card>
+  <Card title="Model Management" href="/developer/model-management">
+    Unload models to free GPU memory
+  </Card>
+  <Card title="Troubleshooting" href="/overview/troubleshooting">
+    General troubleshooting beyond GPU
+  </Card>
+</Cards>
@@ -6,7 +6,9 @@
    "installation",
    "docker",
    "quick-start",
+    "gpu-acceleration",
    "voice-cloning",
+    "preset-voices",
    "stories-editor",
    "recording-transcription",
    "generation-history",
@@ -0,0 +1,202 @@
+---
+title: "Preset Voices"
+description: "Use built-in, ready-made voices without recording audio samples"
+---
+
+## Overview
+
+Some Voicebox engines ship with a curated set of pre-built voices. Instead of cloning from your own audio sample, you pick a voice from a fixed catalog and the model speaks in that voice. No recording, no upload, no per-voice training required.
+
+Two engines in 0.4 ship preset voices:
+
+| Engine                | Voices                  | Languages | Strengths                                               |
+| --------------------- | ----------------------- | --------- | ------------------------------------------------------- |
+| **Kokoro 82M**        | 50                      | 9         | Tiny model, CPU-friendly, lowest VRAM of any engine     |
+| **Qwen CustomVoice**  | 9 (premium curated)     | 4         | Natural-language style control over tone, emotion, pace |
+
+<Callout type="info">
+  Looking for cloning a specific person's voice instead? See [Voice Cloning](/overview/voice-cloning).
+</Callout>
+
+## When to Use Preset Voices
+
+<Cards>
+  <Card title="No reference audio">
+    You don't have (or don't want to provide) a recording of the target voice
+  </Card>
+  <Card title="Production reliability">
+    Curated voices have predictable quality across any text input
+  </Card>
+  <Card title="Speed">
+    Skip the audio cleanup, sample preparation, and quality iteration loop
+  </Card>
+  <Card title="Lightweight setup">
+    Kokoro runs at CPU realtime with ~150 MB on disk — no GPU needed
+  </Card>
+</Cards>
+
+## Creating a Preset-Voice Profile
+
+<Steps>
+  <Step title="Open Profiles → New Profile">
+    Same entry point as cloning profiles
+  </Step>
+  <Step title="Choose the engine">
+    Select **Kokoro** or **Qwen CustomVoice** from the engine dropdown
+  </Step>
+  <Step title="Pick a preset voice">
+    The voice catalog for the chosen engine appears — preview each by clicking it
+  </Step>
+  <Step title="Name and save">
+    Give the profile a name. No audio sample needed — just save
+  </Step>
+  <Step title="Generate">
+    Use the profile like any other in the floating generate box or the Generate page
+  </Step>
+</Steps>
+
+<Callout type="info">
+  Preset profiles are locked to their source engine — switching engines won't work since the voice exists only for that model. The profile grid greys out preset profiles when you switch to a different engine, and clicking one auto-switches the engine back to the right one.
+</Callout>
+
+## Kokoro 82M — 50 Voices Across 9 Languages
+
+Kokoro is the smallest engine in Voicebox at 82M parameters. It runs at CPU realtime with negligible VRAM, making it the best option for lightweight local inference. Voices are pre-built style vectors trained into the model — there's no concept of cloning here.
+
+**Repository:** [`hexgrad/Kokoro-82M`](https://huggingface.co/hexgrad/Kokoro-82M) · Apache 2.0 licensed
+
+### American English
+
+| Female  | Male    |
+| ------- | ------- |
+| Alloy   | Adam    |
+| Aoede   | Echo    |
+| Bella   | Eric    |
+| Heart   | Fenrir  |
+| Jessica | Liam    |
+| Kore    | Michael |
+| Nicole  | Onyx    |
+| Nova    | Puck    |
+| River   | Santa   |
+| Sarah   |         |
+| Sky     |         |
+
+### British English
+
+| Female   | Male   |
+| -------- | ------ |
+| Alice    | Daniel |
+| Emma     | Fable  |
+| Isabella | George |
+| Lily     | Lewis  |
+
+### Other Languages
+
+| Language          | Voices                                      |
+| ----------------- | ------------------------------------------- |
+| Spanish (`es`)    | Dora (f), Alex (m), Santa (m)               |
+| French (`fr`)     | Siwis (f)                                   |
+| Hindi (`hi`)      | Alpha (f), Beta (f), Omega (m), Psi (m)     |
+| Italian (`it`)    | Sara (f), Nicola (m)                        |
+| Japanese (`ja`)   | Alpha (f), Gongitsune (f), Nezumi (f), Tebukuro (f), Kumo (m) |
+| Portuguese (`pt`) | Dora (f), Alex (m), Santa (m)               |
+| Chinese (`zh`)    | Xiaobei (f), Xiaoni (f), Xiaoxiao (f), Xiaoyi (f) |
+
+### Kokoro at a Glance
+
+| Property        | Value                                        |
+| --------------- | -------------------------------------------- |
+| Parameters      | 82M                                          |
+| Sample rate     | 24 kHz                                       |
+| VRAM            | ~150 MB (negligible on CPU)                  |
+| Speed           | Realtime on CPU, faster on GPU               |
+| Instruct        | Not supported (preset voice carries the style) |
+| License         | Apache 2.0                                   |
+
+## Qwen CustomVoice — 9 Premium Voices with Instruct Control
+
+Qwen CustomVoice ships with 9 curated speakers and supports **natural-language style control** — you tell the model how to deliver the line ("speak slowly with warmth", "authoritative and clear") and it adapts tone, emotion, and pace.
+
+Two model sizes:
+- **1.7B** — full quality, recommended default
+- **0.6B** — lighter, faster, lower-end hardware
+
+**Repository:** [`Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice`](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice) (and 0.6B variant) · by Alibaba
+
+### Voice Catalog
+
+| Speaker   | Gender | Language | Description                                                  |
+| --------- | ------ | -------- | ------------------------------------------------------------ |
+| Vivian    | female | Chinese  | Bright, slightly edgy young female voice                     |
+| Serena    | female | Chinese  | Warm, gentle young female voice                              |
+| Uncle Fu  | male   | Chinese  | Seasoned male voice with a low, mellow timbre                |
+| Dylan     | male   | Chinese  | Youthful Beijing male voice with a clear, natural timbre     |
+| Eric      | male   | Chinese  | Lively Chengdu male voice with a slightly husky brightness   |
+| Ryan      | male   | English  | Dynamic male voice with strong rhythmic drive (default)      |
+| Aiden     | male   | English  | Sunny American male voice with a clear midrange              |
+| Ono Anna  | female | Japanese | Playful Japanese female voice with a light, nimble timbre    |
+| Sohee     | female | Korean   | Warm Korean female voice with rich emotion                   |
+
+### Using Instruct Mode
+
+In the floating generate box, switch to a Qwen CustomVoice profile and click the **delivery instructions** toggle (slider icon, left of the generate button). A second textarea appears below the main text:
+
+- Main text → what you want the voice to say
+- Instruct text → how you want it delivered
+
+Examples of effective instruct prompts:
+
+```
+Speak slowly with emphasis, like reading bedtime stories
+Warm and friendly, conversational tone
+Professional and authoritative, broadcast quality
+Whisper, intimate and close
+Excited and energetic, like sports commentary
+```
+
+The full Generate page also surfaces the instruct field as a separate input.
+
+### Qwen CustomVoice at a Glance
+
+| Property        | Value                                              |
+| --------------- | -------------------------------------------------- |
+| Parameters      | 1.7B / 0.6B                                        |
+| Languages       | Chinese, English, Japanese, Korean (10 supported)  |
+| Voices          | 9 curated preset speakers                          |
+| VRAM            | ~3.5 GB (1.7B), ~1.2 GB (0.6B)                     |
+| Instruct        | Yes — natural-language style control               |
+| Cloning         | No — paired Base Qwen3-TTS engine handles cloning  |
+
+## Cloning vs Preset — Quick Decision
+
+| You want…                                          | Use                                       |
+| -------------------------------------------------- | ----------------------------------------- |
+| To replicate a specific person's voice             | [Voice Cloning](/overview/voice-cloning)  |
+| Production-ready voices with no audio prep         | Kokoro or Qwen CustomVoice                |
+| The smallest possible footprint (CPU-only)         | Kokoro                                    |
+| Fine control over delivery (tone, pace, emotion)   | Qwen CustomVoice                          |
+| The broadest language coverage                     | [Voice Cloning](/overview/voice-cloning) via Chatterbox Multilingual (23 langs) |
+
+## Limitations
+
+<Callout type="warn">
+  Preset voices are fixed — you can't fine-tune or modify the underlying voice. If you want a specific voice that isn't in the catalog, use a cloning engine and provide a reference sample.
+</Callout>
+
+- Preset voices can't be exported to use in other Voicebox installations as audio (only as profile metadata pointing to the same engine + voice ID)
+- The Kokoro voice catalog is set by the upstream model — new voices appear only when hexgrad publishes new model releases
+- Qwen CustomVoice's 9 speakers are part of the model checkpoint — same constraint
+
+## Next Steps
+
+<Cards>
+  <Card title="Voice Cloning" href="/overview/voice-cloning">
+    Clone a specific voice from your own audio
+  </Card>
+  <Card title="Generate Speech" href="/overview/generating-speech">
+    Use a profile to generate audio
+  </Card>
+  <Card title="Build Stories" href="/overview/building-stories">
+    Compose multi-voice narratives
+  </Card>
+</Cards>
@@ -1,11 +1,25 @@
 ---
 title: "Voice Cloning"
-description: "Clone any voice from just a few seconds of audio"
+description: "Clone any voice from a few seconds of reference audio"
 ---

 ## Overview

-Voicebox uses **Qwen3-TTS** from Alibaba to achieve near-perfect voice cloning from just a few seconds of audio. The model captures prosody, emotion, and natural cadence.
+Voicebox can replicate a specific person's voice from a short audio sample — known as **zero-shot voice cloning**. You provide 10-30 seconds of clear speech, the model extracts a voice embedding, and from then on you can generate any text in that voice.
+
+Five engines in 0.4 support cloning:
+
+| Engine                      | Languages | Strengths                                                                  |
+| --------------------------- | --------- | -------------------------------------------------------------------------- |
+| **Qwen3-TTS** (0.6B / 1.7B) | 10        | High-quality multilingual, supports delivery instructions on the same kwarg |
+| **Chatterbox Multilingual** | 23        | Broadest language coverage — Arabic, Hindi, Swahili, Hebrew, more          |
+| **Chatterbox Turbo**        | English   | Fast 350M model with paralinguistic emotion tags (`[laugh]`, `[sigh]`)     |
+| **LuxTTS**                  | English   | Lightweight (~1 GB VRAM), 48 kHz output, 150x realtime on CPU              |
+| **TADA** (1B / 3B)          | 10        | Speech-language model with 700s+ coherent long-form generation             |
+
+<Callout type="info">
+  Don't want to record audio? Use a curated voice from Kokoro or Qwen CustomVoice instead — see [Preset Voices](/overview/preset-voices).
+</Callout>

 ## How It Works

@@ -13,17 +27,30 @@ Voicebox uses **Qwen3-TTS** from Alibaba to achieve near-perfect voice cloning f
  <Step title="Upload or Record Sample">
    Provide 10-30 seconds of clear speech from the target voice
  </Step>
-  <Step title="Model Analysis">
-    Qwen3-TTS analyzes vocal characteristics, tone, and speaking patterns
+  <Step title="Engine Analysis">
+    The selected engine analyzes vocal characteristics, tone, and speaking patterns
  </Step>
  <Step title="Voice Profile Created">
-    The model generates a voice embedding for synthesis
+    A voice embedding is generated and stored with your profile
  </Step>
  <Step title="Generate Speech">
    Use the profile to generate any text in the cloned voice
  </Step>
 </Steps>

+## Choosing an Engine for Cloning
+
+Different engines suit different use cases. The profile grid greys out unsupported engines so you can switch easily.
+
+| If you want…                                       | Pick                  |
+| -------------------------------------------------- | --------------------- |
+| Best overall quality on a few common languages     | **Qwen3-TTS 1.7B**    |
+| Faster generation, slightly lower quality          | **Qwen3-TTS 0.6B**    |
+| Languages outside Qwen's 10 (Arabic, Hindi, etc.)  | **Chatterbox Multilingual** |
+| Expressive English with `[laugh]` `[sigh]` tags    | **Chatterbox Turbo**  |
+| CPU-only or GPU-light setup, English               | **LuxTTS**            |
+| Long-form generation (audiobooks, full chapters)   | **TADA 3B**           |
+
 ## Best Practices

 ### Sample Quality
@@ -52,24 +79,40 @@ Adding multiple samples from the same speaker can improve quality:
 - Different recording conditions

 <Callout type="info">
-  The model will learn a more robust representation from diverse samples.
+  The model will learn a more robust representation from diverse samples. Especially helpful for distinctive voices the model might otherwise smooth over.
 </Callout>

-## Supported Languages
+## Supported Languages by Engine

-Currently supported:
- English
- Chinese (Mandarin)
+- **Qwen3-TTS** — English, Chinese, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian (10)
+- **Chatterbox Multilingual** — Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish (23)
+- **Chatterbox Turbo** — English
+- **LuxTTS** — English
+- **TADA 3B** — 10 multilingual; **TADA 1B** — English

-More languages coming soon.
+For complete language tables and engine-specific notes, see the [TTS Engines developer guide](/developer/tts-engines).

 ## Limitations

 <Callout type="warn">
-  Voice cloning should only be used with consent. Ensure you have permission to clone someone's voice.
+  Voice cloning should only be used with consent. Ensure you have permission to clone someone's voice. See the project's [SECURITY.md](https://github.com/jamiepine/voicebox/blob/main/SECURITY.md) and your local laws on synthetic voice content.
 </Callout>

- Quality depends on sample clarity
- Works best with consistent speaking tone
+- Quality depends on sample clarity — noisy samples produce noisy clones
+- Works best with consistent speaking tone within a sample
 - May struggle with extreme accents or speech impediments
- Background noise reduces quality
+- Background noise reduces quality and can introduce artifacts
+
+## Next Steps
+
+<Cards>
+  <Card title="Creating Voice Profiles" href="/overview/creating-voice-profiles">
+    Step-by-step guide to creating profiles
+  </Card>
+  <Card title="Preset Voices" href="/overview/preset-voices">
+    Use built-in voices instead of cloning
+  </Card>
+  <Card title="Generating Speech" href="/overview/generating-speech">
+    Use a profile to generate audio
+  </Card>
+</Cards>
@@ -1,6 +1,6 @@
 # Voicebox Project Status & Roadmap

-> Last updated: 2026-03-13 | Current version: **v0.1.13** | 13.1k stars | ~176 open issues | 25 open PRs
+> Last updated: 2026-03-18 | Current version: **v0.3.0** | 13.4k stars | ~136 open issues | 9 open PRs

 ---

@@ -100,7 +100,7 @@ POST /generate

 ## Current State

-### What's Shipped (v0.1.13 + recent merges)
+### What's Shipped (v0.3.0)

 **Core TTS:**
 - Qwen3-TTS voice cloning (1.7B and 0.6B models)
@@ -108,30 +108,42 @@ POST /generate
 - Multi-engine TTS architecture with thread-safe backend registry (PR #254)
 - LuxTTS integration — fast, CPU-friendly English TTS (PR #254)
 - Chatterbox Multilingual TTS — 23 languages including Hebrew (PR #257)
- Instruct parameter UI exists but is non-functional across all backends (see #224, Known Limitations)
+- Chatterbox Turbo — paralinguistic tags, low latency English (PR #258)
 - HumeAI TADA integration — 1B English + 3B Multilingual speech-language model (PR #296)
- Single flat model dropdown (Qwen 1.7B, Qwen 0.6B, LuxTTS, Chatterbox, Chatterbox Turbo, TADA 1B, TADA 3B)
- Centralized model config registry (`ModelConfig` dataclass) — no per-engine dispatch maps in `main.py`
+- Chunked TTS generation for long text — engine-agnostic, removes ~500 char limit (PR #266)
+- Async generation queue (PR #269)
+- Post-processing audio effects system (PR #271)
+- Centralized model config registry (`ModelConfig` dataclass) — no per-engine dispatch maps
 - Shared `EngineModelSelector` component — engine/model dropdown defined once, used in both generation forms

 **Infrastructure:**
- CUDA backend swap via binary download and restart (PR #252)
- GPU acceleration settings UI
+- CUDA backend swap via binary download and restart (PR #252), upgraded to cu128 (PR #316)
+- CUDA backend split into independently versioned server + libs archives (PR #298)
+- Docker + web deployment (PR #161)
+- Backend refactor: modular architecture, style guide, tooling (PR #285)
+- Settings overhaul: routed sub-tabs, server logs, changelog, about page (PR #294)
+- Windows support: CUDA detection, cross-platform justfile, clean server shutdown (PR #272)
 - Voice profiles with multi-sample support
 - Stories editor (multi-track DAW timeline)
 - Whisper transcription (base, small, medium, large variants)
- Model management UI with inline download progress bars (HFProgressTracker)
+- Model management UI with inline download progress bars + folder migration (PR #268)
 - Download cancel/clear UI with error panel (PR #238)
 - Generation history with caching
 - Streaming generation endpoint (MLX only)
- Duplicate profile name validation (PR #175)
- Linux NVIDIA GBM buffer + WebKitGTK microphone fix (PR #210)
+- Audio player freeze fix + UX improvements (PR #293)
+- CORS restriction to known local origins (PR #88)
+
+### Abandoned Integrations
+
+| Model | PR | Reason |
+|-------|----|--------|
+| **CosyVoice2/3** | PR #311 | Output quality too poor. Heavy deps, no PyPI, needed 5+ shims. |

 ### What's In-Flight

 | Feature | Branch/PR | Status |
 |---------|-----------|--------|
-| Chatterbox Turbo + per-engine language lists | `feat/chatterbox-turbo` / PR #258 | Open, ready for review |
+| Kokoro 82M TTS engine | WIP | In development — 82M CPU-realtime engine, 8 languages |

 ### TTS Engine Comparison

@@ -144,6 +156,7 @@ POST /generate
 | Chatterbox Turbo | `chatterbox-turbo` | English | ~1.5 GB | Paralinguistic tags ([laugh], [cough]), 350M params, low latency | Partial — inline tags only, no separate instruct param |
 | TADA 1B | `tada-1b` | English | ~4 GB | HumeAI speech-language model, 700s+ coherent audio | None |
 | TADA 3B Multilingual | `tada-3b-ml` | 10 (en, ar, zh, de, es, fr, it, ja, pl, pt) | ~8 GB | Multilingual, text-acoustic dual alignment | None |
+| Kokoro 82M | `kokoro` | 8 (en, es, fr, hi, it, pt, ja, zh) | ~350 MB | 82M params, CPU realtime, Apache 2.0, pre-built voices | None |

 ### Multi-Engine Architecture (Shipped)

@@ -173,69 +186,41 @@ The singleton TTS backend blocker described in the previous version of this doc

 | PR | Title | Merged |
 |----|-------|--------|
-| **#257** | feat: Chatterbox TTS engine with multilingual voice cloning | 2026-03-13 |
-| **#254** | feat: LuxTTS integration — multi-engine TTS support | 2026-03-13 |
-| **#252** | feat: CUDA backend swap via binary download and restart | 2026-03-13 |
-| **#238** | Download cancel/clear UI, fixed model downloading | 2026-03-13 |
-| **#250** | docs: align local API port examples | 2026-03-13 |
-| **#210** | fix: Linux NVIDIA GBM buffer crash | 2026-03-13 |
-| **#175** | Fix #134: duplicate profile name validation | 2026-03-13 |
+| **#316** | Upgrade CUDA backend from cu126 to cu128, fix GPU settings UI | 2026-03-18 |
+| **#305** | fix: bundle qwen_tts source files in PyInstaller build | 2026-03-17 |
+| **#298** | feat: split CUDA backend into independently versioned server + libs archives | 2026-03-17 |
+| **#296** | Add HumeAI TADA TTS engine (1B English + 3B Multilingual) | 2026-03-17 |
+| **#295** | fix: batch of bug fixes from issue tracker | 2026-03-17 |
+| **#293** | Fix audio player freezing and improve UX | 2026-03-17 |
+| **#294** | Settings overhaul: routed sub-tabs, server logs, changelog, about page | 2026-03-16 |
+| **#288** | Better docs | 2026-03-16 |
+| **#285** | Backend refactor: modular architecture, style guide, tooling | 2026-03-16 |
+| **#274** | Landing page v0.2.0 redesign | 2026-03-15 |
+| **#272** | Windows support: CUDA detection, cross-platform justfile, clean server shutdown | 2026-03-15 |
+| **#271** | Add post-processing audio effects system | 2026-03-14 |
+| **#269** | feat: async generation queue | 2026-03-13 |
+| **#268** | feat: model management improvements and folder migration | 2026-03-13 |
+| **#266** | feat: chunked TTS generation for long text (engine-agnostic) | 2026-03-13 |
+| **#265** | feat: paralinguistic tag autocomplete for Chatterbox Turbo | 2026-03-13 |
+| **#264** | fix: Chatterbox float64 dtype mismatch + model unload button | 2026-03-13 |
+| **#258** | feat: Chatterbox Turbo engine + per-engine language lists | 2026-03-13 |
+| **#230** | docs: fix README grammar | 2026-03-13 |
+| **#161** | feat: Docker + web deployment | 2026-03-13 |
+| **#88** | security: restrict CORS to known local origins | 2026-03-13 |

-### In-Flight (Our Work)
+### Currently Open (9 PRs)

 | PR | Title | Status | Notes |
 |----|-------|--------|-------|
-| **#258** | feat: Chatterbox Turbo engine + per-engine language lists | Open | Ready for review. Adds Turbo engine + dynamic language dropdown. |
-
-### Merge-Ready / Near-Ready (Bug Fixes & Small Features)
-
-| PR | Title | Risk | Notes |
-|----|-------|------|-------|
-| **#230** | docs: fix README grammar | None | Docs-only |
-| **#243** | a11y: screen reader and keyboard improvements | Low | Accessibility, no backend changes |
-| **#178** | Fix #168 #140: generation error handling | Low | Error handling improvements |
-| **#152** | Fix: prevent crashes when HuggingFace unreachable | Medium | Monkey-patches HF hub; solves real offline bug (#150, #151) |
-| **#218** | fix: unify qwen tts cache dir on Windows | Low | Windows-specific path fix |
-| **#214** | fix: panic on launch from tokio::spawn | Low | Rust-side Tauri fix |
-| **#88** | security: restrict CORS to known local origins | Low | Security hardening |
-| **#133** | feat: network access toggle | Low | Wires up existing plumbing |
-
-### Significant Feature PRs
-
-| PR | Title | Complexity | Notes |
-|----|-------|-----------|-------|
-| **#253** | Enhance speech tokenizer with 48kHz version | Medium | Qwen tokenizer upgrade |
-| **#97** | fix: pass language parameter to TTS models | Medium | May be partially obsoleted by multi-engine work — needs review |
-| **#99** | feat: chunked TTS with quality selector | Medium | Solves 500-char limit. Addresses #191, #203, #69, #111. |
-| **#154** | feat: Audiobook tab | Medium | Full audiobook workflow. Depends on #99 concepts. |
-| **#91** | fix: CoreAudio device enumeration | Medium | macOS audio device handling |
-
-### Architectural PRs (Need Careful Review)
-
-| PR | Title | Complexity | Notes |
-|----|-------|-----------|-------|
-| **#225** | feat: custom HuggingFace model support | High | Arbitrary HF repo loading. May need rework given multi-engine arch is now shipped. |
-| **#194** | feat: Hebrew + Chatterbox TTS | High | **Superseded** by PR #257 which shipped Chatterbox multilingual (23 langs incl. Hebrew). May be closeable. |
-| **#195** | feat: per-profile LoRA fine-tuning | Very High | Training pipeline, adapter management, 15 new endpoints. Depends on #194 (now superseded). |
-| **#161** | feat: Docker + web deployment | High | 3-stage Dockerfile, SPA serving. Independent of TTS engine work. |
-| **#124** / **#123** | Docker (simpler attempts) | Low-Medium | Overlap with #161 |
-| **#227** | fix: harden input validation & file safety | Medium | Coupled to #225 (custom models) |
-
-### PRs That Need Author Action / Are Stale
-
-| PR | Title | Notes |
-|----|-------|-------|
-| **#237** | fix: bundle qwen_tts source files in PyInstaller | Build system, needs review |
-| **#215** | Update prerequisites with Tauri deps | Branch is `main` — will have conflicts |
-| **#89** | Linux Support | Branch is `main` — will have conflicts. Broad scope. |
-| **#83** | Update download links for v0.1.12 | Outdated (we're on v0.1.13) |
-
-### PRs Likely Superseded
-
-| PR | Superseded By | Notes |
-|----|--------------|-------|
-| **#194** (Hebrew + Chatterbox) | PR #257 (merged) | #257 ships Chatterbox multilingual with 23 languages including Hebrew. #194 took a different approach (route by language). Can likely be closed. |
-| **#33** (External provider binaries) | PR #252 (merged) | #252 shipped CUDA backend swap. #33's broader provider architecture may still have value but needs reassessment. |
+| **#311** | feat: add CosyVoice2/3 TTS engine | **Will close** | Model quality too poor. See Abandoned Integrations. |
+| **#253** | Enhance speech tokenizer with 48kHz version | Community PR | Qwen tokenizer upgrade. Worth reviewing. |
+| **#237** | fix: bundle qwen_tts source files in PyInstaller | Superseded | Our PR #305 shipped this. Can close. |
+| **#227** | fix: harden input validation & file safety | Community PR | Coupled to #225 (custom models). |
+| **#225** | feat: custom HuggingFace model support | Community PR | Needs rework for multi-engine arch. |
+| **#218** | fix: unify qwen tts cache dir on Windows | Community PR | Windows-specific path fix. Still relevant. |
+| **#195** | feat: per-profile LoRA fine-tuning | Draft | Complex. 15 new endpoints. |
+| **#154** | feat: Audiobook tab | Community PR | Chunked generation now shipped (#266). |
+| **#91** | fix: CoreAudio device enumeration | Draft | macOS audio device handling. |

 ---

@@ -280,7 +265,7 @@ Strong demand for: Hindi (#245), Indonesian (#247), Dutch (#236), Hebrew (#199),
 | #132 | LavaSR (transcription) |
 | #76 | (General model expansion) |

-Community also requests: XTTS-v2, Fish Speech, CosyVoice, Kokoro. The multi-engine architecture is now in place, making new model integration significantly easier.
+Community also requests: XTTS-v2, Fish Speech, Kokoro. CosyVoice was tried and abandoned. The multi-engine architecture is in place, making new model integration straightforward.

 ### Long-Form / Chunking (5 issues)

@@ -288,7 +273,7 @@ Users hitting the ~500 character practical limit.

 **Key issues:** #234 (queue system), #203 (500 char limit), #191 (auto-split), #111, #69

-**Fix path:** PR #99 (chunked TTS + quality selector) directly addresses this. PR #154 (Audiobook tab) builds on it.
+**Fix path:** **Mostly resolved.** PR #266 (engine-agnostic chunked TTS) and PR #269 (async generation queue) are both merged. PR #154 (Audiobook tab) is still open.

 ### Feature Requests (23 issues)

@@ -326,7 +311,7 @@ Notable requests:
 | `CUDA_BACKEND_SWAP_FINAL.md` | — | **Shipped** (PR #252) | Final implementation plan |
 | `EXTERNAL_PROVIDERS.md` | v0.2.0 | **Not started** | Remote server support |
 | `MLX_AUDIO.md` | — | **Shipped** | MLX backend is live |
-| `DOCKER_DEPLOYMENT.md` | v0.2.0 | **PR exists** (#161) | Waiting on review |
+| `DOCKER_DEPLOYMENT.md` | v0.2.0 | **Shipped** (PR #161) | Docker + web deployment |
 | `OPENAI_SUPPORT.md` | v0.2.0 | **Not started** | OpenAI-compatible API layer |
 | `PR33_CUDA_PROVIDER_REVIEW.md` | — | **Reference** | Analysis of the original provider approach |

@@ -334,31 +319,31 @@ Notable requests:

 ## New Model Integration — Landscape

-### Models Worth Supporting (2026 SOTA — updated March 13)
+### Models Worth Supporting (2026 SOTA — updated March 18)

 | Model | Cloning | Speed | Sample Rate | Languages | VRAM | Instruct Support | Integration Ease | Status |
 |-------|---------|-------|-------------|-----------|------|-----------------|-----------------|--------|
 | **Qwen3-TTS** | 10s zero-shot | Medium | 24 kHz | 10 | Medium | None (Base); Yes (CustomVoice variant, predefined speakers only) | **Shipped** | v0.1.13 |
 | **LuxTTS** | 3s zero-shot | 150x RT, CPU ok | 48 kHz | English | <1 GB | None | **Shipped** | PR #254 |
 | **Chatterbox MTL** | 5s zero-shot | Medium | 24 kHz | 23 | Medium | Partial — `exaggeration` float | **Shipped** | PR #257 |
-| **Chatterbox Turbo** | 5s zero-shot | Fast | 24 kHz | English | Low | Partial — inline tags only | **PR #258** | In review |
-| **CosyVoice2-0.5B** | 3-10s zero-shot | Very fast | 24 kHz | Multilingual | Low | **Yes** — `inference_instruct2()`, works with cloning | Ready | Best instruct candidate |
-| **Fish Speech** | 10-30s few-shot | Real-time | 24-44 kHz | 50+ | Medium | **Yes** — inline text descriptions, word-level control | Ready | Multi-engine arch in place |
-| **MOSS-TTS Family** | Zero-shot | — | — | Multilingual | Medium | **Yes** — text prompts for style + timbre design | Needs vetting | Apache 2.0, multi-speaker dialogue |
-| **HumeAI TADA 1B/3B** | Zero-shot | 5× faster than LLM-TTS | 24 kHz | EN (1B), Multilingual (3B) | Medium | Partial — automatic prosody from text context | **Shipped** | PR #296, MIT, 700s+ coherent |
-| **VoxCPM 1.5** | Zero-shot (seconds) | ~0.15 RTF streaming | — | Bilingual (EN/ZH) | Medium | Partial — automatic context-aware prosody | Needs vetting | Apache 2.0, tokenizer-free continuous diffusion |
-| **Kokoro-82M** | 3s instant | CPU realtime | 24 kHz | English | Tiny (82M) | Partial — automatic style inference | Ready | Apache 2.0, multi-engine arch in place |
-| **XTTS-v2** | 6s zero-shot | Mid-GPU | 24 kHz | 17+ | Medium | Partial — style transfer from ref audio only | Ready | Multi-engine arch in place |
-| **Pocket TTS** | Zero-shot + streaming | >1× RT on CPU | — | English | ~100M params, CPU-first | None | Needs vetting | MIT, Kyutai Labs, no GPU required |
+| **Chatterbox Turbo** | 5s zero-shot | Fast | 24 kHz | English | Low | Partial — inline tags only | **Shipped** | PR #258 |
+| **HumeAI TADA 1B/3B** | Zero-shot | 5x faster than LLM-TTS | 24 kHz | EN (1B), Multilingual (3B) | Medium | Partial — automatic prosody | **Shipped** | PR #296 |
+| **Kokoro-82M** | Pre-built voices | CPU realtime | 24 kHz | 8 | Tiny (82M) | None | **In progress** | Apache 2.0, pip install, ~350MB |
+| ~~**CosyVoice2-0.5B**~~ | 3-10s zero-shot | Very fast | 24 kHz | Multilingual | Low | Yes — `inference_instruct2()` | **Abandoned** | PR #311 — poor output quality |
+| **Fish Speech** | 10-30s few-shot | Real-time | 24-44 kHz | 50+ | Medium | **Yes** — inline text descriptions, word-level control | Ready | Needs license clarification |
+| **XTTS-v2** | 6s zero-shot | Mid-GPU | 24 kHz | 17+ | Medium | Partial — style transfer from ref audio only | Ready | Mature pip package |
+| **Pocket TTS** | Zero-shot + streaming | >1x RT on CPU | — | English | ~100M params, CPU-first | None | Ready | MIT, Kyutai Labs |
+| **MOSS-TTS Family** | Zero-shot | — | — | Multilingual | Medium | **Yes** — text prompts for style + timbre design | Needs vetting | Apache 2.0 |
+| **VoxCPM 1.5** | Zero-shot (seconds) | ~0.15 RTF streaming | — | Bilingual (EN/ZH) | Medium | Partial — automatic context-aware prosody | Needs vetting | Apache 2.0 |

-#### Notes on New Candidates (March 2026)
+#### Notes on Candidates (March 2026)

- **CosyVoice2-0.5B** — Best candidate for instruct support. `inference_instruct2()` accepts a text instruct parameter for emotions, speed, volume, dialects — and it works alongside voice cloning. This is the closest match to what users expect from our instruct UI. [HF: FunAudioLLM/CosyVoice2-0.5B](https://huggingface.co/FunAudioLLM/CosyVoice2-0.5B)
- **HumeAI TADA** — Text-Audio Dual Alignment arch. Near-zero hallucinations/drift, free synced transcript. 700+ seconds coherent audio. Best candidate for Stories long-form reliability. Prosody/emotion is automatic from text context, not user-controllable. [HF: HumeAI/tada-1b](https://huggingface.co/HumeAI/tada-1b) | [GitHub: HumeAI/tada](https://github.com/HumeAI/tada)
- **MOSS-TTS** — Modular suite: flagship cloning, MOSS-TTSD (multi-speaker dialogue), MOSS-VoiceGenerator (create voices from text descriptions). VoiceGenerator unifies timbre design and style control via text prompts, usable as a layer for downstream TTS including cloning. [HF: OpenMOSS-Team/MOSS-VoiceGenerator](https://huggingface.co/OpenMOSS-Team/MOSS-VoiceGenerator) | [GitHub: OpenMOSS/MOSS-TTS](https://github.com/OpenMOSS/MOSS-TTS)
- **Fish Speech** — Word-level fine-grained control using plain language descriptions inline in the script. Works with cloning. Note: Fish Audio S2 has a restrictive research license (commercial use requires approval), but the open-source Fish Speech model may differ. Needs license clarification. [fish.audio blog](https://fish.audio/blog/fish-audio-s2-fine-grained-ai-voice-control-at-the-word-level)
- **VoxCPM 1.5** — Tokenizer-free continuous diffusion + autoregressive. No discrete token artifacts. Prosody/emotion is context-aware but automatic, not explicitly controllable via text prompt. Real-time streaming, LoRA fine-tuning. Trained on 1.8M+ hours. [GitHub: OpenBMB/VoxCPM](https://github.com/OpenBMB/VoxCPM)
- **Pocket TTS** — 100M param CPU-first model from Kyutai Labs (Moshi team). Runs >1× realtime without GPU. No style control. Broadens hardware support significantly. [GitHub: kyutai-labs/pocket-tts](https://github.com/kyutai-labs/pocket-tts)
+- **CosyVoice2-0.5B** — **Tried and abandoned** (PR #311). Despite having the best instruct API, output quality was poor. No PyPI package, needed 5+ shims, heavy deps. Not worth it.
+- **HumeAI TADA** — **Shipped** (PR #296). 700+ seconds coherent audio. [GitHub: HumeAI/tada](https://github.com/HumeAI/tada)
+- **Kokoro-82M** — **In progress.** 82M params, CPU realtime, Apache 2.0, clean `pip install kokoro`. Uses pre-built voice styles (not zero-shot cloning from arbitrary audio). [GitHub: hexgrad/kokoro](https://github.com/hexgrad/kokoro)
+- **Fish Speech** — Word-level fine-grained control. License needs clarification. [fish.audio blog](https://fish.audio/blog/fish-audio-s2-fine-grained-ai-voice-control-at-the-word-level)
+- **XTTS-v2** — Coqui's multilingual cloning. 17+ languages, pip-installable. [GitHub: coqui-ai/TTS](https://github.com/coqui-ai/TTS)
+- **Pocket TTS** — 100M param CPU-first model from Kyutai Labs. [GitHub: kyutai-labs/pocket-tts](https://github.com/kyutai-labs/pocket-tts)
 - **Watch list:** MioTTS-2.6B (fast LLM-based EN/JP, vLLM compatible), Oolel-Voices (Soynade Research, expressive modular control)

 ### Adding a New Engine (Now Straightforward)
@@ -402,49 +387,44 @@ The generation form now uses a flat model dropdown with engine-based routing. Pe

 ## Recommended Priorities

-### Tier 1 — Ship Now (Low Risk)
+### Tier 1 — Ship Now

 | Priority | PR/Item | Impact | Effort |
 |----------|---------|--------|--------|
-| 1 | **#258** — Chatterbox Turbo + per-engine languages | Paralinguistic tags, proper language filtering | Review only |
-| 2 | **#152** — Offline mode crash fix | Fixes #150, #151 | Low |
-| 3 | **#99** — Chunked TTS + quality selector | Removes 500-char limit, addresses 5 issues | Medium |
-| 4 | **#218** — Windows HF cache dir fix | Windows-specific pain | Low |
-| 5 | **#178** — Generation error handling | Error UX | Low |
-| 6 | **#230** — Docs fixes | Zero risk | None |
-| 7 | **#133** — Network access toggle | Wires up existing code | Low |
-| 8 | **#88** — CORS restriction | Security improvement | Low |
-| 9 | **#214** — Tauri window close panic fix | Stability | Low |
-| 10 | Triage GPU issues | Many may be resolved by CUDA swap (#252) | Low |
-| 11 | Close superseded PRs | #194 (superseded by #257), #83 (outdated) | None |
+| 1 | **Kokoro 82M** — finish integration | New engine, CPU-friendly, 8 langs | Low (nearly done) |
+| 2 | Close PR #311 (CosyVoice) and #237 (superseded by #305) | Housekeeping | None |
+| 3 | **#218** — Windows HF cache dir fix | Windows-specific pain | Low |
+| 4 | **#253** — 48kHz speech tokenizer | Quality improvement for Qwen | Medium |

-### Tier 2 — Next Release (v0.2.0)
+### Tier 2 — Feature Work

 | Priority | Item | Impact | Effort |
 |----------|------|--------|--------|
-| 1 | **#253** — 48kHz speech tokenizer | Quality improvement | Medium |
-| 2 | **#161** — Docker deployment | Server/headless users | Medium |
-| 3 | **#154** — Audiobook tab | Long-form users | Medium |
-| 4 | ~~**Model config registry**~~ | ~~Reduce dispatch duplication in main.py~~ | **Done** |
-| 5 | **#225** — Custom HuggingFace models | User-supplied models | High (needs rework for multi-engine) |
+| 1 | **#154** — Audiobook tab | Long-form users. Chunking + queue now shipped. | Medium |
+| 2 | **#225** — Custom HuggingFace models | User-supplied models. Needs rework. | High |
+| 3 | OpenAI-compatible API (plan doc exists) | Low effort once API is stable | Low |
+| 4 | LoRA fine-tuning (PR #195) | Complex, needs rework for multi-engine | Very High |
+| 5 | Streaming for non-MLX engines | Currently MLX-only | Medium |

-### Tier 3 — Future (v0.3.0+)
+### Tier 3 — Future Engines

 | Priority | Item | Notes |
 |----------|------|-------|
-| 1 | **HumeAI TADA** | Long-form reliability for Stories, synced transcripts. Addresses #234, #203, #191, #111, #69. Needs API vetting. |
-| 2 | **Pocket TTS** (Kyutai) | CPU-first 100M model, broadens hardware support. Kyutai ships clean code. Needs API vetting. |
-| 3 | **MOSS-TTS** | Text-to-voice design (no ref audio) is unique. Multi-speaker dialogue for Stories. Needs thorough API vetting. |
-| 4 | **Kokoro-82M** | 82M params, CPU realtime, Apache 2.0. Easy win. |
-| 5 | ~~**Model config registry refactor**~~ | **Done** — consolidated in `backend/backends/__init__.py` + `EngineModelSelector.tsx` |
-| 6 | XTTS-v2 / Fish Speech / CosyVoice | Multi-engine arch is ready; just needs backend implementation |
-| 7 | **VoxCPM 1.5** | Tokenizer-free streaming, interesting but uncertain integration surface |
-| 8 | OpenAI-compatible API (plan doc exists) | Low effort once API is stable |
-| 9 | LoRA fine-tuning (PR #195) | Complex, needs rework for multi-engine |
-| 10 | External/remote providers | Depends on use case demand |
-| 11 | GGUF support (#226) | Depends on model ecosystem maturity |
-| 12 | Queue system (#234) | Batch generation |
-| 13 | Streaming for non-MLX engines | Currently MLX-only |
+| 1 | **Fish Speech** | 50+ langs, word-level instruct. License TBD. |
+| 2 | **XTTS-v2** | 17+ langs, mature pip package. Best multilingual cloning. |
+| 3 | **Pocket TTS** (Kyutai) | CPU-first 100M model. MIT. |
+| 4 | **MOSS-TTS** | Text-to-voice design. Multi-speaker dialogue for Stories. |
+| 5 | **VoxCPM 1.5** | Tokenizer-free streaming. Uncertain integration surface. |
+
+### ~~Previously Prioritized — Now Done~~
+
+- ~~#258 — Chatterbox Turbo~~ **Merged**
+- ~~#99 — Chunked TTS~~ **Superseded by #266, merged**
+- ~~#88 — CORS restriction~~ **Merged**
+- ~~#161 — Docker deployment~~ **Merged**
+- ~~#234 — Queue system~~ **Addressed by #269, merged**
+- ~~HumeAI TADA~~ **Shipped** (PR #296)
+- ~~Kokoro-82M~~ **In progress**

 ---

@@ -452,13 +432,10 @@ The generation form now uses a flat model dropdown with engine-based routing. Pe

 | Branch | PR | Status | Notes |
 |--------|-----|--------|-------|
-| `feat/chatterbox-turbo` | #258 | Open | Chatterbox Turbo + per-engine languages |
+| `feat/cosyvoice-engine` | #311 | Open — closing | CosyVoice2/3 — abandoned, poor quality |
+| `feat/chatterbox-turbo` | #258 | **Merged** | Chatterbox Turbo + per-engine languages |
 | `feat/chatterbox` | #257 | **Merged** | Chatterbox Multilingual |
 | `feat/luxtts` | #254 | **Merged** | LuxTTS + multi-engine arch |
-| `external-provider-binaries` | #33 | Superseded by #252 | Original CUDA provider approach |
-| `feat/dual-server-binaries` | — | No PR | Related to provider split |
-| `fix-multi-sample` | — | No PR | Voice profile multi-sample fix |
-| `fix-dl-notification-...` | — | No PR | Model download UX |

 ---

@@ -0,0 +1,428 @@
+# Voicebox API Refactor Plan
+
+Date: 2026-03-19
+Status: Proposed
+Scope: Backend HTTP API structure, schemas, docs, and compatibility strategy
+
+## Goals
+
+- Make the API easier to understand and automate against.
+- Improve endpoint consistency without breaking the desktop app or existing local integrations.
+- Align generated docs and checked-in OpenAPI artifacts with the actual backend.
+- Separate app-facing resources from internal or operational actions.
+- Create a migration path toward a cleaner `v2` resource model while preserving `v1` routes during transition.
+
+## Non-Goals
+
+- Rewriting backend business logic or generation internals.
+- Introducing authentication for all deployment modes in the first pass.
+- Changing storage models or database schema unless required for API correctness.
+- Removing current routes immediately.
+
+## Current Pain Points
+
+- Mixed endpoint styles: resource-oriented (`/profiles`) and command-oriented (`/generate`, `/tasks/clear`) coexist.
+- Related generation resources are split across multiple namespaces: `/generate`, `/history`, `/audio`, `/effects`, and `/generations/.../versions`.
+- Response payloads vary widely: typed models, raw dicts with `message`, booleans, and `HTTPException(detail=...)` payloads.
+- Some async flows use exception-shaped `202` responses instead of first-class task contracts.
+- Checked-in OpenAPI output can drift from actual backend models.
+- Operational endpoints such as `/shutdown` are exposed in the same surface as user workflows.
+
+## Guiding Principles
+
+1. Prefer additive changes before destructive changes.
+2. Keep `v1` behavior working until the app and docs fully migrate.
+3. Add compatibility shims close to the routing layer, not deep in services.
+4. Treat OpenAPI as a release artifact that must be kept in sync.
+5. Standardize public contracts before renaming everything.
+
+## Target API Shape
+
+This is the intended end state, not the immediate first milestone.
+
+### Core Resources
+
+- `/profiles`
+- `/profiles/{profile_id}/samples`
+- `/profiles/{profile_id}/avatar`
+- `/profiles/{profile_id}/effects`
+- `/generations`
+- `/generations/{generation_id}`
+- `/generations/{generation_id}/status`
+- `/generations/{generation_id}/audio`
+- `/generations/{generation_id}/versions`
+- `/generations/{generation_id}/versions/{version_id}`
+- `/generations/{generation_id}/versions/{version_id}/audio`
+- `/stories`
+- `/stories/{story_id}/items`
+- `/effects/presets`
+- `/models`
+- `/models/{model_name}`
+- `/tasks`
+
+### Operational or Internal Endpoints
+
+Move under an explicit namespace and disable where appropriate:
+
+- `/admin/shutdown`
+- `/admin/watchdog/disable`
+- `/admin/cache/clear`
+- `/admin/tasks/clear`
+
+### Response Contract Direction
+
+- Resource reads and writes return typed resource models.
+- Delete and action endpoints return small typed action result models.
+- Errors use a consistent structure.
+- Async actions return explicit task metadata instead of overloading `detail`.
+
+## Migration Strategy Overview
+
+The refactor is split into six phases. Phases 1-3 are the highest impact and safest to ship first.
+
+| Phase | Focus | Est. Duration | Risk | Backward Compatibility |
+| --- | --- | --- | --- | --- |
+| 1 | Documentation and contract correctness | 2-3 days | Low | Full |
+| 2 | Response and error consistency | 3-5 days | Low-Medium | Full |
+| 3 | Router structure and internal organization | 3-4 days | Low | Full |
+| 4 | Additive `v2` resource endpoints | 1-2 weeks | Medium | Full |
+| 5 | Client migration and deprecation rollout | 1 week | Medium | Full during rollout |
+| 6 | Cleanup and optional removals | 1-2 releases | Medium-High | Partial after notice |
+
+## Phase 1: Fix Contract Drift First
+
+Priority: Highest
+Outcome: The documented API matches the running backend.
+
+### Problems Addressed
+
+- `docs/openapi.json` can become stale.
+- Generated API reference pages may describe outdated request bodies.
+- App metadata still frames the backend too narrowly.
+
+### Implementation Steps
+
+1. Update FastAPI app metadata in `backend/app.py`.
+   - Replace the old Qwen-specific description with a multi-engine Voicebox API description.
+   - Add tags metadata for major domains if desired.
+2. Regenerate OpenAPI from the running app using the existing docs script flow.
+3. Compare `backend/models.py` to the checked-in schema.
+   - Verify `GenerationRequest`, effects endpoints, stories endpoints, and model endpoints.
+4. Regenerate or refresh API reference pages under `docs/content/docs/api-reference/`.
+5. Add a CI check that fails if `docs/openapi.json` is out of date.
+6. Add a short maintainer note describing when schema regeneration is required.
+
+### Backward Compatibility
+
+- No route changes.
+- No payload changes.
+- Safe to release immediately.
+
+### Success Criteria
+
+- `docs/openapi.json` matches the live app.
+- Generated docs include all currently supported generate parameters.
+- No frontend code changes required.
+
+## Phase 2: Standardize Responses and Errors
+
+Priority: High
+Outcome: Clients can handle responses predictably.
+
+### Problems Addressed
+
+- Delete endpoints return ad hoc message dicts.
+- Toggle endpoints return special one-off payloads.
+- `202` async responses are encoded as `HTTPException(detail=...)` in some places.
+
+### Implementation Steps
+
+1. Add shared response models in `backend/models.py`.
+   - `ActionResult`
+   - `DeleteResult`
+   - `ToggleFavoriteResponse`
+   - `AcceptedTaskResponse`
+   - `ApiError`
+2. Convert routes that currently return raw dicts to explicit `response_model`s.
+   - `DELETE /profiles/{profile_id}`
+   - `DELETE /history/{generation_id}`
+   - `DELETE /stories/{story_id}`
+   - `POST /tasks/clear`
+   - `POST /cache/clear`
+   - similar endpoints across routes
+3. Replace exception-shaped `202` responses in `transcription.py` with an explicit accepted response body.
+   - Return `JSONResponse(status_code=202, content=...)` or typed FastAPI response model.
+4. Add a global exception handler for known API errors if helpful.
+   - Normalize `ValueError` to `400` with a consistent error body.
+   - Preserve FastAPI validation errors for now, or wrap them in a consistent top-level shape in a later pass.
+5. Document the stable error contract in the docs.
+
+### Migration Strategy
+
+- Keep field names inside successful payloads compatible where possible.
+- For existing dict responses, preserve the current keys while introducing typed models with the same shape.
+- For `202` flows, support both old and new client handling for one release if needed.
+
+### Timeline Estimate
+
+- 3-5 engineering days including tests and docs refresh.
+
+### Success Criteria
+
+- All mutation endpoints declare response models.
+- Clients can programmatically distinguish success, accepted, and error cases without special casing `detail` payloads.
+
+## Phase 3: Normalize Router Structure Internally
+
+Priority: High
+Outcome: The backend becomes easier to maintain before public path changes begin.
+
+### Problems Addressed
+
+- Route files hardcode full paths and are all mounted at root.
+- There is no consistent use of router prefixes or tags.
+- Route grouping in code does not cleanly express the public API shape.
+
+### Implementation Steps
+
+1. Add prefixes and tags to routers.
+   - `profiles`: `prefix="/profiles"`
+   - `generations`: `prefix="/generate"` for now or split additive aliases carefully
+   - `history`: `prefix="/history"`
+   - `effects`: `prefix="/effects"`
+   - and so on
+2. Convert route declarations to relative paths within each router.
+3. Introduce a small route compatibility layer for routes that are likely to move later.
+   - Example: helper functions that can be mounted under both old and new paths.
+4. Add explicit route tags so Swagger/OpenAPI groups are coherent.
+5. Document the intended public ownership of each namespace.
+
+### Backward Compatibility
+
+- No public path changes yet if existing paths are preserved through prefixes and aliases.
+- Mostly internal refactoring.
+
+### Timeline Estimate
+
+- 3-4 engineering days.
+
+### Success Criteria
+
+- All route modules use prefixes and tags.
+- Route registration in `backend/routes/__init__.py` becomes simpler.
+- OpenAPI groups read cleanly by domain.
+
+## Phase 4: Introduce Additive `v2` Resource Endpoints
+
+Priority: High
+Outcome: A cleaner API exists without breaking the current one.
+
+### Problems Addressed
+
+- Generation-related resources are fragmented.
+- Sample and audio endpoints are not consistently modeled as resources.
+- Command-style naming makes the API harder to reason about.
+
+### New Endpoints to Add
+
+These should be introduced alongside current endpoints, not as replacements.
+
+- `POST /generations` -> alias for current `/generate`
+- `GET /generations` -> alias for current `/history`
+- `GET /generations/{id}` -> alias for current `/history/{id}`
+- `POST /generations/{id}/retry` -> alias for current `/generate/{id}/retry`
+- `POST /generations/{id}/regenerate` -> alias for current `/generate/{id}/regenerate`
+- `GET /generations/{id}/status` -> alias for current `/generate/{id}/status`
+- `POST /generations/stream` -> alias for current `/generate/stream`
+- `GET /generations/{id}/audio` -> alias for current `/audio/{generation_id}`
+- `GET /generations/{id}/export` -> alias for current `/history/{generation_id}/export`
+- `GET /generations/{id}/export-audio` -> alias for current `/history/{generation_id}/export-audio`
+- `GET /profiles/{profile_id}/samples/{sample_id}` or `GET /samples/{sample_id}` as a consciously chosen model
+- `PUT /profiles/{profile_id}/samples/{sample_id}` -> alias for current sample update route
+- `DELETE /profiles/{profile_id}/samples/{sample_id}` -> alias for current sample delete route
+
+### Implementation Steps
+
+1. Create new handler entry points that call the existing service functions.
+2. Keep old handlers in place, but mark them deprecated in OpenAPI.
+3. Add `summary` and `description` text clarifying preferred routes.
+4. Update frontend and docs examples to use new endpoints first.
+5. Add tests proving both old and new paths return equivalent responses.
+
+### Migration Strategy
+
+- Old paths remain functional for at least one stable release cycle.
+- New docs and client examples use `v2-style` resource routes immediately.
+- Include deprecation headers where feasible, for example:
+  - `Deprecation: true`
+  - `Sunset: <date>`
+  - `Link: <new-doc-url>; rel="successor-version"`
+
+### Timeline Estimate
+
+- 1-2 weeks depending on test coverage and frontend updates.
+
+### Success Criteria
+
+- All major generation workflows are accessible through resource-oriented routes.
+- Old routes still work unchanged.
+
+## Phase 5: Migrate First-Party Clients and Publish Deprecations
+
+Priority: Medium
+Outcome: Voicebox itself stops depending on legacy paths.
+
+### Problems Addressed
+
+- The desktop app and docs may continue to reinforce old route shapes.
+- Third-party consumers need a visible migration path.
+
+### Implementation Steps
+
+1. Update `app/src/lib/api/client.ts` to use the new preferred endpoints.
+2. Regenerate or refresh any generated API clients.
+3. Update docs examples, tutorials, and code snippets to use preferred routes only.
+4. Add a changelog entry describing the migration path.
+5. Add runtime deprecation logging for legacy route usage in development mode.
+6. If feasible, expose a small `/health` or `/meta` field showing API version and deprecation window.
+
+### Migration Strategy
+
+- Keep old endpoints available but clearly documented as legacy.
+- Publish a mapping table from old route to new route.
+- Do not change request or response payloads during the same phase unless necessary.
+
+### Timeline Estimate
+
+- About 1 week including docs and app verification.
+
+### Success Criteria
+
+- First-party app no longer depends on legacy route names.
+- Docs do not advertise deprecated paths as the primary interface.
+
+## Phase 6: Cleanup, Namespace Hardening, and Optional Breaking Changes
+
+Priority: Medium
+Outcome: The API surface is cleaner and safer for remote or Docker use.
+
+### Problems Addressed
+
+- Internal/admin endpoints are mixed into the public API.
+- Legacy aliases increase maintenance cost forever if never retired.
+
+### Implementation Steps
+
+1. Move operational endpoints under `/admin` or `/internal`.
+   - `/shutdown`
+   - `/watchdog/disable`
+   - `/tasks/clear`
+   - `/cache/clear`
+2. Gate these endpoints behind configuration for non-local deployments.
+   - Example: `VOICEBOX_ENABLE_ADMIN_API=true`
+3. Decide whether to remove or keep legacy aliases.
+   - If removing, do so only after a published deprecation window.
+4. Remove deprecated docs pages and old examples.
+5. Tighten route-level tests to prevent accidental reintroduction of legacy patterns.
+
+### Migration Strategy
+
+- For desktop-only local use, aliases may remain indefinitely if removal cost outweighs benefit.
+- For published remote API guidance, hide admin endpoints from default docs even if they still exist.
+
+### Timeline Estimate
+
+- 1-2 releases after the additive migration is complete.
+
+### Success Criteria
+
+- Public docs expose a coherent resource API.
+- Operational endpoints are clearly separate or disabled in remote contexts.
+
+## Cross-Cutting Work Items
+
+These should happen throughout the migration, not only in a single phase.
+
+### Testing
+
+- Add route equivalence tests for old and new paths.
+- Add schema snapshot tests for OpenAPI generation.
+- Add response-shape tests for common mutations and async workflows.
+- Add contract tests for `202 Accepted` flows.
+
+### Documentation
+
+- Maintain an old-to-new endpoint mapping table.
+- Add per-endpoint examples for create profile, generate, apply effects, transcribe, and stories operations.
+- Explicitly document which endpoints are app-facing vs admin-facing.
+
+### Observability
+
+- Add warning logs when deprecated endpoints are used.
+- Track usage counts in development or optional telemetry-free local logs.
+
+### Release Management
+
+- Mention API changes in `CHANGELOG.md`.
+- Ensure docs and app updates ship in the same release as new preferred routes.
+
+## Recommended Execution Order
+
+If engineering time is limited, implement in this exact order:
+
+1. Fix OpenAPI and docs drift.
+2. Standardize response models and accepted-task responses.
+3. Add router prefixes and tags internally.
+4. Add `/generations` aliases and sample path aliases.
+5. Migrate the first-party app to preferred routes.
+6. Deprecate or hide legacy/admin routes.
+
+## Old-to-New Route Mapping
+
+| Current Route | Preferred Route |
+| --- | --- |
+| `POST /generate` | `POST /generations` |
+| `POST /generate/stream` | `POST /generations/stream` |
+| `POST /generate/{id}/retry` | `POST /generations/{id}/retry` |
+| `POST /generate/{id}/regenerate` | `POST /generations/{id}/regenerate` |
+| `GET /generate/{id}/status` | `GET /generations/{id}/status` |
+| `GET /history` | `GET /generations` |
+| `GET /history/{id}` | `GET /generations/{id}` |
+| `GET /audio/{id}` | `GET /generations/{id}/audio` |
+| `GET /history/{id}/export` | `GET /generations/{id}/export` |
+| `GET /history/{id}/export-audio` | `GET /generations/{id}/export-audio` |
+| `PUT /profiles/samples/{sample_id}` | `PUT /profiles/{profile_id}/samples/{sample_id}` |
+| `DELETE /profiles/samples/{sample_id}` | `DELETE /profiles/{profile_id}/samples/{sample_id}` |
+| `POST /tasks/clear` | `POST /admin/tasks/clear` |
+| `POST /cache/clear` | `POST /admin/cache/clear` |
+| `POST /shutdown` | `POST /admin/shutdown` |
+| `POST /watchdog/disable` | `POST /admin/watchdog/disable` |
+
+## Risks and Mitigations
+
+### Risk: App regressions during endpoint migration
+
+- Mitigation: Add new routes before changing client usage.
+- Mitigation: Keep payloads identical while paths change.
+
+### Risk: Docs still drift after cleanup
+
+- Mitigation: Add CI enforcement and a release checklist step.
+
+### Risk: Third-party local scripts break on removal
+
+- Mitigation: Prefer indefinite aliases for one-person local workflows unless maintenance becomes painful.
+
+### Risk: Admin endpoints remain dangerous in remote mode
+
+- Mitigation: Hide and gate them before promoting remote deployment more broadly.
+
+## Definition of Done
+
+The refactor can be considered complete when all of the following are true:
+
+- OpenAPI, checked-in docs, and backend models match.
+- The preferred public API is resource-oriented and documented consistently.
+- The Voicebox app uses preferred routes exclusively.
+- Legacy routes are either deprecated with a timeline or intentionally retained as compatibility aliases.
+- Operational endpoints are clearly separated from the public app API.
@@ -1,9 +1,4 @@
-import {
-  defineConfig,
-  defineDocs,
-  frontmatterSchema,
-  metaSchema,
-} from 'fumadocs-mdx/config';
+import { defineConfig, defineDocs, frontmatterSchema, metaSchema } from 'fumadocs-mdx/config';

 // You can customise Zod schemas for frontmatter and `meta.json` here
 // see https://fumadocs.dev/docs/mdx/collections
@@ -2,11 +2,7 @@
  "compilerOptions": {
    "baseUrl": ".",
    "target": "ESNext",
-    "lib": [
-      "dom",
-      "dom.iterable",
-      "esnext"
-    ],
+    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
@@ -20,12 +16,8 @@
    "jsx": "react-jsx",
    "incremental": true,
    "paths": {
-      "@/*": [
-        "./*"
-      ],
-      "@/.source": [
-        ".source"
-      ]
+      "@/*": ["./*"],
+      "@/.source": [".source"]
    },
    "plugins": [
      {
@@ -40,7 +32,5 @@
    ".next/types/**/*.ts",
    ".next/dev/types/**/*.ts"
  ],
-  "exclude": [
-    "node_modules"
-  ]
+  "exclude": ["node_modules"]
 }
@@ -69,10 +69,22 @@ setup-python:
    }
    Write-Host "Installing Python dependencies..."
    & "{{ python }}" -m pip install --upgrade pip -q
-    $hasNvidia = $null -ne (Get-WmiObject Win32_VideoController | Where-Object { $_.Name -match 'NVIDIA' })
+    $gpus = Get-CimInstance Win32_VideoController | Select-Object -ExpandProperty Name
+    Write-Host "Detected GPUs: $($gpus -join ', ')"
+    $hasNvidia = ($gpus | Where-Object { $_ -match 'NVIDIA' }).Count -gt 0
+    $hasIntelArc = ($gpus | Where-Object { $_ -match 'Arc' }).Count -gt 0
    if ($hasNvidia) { \
        Write-Host "NVIDIA GPU detected — installing PyTorch with CUDA support..."; \
        & "{{ pip }}" install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128; \
+    } elseif ($hasIntelArc) { \
+        Write-Host "Intel Arc GPU detected — installing PyTorch with XPU support..."; \
+        & "{{ pip }}" install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu; \
+        & "{{ pip }}" install intel-extension-for-pytorch --index-url https://download.pytorch.org/whl/xpu; \
+    } else { \
+        Write-Host "No NVIDIA or Intel Arc GPU detected — using CPU-only PyTorch."; \
+        Write-Host "If you have an Intel Arc GPU, install XPU support manually:"; \
+        Write-Host "  pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu"; \
+        Write-Host "  pip install intel-extension-for-pytorch --index-url https://download.pytorch.org/whl/xpu"; \
    }
    & "{{ pip }}" install -r {{ backend_dir }}/requirements.txt
    & "{{ pip }}" install --no-deps chatterbox-tts
@@ -1,6 +1,6 @@
 {
  "name": "@voicebox/landing",
-  "version": "0.3.1",
+  "version": "0.4.0",
  "description": "Landing page for voicebox.sh",
  "scripts": {
    "dev": "bun --bun next dev --turbo",
@@ -1,6 +1,6 @@
 'use client';

-import { Github, Globe, Languages, MessageSquare, Zap } from 'lucide-react';
+import { Github, Globe, Languages, MessageSquare, SlidersHorizontal, Zap } from 'lucide-react';
 import { useEffect, useState } from 'react';
 import { ControlUI } from '@/components/ControlUI';
 import { Features } from '@/components/Features';
@@ -236,6 +236,101 @@ export default function Home() {
                </span>
              </div>
            </div>
+
+            {/* Qwen CustomVoice */}
+            <div className="rounded-xl border border-border bg-card/60 backdrop-blur-sm p-6 transition-colors hover:border-accent/30">
+              <div className="flex items-start justify-between mb-3">
+                <div>
+                  <h3 className="text-base font-semibold text-foreground">Qwen CustomVoice</h3>
+                  <span className="text-xs text-muted-foreground/60">by Alibaba</span>
+                </div>
+                <div className="flex gap-1.5">
+                  <span className="text-[10px] px-2 py-0.5 rounded-full border border-border bg-background text-muted-foreground">
+                    1.7B
+                  </span>
+                  <span className="text-[10px] px-2 py-0.5 rounded-full border border-border bg-background text-muted-foreground">
+                    0.6B
+                  </span>
+                </div>
+              </div>
+              <p className="text-sm text-muted-foreground leading-relaxed mb-4">
+                Nine premium preset speakers with natural-language style control. Tell the model how
+                to deliver — "speak slowly with warmth", "authoritative and clear" — and it adapts
+                tone, emotion, and pace.
+              </p>
+              <div className="flex flex-wrap gap-2">
+                <span className="flex items-center gap-1 text-[11px] text-muted-foreground/70">
+                  <SlidersHorizontal className="h-3 w-3" />
+                  Instruct control
+                </span>
+                <span className="flex items-center gap-1 text-[11px] text-muted-foreground/70">
+                  <Globe className="h-3 w-3" />
+                  10 languages
+                </span>
+                <span className="flex items-center gap-1 text-[11px] text-muted-foreground/70">
+                  9 preset voices
+                </span>
+              </div>
+            </div>
+
+            {/* HumeAI TADA */}
+            <div className="rounded-xl border border-border bg-card/60 backdrop-blur-sm p-6 transition-colors hover:border-accent/30">
+              <div className="flex items-start justify-between mb-3">
+                <div>
+                  <h3 className="text-base font-semibold text-foreground">TADA</h3>
+                  <span className="text-xs text-muted-foreground/60">by Hume AI</span>
+                </div>
+                <div className="flex gap-1.5">
+                  <span className="text-[10px] px-2 py-0.5 rounded-full border border-border bg-background text-muted-foreground">
+                    3B
+                  </span>
+                  <span className="text-[10px] px-2 py-0.5 rounded-full border border-border bg-background text-muted-foreground">
+                    1B
+                  </span>
+                </div>
+              </div>
+              <p className="text-sm text-muted-foreground leading-relaxed mb-4">
+                Speech-language model with text-acoustic dual alignment. Built for long-form
+                generation — produces 700s+ of coherent audio without drift. Multilingual at 3B,
+                English-focused at 1B.
+              </p>
+              <div className="flex flex-wrap gap-2">
+                <span className="flex items-center gap-1 text-[11px] text-muted-foreground/70">
+                  <Globe className="h-3 w-3" />
+                  10 languages
+                </span>
+                <span className="flex items-center gap-1 text-[11px] text-muted-foreground/70">
+                  Long-form coherent
+                </span>
+              </div>
+            </div>
+
+            {/* Kokoro 82M */}
+            <div className="rounded-xl border border-border bg-card/60 backdrop-blur-sm p-6 transition-colors hover:border-accent/30">
+              <div className="flex items-start justify-between mb-3">
+                <div>
+                  <h3 className="text-base font-semibold text-foreground">Kokoro</h3>
+                  <span className="text-xs text-muted-foreground/60">by hexgrad · Apache 2.0</span>
+                </div>
+                <span className="text-[10px] px-2 py-0.5 rounded-full border border-border bg-background text-muted-foreground">
+                  82M
+                </span>
+              </div>
+              <p className="text-sm text-muted-foreground leading-relaxed mb-4">
+                Tiny 82M-parameter TTS that runs at CPU realtime with negligible VRAM. Pre-built
+                voice styles instead of cloning — pick a voice, type, generate. Smallest footprint
+                of any engine.
+              </p>
+              <div className="flex flex-wrap gap-2">
+                <span className="flex items-center gap-1 text-[11px] text-muted-foreground/70">
+                  <Zap className="h-3 w-3" />
+                  CPU realtime
+                </span>
+                <span className="flex items-center gap-1 text-[11px] text-muted-foreground/70">
+                  Preset voices
+                </span>
+              </div>
+            </div>
          </div>
        </div>
      </section>
@@ -1,6 +1,7 @@
+import { Coffee } from 'lucide-react';
 import Image from 'next/image';
 import Link from 'next/link';
-import { GITHUB_REPO } from '@/lib/constants';
+import { DONATE_URL, GITHUB_REPO } from '@/lib/constants';

 export function Footer() {
  return (
@@ -19,9 +20,19 @@ export function Footer() {
              />
              <span className="text-sm font-semibold">Voicebox</span>
            </div>
-            <p className="text-sm text-muted-foreground leading-relaxed">
+            <p className="text-sm text-muted-foreground leading-relaxed mb-4">
              Open source voice cloning studio. Local-first, free forever.
            </p>
+            <a
+              href={DONATE_URL}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-2 rounded-lg border border-border/60 bg-card/60 px-3 py-2 text-sm text-muted-foreground transition-colors hover:text-foreground hover:border-[#FFDD00]/40"
+              aria-label="Donate via Buy Me a Coffee"
+            >
+              <Coffee className="h-4 w-4 text-[#FFDD00]" />
+              <span className="text-[13px] font-medium">Donate</span>
+            </a>
          </div>

          {/* Product */}
@@ -1,9 +1,9 @@
 'use client';

-import { Github } from 'lucide-react';
+import { Coffee, Github } from 'lucide-react';
 import Image from 'next/image';
 import { useEffect, useState } from 'react';
-import { GITHUB_REPO } from '@/lib/constants';
+import { DONATE_URL, GITHUB_REPO } from '@/lib/constants';

 function formatStarCount(count: number): string {
  if (count >= 1000) {
@@ -75,21 +75,33 @@ export function Navbar() {
          </a>
        </div>

-        {/* GitHub star button */}
-        <a
-          href={GITHUB_REPO}
-          target="_blank"
-          rel="noopener noreferrer"
-          className="flex items-center gap-2 justify-self-end rounded-lg border border-border/60 bg-card/60 px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:text-foreground hover:border-border"
-        >
-          <Github className="h-4 w-4" />
-          <span className="text-[13px] font-medium">Star</span>
-          {starCount !== null && (
-            <span className="border-l border-border/60 pl-2 text-[13px] font-semibold text-foreground">
-              {formatStarCount(starCount)}
-            </span>
-          )}
-        </a>
+        {/* Donate + GitHub star buttons */}
+        <div className="flex items-center gap-2 justify-self-end">
+          <a
+            href={DONATE_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="hidden sm:flex items-center gap-2 rounded-lg border border-border/60 bg-card/60 px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:text-foreground hover:border-[#FFDD00]/40"
+            aria-label="Donate via Buy Me a Coffee"
+          >
+            <Coffee className="h-4 w-4 text-[#FFDD00]" />
+            <span className="text-[13px] font-medium">Donate</span>
+          </a>
+          <a
+            href={GITHUB_REPO}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="flex items-center gap-2 rounded-lg border border-border/60 bg-card/60 px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:text-foreground hover:border-border"
+          >
+            <Github className="h-4 w-4" />
+            <span className="text-[13px] font-medium">Star</span>
+            {starCount !== null && (
+              <span className="border-l border-border/60 pl-2 text-[13px] font-semibold text-foreground">
+                {formatStarCount(starCount)}
+              </span>
+            )}
+          </a>
+        </div>
      </div>
    </nav>
  );
@@ -4,6 +4,7 @@ export const LATEST_VERSION = 'v0.1.0';

 export const GITHUB_REPO = 'https://github.com/jamiepine/voicebox';
 export const GITHUB_RELEASES_PAGE = `${GITHUB_REPO}/releases`;
+export const DONATE_URL = 'https://buymeacoffee.com/jamiepine';

 export const DOWNLOAD_LINKS = {
  macArm: GITHUB_RELEASES_PAGE,
@@ -1,6 +1,6 @@
 {
  "name": "voicebox",
-  "version": "0.3.1",
+  "version": "0.4.0",
  "private": true,
  "workspaces": [
    "app",
@@ -1,7 +1,7 @@
 {
  "name": "@voicebox/tauri",
  "private": true,
-  "version": "0.3.1",
+  "version": "0.4.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
@@ -5041,7 +5041,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"

 [[package]]
 name = "voicebox"
-version = "0.2.3"
+version = "0.4.0"
 dependencies = [
 "base64 0.22.1",
 "core-foundation-sys",
@@ -1,6 +1,6 @@
 [package]
 name = "voicebox"
-version = "0.3.1"
+version = "0.4.0"
 description = "A production-quality desktop app for Qwen3-TTS voice cloning and generation"
 authors = ["you"]
 license = ""
@@ -5,6 +5,10 @@ fn main() {
    // Link Swift runtime libraries for screencapturekit crate
    #[cfg(target_os = "macos")]
    {
+        // ScreenCaptureKit does not exist on macOS 11, so weak-link it to
+        // allow the app to launch and gate usage at runtime instead.
+        println!("cargo:rustc-link-arg=-Wl,-weak_framework,ScreenCaptureKit");
+
        // Add Swift runtime library paths to RPATH
        println!("cargo:rustc-link-arg=-Wl,-rpath,/usr/lib/swift");
        println!("cargo:rustc-link-arg=-L/usr/lib/swift");
@@ -13,6 +13,7 @@ use screencapturekit::{
    },
 };
 use std::io::Cursor;
+use std::process::Command;
 use std::sync::{Arc, Mutex};
 use tokio::sync::mpsc;

@@ -20,6 +21,10 @@ pub async fn start_capture(
    state: &AudioCaptureState,
    max_duration_secs: u32,
 ) -> Result<(), String> {
+    if !is_supported() {
+        return Err("System audio capture requires macOS 12.3 or newer.".to_string());
+    }
+
    // Reset previous samples
    state.reset();

@@ -144,17 +149,22 @@ pub async fn stop_capture(state: &AudioCaptureState) -> Result<String, String> {
 }

 pub fn is_supported() -> bool {
-    // ScreenCaptureKit requires macOS 12.3+
-    // Check if we're on a supported version
-    #[cfg(target_os = "macos")]
-    {
-        // Basic check - ScreenCaptureKit should be available on macOS 12.3+
-        true
-    }
-    #[cfg(not(target_os = "macos"))]
-    {
-        false
-    }
+    macos_version_at_least(12, 3)
+}
+
+fn macos_version_at_least(required_major: u64, required_minor: u64) -> bool {
+    let output = match Command::new("sw_vers").arg("-productVersion").output() {
+        Ok(output) if output.status.success() => output,
+        _ => return false,
+    };
+
+    let version = String::from_utf8_lossy(&output.stdout);
+    let mut parts = version.trim().split('.');
+
+    let major = parts.next().and_then(|part| part.parse::<u64>().ok()).unwrap_or(0);
+    let minor = parts.next().and_then(|part| part.parse::<u64>().ok()).unwrap_or(0);
+
+    major > required_major || (major == required_major && minor >= required_minor)
 }

 fn extract_audio_samples(sample_buffer: CMSampleBuffer) -> Result<Vec<f32>, String> {
--- a/Show More
+++ b/Show More