feat: implement real voice cloning with Qwen3-TTS (sprint step 3)

- Add voice_clone.py: Qwen3-TTS model wrapper with server-side profile
cache, create_voice_profile() and synthesize_cloned() API
- Refactor tts.py: backend-neutral interface delegates to Qwen3-TTS
when voice_profile_id provided, Supertonic fallback otherwise
- Wire app.py: real cloning in animate_cloning_pipeline, voice profile
flows via gr.State to narration (stream_tts) and Q&A
- Fix XSS: html.escape in render_story_text and clone success card
- Fix misleading fallback: hide audio widget when TTS fails instead of
playing fake chime audio
- Add qwen-tts to requirements.txt
- Update copilot-instructions.md with new architecture

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/copilot-instructions.md

@@ -12,13 +12,16 @@ Requires a GPU (T4 or A10G) for inference. No Docker, no database, no external A
 
 ## Architecture
 
-Single-process Gradio app (`app.py`, ~1200 lines) that orchestrates three ML models:
+Single-process Gradio app (`app.py`, ~1200 lines) that orchestrates four ML models:
 
-- **QWEN-TTS-0.6B** — voice cloning + TTS (always loaded)
-- **Qwen2.5-3B-Instruct** — story Q&A, 4-bit quantized on T4 (always loaded)
-- **Whisper-small** — child speech-to-text (loaded on demand)
+- **Qwen3-TTS-1.7B** (`voice_clone.py`) — zero-shot voice cloning from reference audio + cloned voice synthesis
+- **Supertonic TTS** — fast stock-voice fallback when no clone is available
+- **Qwen2.5-3B-Instruct** (`inference.py`) — story Q&A, 4-bit quantized on T4
+- **Whisper-small** (`inference.py`) — child speech-to-text (loaded on demand)
 
-`tts.py` wraps Supertonic TTS with sentence-level chunking and background-threaded streaming via a queue (maxsize=2 buffer).
+`tts.py` is the unified TTS interface. It delegates to Qwen3-TTS when a `voice_profile_id` is provided, otherwise falls back to Supertonic. Both backends use background-threaded streaming with a queue (maxsize=2 buffer).
+
+`voice_clone.py` manages the Qwen3-TTS model and a server-side in-memory cache of voice profiles keyed by UUID. Profiles are created via `create_voice_profile(ref_audio_path)` and reused for all subsequent synthesis calls.
 
 Stories are plain `.txt` files in `stories/` — title on line 1, blank line, then prose. No metadata DB.
 
@@ -30,7 +33,7 @@ Stories are plain `.txt` files in `stories/` — title on line 1, blank line, th
 - **In-memory session cache only** — no database, no persistent storage of user data.
 - **Interruptible chunked streaming** — paragraphs are synthesized and played one at a time. Cached chunks enable instant replay/resume.
 - **Pre-generated Q&A** — anticipated questions generated in background during narration for sub-1s cache hits.
-- **VRAM budget awareness** — total ~5-6 GB on T4 (16 GB). Load ASR only on demand. Use 4-bit quantization for the LLM.
+- **VRAM budget awareness** — total ~8-9 GB on T4 (16 GB). All models lazy-loaded on demand. Use 4-bit quantization for the LLM. Qwen3-TTS (~1.7B) loads only when cloning starts.
 
 ## Story Pipeline
 

app.py

@@ -309,14 +309,15 @@ def load_paragraphs(story_path: str) -> list:
 def render_story_text(paragraphs: list, current_idx: int) -> str:
     if not paragraphs:
         return ""
-    html = """<div style="max-height: 420px; overflow-y: auto; padding: 4px 2px; margin-top: 12px;">"""
+    result = """<div style="max-height: 420px; overflow-y: auto; padding: 4px 2px; margin-top: 12px;">"""
     for i, para in enumerate(paragraphs):
+        safe_para = html.escape(para)
         if i == current_idx:
-            html += f"""<p style="font-family: 'Playfair Display', Georgia, serif; font-size: 13px; line-height: 1.8; color: #FAF7F2; background: rgba(245,132,31,0.18); border-left: 3px solid #f5841f; padding: 8px 12px; border-radius: 6px; margin: 6px 0;">{para}</p>"""
+            result += f"""<p style="font-family: 'Playfair Display', Georgia, serif; font-size: 13px; line-height: 1.8; color: #FAF7F2; background: rgba(245,132,31,0.18); border-left: 3px solid #f5841f; padding: 8px 12px; border-radius: 6px; margin: 6px 0;">{safe_para}</p>"""
         else:
-            html += f"""<p style="font-family: 'Playfair Display', Georgia, serif; font-size: 13px; line-height: 1.8; color: #94a3b8; padding: 4px 12px; margin: 4px 0;">{para}</p>"""
-    html += "</div>"
-    return html
+            result += f"""<p style="font-family: 'Playfair Display', Georgia, serif; font-size: 13px; line-height: 1.8; color: #94a3b8; padding: 4px 12px; margin: 4px 0;">{safe_para}</p>"""
+    result += "</div>"
+    return result
 
 def render_cloned_voices_html(voices_list):
     html = """<div class="book-shelf-grid">"""
@@ -357,6 +358,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
     voices_state = gr.State(mock_voices)
     paragraphs_state = gr.State([])
     tts_chunks_state = gr.State([])
+    voice_profile_state = gr.State(None)
 
     gr.HTML("""
     <div style="display: flex; align-items: center; justify-content: space-between; padding: 16px 0; border-bottom: 1px solid #ebdccb; margin-bottom: 24px; flex-wrap: wrap; gap: 16px;">
@@ -681,34 +683,45 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
         if not v_name.strip():
             return (
                 """<div style="padding: 12px; background: #fef2f2; border: 1px solid #fecaca; color: #991b1b; border-radius: 12px; font-size: 12px; font-weight: 600;">
-                    ⚠️ Please provide a comforting nickname for your cloning candidate.
+                    Please provide a comforting nickname for your cloning candidate.
                    </div>""",
                 gr.HTML(visible=False),
                 gr.HTML(visible=False),
                 gr.Audio(visible=False),
-                gr.Button(visible=False)
+                gr.Button(visible=False),
+                None,
             )
         if recorder_data is None:
             return (
                 """<div style="padding: 12px; background: #fef2f2; border: 1px solid #fecaca; color: #991b1b; border-radius: 12px; font-size: 12px; font-weight: 600;">
-                    ⚠️ Microphone recording sample missing. Speak some script lines!
+                    Microphone recording sample missing. Speak some script lines!
                    </div>""",
                 gr.HTML(visible=False),
                 gr.HTML(visible=False),
                 gr.Audio(visible=False),
-                gr.Button(visible=False)
+                gr.Button(visible=False),
+                None,
             )
 
-        progress(0, desc="Extracting speech samples patterns...")
-        time.sleep(1.0)
-        progress(0.3, desc="Filtering ambient air-con noise frequencies...")
-        time.sleep(1.2)
-        progress(0.65, desc="Mapping vocal vocal tracts formant spaces & frequencies...")
-        time.sleep(1.5)
-        progress(0.9, desc="Validating speech prosody & standard conversational matching...")
-        time.sleep(1.0)
+        from voice_clone import create_voice_profile, synthesize_cloned_preview
+        import soundfile as sf
+
+        progress(0.1, desc="Extracting speaker embedding from recording...")
+        profile_id = create_voice_profile(recorder_data)
+
+        progress(0.7, desc="Generating voice preview...")
+        try:
+            preview_wav, preview_sr = synthesize_cloned_preview(profile_id)
+            preview_path = f"sample_sounds/clone_preview_{profile_id}.wav"
+            sf.write(preview_path, preview_wav, preview_sr)
+        except Exception as e:
+            import logging
+            logging.getLogger(__name__).exception("Preview synthesis failed")
+            preview_path = None
+
+        progress(1.0, desc="Voice cloned successfully!")
 
-        preview_text = f"&ldquo;Hello! I have created my brand new clone under '{v_name}'. Ready to narrate any classical story inside your library shelves.&rdquo;"
+        safe_name = html.escape(v_name)
         avatar = "👩" if v_gender == "Female" else "👨"
 
         cloned_card_html = f"""
@@ -718,12 +731,12 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
                     {avatar}
                 </div>
                 <div>
-                    <h4 class="serif-header" style="font-size: 16px; margin: 0;">{v_name} <span style="font-size: 9px; background: #f0fdf4; color: #16a34a; padding: 2px 6px; border-radius: 4px; font-weight:700;">Cloned successfully</span></h4>
-                    <p style="font-size: 11px; color:#6f6257; margin-top:2px;">Synthesized today • Calibrated for Classical Audiobooks</p>
+                    <h4 class="serif-header" style="font-size: 16px; margin: 0;">{safe_name} <span style="font-size: 9px; background: #f0fdf4; color: #16a34a; padding: 2px 6px; border-radius: 4px; font-weight:700;">Cloned successfully</span></h4>
+                    <p style="font-size: 11px; color:#6f6257; margin-top:2px;">Synthesized today using Qwen3-TTS voice cloning</p>
                 </div>
             </div>
             <div style="background:#FAF7F2; border-left: 3px solid #f5841f; padding: 10px; font-family: Georgia, serif; font-style: italic; font-size: 12px; color: #1c1c19;">
-                {preview_text}
+                Voice profile ready. Select a story and tap Play to hear narration in this voice.
             </div>
         </div>
         """
@@ -732,14 +745,15 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
             gr.HTML(visible=False),
             gr.HTML(visible=False),
             gr.HTML(value=cloned_card_html, visible=True),
-            gr.Audio(visible=True),
-            gr.Button(visible=True)
+            gr.Audio(value=preview_path, visible=preview_path is not None),
+            gr.Button(visible=True),
+            profile_id,
         )
 
     extract_btn.click(
         animate_cloning_pipeline,
         inputs=[new_voice_name, new_voice_gender, mic_recorder],
-        outputs=[cloning_progress_msg, loading_spinner, voice_cloning_success_panel, voice_sample_preview_widget, add_to_library_btn]
+        outputs=[cloning_progress_msg, loading_spinner, voice_cloning_success_panel, voice_sample_preview_widget, add_to_library_btn, voice_profile_state]
     )
 
     # 4. Add cloned voice to inventory
@@ -773,7 +787,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
     )
 
     # 5. Play button — streams TTS audio chunk by chunk
-    def stream_tts(tts_chunks, paras):
+    def stream_tts(tts_chunks, paras, profile_id):
         _status_playing = """
             <div style="margin-top: 12px; display: flex; align-items: center; gap: 10px; justify-content: center;">
                 <span style="width: 8px; height: 8px; border-radius: 50%; background: #4ade80; display: inline-block;"></span>
@@ -795,7 +809,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
         # Immediately show PLAYING state
         yield None, _status_playing, f"<div style='text-align:center;font-size:10px;color:#4ade80;font-family:monospace;margin-top:8px;'>Generating chunk 1 / {n}…</div>", gr.Button(visible=False), gr.Button(visible=True), gr.Button(visible=False)
 
-        for sample_rate, wav, i, total, err in generate_audio_stream(tts_chunks):
+        for sample_rate, wav, i, total, err in generate_audio_stream(tts_chunks, voice_profile_id=profile_id):
             if err:
                 yield None, f"<div style='color:#ef4444;font-size:11px;'>Error on chunk {i+1}: {err}</div>", "", gr.Button(visible=True), gr.Button(visible=False), gr.Button(visible=False)
                 return
@@ -808,7 +822,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
 
     play_btn.click(
         stream_tts,
-        inputs=[tts_chunks_state, paragraphs_state],
+        inputs=[tts_chunks_state, paragraphs_state, voice_profile_state],
         outputs=[player_audio_control, player_status_bar, chunk_status, play_btn, pause_btn, ask_btn]
     )
 
@@ -871,7 +885,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
     )
 
     # 9. Submit question
-    def handle_question_submit(question_txt, question_audio_path, paragraphs, slider_val):
+    def handle_question_submit(question_txt, question_audio_path, paragraphs, slider_val, profile_id):
         if not question_txt.strip() and question_audio_path is None:
             answer_html = """
                 <div style="padding: 10px; background: #fef2f2; border: 1px solid #fecaca; border-radius: 10px; font-size: 12px; color: #991b1b;">
@@ -913,7 +927,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
             chunks = _split(answer_text)
             audio_segments = []
             sample_rate = 16000
-            for sr, wav, idx, total, err in _gen_stream(chunks):
+            for sr, wav, idx, total, err in _gen_stream(chunks, voice_profile_id=profile_id):
                 if wav is not None:
                     audio_segments.append(wav)
                     sample_rate = sr
@@ -940,11 +954,11 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
         """
         if answer_audio_path:
             return answer_html, gr.Audio(value=answer_audio_path, visible=True)
-        return answer_html, gr.Audio(value="sample_sounds/cloned_preview.wav", visible=True)
+        return answer_html, gr.Audio(visible=False)
 
     submit_question_btn.click(
         handle_question_submit,
-        inputs=[question_text, question_audio, paragraphs_state, timeline_slider],
+        inputs=[question_text, question_audio, paragraphs_state, timeline_slider, voice_profile_state],
         outputs=[answer_display, answer_audio]
     )
 

requirements.txt

@@ -6,9 +6,10 @@ bitsandbytes
 soundfile
 numpy
 
-
-# Supertonic TTS
+# Supertonic TTS (fallback voice)
 supertonic>=1.3.1
-soundfile>=0.12.0
 onnxruntime>=1.18.0
 huggingface-hub>=0.23.0
+
+# Qwen3-TTS (voice cloning)
+qwen-tts>=0.1.1

sprint.md

@@ -13,7 +13,7 @@ Ship a public Hugging Face Space: parent clones voice → story streams in that
 |---|---|---|---|
 | 1 | Set up repo: `app.py`, `requirements.txt`, `stories/` | 30m | ☑ |
 | 2 | Load QWEN-TTS-0.6B locally, test basic TTS (text → audio) | 1h | ☑ | *(switched to Supertonic TTS; wired in `tts.py`, tested in `test_modules/`)* |
-| 3 | Implement voice cloning and cache voice representation after recording | 1.5h | ☐ | *(UI flow complete; actual mic→voice-representation synthesis still placeholder `time.sleep()`)* |
+| 3 | Implement voice cloning and cache voice representation after recording | 1.5h | ☑ | *(Qwen3-TTS voice cloning in `voice_clone.py`; `create_voice_profile()` extracts speaker embedding, cached server-side; preview synthesis on clone; profile_id flows via `gr.State` to narration + Q&A)* |
 | 4 | Add 10 short stories as `.txt` files (public domain, from Project Gutenberg) | 30m | ☑ |
 | 5 | Wire up: pick story → stream first narration chunk, track chunk index, cache story audio | 1h | ☑ | *(`handle_book_select` loads paragraphs + splits chunks; `stream_tts` generator streams audio with play/pause/chunk-index tracking)* |
 

test_modules/test_qwen3_tts_clone.py

@@ -0,0 +1,107 @@
+"""
+Test Qwen3-TTS voice cloning: load model, extract voice from reference audio, synthesize.
+Usage: python test_modules/test_qwen3_tts_clone.py
+"""
+import sys
+import time
+import numpy as np
+import soundfile as sf
+
+print("=" * 60)
+print("Testing Qwen3-TTS Voice Cloning")
+print("=" * 60)
+
+# Generate a synthetic reference audio (sine wave simulating speech duration)
+# In production this would be the parent's recorded voice
+print("Creating synthetic reference audio for testing...")
+sr = 16000
+duration = 5  # 5 seconds
+t = np.linspace(0, duration, sr * duration, dtype=np.float32)
+# Simple multi-frequency signal (not real speech, but tests the pipeline)
+ref_audio = 0.3 * np.sin(2 * np.pi * 200 * t) + 0.2 * np.sin(2 * np.pi * 400 * t)
+ref_audio_path = "sample_sounds/test_ref_audio.wav"
+sf.write(ref_audio_path, ref_audio, sr)
+print(f"[OK] Reference audio created: {ref_audio_path} ({duration}s)")
+
+print()
+print("Loading Qwen3-TTS model (this downloads ~1.7GB on first run)...")
+start = time.time()
+
+try:
+    import torch
+    from qwen_tts import Qwen3TTSModel
+
+    model = Qwen3TTSModel.from_pretrained(
+        "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
+        device_map="cuda" if torch.cuda.is_available() else "cpu",
+        torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
+    )
+    elapsed = time.time() - start
+    print(f"[OK] Qwen3-TTS loaded in {elapsed:.1f}s")
+except Exception as e:
+    print(f"[FAIL] Model loading failed: {e}")
+    import traceback
+    traceback.print_exc()
+    sys.exit(1)
+
+# Test 1: Voice cloning with x_vector_only_mode (speaker embedding only, no ref_text needed)
+print()
+print("Test 1: Voice clone with x_vector_only_mode=True...")
+try:
+    start = time.time()
+    audio_list, sample_rate = model.generate_voice_clone(
+        text="Hello! I am reading a bedtime story for you tonight.",
+        language="en",
+        ref_audio=ref_audio_path,
+        x_vector_only_mode=True,
+    )
+    elapsed = time.time() - start
+    total_samples = sum(len(a) for a in audio_list)
+    duration_out = total_samples / sample_rate
+    print(f"[OK] Voice clone (x_vector) in {elapsed:.1f}s, output: {duration_out:.1f}s at {sample_rate}Hz")
+
+    # Save output
+    output = np.concatenate(audio_list)
+    sf.write("sample_sounds/test_clone_xvector.wav", output, sample_rate)
+    print(f"[OK] Saved to sample_sounds/test_clone_xvector.wav")
+except Exception as e:
+    print(f"[FAIL] x_vector clone failed: {e}")
+    import traceback
+    traceback.print_exc()
+
+# Test 2: Create and reuse voice clone prompt (for caching)
+print()
+print("Test 2: Create reusable voice clone prompt...")
+try:
+    start = time.time()
+    prompt_items = model.create_voice_clone_prompt(
+        ref_audio=ref_audio_path,
+        x_vector_only_mode=True,
+    )
+    elapsed = time.time() - start
+    print(f"[OK] Voice clone prompt created in {elapsed:.1f}s")
+
+    # Reuse cached prompt for synthesis
+    start = time.time()
+    audio_list2, sr2 = model.generate_voice_clone(
+        text="Once upon a time, there was a little rabbit named Peter.",
+        language="en",
+        voice_clone_prompt=prompt_items,
+    )
+    elapsed = time.time() - start
+    total_samples2 = sum(len(a) for a in audio_list2)
+    duration_out2 = total_samples2 / sr2
+    print(f"[OK] Synthesis from cached prompt in {elapsed:.1f}s, output: {duration_out2:.1f}s")
+
+    output2 = np.concatenate(audio_list2)
+    sf.write("sample_sounds/test_clone_cached.wav", output2, sr2)
+    print(f"[OK] Saved to sample_sounds/test_clone_cached.wav")
+except Exception as e:
+    print(f"[FAIL] Cached prompt failed: {e}")
+    import traceback
+    traceback.print_exc()
+
+print()
+print("=" * 60)
+print("[OK] Qwen3-TTS voice cloning tests complete")
+print("=" * 60)

tts.py

@@ -1,12 +1,22 @@
 """
-TTS module — wraps Supertonic TTS with sentence-level chunking and
-background-threaded streaming generation.
+TTS module — unified interface for text-to-speech synthesis.
+
+Supports two backends:
+  - Qwen3-TTS: voice-cloned synthesis using a cached voice profile
+  - Supertonic: fast stock voice fallback (no cloning)
+
+Usage:
+    chunks = split_into_chunks(text)
+    for sr, wav, i, n, err in generate_audio_stream(chunks, voice_profile_id="abc123"):
+        ...
 """
 import logging
 import queue
 import re
 import threading
 
+import numpy as np
+
 logger = logging.getLogger(__name__)
 
 _SENTENCE_RE = re.compile(r'(?<=[.!?;])\s+')
@@ -15,11 +25,11 @@ _SENTINEL = object()
 _tts_instance = None
 
 
-def get_tts():
+def _get_supertonic():
     global _tts_instance
     if _tts_instance is None:
         from supertonic import TTS
-        logger.info("Loading Supertonic TTS model…")
+        logger.info("Loading Supertonic TTS model...")
         _tts_instance = TTS(auto_download=True)
     return _tts_instance
 
@@ -30,33 +40,67 @@ def split_into_chunks(text: str) -> list[str]:
     return [p.strip() for p in parts if p.strip()]
 
 
-def generate_audio_stream(chunks: list[str], voice_name: str = "F1"):
+def generate_audio_stream(
+    chunks: list[str],
+    voice_profile_id: str | None = None,
+    voice_name: str = "F1",
+):
     """
     Generator: synthesizes chunks in a background thread (maxsize=2 buffer).
     Yields (sample_rate, wav_array, chunk_idx, total_chunks, error_msg).
-    wav_array is None on error.
+
+    If voice_profile_id is provided, uses Qwen3-TTS with the cloned voice.
+    Otherwise falls back to Supertonic with the given voice_name.
     """
-    tts = get_tts()
-    style = tts.get_voice_style(voice_name)
     n = len(chunks)
     chunk_q: queue.Queue = queue.Queue(maxsize=2)
 
+    if voice_profile_id:
+        _start_qwen_worker(chunks, voice_profile_id, chunk_q)
+        sample_rate = 24000  # Qwen3-TTS output rate
+    else:
+        sample_rate = _start_supertonic_worker(chunks, voice_name, chunk_q)
+
+    while True:
+        item = chunk_q.get()
+        if item is _SENTINEL:
+            break
+        i, wav, err = item
+        yield sample_rate, wav, i, n, err
+
+
+def _start_qwen_worker(chunks, profile_id, chunk_q):
+    """Background thread: synthesize chunks with Qwen3-TTS voice clone."""
+    def _worker():
+        from voice_clone import synthesize_cloned
+        for i, stmt in enumerate(chunks):
+            try:
+                wav, _sr = synthesize_cloned(stmt, profile_id)
+                chunk_q.put((i, wav, None))
+            except Exception as exc:
+                logger.exception("Qwen3-TTS synthesis failed on chunk %d", i)
+                chunk_q.put((i, None, str(exc)))
+                return
+        chunk_q.put(_SENTINEL)
+
+    threading.Thread(target=_worker, daemon=True).start()
+
+
+def _start_supertonic_worker(chunks, voice_name, chunk_q):
+    """Background thread: synthesize chunks with Supertonic (stock voice)."""
+    tts = _get_supertonic()
+    style = tts.get_voice_style(voice_name)
+
     def _worker():
         for i, stmt in enumerate(chunks):
             try:
                 wav, _ = tts.synthesize(stmt, voice_style=style)
                 chunk_q.put((i, wav.squeeze(), None))
             except Exception as exc:
-                logger.exception("TTS synthesis failed on chunk %d", i)
+                logger.exception("Supertonic synthesis failed on chunk %d", i)
                 chunk_q.put((i, None, str(exc)))
                 return
         chunk_q.put(_SENTINEL)
 
     threading.Thread(target=_worker, daemon=True).start()
-
-    while True:
-        item = chunk_q.get()
-        if item is _SENTINEL:
-            break
-        i, wav, err = item
-        yield tts.sample_rate, wav, i, n, err
+    return tts.sample_rate

voice_clone.py

@@ -0,0 +1,101 @@
+"""
+Voice cloning module — wraps Qwen3-TTS for zero-shot voice cloning.
+
+Usage:
+    profile_id = create_voice_profile(ref_audio_path)
+    wav, sr = synthesize_cloned(text, profile_id)
+"""
+import logging
+import uuid
+import threading
+
+import numpy as np
+import torch
+
+logger = logging.getLogger(__name__)
+
+# Server-side cache: { profile_id -> VoiceClonePromptItem list }
+_PROFILE_CACHE: dict[str, list] = {}
+_cache_lock = threading.Lock()
+
+_qwen_tts_model = None
+_model_lock = threading.Lock()
+
+QWEN_TTS_MODEL_ID = "Qwen/Qwen3-TTS-12Hz-1.7B-Base"
+
+
+def get_qwen_tts():
+    """Lazy-load Qwen3-TTS model. Thread-safe, cached globally."""
+    global _qwen_tts_model
+    if _qwen_tts_model is None:
+        with _model_lock:
+            if _qwen_tts_model is None:
+                from qwen_tts import Qwen3TTSModel
+
+                logger.info("Loading %s...", QWEN_TTS_MODEL_ID)
+                _qwen_tts_model = Qwen3TTSModel.from_pretrained(
+                    QWEN_TTS_MODEL_ID,
+                    device_map="cuda" if torch.cuda.is_available() else "cpu",
+                    torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
+                )
+                logger.info("Qwen3-TTS loaded.")
+    return _qwen_tts_model
+
+
+def create_voice_profile(ref_audio_path: str) -> str:
+    """
+    Extract speaker embedding from reference audio and cache it.
+    Returns a profile_id string for later synthesis.
+    """
+    model = get_qwen_tts()
+
+    logger.info("Creating voice profile from %s...", ref_audio_path)
+    prompt_items = model.create_voice_clone_prompt(
+        ref_audio=ref_audio_path,
+        x_vector_only_mode=True,
+    )
+
+    profile_id = uuid.uuid4().hex[:12]
+    with _cache_lock:
+        _PROFILE_CACHE[profile_id] = prompt_items
+
+    logger.info("Voice profile %s created.", profile_id)
+    return profile_id
+
+
+def synthesize_cloned(text: str, profile_id: str) -> tuple[np.ndarray, int]:
+    """
+    Synthesize text using a cached voice profile.
+    Returns (wav_array, sample_rate).
+    """
+    with _cache_lock:
+        prompt_items = _PROFILE_CACHE.get(profile_id)
+    if prompt_items is None:
+        raise ValueError(f"Voice profile '{profile_id}' not found. Record voice first.")
+
+    model = get_qwen_tts()
+
+    audio_list, sample_rate = model.generate_voice_clone(
+        text=text,
+        language="english",
+        voice_clone_prompt=prompt_items,
+    )
+
+    wav = np.concatenate(audio_list) if audio_list else np.zeros(0, dtype=np.float32)
+    return wav, sample_rate
+
+
+def synthesize_cloned_preview(profile_id: str) -> tuple[np.ndarray, int]:
+    """Short preview sentence to verify the clone sounds right."""
+    return synthesize_cloned(
+        "Hello! I'm ready to read a bedtime story for you tonight.",
+        profile_id,
+    )
+
+
+def has_profile(profile_id: str | None) -> bool:
+    """Check if a voice profile exists in cache."""
+    if not profile_id:
+        return False
+    with _cache_lock:
+        return profile_id in _PROFILE_CACHE