Add audible fallback for reader voice

Co-authored-by: Codex <codex@openai.com>

FIELD_NOTES.md

@@ -46,3 +46,5 @@ Keyboard map:
 Live accessibility demos need dependable behavior. If llama.cpp is not available, the app uses deterministic local narration prefixes. If Kokoro is not installed or cannot load a voice, the app returns a short silent WAV while keeping the transcript visible. If the VLM integration is unavailable, image ids map to cached alt text.
 
 The app preloads image descriptions through `/api/image-descriptions`, caches them in the frontend, and writes the descriptions back into each image's `alt` attribute. That keeps the visible article, transcript, and spoken image narration aligned.
+
+Kokoro is still the intended model-backed TTS path. For local resilience, the frontend can use the browser speech engine when Kokoro is unavailable, and the session panel labels that as a browser fallback instead of model audio.

README.md

@@ -87,3 +87,5 @@ Each readable node is sent to the reader brain for concise narration, then Kokor
 The session panel keeps a transcript of recent narration with copy and clear controls, making the spoken path inspectable during demos and useful for the Field Notes write-up.
 
 Image descriptions are preloaded into a local cache and written into the page's real `img alt` attributes. When the planned MiniCPM-V runtime is unavailable, deterministic alt-text fallbacks keep the screen-reader path usable.
+
+Kokoro remains the planned tiny-model TTS path. During local demos, if the server-side Kokoro call falls back, the browser speech engine can read the same transcript so screen-reader mode still produces audible feedback.

scripts/verify.py

@@ -76,6 +76,7 @@ def verify_routes() -> None:
     assert_true("readerToggle" in home.text, "Home route should include reader toggle")
     assert_true("summaryButton" in home.text, "Home route should include summary control")
     assert_true("imageStatus" in home.text, "Home route should include image status")
+    assert_true("voiceStatus" in home.text, "Home route should include voice status")
     assert_true("transcriptLog" in home.text, "Home route should include transcript log")
 
     health = client.get("/api/health")

static/app.js

@@ -5,6 +5,7 @@ const currentStatus = document.querySelector("#currentStatus");
 const runtimeStatus = document.querySelector("#runtimeStatus");
 const modelStatus = document.querySelector("#modelStatus");
 const imageStatus = document.querySelector("#imageStatus");
+const voiceStatus = document.querySelector("#voiceStatus");
 const liveNarration = document.querySelector("#liveNarration");
 const audio = document.querySelector("#speechAudio");
 const speedControl = document.querySelector("#speedControl");
@@ -37,6 +38,7 @@ let playing = false;
 let requestSerial = 0;
 let transcriptEntries = [];
 let imageDescriptions = new Map();
+let lastSpokenText = "";
 
 function escapeHtml(value) {
   return value.replace(/[&<>"']/g, (char) => ({
@@ -146,10 +148,61 @@ function setActive(index) {
 function stopAudio() {
   audio.pause();
   audio.removeAttribute("src");
+  window.speechSynthesis?.cancel();
   playing = false;
   controls.play.textContent = "Play";
 }
 
+function browserSpeak(text) {
+  if (!("speechSynthesis" in window)) {
+    return false;
+  }
+  window.speechSynthesis.cancel();
+  const utterance = new SpeechSynthesisUtterance(text);
+  utterance.rate = Number(speedControl.value);
+  utterance.onend = () => {
+    playing = false;
+    controls.play.textContent = "Play";
+  };
+  window.speechSynthesis.speak(utterance);
+  playing = true;
+  controls.play.textContent = "Pause";
+  return true;
+}
+
+async function speakNarration(text, serial) {
+  lastSpokenText = text;
+  const speech = await postJson("/api/speak", {
+    text,
+    speed: Number(speedControl.value),
+  });
+
+  if (serial !== requestSerial) return;
+
+  if (speech.runtime === "fallback") {
+    const spoke = browserSpeak(text);
+    voiceStatus.textContent = spoke ? "Browser fallback" : "Transcript only";
+    if (!spoke) {
+      liveNarration.textContent = `${text} Audio fallback is unavailable. Transcript is visible.`;
+    }
+    return;
+  }
+
+  if (speech.audio_url) {
+    audio.src = speech.audio_url;
+    await audio.play().catch(() => {
+      const spoke = browserSpeak(text);
+      voiceStatus.textContent = spoke ? "Browser fallback" : "Audio ready";
+      liveNarration.textContent = spoke ? text : `${text} Audio is ready. Press Play to hear it.`;
+    });
+    playing = !audio.paused || window.speechSynthesis?.speaking;
+    controls.play.textContent = playing ? "Pause" : "Play";
+    if (!window.speechSynthesis?.speaking) {
+      voiceStatus.textContent = speech.runtime;
+    }
+  }
+}
+
 async function postJson(url, payload) {
   const options = payload === undefined ? {} : {
     method: "POST",
@@ -201,21 +254,7 @@ async function narrate(index) {
       text: result.narration,
     });
 
-    const speech = await postJson("/api/speak", {
-      text: result.narration,
-      speed: Number(speedControl.value),
-    });
-
-    if (serial !== requestSerial) return;
-
-    if (speech.audio_url) {
-      audio.src = speech.audio_url;
-      await audio.play().catch(() => {
-        liveNarration.textContent = `${result.narration} Audio is ready. Press Play to hear it.`;
-      });
-      playing = !audio.paused;
-      controls.play.textContent = playing ? "Pause" : "Play";
-    }
+    await speakNarration(result.narration, serial);
   } catch (error) {
     runtimeStatus.textContent = "Error";
     liveNarration.textContent = `Narration failed: ${error.message}`;
@@ -249,21 +288,7 @@ async function summarizeCurrentSection() {
       text: result.narration,
     });
 
-    const speech = await postJson("/api/speak", {
-      text: result.narration,
-      speed: Number(speedControl.value),
-    });
-
-    if (serial !== requestSerial) return;
-
-    if (speech.audio_url) {
-      audio.src = speech.audio_url;
-      await audio.play().catch(() => {
-        liveNarration.textContent = `${result.narration} Audio is ready. Press Play to hear it.`;
-      });
-      playing = !audio.paused;
-      controls.play.textContent = playing ? "Pause" : "Play";
-    }
+    await speakNarration(result.narration, serial);
   } catch (error) {
     runtimeStatus.textContent = "Error";
     liveNarration.textContent = `Summary failed: ${error.message}`;
@@ -316,12 +341,19 @@ controls.play.addEventListener("click", () => {
   }
   if (playing) {
     audio.pause();
+    window.speechSynthesis?.pause();
     playing = false;
     controls.play.textContent = "Play";
+  } else if (window.speechSynthesis?.paused) {
+    window.speechSynthesis.resume();
+    playing = true;
+    controls.play.textContent = "Pause";
   } else if (audio.src) {
     audio.play();
     playing = true;
     controls.play.textContent = "Pause";
+  } else if (lastSpokenText) {
+    browserSpeak(lastSpokenText);
   } else {
     narrate(currentIndex);
   }

static/index.html

@@ -100,6 +100,10 @@
             <dt>Image Alt</dt>
             <dd id="imageStatus">Waiting</dd>
           </div>
+          <div>
+            <dt>Voice</dt>
+            <dd id="voiceStatus">Waiting</dd>
+          </div>
         </dl>
         <p id="liveNarration" class="live-narration" aria-live="polite">
           Turn on screen reader mode to begin.