Upload folder using huggingface_hub

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 gentleman_icon.png filter=lfs diff=lfs merge=lfs -text
+demo.mp4 filter=lfs diff=lfs merge=lfs -text

demo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:22e6912378900da532d21c1400cfdd0592ae724b231602364ceeeae400210cf9
+size 792374

demo_video.py

@@ -0,0 +1,298 @@
+"""Talkie Gentleman Reachy Mini demo video.
+
+Split-screen: left = MuJoCo 3D robot, right = Victorian chat overlay.
+15 seconds, 720p, 24fps.
+
+Usage: GST_PLUGIN_SCANNER="" python3.13 demo_video.py
+"""
+import os, sys, math, subprocess
+from pathlib import Path
+
+os.environ["GST_PLUGIN_SCANNER"] = ""
+os.environ["GST_REGISTRY_UPDATE"] = "no"
+
+import mujoco
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+
+# --- Config ---
+SCENE_XML = Path(__file__).parent.parent / "reachy_mini/src/reachy_mini/descriptions/reachy_mini/mjcf/scenes/minimal.xml"
+OUTPUT_MP4 = Path(__file__).parent / "demo.mp4"
+TOTAL_W, TOTAL_H = 1280, 720
+ROBOT_W = TOTAL_W // 2  # 640
+CHAT_W = TOTAL_W - ROBOT_W
+FPS = 24
+TOTAL_DURATION = 15.0
+
+# Actuator indices
+YAW, S1, S2, S3, S4, S5, S6, R_ANT, L_ANT = 0, 1, 2, 3, 4, 5, 6, 7, 8
+
+# --- Chat content ---
+CHAT_EVENTS = [
+    # (start_time, role, text)
+    (0.5,  "header", "~ Talkie Gentleman ~"),
+    (1.0,  "user",   "Good evening, what are your\nthoughts on modern inventions?"),
+    (4.5,  "bot",    "Ah, a most splendid inquiry!\nThe telegraph astounds me —\nto send words across vast\ndistances in mere moments.\nTruly, we live in an age\nof marvels, dear friend."),
+    (9.0,  "user",   "What music do you enjoy?"),
+    (11.5, "bot",    "Beethoven, without question.\nHis symphonies stir the very\nsoul. The Moonlight Sonata\nis a masterwork of the\nhighest order."),
+]
+
+# --- Robot motion timeline ---
+# (start, end, gesture_name)
+GESTURES = [
+    # Idle breathing at start
+    (0.0,  1.0,  "idle"),
+    # Listen to first question - slight attentive tilt
+    (1.0,  2.5,  "attentive_listen"),
+    # Thinking head tilt before answering
+    (2.5,  4.5,  "thinking_tilt"),
+    # Speaking - gentle nods while responding
+    (4.5,  8.5,  "speaking_nods"),
+    # Brief return to neutral
+    (8.5,  9.0,  "idle"),
+    # Listen to second question
+    (9.0,  10.0, "attentive_listen"),
+    # Enthusiastic nod about Beethoven
+    (10.0, 11.5, "enthusiastic_think"),
+    # Speaking with conviction
+    (11.5, 14.5, "speaking_nods"),
+    # Elegant settle
+    (14.5, 15.0, "idle"),
+]
+
+
+def get_robot_pose(t: float) -> dict:
+    """Return target ctrl values for time t."""
+    gesture = "idle"
+    gesture_t = 0.0
+    for gs, ge, gn in GESTURES:
+        if gs <= t < ge:
+            gesture = gn
+            gesture_t = (t - gs) / max(0.01, ge - gs)  # normalized 0-1
+            break
+
+    ctrl = {YAW: 0, S1: 0, S2: 0, S3: 0, S4: 0, S5: 0, S6: 0, R_ANT: 0, L_ANT: 0}
+
+    if gesture == "idle":
+        # Gentle breathing - subtle vertical oscillation
+        breath = math.sin(t * 1.8) * 0.02
+        ctrl[S3] = breath
+        ctrl[R_ANT] = math.sin(t * 0.7) * 0.05
+        ctrl[L_ANT] = math.sin(t * 0.7 + 0.5) * 0.05
+
+    elif gesture == "attentive_listen":
+        # Gentle head tilt to the right, antenna perk
+        ease = math.sin(gesture_t * math.pi)  # smooth in-out
+        ctrl[S5] = math.radians(12) * ease   # roll tilt
+        ctrl[S4] = math.radians(-5) * ease   # slight pitch down (attentive)
+        ctrl[R_ANT] = 0.3 * ease
+        ctrl[L_ANT] = 0.15 * ease
+
+    elif gesture == "thinking_tilt":
+        # Head tilts left, one antenna raises - pondering
+        ease = min(1.0, gesture_t * 2.5)  # quick settle
+        hold = math.sin(gesture_t * math.pi * 0.8)
+        ctrl[S5] = math.radians(-15) * ease  # tilt left
+        ctrl[S4] = math.radians(8) * ease    # slight look up
+        ctrl[YAW] = math.radians(5) * ease   # slight turn
+        ctrl[R_ANT] = -0.2 * ease
+        ctrl[L_ANT] = 0.5 * ease  # one antenna raised = thinking
+        # Subtle micro-movement
+        ctrl[S4] += math.sin(t * 3) * 0.01
+
+    elif gesture == "speaking_nods":
+        # Gentle periodic nods with slight body sway
+        nod_cycle = math.sin(gesture_t * math.pi * 5)  # ~2.5 nods over the gesture
+        sway = math.sin(gesture_t * math.pi * 2) * 0.3
+        ctrl[S4] = math.radians(6) * nod_cycle   # pitch nod
+        ctrl[S5] = math.radians(3) * sway         # gentle roll sway
+        ctrl[YAW] = math.radians(2) * math.sin(gesture_t * math.pi * 1.5)
+        # Antennas follow speech rhythm
+        ctrl[R_ANT] = 0.2 * nod_cycle
+        ctrl[L_ANT] = 0.2 * nod_cycle
+        # Subtle vertical
+        ctrl[S3] = 0.01 * nod_cycle
+
+    elif gesture == "enthusiastic_think":
+        # More energetic thinking - tilt + antenna waggle
+        ease = min(1.0, gesture_t * 3)
+        ctrl[S5] = math.radians(10) * ease
+        ctrl[S4] = math.radians(10) * ease
+        ctrl[R_ANT] = 0.4 * math.sin(gesture_t * math.pi * 4)
+        ctrl[L_ANT] = 0.4 * math.cos(gesture_t * math.pi * 4)
+
+    return ctrl
+
+
+def render_chat_panel(t: float) -> Image.Image:
+    """Render the Victorian chat panel for time t."""
+    img = Image.new("RGB", (CHAT_W, TOTAL_H), (28, 22, 18))
+    draw = ImageDraw.Draw(img)
+
+    # Try to get a nice font, fall back to default
+    try:
+        font_title = ImageFont.truetype("/System/Library/Fonts/Supplemental/Times New Roman.ttf", 26)
+        font_msg = ImageFont.truetype("/System/Library/Fonts/Supplemental/Times New Roman.ttf", 18)
+        font_label = ImageFont.truetype("/System/Library/Fonts/Supplemental/Times New Roman.ttf", 14)
+    except:
+        font_title = ImageFont.load_default()
+        font_msg = font_title
+        font_label = font_title
+
+    # Colors
+    BG_DARK = (28, 22, 18)
+    GOLD = (198, 166, 100)
+    CREAM = (230, 218, 195)
+    USER_BG = (48, 40, 32)
+    BOT_BG = (42, 35, 28)
+    BORDER = (100, 82, 58)
+    DIM = (140, 120, 90)
+
+    # Ornamental border
+    draw.rectangle([0, 0, CHAT_W-1, TOTAL_H-1], outline=BORDER, width=2)
+    draw.rectangle([4, 4, CHAT_W-5, TOTAL_H-5], outline=(60, 50, 38), width=1)
+
+    # Decorative top line
+    draw.line([(20, 55), (CHAT_W-20, 55)], fill=BORDER, width=1)
+    # Small ornaments
+    draw.text((CHAT_W//2 - 10, 48), "◆", fill=GOLD, font=font_label)
+
+    y = 70
+    for evt_t, role, text in CHAT_EVENTS:
+        if t < evt_t:
+            break
+
+        if role == "header":
+            # Title
+            bbox = draw.textbbox((0, 0), text, font=font_title)
+            tw = bbox[2] - bbox[0]
+            draw.text(((CHAT_W - tw) // 2, 18), text, fill=GOLD, font=font_title)
+            continue
+
+        # Typewriter effect for messages appearing
+        elapsed = t - evt_t
+        chars_visible = int(elapsed * 35)  # 35 chars/sec typing speed
+        visible_text = text[:chars_visible]
+        if not visible_text:
+            continue
+
+        # Message bubble
+        margin = 15
+        pad = 10
+
+        if role == "user":
+            label = "You"
+            label_color = DIM
+            bg = USER_BG
+            text_color = CREAM
+        else:
+            label = "Gentleman"
+            label_color = GOLD
+            bg = BOT_BG
+            text_color = CREAM
+
+        # Label
+        draw.text((margin + 5, y), label, fill=label_color, font=font_label)
+        y += 18
+
+        # Calculate text height
+        bbox = draw.textbbox((0, 0), visible_text, font=font_msg)
+        th = bbox[3] - bbox[1]
+        tw = bbox[2] - bbox[0]
+
+        # Bubble background
+        bubble_h = th + pad * 2 + 4
+        draw.rounded_rectangle(
+            [margin, y, CHAT_W - margin, y + bubble_h],
+            radius=6, fill=bg, outline=BORDER
+        )
+
+        # Text
+        draw.text((margin + pad, y + pad), visible_text, fill=text_color, font=font_msg)
+
+        y += bubble_h + 12
+
+        # Typing indicator for bot messages still typing
+        if role == "bot" and chars_visible < len(text):
+            dots = "..." [:int((t * 3) % 4)]
+            draw.text((margin + pad, y - 5), f"✎ {dots}", fill=DIM, font=font_label)
+
+    # Bottom ornament
+    draw.line([(20, TOTAL_H - 25), (CHAT_W - 20, TOTAL_H - 25)], fill=BORDER, width=1)
+    draw.text((CHAT_W // 2 - 30, TOTAL_H - 20), "⚙ Anno 1842", fill=DIM, font=font_label)
+
+    return img
+
+
+def main():
+    print(f"Loading MuJoCo scene: {SCENE_XML}")
+    model = mujoco.MjModel.from_xml_path(str(SCENE_XML))
+    model.vis.global_.offwidth = ROBOT_W
+    model.vis.global_.offheight = TOTAL_H
+    data = mujoco.MjData(model)
+    renderer = mujoco.Renderer(model, TOTAL_H, ROBOT_W)
+
+    cam = mujoco.MjvCamera()
+    cam.type = mujoco.mjtCamera.mjCAMERA_FREE
+    cam.distance = 0.48
+    cam.azimuth = 175
+    cam.elevation = -8
+    cam.lookat[:] = [0, 0, 0.14]
+
+    stp = max(1, int(1.0 / (model.opt.timestep * FPS)))
+    n_frames = int(TOTAL_DURATION * FPS)
+
+    frames = []
+    print(f"Rendering {n_frames} frames ({TOTAL_DURATION:.0f}s @ {FPS}fps)...")
+
+    for i in range(n_frames):
+        t = i / FPS
+
+        # Set robot pose
+        pose = get_robot_pose(t)
+        for k, v in pose.items():
+            data.ctrl[k] = v
+
+        # Step physics
+        for _ in range(stp):
+            mujoco.mj_step(model, data)
+
+        # Render robot view
+        renderer.update_scene(data, cam)
+        robot_rgb = renderer.render().copy()  # (H, W, 3)
+
+        # Render chat panel
+        chat_img = render_chat_panel(t)
+        chat_rgb = np.array(chat_img)
+
+        # Composite split-screen
+        composite = np.concatenate([robot_rgb, chat_rgb], axis=1)
+        frames.append(composite)
+
+        if (i + 1) % (FPS * 3) == 0:
+            print(f"  {i+1}/{n_frames} frames...")
+
+    # Encode video
+    print(f"\nEncoding {len(frames)} frames to {OUTPUT_MP4}...")
+    proc = subprocess.Popen([
+        'ffmpeg', '-y', '-f', 'rawvideo', '-vcodec', 'rawvideo',
+        '-s', f'{TOTAL_W}x{TOTAL_H}', '-pix_fmt', 'rgb24', '-r', str(FPS),
+        '-i', '-', '-c:v', 'libx264', '-pix_fmt', 'yuv420p',
+        '-preset', 'fast', '-crf', '18', str(OUTPUT_MP4)
+    ], stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+
+    for frame in frames:
+        proc.stdin.write(frame.tobytes())
+    proc.stdin.close()
+    _, stderr = proc.communicate()
+
+    if proc.returncode == 0:
+        size = os.path.getsize(str(OUTPUT_MP4))
+        print(f"✅ {OUTPUT_MP4} ({size/1024:.0f}KB, {TOTAL_DURATION:.0f}s)")
+    else:
+        print(f"❌ ffmpeg error: {stderr.decode()[:500]}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

talkie_gentleman/main.py

@@ -9,6 +9,7 @@ A Victorian/Edwardian speaking robot using:
 
 import asyncio
 import logging
+import os
 import tempfile
 from pathlib import Path
 
@@ -16,6 +17,7 @@ from .stt_engine import transcribe
 from .talkie_inference import generate_response
 from .tts_engine import speak_british
 from .robot_behavior import GentlemanBehavior
+from .setup_wizard import SetupServer, get_setup_status, _read_key
 
 logger = logging.getLogger(__name__)
 
@@ -105,17 +107,44 @@ def main():
     """CLI entry point for testing."""
     import sys
 
+    # Always start setup wizard
+    setup = SetupServer(port=8889)
+    setup.start()
+
+    status = get_setup_status()
+    if not status["ready"]:
+        print("\n🎩 Talkie Gentleman — Setup Required")
+        print(f"   Open http://localhost:8889/setup to configure.\n")
+        if not status["hf_token_set"]:
+            print("   ❌ HuggingFace token not set")
+        if not status["piper_available"] and not status["elevenlabs_key_set"]:
+            print("   ❌ No voice engine available")
+        print()
+        # Keep alive for setup
+        import signal
+        signal.signal(signal.SIGINT, lambda *a: sys.exit(0))
+        signal.pause()
+        return
+
+    # Load saved keys into env
+    hf = _read_key("hf_token")
+    el = _read_key("elevenlabs_key")
+    if hf:
+        os.environ["HF_TOKEN"] = hf
+    if el:
+        os.environ["ELEVENLABS_API_KEY"] = el
+
     app = TalkieGentleman()
 
     if len(sys.argv) > 1:
         text = " ".join(sys.argv[1:])
         result = asyncio.run(app.process_text(text))
-        print(f"🎩 {result['response_text']}")
+        print(f"\n🎩 {result['response_text']}")
         print(f"🔊 Audio: {result['audio_path']}")
     else:
-        print("🎩 Talkie Gentleman — Victorian Conversationalist")
-        print("Usage: python -m talkie_gentleman 'Good evening, sir!'")
-
-
-if __name__ == "__main__":
-    main()
+        print("\n🎩 Talkie Gentleman — Victorian Conversationalist")
+        print(f"   Setup wizard: http://localhost:8889/setup")
+        print(f"   Usage: python -m talkie_gentleman 'Good evening, sir!'\n")
+        import signal
+        signal.signal(signal.SIGINT, lambda *a: sys.exit(0))
+        signal.pause()

talkie_gentleman/setup_wizard.py

@@ -0,0 +1,434 @@
+"""Setup wizard for Talkie Gentleman — guides users through HF Token + TTS setup."""
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+import threading
+import urllib.request
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+PIPER_VOICE_DIR = Path.home() / ".cache" / "talkie_gentleman" / "voices"
+PIPER_MODEL_NAME = "en_GB-alan-medium"
+PIPER_MODEL_URL = "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_GB/alan/medium/en_GB-alan-medium.onnx"
+PIPER_CONFIG_URL = "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_GB/alan/medium/en_GB-alan-medium.onnx.json"
+CONFIG_DIR = Path.home() / ".config" / "talkie_gentleman"
+
+SETUP_HTML = r"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Talkie Gentleman — Setup</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font-family: 'Inter', -apple-system, sans-serif; background: #0f0e17; color: #e0e0e0; min-height: 100vh; display: flex; align-items: center; justify-content: center; }
+.container { max-width: 900px; width: 100%; padding: 2rem; }
+h1 { font-size: 1.8rem; margin-bottom: 0.5rem; color: #c9a84c; }
+.subtitle { color: #888; margin-bottom: 2rem; }
+.main-layout { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; align-items: start; }
+.steps-col { display: flex; flex-direction: column; gap: 1rem; }
+@media (max-width: 700px) { .main-layout { grid-template-columns: 1fr; } }
+.step { background: #1a1825; border-radius: 12px; padding: 1.5rem; margin-bottom: 0rem; border: 1px solid #2d2b3a; }
+.step.done { border-color: #c9a84c; }
+.step.active { border-color: #7c5cfc; }
+.step.skip { opacity: 0.7; }
+.step-header { display: flex; align-items: center; gap: 0.75rem; margin-bottom: 0.5rem; }
+.step-num { width: 28px; height: 28px; border-radius: 50%; display: flex; align-items: center; justify-content: center; font-size: 0.85rem; font-weight: 600; background: #2d2b3a; }
+.done .step-num { background: #c9a84c; color: #000; }
+.active .step-num { background: #7c5cfc; color: #fff; }
+.step-title { font-weight: 600; }
+.step-body { margin-left: 2.5rem; color: #aaa; font-size: 0.9rem; line-height: 1.6; }
+button { background: #c9a84c; color: #000; border: none; padding: 0.7rem 1.5rem; border-radius: 8px; font-weight: 600; cursor: pointer; font-size: 0.9rem; margin-top: 0.75rem; }
+button:hover { background: #d4b45f; }
+button:disabled { background: #333; color: #666; cursor: not-allowed; }
+button.secondary { background: #2d2b3a; color: #e0e0e0; }
+button.secondary:hover { background: #3d3b4a; }
+.status { margin-top: 0.5rem; font-size: 0.85rem; padding: 0.5rem; border-radius: 6px; }
+.status.ok { background: rgba(201,168,76,0.15); color: #c9a84c; }
+.status.err { background: #ff444422; color: #ff6666; }
+.status.info { background: rgba(124,92,252,0.15); color: #9d7fff; }
+.input-row { display: flex; gap: 0.5rem; margin-top: 0.75rem; }
+.input-row input { flex: 1; background: #222; border: 1px solid #444; border-radius: 6px; padding: 0.5rem 0.75rem; color: #e0e0e0; font-size: 0.85rem; }
+a { color: #c9a84c; }
+code { background: rgba(201,168,76,0.15); color: #c9a84c; padding: 2px 6px; border-radius: 4px; font-size: 0.8rem; }
+.ready-banner { background: rgba(201,168,76,0.12); border: 1px solid #c9a84c; border-radius: 12px; padding: 2rem; text-align: center; display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 200px; }
+.ready-banner h2 { color: #c9a84c; margin-bottom: 0.5rem; font-size: 1.6rem; }
+.ready-banner p { color: #aaa; margin-bottom: 0.3rem; }
+.ready-banner .big { font-size: 1.1rem; color: #e0e0e0; margin-bottom: 0.5rem; }
+.spinner { display: inline-block; width: 16px; height: 16px; border: 2px solid #444; border-top-color: #c9a84c; border-radius: 50%; animation: spin 0.8s linear infinite; margin-right: 0.5rem; vertical-align: middle; }
+@keyframes spin { to { transform: rotate(360deg); } }
+</style>
+</head>
+<body>
+<div class="container">
+<h1>🎩 Talkie Gentleman — Setup</h1>
+<p class="subtitle">Get your Victorian robot companion ready in 3 steps</p>
+
+<div class="main-layout">
+<div class="steps-col">
+
+<div class="step active" id="step1">
+  <div class="step-header"><div class="step-num">1</div><span class="step-title">HuggingFace Token (required)</span></div>
+  <div class="step-body">
+    <p>The gentleman needs a HuggingFace token to think. It's free — create one at <a href="https://huggingface.co/settings/tokens" target="_blank">huggingface.co/settings/tokens</a> (read access is enough).</p>
+    <div class="input-row">
+      <input type="text" id="hf-token" placeholder="hf_xxxxxxxxxx...">
+      <button onclick="saveHfToken()">Save</button>
+    </div>
+    <div class="status" id="status-hf" style="display:none"></div>
+  </div>
+</div>
+
+<div class="step" id="step2">
+  <div class="step-header"><div class="step-num">2</div><span class="step-title">Voice engine</span></div>
+  <div class="step-body">
+    <p>The app auto-downloads a free British voice (Piper TTS, ~60MB) on first use. No setup needed.</p>
+    <p style="margin-top:0.5rem"><strong>Optional upgrade:</strong> For a premium natural voice, paste your <a href="https://elevenlabs.io/app/settings/api-keys" target="_blank">ElevenLabs API key</a> (free tier: 10K chars/month).</p>
+    <div class="input-row">
+      <input type="text" id="el-key" placeholder="sk_xxxxxxxxxx... (optional)">
+      <button class="secondary" onclick="saveElKey()">Save</button>
+    </div>
+    <div class="status" id="status-el" style="display:none"></div>
+    <button onclick="testVoice()" style="margin-top:0.5rem" class="secondary">🔊 Test voice</button>
+    <div class="status" id="status-voice" style="display:none"></div>
+  </div>
+</div>
+
+<div class="step" id="step3">
+  <div class="step-header"><div class="step-num">3</div><span class="step-title">Dependencies check</span></div>
+  <div class="step-body">
+    <p>Checking that everything needed is installed on this device...</p>
+    <button onclick="checkDeps()">Check dependencies</button>
+    <div class="status" id="status-deps" style="display:none"></div>
+  </div>
+</div>
+
+</div>
+
+<div class="ready-banner" id="ready-banner" style="display:none">
+  <h2>🎩 Ready, old chap!</h2>
+  <p class="big">Your gentleman is prepared to converse.</p>
+  <p>Speak to your Reachy Mini and enjoy a conversation from a century ago.</p>
+  <p id="voice-mode" style="margin-top:1rem; color:#c9a84c;"></p>
+</div>
+
+</div>
+</div>
+
+<script>
+async function api(endpoint, body) {
+  const r = await fetch('/api/' + endpoint, { method: 'POST', headers: {'Content-Type':'application/json'}, body: JSON.stringify(body || {}) });
+  return r.json();
+}
+
+function showStatus(id, cls, msg) {
+  const el = document.getElementById(id);
+  el.style.display = 'block';
+  el.className = 'status ' + cls;
+  el.innerHTML = msg;
+}
+
+function markStepDone(n) {
+  document.getElementById('step'+n).className = 'step done';
+}
+
+async function checkStatus() {
+  const data = await api('status');
+  if (data.hf_token_set) {
+    markStepDone(1);
+    document.getElementById('hf-token').value = '••••••••';
+    document.getElementById('hf-token').disabled = true;
+  }
+  if (data.elevenlabs_key_set) {
+    showStatus('status-el', 'ok', 'ElevenLabs key saved — premium voice active');
+  }
+  if (data.piper_available || data.elevenlabs_key_set) {
+    markStepDone(2);
+  }
+  if (data.ready) {
+    markStepDone(3);
+    showStatus('status-deps', 'ok', data.deps_detail || 'All dependencies OK');
+    document.getElementById('ready-banner').style.display = 'flex';
+    const mode = data.elevenlabs_key_set ? '🎙️ Premium voice (ElevenLabs Daniel)' : '🔊 Built-in British voice (Piper)';
+    document.getElementById('voice-mode').textContent = mode;
+  }
+}
+
+async function saveHfToken() {
+  const token = document.getElementById('hf-token').value.trim();
+  if (!token) return;
+  showStatus('status-hf', 'info', '<span class="spinner"></span> Verifying token...');
+  const r = await api('save_hf_token', { token });
+  if (r.success) {
+    showStatus('status-hf', 'ok', '✅ Token verified — ' + (r.username || 'authenticated'));
+    markStepDone(1);
+    document.getElementById('step2').className = 'step active';
+  } else {
+    showStatus('status-hf', 'err', '❌ ' + (r.error || 'Invalid token'));
+  }
+}
+
+async function saveElKey() {
+  const key = document.getElementById('el-key').value.trim();
+  if (!key) return;
+  showStatus('status-el', 'info', '<span class="spinner"></span> Verifying...');
+  const r = await api('save_el_key', { key });
+  if (r.success) {
+    showStatus('status-el', 'ok', '✅ ElevenLabs connected — premium voice active');
+    markStepDone(2);
+  } else {
+    showStatus('status-el', 'err', '❌ ' + (r.error || 'Invalid key'));
+  }
+}
+
+async function testVoice() {
+  showStatus('status-voice', 'info', '<span class="spinner"></span> Generating test audio...');
+  const r = await api('test_voice');
+  if (r.success) {
+    showStatus('status-voice', 'ok', '✅ Voice works! Engine: ' + (r.engine || 'unknown'));
+  } else {
+    showStatus('status-voice', 'err', '❌ ' + (r.error || 'Voice test failed'));
+  }
+}
+
+async function checkDeps() {
+  showStatus('status-deps', 'info', '<span class="spinner"></span> Checking and installing dependencies...');
+  const r = await api('check_deps');
+  if (r.success) {
+    showStatus('status-deps', 'ok', '✅ ' + r.detail);
+    markStepDone(3);
+    checkStatus();
+  } else {
+    showStatus('status-deps', 'err', '❌ ' + r.detail);
+  }
+}
+
+checkStatus();
+</script>
+</body>
+</html>"""
+
+
+def _config_path(name: str) -> Path:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    return CONFIG_DIR / name
+
+
+def _save_key(name: str, value: str):
+    path = _config_path(name)
+    path.write_text(value)
+    path.chmod(0o600)
+
+
+def _read_key(name: str) -> Optional[str]:
+    path = _config_path(name)
+    if path.exists():
+        v = path.read_text().strip()
+        return v if v else None
+    # Also check env
+    env_map = {"hf_token": "HF_TOKEN", "elevenlabs_key": "ELEVENLABS_API_KEY"}
+    return os.environ.get(env_map.get(name, ""), None)
+
+
+def _verify_hf_token(token: str) -> dict:
+    """Verify HF token by calling whoami endpoint."""
+    try:
+        req = urllib.request.Request(
+            "https://huggingface.co/api/whoami-v2",
+            headers={"Authorization": f"Bearer {token}"}
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+            return {"success": True, "username": data.get("name", "ok")}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def _verify_el_key(key: str) -> dict:
+    """Verify ElevenLabs key."""
+    try:
+        req = urllib.request.Request(
+            "https://api.elevenlabs.io/v1/voices",
+            headers={"xi-api-key": key}
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return {"success": True}
+    except Exception as e:
+        err = str(e)
+        if "401" in err or "403" in err:
+            return {"success": False, "error": "Invalid key or missing TTS permission"}
+        return {"success": False, "error": err}
+
+
+def _check_dependencies() -> dict:
+    """Check and try to install missing dependencies."""
+    results = []
+    all_ok = True
+
+    # Check piper or sag
+    has_sag = shutil.which("sag") is not None
+    has_piper = shutil.which("piper") is not None
+    el_key = _read_key("elevenlabs_key")
+
+    if has_sag and el_key:
+        results.append("TTS: ElevenLabs (sag) ✓")
+    elif has_piper:
+        results.append("TTS: Piper ✓")
+    else:
+        # Try to install piper
+        try:
+            subprocess.run(["pip3", "install", "piper-tts"], capture_output=True, timeout=120)
+            if shutil.which("piper"):
+                results.append("TTS: Piper installed ✓")
+            else:
+                results.append("TTS: Piper install failed ✗")
+                all_ok = False
+        except Exception:
+            results.append("TTS: No TTS engine available ✗")
+            all_ok = False
+
+    # Check piper voice
+    voice_path = PIPER_VOICE_DIR / f"{PIPER_MODEL_NAME}.onnx"
+    if not voice_path.exists() and not (has_sag and el_key):
+        try:
+            PIPER_VOICE_DIR.mkdir(parents=True, exist_ok=True)
+            urllib.request.urlretrieve(PIPER_MODEL_URL, str(voice_path))
+            config_path = PIPER_VOICE_DIR / f"{PIPER_MODEL_NAME}.onnx.json"
+            urllib.request.urlretrieve(PIPER_CONFIG_URL, str(config_path))
+            results.append("British voice: downloaded ✓")
+        except Exception as e:
+            results.append(f"British voice: download failed ✗ ({e})")
+            all_ok = False
+    elif voice_path.exists():
+        results.append("British voice: ready ✓")
+    else:
+        results.append("British voice: not needed (ElevenLabs active) ✓")
+
+    # HF token
+    hf = _read_key("hf_token")
+    if hf:
+        results.append("HF Token: set ✓")
+    else:
+        results.append("HF Token: missing ✗")
+        all_ok = False
+
+    return {"success": all_ok, "detail": " | ".join(results)}
+
+
+def _test_voice() -> dict:
+    """Generate a short test audio."""
+    try:
+        from talkie_gentleman.tts_engine import speak_british
+        # Temporarily set env vars from config
+        hf = _read_key("hf_token")
+        el = _read_key("elevenlabs_key")
+        if hf:
+            os.environ["HF_TOKEN"] = hf
+        if el:
+            os.environ["ELEVENLABS_API_KEY"] = el
+
+        path = speak_british("I say, what a pleasure to make your acquaintance.")
+        engine = "ElevenLabs" if el and shutil.which("sag") else "Piper"
+        return {"success": True, "engine": engine, "path": path}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def get_setup_status() -> dict:
+    hf = _read_key("hf_token")
+    el = _read_key("elevenlabs_key")
+    has_piper = shutil.which("piper") is not None
+    voice_exists = (PIPER_VOICE_DIR / f"{PIPER_MODEL_NAME}.onnx").exists()
+
+    tts_ok = (el and shutil.which("sag")) or has_piper or voice_exists
+    ready = bool(hf) and tts_ok
+
+    return {
+        "hf_token_set": bool(hf),
+        "elevenlabs_key_set": bool(el),
+        "piper_available": has_piper or voice_exists,
+        "ready": ready,
+    }
+
+
+class SetupHandler(BaseHTTPRequestHandler):
+    def do_GET(self):
+        if self.path in ("/", "/setup"):
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(SETUP_HTML.encode())
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def do_POST(self):
+        content_len = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(content_len)) if content_len else {}
+
+        result = {}
+        if self.path == "/api/status":
+            result = get_setup_status()
+        elif self.path == "/api/save_hf_token":
+            token = body.get("token", "").strip()
+            if not token:
+                result = {"success": False, "error": "Token is empty"}
+            else:
+                verify = _verify_hf_token(token)
+                if verify["success"]:
+                    _save_key("hf_token", token)
+                    os.environ["HF_TOKEN"] = token
+                    result = verify
+                else:
+                    result = verify
+        elif self.path == "/api/save_el_key":
+            key = body.get("key", "").strip()
+            if not key:
+                result = {"success": False, "error": "Key is empty"}
+            else:
+                verify = _verify_el_key(key)
+                if verify["success"]:
+                    _save_key("elevenlabs_key", key)
+                    os.environ["ELEVENLABS_API_KEY"] = key
+                    result = verify
+                else:
+                    result = verify
+        elif self.path == "/api/test_voice":
+            result = _test_voice()
+        elif self.path == "/api/check_deps":
+            result = _check_dependencies()
+        else:
+            self.send_response(404)
+            self.end_headers()
+            return
+
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(result).encode())
+
+    def log_message(self, format, *args):
+        logger.debug(f"Setup: {args[0]}")
+
+
+class SetupServer:
+    def __init__(self, port: int = 8889):
+        self.port = port
+        self._server: Optional[HTTPServer] = None
+        self._thread: Optional[threading.Thread] = None
+
+    def start(self):
+        self._server = HTTPServer(("0.0.0.0", self.port), SetupHandler)
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+        logger.info(f"Setup wizard at http://localhost:{self.port}/setup")
+
+    def stop(self):
+        if self._server:
+            self._server.shutdown()