fix(audio): prevent WKWebView audio session teardown after backgrounding (#41)

Keep a silent looping <audio> element mounted at the app root so macOS
never tears down the CoreAudio session. Without this, backgrounding the
app long enough leaves WaveSurfer's AudioContext in a state where play()
resolves and timeupdate fires, but no audio reaches the output — and not
even cmd+R (full JS reload) restores it, only a full app relaunch.

Uses a zero-PCM WAV blob at full volume rather than a muted element,
since WebKit can optimize muted media away and defeat the purpose.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

README.md

@@ -62,13 +62,14 @@
 
 ## What is Voicebox?
 
-Voicebox is a **local-first voice cloning studio** — a free and open-source alternative to ElevenLabs. Clone voices from a few seconds of audio, generate speech in 23 languages across 5 TTS engines, apply post-processing effects, and compose multi-voice projects with a timeline editor.
+Voicebox is a **local-first voice cloning studio** — a free and open-source alternative to ElevenLabs. Clone voices from a few seconds of audio or pick from 50+ preset voices, generate speech in 23 languages across 7 TTS engines, apply post-processing effects, and compose multi-voice projects with a timeline editor.
 
 - **Complete privacy** — models and voice data stay on your machine
-- **5 TTS engines** — Qwen3-TTS, LuxTTS, Chatterbox Multilingual, Chatterbox Turbo, and HumeAI TADA
+- **7 TTS engines** — Qwen3-TTS, Qwen CustomVoice, LuxTTS, Chatterbox Multilingual, Chatterbox Turbo, HumeAI TADA, and Kokoro
+- **Cloning and preset voices** — zero-shot cloning from a reference sample, or curated preset voices via Kokoro (50 voices) and Qwen CustomVoice (9 voices)
 - **23 languages** — from English to Arabic, Japanese, Hindi, Swahili, and more
 - **Post-processing effects** — pitch shift, reverb, delay, chorus, compression, and filters
-- **Expressive speech** — paralinguistic tags like `[laugh]`, `[sigh]`, `[gasp]` via Chatterbox Turbo
+- **Expressive speech** — paralinguistic tags like `[laugh]`, `[sigh]`, `[gasp]` via Chatterbox Turbo; natural-language delivery control via Qwen CustomVoice
 - **Unlimited length** — auto-chunking with crossfade for scripts, articles, and chapters
 - **Stories editor** — multi-track timeline for conversations, podcasts, and narratives
 - **API-first** — REST API for integrating voice synthesis into your own projects
@@ -96,15 +97,17 @@ Voicebox is a **local-first voice cloning studio** — a free and open-source al
 
 ### Multi-Engine Voice Cloning
 
-Five TTS engines with different strengths, switchable per-generation:
+Seven TTS engines with different strengths, switchable per-generation:
 
 | Engine                      | Languages | Strengths                                                                                                                                |
 | --------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | **Qwen3-TTS** (0.6B / 1.7B) | 10        | High-quality multilingual cloning, delivery instructions ("speak slowly", "whisper")                                                     |
+| **Qwen CustomVoice**        | 10        | 9 curated preset voices with natural-language delivery control — no reference audio required                                             |
 | **LuxTTS**                  | English   | Lightweight (~1GB VRAM), 48kHz output, 150x realtime on CPU                                                                              |
 | **Chatterbox Multilingual** | 23        | Broadest language coverage — Arabic, Danish, Finnish, Greek, Hebrew, Hindi, Malay, Norwegian, Polish, Swahili, Swedish, Turkish and more |
 | **Chatterbox Turbo**        | English   | Fast 350M model with paralinguistic emotion/sound tags                                                                                   |
 | **TADA** (1B / 3B)          | 10        | HumeAI speech-language model — 700s+ coherent audio, text-acoustic dual alignment                                                        |
+| **Kokoro**                  | 8         | 50 curated preset voices, tiny 82M model, fast CPU inference                                                                             |
 
 ### Emotions & Paralinguistic Tags
 
@@ -239,7 +242,7 @@ Full API documentation available at `http://localhost:17493/docs`.
 | Frontend      | React, TypeScript, Tailwind CSS                   |
 | State         | Zustand, React Query                              |
 | Backend       | FastAPI (Python)                                  |
-| TTS Engines   | Qwen3-TTS, LuxTTS, Chatterbox, Chatterbox Turbo, TADA |
+| TTS Engines   | Qwen3-TTS, Qwen CustomVoice, LuxTTS, Chatterbox, Chatterbox Turbo, TADA, Kokoro |
 | Effects       | Pedalboard (Spotify)                              |
 | Transcription | Whisper / Whisper Turbo (PyTorch or MLX)          |
 | Inference     | MLX (Apple Silicon) / PyTorch (CUDA/ROCm/XPU/CPU) |

app/src/components/AppFrame/AppFrame.tsx

@@ -1,5 +1,6 @@
 import { useRouterState } from '@tanstack/react-router';
 import { TitleBarDragRegion } from '@/components/TitleBarDragRegion';
+import { AudioKeepAlive } from '@/components/AudioPlayer/AudioKeepAlive';
 import { AudioPlayer } from '@/components/AudioPlayer/AudioPlayer';
 import { StoryTrackEditor } from '@/components/StoriesTab/StoryTrackEditor';
 import { TOP_SAFE_AREA_PADDING } from '@/lib/constants/ui';
@@ -26,6 +27,7 @@ export function AppFrame({ children }: AppFrameProps) {
       className={cn('h-screen bg-background flex flex-col overflow-hidden', TOP_SAFE_AREA_PADDING)}
     >
       <TitleBarDragRegion />
+      <AudioKeepAlive />
       {children}
       {showTrackEditor ? (
         <StoryTrackEditor storyId={story.id} items={story.items} />

app/src/components/AudioPlayer/AudioKeepAlive.tsx

@@ -0,0 +1,85 @@
+import { useEffect, useRef } from 'react';
+import { debug } from '@/lib/utils/debug';
+
+// WKWebView tears down the app's CoreAudio output when idle for long enough,
+// and a JS-level reload (cmd+R) does NOT restore it — only relaunching the
+// Tauri app does. Keeping a silent <audio> element looping forever prevents
+// the OS audio session from ever going dormant.
+//
+// Real silence (zero PCM samples) at full volume is preferred over a muted
+// element: browsers/WebKit can optimize muted media away, which defeats the
+// purpose of holding the session open.
+
+function buildSilentWavUrl(seconds = 1, sampleRate = 8000): string {
+  const numSamples = seconds * sampleRate;
+  const bytes = 44 + numSamples * 2;
+  const buffer = new ArrayBuffer(bytes);
+  const view = new DataView(buffer);
+  const write = (offset: number, str: string) => {
+    for (let i = 0; i < str.length; i++) view.setUint8(offset + i, str.charCodeAt(i));
+  };
+  write(0, 'RIFF');
+  view.setUint32(4, bytes - 8, true);
+  write(8, 'WAVE');
+  write(12, 'fmt ');
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  write(36, 'data');
+  view.setUint32(40, numSamples * 2, true);
+  return URL.createObjectURL(new Blob([buffer], { type: 'audio/wav' }));
+}
+
+export function AudioKeepAlive() {
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+
+  useEffect(() => {
+    const url = buildSilentWavUrl(1, 8000);
+    const el = new Audio(url);
+    el.loop = true;
+    el.volume = 1;
+    el.preload = 'auto';
+    audioRef.current = el;
+
+    const tryPlay = () => {
+      if (!audioRef.current) return;
+      if (!audioRef.current.paused) return;
+      audioRef.current.play().catch((err) => {
+        debug.log('[AudioKeepAlive] play blocked (will retry on next gesture):', err);
+      });
+    };
+
+    tryPlay();
+
+    // Autoplay may be blocked until first user interaction — re-attempt then.
+    const onGesture = () => tryPlay();
+    window.addEventListener('pointerdown', onGesture, { once: false });
+    window.addEventListener('keydown', onGesture, { once: false });
+
+    // If the webview ever pauses the element on background, resume on return.
+    const onWake = () => {
+      if (!document.hidden) tryPlay();
+    };
+    document.addEventListener('visibilitychange', onWake);
+    window.addEventListener('focus', onWake);
+    window.addEventListener('pageshow', onWake);
+
+    return () => {
+      window.removeEventListener('pointerdown', onGesture);
+      window.removeEventListener('keydown', onGesture);
+      document.removeEventListener('visibilitychange', onWake);
+      window.removeEventListener('focus', onWake);
+      window.removeEventListener('pageshow', onWake);
+      el.pause();
+      el.src = '';
+      URL.revokeObjectURL(url);
+      audioRef.current = null;
+    };
+  }, []);
+
+  return null;
+}

tauri/src-tauri/Cargo.lock

@@ -5041,7 +5041,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
 [[package]]
 name = "voicebox"
-version = "0.4.0"
+version = "0.4.1"
 dependencies = [
  "base64 0.22.1",
  "core-foundation-sys",