Add reader voice controls

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

FIELD_NOTES.md

@@ -48,3 +48,5 @@ Live accessibility demos need dependable behavior. If llama.cpp is not available
 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.
+
+Reader settings are manifest-backed: the app exposes known Kokoro voices and speed bounds through `/api/article-manifest`, then the custom frontend renders the controls and passes the selected voice to `/api/speak`.

README.md

@@ -89,3 +89,5 @@ The session panel keeps a transcript of recent narration with copy and clear con
 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.
+
+The reader bar exposes Kokoro voice selection and speaking speed controls. Defaults come from `/api/article-manifest` so the UI, docs, and backend stay aligned.

app.py

@@ -74,6 +74,18 @@ ARTICLE_IMAGES: list[dict[str, str]] = [
     },
 ]
 
+READER_SETTINGS: dict[str, Any] = {
+    "default_voice": "af_heart",
+    "default_speed": 1.0,
+    "voices": [
+        {"id": "af_heart", "label": "Heart"},
+        {"id": "af_bella", "label": "Bella"},
+        {"id": "am_adam", "label": "Adam"},
+        {"id": "am_michael", "label": "Michael"},
+    ],
+    "speed": {"min": 0.75, "max": 1.35, "step": 0.05},
+}
+
 ARTICLE_MANIFEST: dict[str, Any] = {
     "title": "A tiny model reader that turns articles into guided narration",
     "reader_controls": [
@@ -89,6 +101,7 @@ ARTICLE_MANIFEST: dict[str, Any] = {
     "bonus_targets": ["Tiny Titan", "Llama Champion", "Off-Brand", "Field Notes"],
     "images": ARTICLE_IMAGES,
     "models": MODEL_MANIFEST,
+    "reader_settings": READER_SETTINGS,
 }
 
 app = Server(title="Tiny Narrator")

scripts/verify.py

@@ -77,6 +77,8 @@ def verify_routes() -> None:
     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("voiceControl" in home.text, "Home route should include voice control")
+    assert_true("speedValue" in home.text, "Home route should include speed value output")
     assert_true("transcriptLog" in home.text, "Home route should include transcript log")
 
     health = client.get("/api/health")
@@ -100,6 +102,14 @@ def verify_routes() -> None:
         manifest_payload["models"]["speech"]["id"] == "hexgrad/Kokoro-82M",
         "Manifest should document Kokoro speech model",
     )
+    assert_true(
+        manifest_payload["reader_settings"]["default_voice"] == "af_heart",
+        "Manifest should document default Kokoro voice",
+    )
+    assert_true(
+        len(manifest_payload["reader_settings"]["voices"]) >= 4,
+        "Manifest should expose multiple Kokoro voice choices",
+    )
 
     image_descriptions = client.get("/api/image-descriptions")
     assert_true(image_descriptions.status_code == 200, "Image descriptions route should return 200")

static/app.css

@@ -28,7 +28,9 @@ body {
 }
 
 button,
-input {
+input,
+select,
+output {
   font: inherit;
 }
 
@@ -45,7 +47,8 @@ button:hover {
 
 button:focus-visible,
 a:focus-visible,
-input:focus-visible {
+input:focus-visible,
+select:focus-visible {
   outline: 3px solid var(--focus);
   outline-offset: 3px;
 }
@@ -362,6 +365,21 @@ dd {
   font-weight: 750;
 }
 
+.reader-bar select {
+  min-height: 42px;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--surface);
+  color: var(--ink);
+  padding: 0 10px;
+}
+
+.reader-bar output {
+  min-width: 48px;
+  color: var(--ink);
+  font-weight: 750;
+}
+
 .speakable {
   scroll-margin: 112px;
 }

static/app.js

@@ -8,7 +8,9 @@ const imageStatus = document.querySelector("#imageStatus");
 const voiceStatus = document.querySelector("#voiceStatus");
 const liveNarration = document.querySelector("#liveNarration");
 const audio = document.querySelector("#speechAudio");
+const voiceControl = document.querySelector("#voiceControl");
 const speedControl = document.querySelector("#speedControl");
+const speedValue = document.querySelector("#speedValue");
 const transcriptLog = document.querySelector("#transcriptLog");
 const copyTranscriptButton = document.querySelector("#copyTranscriptButton");
 const clearTranscriptButton = document.querySelector("#clearTranscriptButton");
@@ -40,6 +42,10 @@ let transcriptEntries = [];
 let imageDescriptions = new Map();
 let lastSpokenText = "";
 
+function updateSpeedValue() {
+  speedValue.textContent = `${Number(speedControl.value).toFixed(2)}x`;
+}
+
 function escapeHtml(value) {
   return value.replace(/[&<>"']/g, (char) => ({
     "&": "&amp;",
@@ -89,6 +95,21 @@ async function loadManifest() {
     const manifest = await postJson("/api/article-manifest");
     const modelCount = Object.keys(manifest.models || {}).length;
     modelStatus.textContent = `${modelCount} tiny models, ${manifest.bonus_targets.join(", ")}`;
+    const settings = manifest.reader_settings;
+    if (settings?.voices?.length) {
+      voiceControl.innerHTML = settings.voices
+        .map((voice) => `<option value="${escapeHtml(voice.id)}">${escapeHtml(voice.label)}</option>`)
+        .join("");
+      voiceControl.value = settings.default_voice;
+      voiceStatus.textContent = voiceControl.selectedOptions[0]?.textContent || "Ready";
+    }
+    if (settings?.speed) {
+      speedControl.min = settings.speed.min;
+      speedControl.max = settings.speed.max;
+      speedControl.step = settings.speed.step;
+      speedControl.value = settings.default_speed;
+      updateSpeedValue();
+    }
   } catch {
     modelStatus.textContent = "Manifest unavailable";
   }
@@ -174,6 +195,7 @@ async function speakNarration(text, serial) {
   lastSpokenText = text;
   const speech = await postJson("/api/speak", {
     text,
+    voice: voiceControl.value || "af_heart",
     speed: Number(speedControl.value),
   });
 
@@ -319,6 +341,12 @@ controls.prev.addEventListener("click", () => narrate(Math.max(currentIndex - 1,
 controls.heading.addEventListener("click", () => nextByType("heading"));
 controls.image.addEventListener("click", () => nextByType("image"));
 controls.summary.addEventListener("click", () => summarizeCurrentSection());
+voiceControl.addEventListener("change", () => {
+  voiceStatus.textContent = voiceControl.selectedOptions[0]?.textContent || "Custom voice";
+});
+speedControl.addEventListener("input", () => {
+  updateSpeedValue();
+});
 copyTranscriptButton.addEventListener("click", async () => {
   const text = transcriptEntries
     .slice()
@@ -361,6 +389,7 @@ controls.play.addEventListener("click", () => {
 
 loadManifest();
 loadImageDescriptions();
+updateSpeedValue();
 
 audio.addEventListener("ended", () => {
   playing = false;

static/index.html

@@ -124,9 +124,14 @@
       <button id="headingButton" type="button" title="Next heading">Heading</button>
       <button id="imageButton" type="button" title="Next image">Image</button>
       <button id="summaryButton" type="button" title="Summarize current section">Summary</button>
+      <label>
+        Voice
+        <select id="voiceControl" aria-label="Reader voice"></select>
+      </label>
       <label>
         Speed
         <input id="speedControl" type="range" min="0.75" max="1.35" value="1" step="0.05" />
+        <output id="speedValue" for="speedControl">1.00x</output>
       </label>
       <audio id="speechAudio"></audio>
     </section>