feat: add browser tts and conversation pacing

app.py

@@ -1,4 +1,5 @@
 from html import escape
+import json
 import os
 from time import sleep
 
@@ -43,7 +44,7 @@ EMPTY_STAGE = """
 </div>
 """
 
-EMPTY_TRANSCRIPT = "No show yet. The transcript will appear here."
+EMPTY_TRANSCRIPT = '<div class="conversation-empty">No show yet. The transcript will appear here.</div>'
 EMPTY_AGENT_STATE = "<div class=\"agent-state-empty\">No agents on stage yet.</div>"
 EMPTY_DIRECTOR_LOG = "No director notes yet."
 EMPTY_TRACE = "No trace events yet."
@@ -80,7 +81,16 @@ OPENBMB_MODEL_ID = os.getenv("OPENBMB_MODEL_ID", DEFAULT_OPENBMB_MODEL_ID)
 HF_API_MODEL_ID = os.getenv("HF_API_MODEL_ID", DEFAULT_HF_API_MODEL_ID)
 DEFAULT_MAX_NEW_TOKENS = 120
 DEFAULT_TEMPERATURE = 0.75
-PLAYBACK_DELAY_SECONDS = 0.75
+MIN_PLAYBACK_DELAY_SECONDS = 0.55
+MAX_PLAYBACK_DELAY_SECONDS = 1.85
+VOICE_MODE_CHOICES = [
+    ("Off", "off"),
+    ("Browser TTS: Character Voices", "character"),
+    ("Browser TTS: Narrator Only", "narrator"),
+]
+DEFAULT_VOICE_MODE = "off"
+EMPTY_TTS_PAYLOAD = "{}"
+EMPTY_TTS_STATUS = "Voice mode is off."
 SHOW_LENGTH_CHOICES = [
     ("Short", "short"),
     ("Standard", "standard"),
@@ -110,6 +120,51 @@ DEFAULT_STAGE_PROPS: list[str] = [
     "scroll",
 ]
 
+VOICE_STYLE_PRESETS = [
+    {
+        "label": "Warm Puppet",
+        "pitch": 1.04,
+        "rate": 0.96,
+        "volume": 0.9,
+        "voiceNameHints": ["Google US English", "Samantha", "Jenny", "Aria"],
+    },
+    {
+        "label": "Tiny Mischief",
+        "pitch": 1.14,
+        "rate": 0.98,
+        "volume": 0.88,
+        "voiceNameHints": ["Google UK English Female", "Samantha", "Jenny", "Aria"],
+    },
+    {
+        "label": "Grumpy Elder",
+        "pitch": 0.92,
+        "rate": 0.9,
+        "volume": 0.9,
+        "voiceNameHints": ["Daniel", "Alex", "Google UK English Male", "Microsoft Guy"],
+    },
+    {
+        "label": "Bright Hero",
+        "pitch": 1.02,
+        "rate": 1.02,
+        "volume": 0.9,
+        "voiceNameHints": ["Google US English", "Microsoft David", "Microsoft Mark", "Alex"],
+    },
+    {
+        "label": "Soft Oracle",
+        "pitch": 0.98,
+        "rate": 0.86,
+        "volume": 0.82,
+        "voiceNameHints": ["Google UK English Female", "Microsoft Zira", "Samantha", "Aria"],
+    },
+]
+NARRATOR_VOICE_STYLE = {
+    "label": "Narrator",
+    "pitch": 0.96,
+    "rate": 0.88,
+    "volume": 0.82,
+    "voiceNameHints": ["Daniel", "Alex", "Google UK English Male", "Microsoft Guy", "Google US English"],
+}
+
 
 def _prop_dropdown_label(canonical: str) -> str:
     emoji = PROP_EMOJI.get(canonical.lower(), "🎁")
@@ -121,6 +176,49 @@ PROP_DROPDOWN_CHOICES: list[tuple[str, str]] = [
     (_prop_dropdown_label(name), name) for name in DEFAULT_STAGE_PROPS
 ]
 
+
+def voice_style_for_actor(session: TheaterSession, speaker_name: str) -> dict[str, object]:
+    for index, actor in enumerate(session.actors):
+        if actor.name == speaker_name:
+            return dict(VOICE_STYLE_PRESETS[index % len(VOICE_STYLE_PRESETS)])
+    return dict(NARRATOR_VOICE_STYLE)
+
+
+def latest_tts_payload(session: TheaterSession | None) -> str:
+    if session is None or not session.transcript:
+        return EMPTY_TTS_PAYLOAD
+
+    latest_beat = session.transcript[-1]
+    latest_tool = session.latest_tool_result
+    if latest_tool is not None and latest_beat.tool_request is not None and latest_tool.actor_name == latest_beat.speaker:
+        payload = {
+            "id": f"{session.session_id}:{len(session.transcript)}:tool:{latest_tool.tool_name}",
+            "kind": "tool",
+            "speaker": "Stage Oracle",
+            "text": latest_tool.result,
+            "style": NARRATOR_VOICE_STYLE,
+            "narratorStyle": NARRATOR_VOICE_STYLE,
+        }
+    else:
+        payload = {
+            "id": f"{session.session_id}:{len(session.transcript)}:actor:{latest_beat.speaker}",
+            "kind": "actor",
+            "speaker": latest_beat.speaker,
+            "text": latest_beat.line,
+            "style": voice_style_for_actor(session, latest_beat.speaker),
+            "narratorStyle": NARRATOR_VOICE_STYLE,
+        }
+    return json.dumps(payload, ensure_ascii=True)
+
+
+def playback_delay_for_latest_line(session: TheaterSession) -> float:
+    if not session.transcript:
+        return MIN_PLAYBACK_DELAY_SECONDS
+    latest = session.transcript[-1].line
+    word_count = len(latest.split())
+    delay = 0.65 + (word_count * 0.28)
+    return max(MIN_PLAYBACK_DELAY_SECONDS, min(4.25, delay))
+
 CUSTOM_CSS = """
 body,
 .gradio-container {
@@ -1021,6 +1119,63 @@ body,
     border: none !important;
     box-shadow: none !important;
 }
+.conversation-empty {
+    color: #cbb7a1;
+    font-size: 0.88rem;
+    padding: 0.45rem 0.2rem;
+}
+.conversation-transcript {
+    display: grid;
+    gap: 0.38rem;
+    padding: 0.15rem 0;
+}
+.conversation-turn {
+    max-width: min(42rem, 84%);
+}
+.conversation-turn.speaker-changed {
+    margin-top: 0.42rem;
+}
+.conversation-turn.same-speaker {
+    margin-top: 0.04rem;
+}
+.conversation-turn:nth-child(even) {
+    justify-self: end;
+}
+.conversation-speaker {
+    color: #ffd166;
+    font-size: 0.68rem;
+    font-weight: 800;
+    letter-spacing: 0.07em;
+    margin: 0 0 0.12rem 0.18rem;
+    text-transform: uppercase;
+}
+.conversation-bubble {
+    background: rgba(10, 12, 23, 0.88);
+    border: 1px solid rgba(246, 196, 83, 0.24);
+    border-radius: 11px;
+    box-shadow: 0 8px 22px rgba(0, 0, 0, 0.24);
+    color: #f8efe4;
+    font-size: 0.9rem;
+    line-height: 1.38;
+    padding: 0.54rem 0.68rem;
+    overflow-wrap: anywhere;
+}
+.conversation-turn.latest .conversation-bubble {
+    background: rgba(246, 196, 83, 0.13);
+    border-color: rgba(246, 196, 83, 0.52);
+    box-shadow:
+        0 0 0 1px rgba(246, 196, 83, 0.14),
+        0 10px 24px rgba(0, 0, 0, 0.28);
+}
+.voice-status {
+    color: #cbb7a1;
+    font-size: 0.8rem;
+    min-height: 1.2rem;
+    padding: 0.15rem 0.05rem 0;
+}
+.voice-status strong {
+    color: #ffd166;
+}
 .agent-state-grid {
     display: grid;
     gap: 0.55rem;
@@ -1538,6 +1693,268 @@ THEATER_THEME = gr.themes.Soft(
 )
 
 
+BROWSER_TTS_JS = r"""
+async (mode, payloadJson, previewKind = "", options = {}) => {
+  const root = globalThis;
+  const speech = root.speechSynthesis;
+  root.aiPuppetSpeech = root.aiPuppetSpeech || {
+    lastAutoId: null,
+    voices: [],
+    voicesReady: false,
+    queue: [],
+    speaking: false,
+  };
+  root.aiPuppetSpeech.voices = Array.isArray(root.aiPuppetSpeech.voices) ? root.aiPuppetSpeech.voices : [];
+  root.aiPuppetSpeech.queue = Array.isArray(root.aiPuppetSpeech.queue) ? root.aiPuppetSpeech.queue : [];
+  root.aiPuppetSpeech.voicesReady = Boolean(root.aiPuppetSpeech.voicesReady);
+  root.aiPuppetSpeech.speaking = Boolean(root.aiPuppetSpeech.speaking);
+  const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (char) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+  })[char]);
+  if (mode === "off") {
+    if (speech) {
+      root.aiPuppetSpeech.queue = [];
+      root.aiPuppetSpeech.speaking = false;
+      speech.cancel();
+    }
+    return '<div class="voice-status">Voice mode is off.</div>';
+  }
+  if (!("speechSynthesis" in root) || typeof SpeechSynthesisUtterance === "undefined") {
+    return '<div class="voice-status"><strong>Browser TTS unavailable.</strong> The show still works without voice.</div>';
+  }
+
+  const cleanSpokenText = (value) => {
+    return String(value || "")
+      .replace(/\[[^\]]{1,140}\]/g, " ")
+      .replace(/\*[^*]{1,140}\*/g, " ")
+      .replace(/\([^)]{1,90}\)/g, " ")
+      .replace(/[\u{1F000}-\u{1FAFF}\u{2600}-\u{27BF}]/gu, " ")
+      .replace(/\s+/g, " ")
+      .trim();
+  };
+  const loadVoices = () => new Promise((resolve) => {
+    const current = speech.getVoices ? speech.getVoices() : [];
+    if (current.length > 0) {
+      root.aiPuppetSpeech.voices = current;
+      root.aiPuppetSpeech.voicesReady = true;
+      resolve(current);
+      return;
+    }
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      const voices = speech.getVoices ? speech.getVoices() : [];
+      root.aiPuppetSpeech.voices = voices;
+      root.aiPuppetSpeech.voicesReady = voices.length > 0;
+      resolve(voices);
+    };
+    speech.onvoiceschanged = () => finish();
+    setTimeout(finish, 700);
+  });
+  const selectVoice = (voices, style) => {
+    if (!voices || voices.length === 0) return null;
+    const hints = (style.voiceNameHints || []).map((hint) => String(hint).toLowerCase());
+    const byHint = voices.find((candidate) => {
+      const name = String(candidate.name || "").toLowerCase();
+      return hints.some((hint) => name.includes(hint) || hint.includes(name));
+    });
+    if (byHint) return byHint;
+    const english = voices.find((candidate) => {
+      const lang = String(candidate.lang || "").toLowerCase();
+      const name = String(candidate.name || "").toLowerCase();
+      return lang.startsWith("en") || name.includes("english");
+    });
+    if (english) return english;
+    const anyVoice = voices[0] || null;
+    if (anyVoice) return anyVoice;
+    if (Number.isInteger(style.voiceIndex) && voices.length > 0) {
+      return voices[Math.abs(style.voiceIndex) % voices.length] || null;
+    }
+    return null;
+  };
+  const payloadFromJson = () => {
+    try {
+      return JSON.parse(payloadJson || "{}");
+    } catch (_error) {
+      return null;
+    }
+  };
+  const buildTask = (payload) => {
+    const narratorStyle = payload.narratorStyle || payload.style || {};
+    const activeStyle = mode === "narrator" || previewKind === "narrator"
+      ? narratorStyle
+      : (payload.style || narratorStyle);
+    let text = payload.text;
+    let speaker = payload.speaker ? String(payload.speaker) : "Latest line";
+    if (previewKind === "actor") {
+      text = `Previewing ${activeStyle.label || "character voice"}. The puppet voice is softer now.`;
+      speaker = activeStyle.label || "Actor voice";
+    } else if (previewKind === "narrator") {
+      text = "Previewing narrator voice. The curtain rises, and the scene begins.";
+      speaker = activeStyle.label || "Narrator";
+    } else if (mode === "narrator") {
+      speaker = "Narrator";
+    }
+    text = cleanSpokenText(text);
+    return { id: payload.id || `${Date.now()}:${speaker}`, text, speaker, style: activeStyle };
+  };
+  const updateStatus = (html) => {
+    const status = document.querySelector(".voice-status");
+    if (status) status.outerHTML = html;
+  };
+  const drainQueue = async () => {
+    if (root.aiPuppetSpeech.speaking || root.aiPuppetSpeech.queue.length === 0) return;
+    const task = root.aiPuppetSpeech.queue.shift();
+    try {
+      const voices = await loadVoices();
+      const utterance = new SpeechSynthesisUtterance(task.text);
+      utterance.pitch = Math.max(0.1, Math.min(2, Number(task.style.pitch ?? 1)));
+      utterance.rate = Math.max(0.1, Math.min(2, Number(task.style.rate ?? 1)));
+      utterance.volume = Math.max(0, Math.min(1, Number(task.style.volume ?? 1)));
+      const voice = selectVoice(voices, task.style);
+      if (voice) utterance.voice = voice;
+      const label = task.style.label ? ` (${escapeHtml(task.style.label)})` : "";
+      const statusHtml = `<div class="voice-status">Speaking: <strong>${escapeHtml(task.speaker)}</strong>${label}</div>`;
+      root.aiPuppetSpeech.speaking = true;
+      updateStatus(statusHtml);
+      utterance.onend = () => {
+        root.aiPuppetSpeech.speaking = false;
+        drainQueue();
+      };
+      utterance.onerror = () => {
+        root.aiPuppetSpeech.speaking = false;
+        drainQueue();
+      };
+      speech.speak(utterance);
+    } catch (error) {
+      root.aiPuppetSpeech.speaking = false;
+      updateStatus('<div class="voice-status"><strong>Browser TTS could not start.</strong> Try Speak Latest Line once, then run the show again.</div>');
+    }
+  };
+
+  const payload = payloadFromJson();
+  if (!payload) {
+    return '<div class="voice-status">No speakable line is ready yet.</div>';
+  }
+  const task = buildTask(payload);
+  if (!task.text) {
+    return '<div class="voice-status">No speakable line is ready yet.</div>';
+  }
+
+  if (!options.queue) {
+    root.aiPuppetSpeech.queue = [];
+    root.aiPuppetSpeech.speaking = false;
+    speech.cancel();
+  }
+  root.aiPuppetSpeech.queue.push(task);
+  drainQueue();
+  const label = task.style.label ? ` (${escapeHtml(task.style.label)})` : "";
+  const prefix = options.queue && root.aiPuppetSpeech.speaking ? "Queued" : "Speaking";
+  return `<div class="voice-status">${prefix}: <strong>${escapeHtml(task.speaker)}</strong>${label}</div>`;
+}
+"""
+
+
+AUTO_BROWSER_TTS_JS = r"""
+async (mode, autoSpeak, payloadJson) => {
+  const root = globalThis;
+  root.aiPuppetSpeech = root.aiPuppetSpeech || {};
+  root.aiPuppetSpeech.lastAutoId = root.aiPuppetSpeech.lastAutoId || null;
+  root.aiPuppetSpeech.voices = Array.isArray(root.aiPuppetSpeech.voices) ? root.aiPuppetSpeech.voices : [];
+  root.aiPuppetSpeech.queue = Array.isArray(root.aiPuppetSpeech.queue) ? root.aiPuppetSpeech.queue : [];
+  root.aiPuppetSpeech.voicesReady = Boolean(root.aiPuppetSpeech.voicesReady);
+  root.aiPuppetSpeech.speaking = Boolean(root.aiPuppetSpeech.speaking);
+  const speech = root.speechSynthesis;
+  try {
+    if (mode === "off") {
+      if (speech) speech.cancel();
+      return '<div class="voice-status">Voice mode is off.</div>';
+    }
+    if (!autoSpeak) {
+      return '<div class="voice-status">Auto-speak is off. Use Speak Latest Line to replay.</div>';
+    }
+    let payload = {};
+    try {
+      payload = JSON.parse(payloadJson || "{}");
+    } catch (_error) {
+      return '<div class="voice-status">No speakable line is ready yet.</div>';
+    }
+    if (!payload.id || root.aiPuppetSpeech.lastAutoId === payload.id) {
+      return '<div class="voice-status">Browser TTS is ready.</div>';
+    }
+    root.aiPuppetSpeech.lastAutoId = payload.id;
+    const speakLatest = %s;
+    return await speakLatest(mode, payloadJson, "", { queue: true });
+  } catch (error) {
+    const detail = error && error.message ? String(error.message) : String(error || "unknown error");
+    const safeDetail = detail.replace(/[&<>"']/g, (char) => ({
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;",
+    })[char]);
+    return `<div class="voice-status"><strong>Auto-speak could not start.</strong> ${safeDetail}</div>`;
+  }
+}
+""" % BROWSER_TTS_JS
+
+
+REGISTER_BROWSER_TTS_JS = r"""
+() => {
+  globalThis.aiPuppetSpeakLatest = %s;
+  if ("speechSynthesis" in globalThis && globalThis.speechSynthesis.getVoices) {
+    globalThis.aiPuppetSpeech = globalThis.aiPuppetSpeech || {};
+    globalThis.aiPuppetSpeech.lastAutoId = globalThis.aiPuppetSpeech.lastAutoId || null;
+    globalThis.aiPuppetSpeech.voices = Array.isArray(globalThis.aiPuppetSpeech.voices) ? globalThis.aiPuppetSpeech.voices : [];
+    globalThis.aiPuppetSpeech.queue = Array.isArray(globalThis.aiPuppetSpeech.queue) ? globalThis.aiPuppetSpeech.queue : [];
+    globalThis.aiPuppetSpeech.voicesReady = Boolean(globalThis.aiPuppetSpeech.voicesReady);
+    globalThis.aiPuppetSpeech.speaking = Boolean(globalThis.aiPuppetSpeech.speaking);
+    const load = () => {
+      const voices = globalThis.speechSynthesis.getVoices();
+      globalThis.aiPuppetSpeech.voices = voices;
+      globalThis.aiPuppetSpeech.voicesReady = voices.length > 0;
+    };
+    globalThis.speechSynthesis.onvoiceschanged = load;
+    load();
+  }
+  globalThis.aiPuppetStopSpeaking = () => {
+    if ("speechSynthesis" in globalThis) {
+      globalThis.aiPuppetSpeech = globalThis.aiPuppetSpeech || {};
+      globalThis.aiPuppetSpeech.queue = [];
+      globalThis.aiPuppetSpeech.speaking = false;
+      globalThis.speechSynthesis.cancel();
+      return '<div class="voice-status">Speech stopped.</div>';
+    }
+    return '<div class="voice-status"><strong>Browser TTS unavailable.</strong> The show still works without voice.</div>';
+  };
+  return '<div class="voice-status">Voice mode is off.</div>';
+}
+""" % BROWSER_TTS_JS
+
+
+STOP_SPEAKING_JS = r"""
+() => {
+  if (globalThis.aiPuppetStopSpeaking) {
+    return globalThis.aiPuppetStopSpeaking();
+  }
+  if ("speechSynthesis" in globalThis) {
+    globalThis.aiPuppetSpeech = globalThis.aiPuppetSpeech || {};
+    globalThis.aiPuppetSpeech.queue = [];
+    globalThis.aiPuppetSpeech.speaking = false;
+    globalThis.speechSynthesis.cancel();
+    return '<div class="voice-status">Speech stopped.</div>';
+  }
+  return '<div class="voice-status"><strong>Browser TTS unavailable.</strong> The show still works without voice.</div>';
+}
+"""
+
+
 def render_stage(session: TheaterSession | None) -> str:
     if session is None:
         return EMPTY_STAGE
@@ -1645,16 +2062,27 @@ def render_transcript(session: TheaterSession | None) -> str:
     if session is None:
         return EMPTY_TRANSCRIPT
 
-    transcript_lines = [
-        "Transcript:",
-        "No puppet lines yet. The first beat will be added in the next milestone.",
-    ]
-    if session.transcript:
-        transcript_lines = ["Transcript:"]
-        for index, beat in enumerate(session.transcript, start=1):
-            transcript_lines.append(f"{index}. {beat.speaker}: {beat.line}")
+    if not session.transcript:
+        return '<div class="conversation-empty">No puppet lines yet. Run one beat to start the scene.</div>'
+
+    turns: list[str] = []
+    previous_speaker: str | None = None
+    latest_index = len(session.transcript)
+    for index, beat in enumerate(session.transcript, start=1):
+        speaker_changed = previous_speaker is not None and previous_speaker != beat.speaker
+        gap_class = "speaker-changed" if speaker_changed else "same-speaker"
+        latest_class = " latest" if index == latest_index else ""
+        turns.append(
+            f"""
+            <div class="conversation-turn {gap_class}{latest_class}">
+              <div class="conversation-speaker">{escape(beat.speaker)}</div>
+              <div class="conversation-bubble">{escape(beat.line)}</div>
+            </div>
+            """
+        )
+        previous_speaker = beat.speaker
 
-    return "\n".join(transcript_lines)
+    return f'<div class="conversation-transcript">{"".join(turns)}</div>'
 
 
 def render_agent_state(session: TheaterSession | None) -> str:
@@ -1807,6 +2235,7 @@ def render_outputs(session: TheaterSession | None):
     return (
         render_stage(session),
         render_transcript(session),
+        latest_tts_payload(session),
         render_agent_state(session),
         render_director_log(session),
         render_trace(session),
@@ -1835,6 +2264,7 @@ def create_show(
             None,
             EMPTY_STAGE,
             "No premise yet. Add a premise to raise the curtain.",
+            EMPTY_TTS_PAYLOAD,
             EMPTY_AGENT_STATE,
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
@@ -1874,6 +2304,7 @@ def reset_show():
         "",
         EMPTY_STAGE,
         EMPTY_TRANSCRIPT,
+        EMPTY_TTS_PAYLOAD,
         EMPTY_AGENT_STATE,
         EMPTY_DIRECTOR_LOG,
         EMPTY_TRACE,
@@ -1884,6 +2315,9 @@ def reset_show():
         DEFAULT_MAX_NEW_TOKENS,
         DEFAULT_TEMPERATURE,
         True,
+        DEFAULT_VOICE_MODE,
+        True,
+        EMPTY_TTS_STATUS,
         EMPTY_BACKEND,
     )
 
@@ -1900,6 +2334,7 @@ def advance_one_beat(
             None,
             EMPTY_STAGE,
             "Create a show before running a beat.",
+            EMPTY_TTS_PAYLOAD,
             EMPTY_AGENT_STATE,
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
@@ -1925,6 +2360,7 @@ def advance_full_act(
             None,
             EMPTY_STAGE,
             "Create a show before running the full act.",
+            EMPTY_TTS_PAYLOAD,
             EMPTY_AGENT_STATE,
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
@@ -1974,7 +2410,7 @@ def advance_full_act(
             session.director_mode = selected_director_mode
         yield session, *render_outputs(session)
         if session.beat_index < session.max_beats:
-            sleep(PLAYBACK_DELAY_SECONDS)
+            sleep(playback_delay_for_latest_line(session))
 
 
 def throw_audience_prop(
@@ -1990,6 +2426,7 @@ def throw_audience_prop(
             None,
             EMPTY_STAGE,
             "Create a show before throwing a prop.",
+            EMPTY_TTS_PAYLOAD,
             EMPTY_AGENT_STATE,
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
@@ -2015,6 +2452,7 @@ def summon_audience_actor(
             None,
             EMPTY_STAGE,
             "Create a show before summoning an actor.",
+            EMPTY_TTS_PAYLOAD,
             EMPTY_AGENT_STATE,
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
@@ -2039,6 +2477,7 @@ def request_audience_finale(
             None,
             EMPTY_STAGE,
             "Create a show before requesting a finale.",
+            EMPTY_TTS_PAYLOAD,
             EMPTY_AGENT_STATE,
             EMPTY_DIRECTOR_LOG,
             EMPTY_TRACE,
@@ -2133,6 +2572,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
                 reset_button = gr.Button("Reset", elem_classes=["reset-action"])
 
     stage_output = gr.HTML(value=EMPTY_STAGE, label="Stage", elem_classes=["stage-output"])
+    latest_tts_payload_output = gr.Textbox(value=EMPTY_TTS_PAYLOAD, visible=False)
 
     with gr.Column(elem_classes=["backstage-stack"]):
         with gr.Group(elem_classes=["control-panel"]):
@@ -2145,6 +2585,31 @@ with gr.Blocks(title="AI Puppet Theater") as app:
                 )
                 run_full_button = gr.Button("Run Full Act", elem_classes=["cue-action"])
 
+        with gr.Group(elem_classes=["control-panel"]):
+            gr.Markdown("### Voice", elem_classes=["show-controls-title", "panel-heading"])
+            voice_mode_select = gr.Radio(
+                choices=VOICE_MODE_CHOICES,
+                value=DEFAULT_VOICE_MODE,
+                label="Voice Mode",
+                interactive=True,
+            )
+            auto_speak_checkbox = gr.Checkbox(
+                value=True,
+                label="Auto-speak latest line",
+                interactive=True,
+            )
+            with gr.Row():
+                speak_latest_button = gr.Button("Speak Latest Line", elem_classes=["cue-action"])
+                stop_speaking_button = gr.Button("Stop Speaking", elem_classes=["reset-action"])
+            with gr.Row():
+                preview_actor_voice_button = gr.Button("Preview Actor Voice", elem_classes=["cue-action"])
+                preview_narrator_voice_button = gr.Button("Preview Narrator Voice", elem_classes=["cue-action"])
+            tts_status_output = gr.HTML(
+                value=f'<div class="voice-status">{EMPTY_TTS_STATUS}</div>',
+                label="Voice Status",
+                elem_classes=["no-field-label"],
+            )
+
         with gr.Group(elem_classes=["control-panel"]):
             gr.Markdown("### Audience", elem_classes=["audience-title", "panel-heading"])
             prop_input = gr.Dropdown(
@@ -2172,11 +2637,9 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             )
 
     with gr.Accordion("Transcript", open=False, elem_classes=["transcript-section"]):
-        transcript_output = gr.Textbox(
+        transcript_output = gr.HTML(
             value=EMPTY_TRANSCRIPT,
             label="Transcript",
-            lines=7,
-            interactive=False,
             elem_classes=["transcript-box", "no-field-label"],
         )
     with gr.Accordion("Agent State", open=False):
@@ -2250,7 +2713,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             elem_classes=["no-field-label"],
         )
 
-    create_button.click(
+    create_event = create_button.click(
         create_show,
         inputs=[
             premise_input,
@@ -2265,6 +2728,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             session_state,
             stage_output,
             transcript_output,
+            latest_tts_payload_output,
             agent_state_output,
             director_output,
             trace_output,
@@ -2272,7 +2736,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             backend_output,
         ],
     )
-    run_one_button.click(
+    run_one_event = run_one_button.click(
         advance_one_beat,
         inputs=[
             session_state,
@@ -2285,6 +2749,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             session_state,
             stage_output,
             transcript_output,
+            latest_tts_payload_output,
             agent_state_output,
             director_output,
             trace_output,
@@ -2292,7 +2757,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             backend_output,
         ],
     )
-    run_full_button.click(
+    run_full_event = run_full_button.click(
         advance_full_act,
         inputs=[
             session_state,
@@ -2306,6 +2771,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             session_state,
             stage_output,
             transcript_output,
+            latest_tts_payload_output,
             agent_state_output,
             director_output,
             trace_output,
@@ -2313,7 +2779,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             backend_output,
         ],
     )
-    throw_prop_button.click(
+    throw_prop_event = throw_prop_button.click(
         throw_audience_prop,
         inputs=[
             session_state,
@@ -2327,6 +2793,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             session_state,
             stage_output,
             transcript_output,
+            latest_tts_payload_output,
             agent_state_output,
             director_output,
             trace_output,
@@ -2334,7 +2801,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             backend_output,
         ],
     )
-    summon_actor_button.click(
+    summon_actor_event = summon_actor_button.click(
         summon_audience_actor,
         inputs=[
             session_state,
@@ -2348,6 +2815,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             session_state,
             stage_output,
             transcript_output,
+            latest_tts_payload_output,
             agent_state_output,
             director_output,
             trace_output,
@@ -2355,7 +2823,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             backend_output,
         ],
     )
-    request_finale_button.click(
+    request_finale_event = request_finale_button.click(
         request_audience_finale,
         inputs=[
             session_state,
@@ -2368,6 +2836,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             session_state,
             stage_output,
             transcript_output,
+            latest_tts_payload_output,
             agent_state_output,
             director_output,
             trace_output,
@@ -2389,6 +2858,7 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             actor_input,
             stage_output,
             transcript_output,
+            latest_tts_payload_output,
             agent_state_output,
             director_output,
             trace_output,
@@ -2399,9 +2869,163 @@ with gr.Blocks(title="AI Puppet Theater") as app:
             max_new_tokens_input,
             temperature_input,
             deterministic_full_act_input,
+            voice_mode_select,
+            auto_speak_checkbox,
+            tts_status_output,
             backend_output,
         ],
     )
+    app.load(
+        None,
+        outputs=[tts_status_output],
+        js=REGISTER_BROWSER_TTS_JS,
+    )
+    voice_mode_select.change(
+        None,
+        inputs=[voice_mode_select],
+        outputs=[tts_status_output],
+        js=r"""
+        (mode) => {
+          if (mode !== "off") {
+            if (!("speechSynthesis" in globalThis) || typeof SpeechSynthesisUtterance === "undefined") {
+              return '<div class="voice-status"><strong>Browser TTS unavailable.</strong> The show still works without voice.</div>';
+            }
+            if (globalThis.speechSynthesis.getVoices) globalThis.speechSynthesis.getVoices();
+            try {
+              const unlock = new SpeechSynthesisUtterance(" ");
+              unlock.volume = 0;
+              unlock.rate = 1;
+              globalThis.speechSynthesis.cancel();
+              globalThis.speechSynthesis.speak(unlock);
+            } catch (_error) {
+              // Some browsers ignore silent unlock utterances; normal speaking still works.
+            }
+            const status = mode === "narrator"
+              ? '<div class="voice-status">Browser TTS narrator-only mode is ready.</div>'
+              : '<div class="voice-status">Browser TTS character voices are ready.</div>';
+            return status;
+          }
+          if ("speechSynthesis" in globalThis) globalThis.speechSynthesis.cancel();
+          return '<div class="voice-status">Voice mode is off.</div>';
+        }
+        """,
+    )
+    auto_speak_checkbox.change(
+        None,
+        inputs=[voice_mode_select, auto_speak_checkbox],
+        outputs=[tts_status_output],
+        js=r"""
+        (mode, autoSpeak) => {
+          if (mode === "off") {
+            return autoSpeak
+              ? '<div class="voice-status">Auto-speak is ready, but voice mode is off.</div>'
+              : '<div class="voice-status">Auto-speak is off.</div>';
+          }
+          return autoSpeak
+            ? '<div class="voice-status">Auto-speak will read each new line.</div>'
+            : '<div class="voice-status">Auto-speak is off. Use Speak Latest Line manually.</div>';
+        }
+        """,
+    )
+    speak_latest_button.click(
+        None,
+        inputs=[voice_mode_select, latest_tts_payload_output],
+        outputs=[tts_status_output],
+        js=BROWSER_TTS_JS,
+    )
+    preview_actor_voice_button.click(
+        None,
+        inputs=[voice_mode_select, latest_tts_payload_output],
+        outputs=[tts_status_output],
+        js=r"""
+        (mode, payloadJson) => {
+          const activeMode = mode === "off" ? "character" : mode;
+          const payload = payloadJson && payloadJson !== "{}"
+            ? payloadJson
+            : JSON.stringify({
+                speaker: "Warm Puppet",
+                text: "Previewing actor voice.",
+                style: {
+                  label: "Warm Puppet",
+                  pitch: 1.04,
+                  rate: 0.96,
+                  volume: 0.9,
+                  voiceNameHints: ["Google US English", "Samantha", "Jenny", "Aria"],
+                },
+                narratorStyle: {
+                  label: "Narrator",
+                  pitch: 0.96,
+                  rate: 0.88,
+                  volume: 0.82,
+                  voiceNameHints: ["Daniel", "Alex", "Google UK English Male", "Microsoft Guy", "Google US English"],
+                },
+              });
+          const speakLatest = %s;
+          return speakLatest(activeMode, payload, "actor");
+        }
+        """ % BROWSER_TTS_JS,
+    )
+    preview_narrator_voice_button.click(
+        None,
+        inputs=[voice_mode_select, latest_tts_payload_output],
+        outputs=[tts_status_output],
+        js=r"""
+        (_mode, payloadJson) => {
+          const payload = payloadJson && payloadJson !== "{}"
+            ? payloadJson
+            : JSON.stringify({
+                speaker: "Narrator",
+                text: "Previewing narrator voice.",
+                style: {
+                  label: "Warm Puppet",
+                  pitch: 1.04,
+                  rate: 0.96,
+                  volume: 0.9,
+                  voiceNameHints: ["Google US English", "Samantha", "Jenny", "Aria"],
+                },
+                narratorStyle: {
+                  label: "Narrator",
+                  pitch: 0.96,
+                  rate: 0.88,
+                  volume: 0.82,
+                  voiceNameHints: ["Daniel", "Alex", "Google UK English Male", "Microsoft Guy", "Google US English"],
+                },
+              });
+          const speakLatest = %s;
+          return speakLatest("narrator", payload, "narrator");
+        }
+        """ % BROWSER_TTS_JS,
+    )
+    stop_speaking_button.click(
+        None,
+        outputs=[tts_status_output],
+        js=STOP_SPEAKING_JS,
+    )
+    reset_button.click(
+        None,
+        outputs=[tts_status_output],
+        js=STOP_SPEAKING_JS,
+    )
+    latest_tts_payload_output.change(
+        None,
+        inputs=[voice_mode_select, auto_speak_checkbox, latest_tts_payload_output],
+        outputs=[tts_status_output],
+        js=AUTO_BROWSER_TTS_JS,
+    )
+    for event in [
+        create_event,
+        run_one_event,
+        run_full_event,
+        throw_prop_event,
+        summon_actor_event,
+        request_finale_event,
+    ]:
+        event.then(
+            None,
+            inputs=[voice_mode_select, auto_speak_checkbox, latest_tts_payload_output],
+            outputs=[tts_status_output],
+            js=AUTO_BROWSER_TTS_JS,
+        )
 
 
 if __name__ == "__main__":