Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

feat(reading): add material-scoped natural read-aloud audio (#1654)

XZHeeb360f66ae5
diff --git a/deeptutor/api/routers/reading_extensions.py b/deeptutor/api/routers/reading_extensions.py
index e9fbcee22..45f20882f 100644
--- a/deeptutor/api/routers/reading_extensions.py
+++ b/deeptutor/api/routers/reading_extensions.py
@@ -9,7 +9,7 @@ import re
from typing import Any
from uuid import uuid4
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, HTTPException, Response, status
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from deeptutor.learning.storage import LearningStore
@@ -24,6 +24,8 @@ from deeptutor.reading.extensions import (
get_reading_extension_registry,
)
from deeptutor.services.llm.exceptions import LLMError
+from deeptutor.services.voice import VoiceProviderError, synthesize_speech
+from deeptutor.services.voice.audio import _parse_pcm_content_type, _pcm16_to_wav
logger = logging.getLogger(__name__)
@@ -55,6 +57,10 @@ class ActionPayload(BaseModel):
locale: str = Field(default="en", max_length=32)
+class ReadAloudAudioPayload(BaseModel):
+ locator: int = Field(ge=1)
+
+
class QuizAnswerItem(BaseModel):
model_config = ConfigDict(extra="ignore")
@@ -142,6 +148,50 @@ async def list_extensions() -> list[dict[str, Any]]:
]
[email protected]("/materials/{material_id}/read-aloud")
+async def read_material_aloud(material_id: str, payload: ReadAloudAudioPayload) -> Response:
+ """Synthesize one assigned material unit with the active server voice."""
+ try:
+ assert_learning_material(material_id)
+ except PermissionError as exc:
+ raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
+
+ allowed = allowed_reading_extensions()
+ if allowed is not None and "read_aloud" not in allowed:
+ raise HTTPException(
+ status_code=status.HTTP_403_FORBIDDEN, detail="This reading extension is not allowed."
+ )
+
+ extension = get_reading_extension_registry().get("read_aloud")
+ if extension is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND, detail="Reading extension not found."
+ )
+
+ try:
+ text = ReadingStore().unit_text(material_id, payload.locator)
+ except Exception as exc:
+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+
+ try:
+ audio, content_type = await synthesize_speech(text)
+ except ValueError as exc:
+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+ except VoiceProviderError as exc:
+ logger.warning("Reading TTS provider error for %s: %s", material_id, exc)
+ raise HTTPException(
+ status_code=status.HTTP_502_BAD_GATEWAY,
+ detail="The speech provider is unavailable. Browser speech will be used instead.",
+ ) from exc
+
+ pcm_info = _parse_pcm_content_type(content_type)
+ if pcm_info:
+ sample_rate, channels = pcm_info
+ audio = _pcm16_to_wav(audio, sample_rate=sample_rate, channels=channels)
+ content_type = "audio/wav"
+ return Response(content=audio, media_type=content_type, headers={"Cache-Control": "no-store"})
+
+
@router.post("/materials/{material_id}/extensions/{extension_id}/actions/{action}")
async def run_extension_action(
material_id: str,
diff --git a/tests/reading/test_read_aloud.py b/tests/reading/test_read_aloud.py
index 375980042..d1c6c3dc7 100644
--- a/tests/reading/test_read_aloud.py
+++ b/tests/reading/test_read_aloud.py
@@ -1,16 +1,21 @@
from __future__ import annotations
+import io
from pathlib import Path
import tomllib
+from typing import Any
+import wave
from fastapi import FastAPI
from fastapi.testclient import TestClient
+import pytest
from deeptutor.api.routers import reading_extensions
from deeptutor.reading import ReadingStore
from deeptutor.reading.extensions import ReadingContext, ReadingExtensionRegistry
from deeptutor.reading.read_aloud import ReadAloudExtension
from deeptutor.services.path_service import PathService
+from deeptutor.services.voice import VoiceProviderError
def test_read_aloud_returns_verified_visible_text_only():
@@ -67,6 +72,137 @@ def test_read_aloud_crosses_the_authenticated_api_boundary_with_stored_text(monk
}
+def _audio_client(monkeypatch, synthesize) -> TestClient:
+ registry = ReadingExtensionRegistry([ReadAloudExtension()])
+ monkeypatch.setattr(
+ reading_extensions,
+ "get_reading_extension_registry",
+ lambda: registry,
+ )
+ monkeypatch.setattr(reading_extensions, "synthesize_speech", synthesize)
+ app = FastAPI()
+ app.include_router(reading_extensions.router, prefix="/api/reading")
+ return TestClient(app)
+
+
+def test_read_aloud_audio_uses_stored_text_not_client_text(monkeypatch, tmp_path):
+ monkeypatch.setenv("DEEPTUTOR_HOME", str(tmp_path))
+ PathService.reset_instance()
+ source = tmp_path / "source.txt"
+ source.write_text("Stored unit text only.", encoding="utf-8")
+ material = ReadingStore().ingest(source)
+ captured: dict[str, Any] = {}
+
+ async def synthesize(text: str, **_: Any):
+ captured["text"] = text
+ return b"natural-audio", "audio/mpeg"
+
+ client = _audio_client(monkeypatch, synthesize)
+ try:
+ response = client.post(
+ f"/api/reading/materials/{material.material_id}/read-aloud",
+ json={"locator": 1, "locale": "en", "text": "Forged speech"},
+ )
+ finally:
+ PathService.reset_instance()
+
+ assert response.status_code == 200, response.text
+ assert response.content == b"natural-audio"
+ assert response.headers["content-type"] == "audio/mpeg"
+ assert captured == {"text": "Stored unit text only."}
+
+
+def test_read_aloud_audio_wraps_pcm_for_browser_playback(monkeypatch, tmp_path):
+ monkeypatch.setenv("DEEPTUTOR_HOME", str(tmp_path))
+ PathService.reset_instance()
+ source = tmp_path / "source.txt"
+ source.write_text("Natural speech.", encoding="utf-8")
+ material = ReadingStore().ingest(source)
+ pcm = b"\x00\x00\x01\x00" * 12
+
+ async def synthesize(_: str, **__: Any):
+ return pcm, "audio/pcm;rate=24000;channels=1"
+
+ client = _audio_client(monkeypatch, synthesize)
+ try:
+ response = client.post(
+ f"/api/reading/materials/{material.material_id}/read-aloud",
+ json={"locator": 1},
+ )
+ finally:
+ PathService.reset_instance()
+
+ assert response.status_code == 200, response.text
+ assert response.headers["content-type"] == "audio/wav"
+ with wave.open(io.BytesIO(response.content), "rb") as audio:
+ assert audio.getframerate() == 24000
+ assert audio.getnchannels() == 1
+ assert audio.readframes(audio.getnframes()) == pcm
+
+
+def test_read_aloud_audio_rejects_invalid_locator(monkeypatch, tmp_path):
+ monkeypatch.setenv("DEEPTUTOR_HOME", str(tmp_path))
+ PathService.reset_instance()
+ source = tmp_path / "source.txt"
+ source.write_text("Natural speech.", encoding="utf-8")
+ material = ReadingStore().ingest(source)
+
+ async def synthesize(_: str, **__: Any):
+ raise AssertionError("invalid locator must not reach the provider")
+
+ client = _audio_client(monkeypatch, synthesize)
+ try:
+ response = client.post(
+ f"/api/reading/materials/{material.material_id}/read-aloud",
+ json={"locator": 2},
+ )
+ finally:
+ PathService.reset_instance()
+
+ assert response.status_code == 400
+
+
+def test_read_aloud_audio_requires_the_extension_grant(monkeypatch, tmp_path):
+ monkeypatch.setattr(
+ reading_extensions,
+ "allowed_reading_extensions",
+ lambda: {"vocabulary"},
+ )
+ client = _audio_client(monkeypatch, lambda *_: None)
+ response = client.post("/api/reading/materials/mat/read-aloud", json={"locator": 1})
+ assert response.status_code == 403
+ assert "not allowed" in response.json()["detail"]
+
+
+ ("error", "status_code"),
+ [
+ (ValueError("No active TTS model is configured."), 400),
+ (VoiceProviderError("provider down"), 502),
+ ],
+)
+def test_read_aloud_audio_maps_provider_failures(monkeypatch, tmp_path, error, status_code):
+ monkeypatch.setenv("DEEPTUTOR_HOME", str(tmp_path))
+ PathService.reset_instance()
+ source = tmp_path / "source.txt"
+ source.write_text("Natural speech.", encoding="utf-8")
+ material = ReadingStore().ingest(source)
+
+ async def synthesize(_: str, **__: Any):
+ raise error
+
+ client = _audio_client(monkeypatch, synthesize)
+ try:
+ response = client.post(
+ f"/api/reading/materials/{material.material_id}/read-aloud",
+ json={"locator": 1},
+ )
+ finally:
+ PathService.reset_instance()
+
+ assert response.status_code == status_code
+
+
def test_read_aloud_rejects_undeclared_actions():
context = ReadingContext(material_id="material", locator=1, visible_text="Text")
diff --git a/web/components/reading/ReadingActionsProvider.tsx b/web/components/reading/ReadingActionsProvider.tsx
index 39d46c75f..b79e4fa5d 100644
--- a/web/components/reading/ReadingActionsProvider.tsx
+++ b/web/components/reading/ReadingActionsProvider.tsx
@@ -16,6 +16,7 @@ import {
} from "@/lib/reading-api";
import { CHAT_ROUTED_READING_ACTIONS } from "@/lib/reading-passage-prompts";
import { builtInActionLabel } from "./ReadingExtensionBar";
+import { useReadAloudSpeech } from "./use-read-aloud-speech";
import {
ReadingActionsContext,
type ReadingActionCard,
@@ -53,7 +54,7 @@ export function ReadingActionsProvider({
const [ageMode, setAgeMode] = useState<ReadingAgeMode>("default");
const [cards, setCards] = useState<ReadingActionCard[]>([]);
const [busyKey, setBusyKey] = useState("");
- const [speaking, setSpeaking] = useState(false);
+ const { speak, speaking, stop: stopSpeaking } = useReadAloudSpeech();
const onStartRef = useRef(onStart);
onStartRef.current = onStart;
@@ -93,11 +94,6 @@ export function ReadingActionsProvider({
};
}, []);
- const stopSpeaking = useCallback(() => {
- window.speechSynthesis?.cancel();
- setSpeaking(false);
- }, []);
-
// A card answers a question about one document; switching documents leaves
// it describing a page that is no longer on screen.
useEffect(() => {
@@ -106,13 +102,7 @@ export function ReadingActionsProvider({
// Speech stops the moment the reader leaves the passage being read, the
// same promise the standalone toolbar makes.
- useEffect(
- () => () => {
- window.speechSynthesis?.cancel();
- setSpeaking(false);
- },
- [locator, materialId],
- );
+ useEffect(() => stopSpeaking, [locator, materialId, stopSpeaking]);
const actions = useMemo<ReadingActionEntry[]>(
() =>
@@ -193,20 +183,18 @@ export function ReadingActionsProvider({
);
if (next.type === "browser_speech") {
const text = String(next.payload.text || "");
- if (!("speechSynthesis" in window) || !text) {
+ const played = await speak({
+ materialId,
+ locator: requestedLocator,
+ locale: String(next.payload.locale || i18n.language),
+ fallbackText: text,
+ });
+ if (!played) {
settle({
status: "error",
error: t("No speech voice is available in this browser."),
});
- return;
}
- window.speechSynthesis.cancel();
- const utterance = new SpeechSynthesisUtterance(text);
- utterance.lang = String(next.payload.locale || i18n.language);
- utterance.onend = () => setSpeaking(false);
- utterance.onerror = () => setSpeaking(false);
- window.speechSynthesis.speak(utterance);
- setSpeaking(true);
return;
}
settle({ status: "done", result: next });
@@ -219,7 +207,7 @@ export function ReadingActionsProvider({
setBusyKey((current) => (current === entry.key ? "" : current));
}
},
- [i18n.language, locator, materialId, t],
+ [i18n.language, locator, materialId, speak, t],
);
const dismiss = useCallback((cardId: string) => {
diff --git a/web/components/reading/ReadingExtensionBar.tsx b/web/components/reading/ReadingExtensionBar.tsx
index 249f83a74..c70fc62af 100644
--- a/web/components/reading/ReadingExtensionBar.tsx
+++ b/web/components/reading/ReadingExtensionBar.tsx
@@ -19,6 +19,7 @@ import {
type ReadingExtensionResult,
} from "@/lib/reading-api";
import { useReadingActions } from "./reading-actions-context";
+import { useReadAloudSpeech } from "./use-read-aloud-speech";
import Tooltip from "@/shared/ui/Tooltip";
type VocabularyTerm = {
@@ -88,13 +89,8 @@ function ExtensionToolbar({
const [busy, setBusy] = useState("");
const [result, setResult] = useState<ReadingExtensionResult | null>(null);
const [resultLocator, setResultLocator] = useState(locator);
- const [speaking, setSpeaking] = useState(false);
const [ageMode, setAgeMode] = useState<ReadingAgeMode>("default");
-
- function stopSpeaking() {
- window.speechSynthesis?.cancel();
- setSpeaking(false);
- }
+ const { speak, speaking, stop: stopSpeaking } = useReadAloudSpeech();
useEffect(() => {
let active = true;
@@ -144,12 +140,7 @@ function ExtensionToolbar({
// Speech, on the other hand, must stop the moment the reader navigates
// away from the passage being read aloud — so this one keeps both keys.
- useEffect(() => {
- return () => {
- window.speechSynthesis?.cancel();
- setSpeaking(false);
- };
- }, [locator, materialId]);
+ useEffect(() => stopSpeaking, [locator, materialId, stopSpeaking]);
const actions = useMemo(
() =>
@@ -180,17 +171,15 @@ function ExtensionToolbar({
setResultLocator(requestedLocator);
if (next.type === "browser_speech") {
const text = String(next.payload.text || "");
- if (!("speechSynthesis" in window) || !text) {
+ const played = await speak({
+ materialId,
+ locator: requestedLocator,
+ locale: String(next.payload.locale || i18n.language),
+ fallbackText: text,
+ });
+ if (!played) {
onError(t("No speech voice is available in this browser."));
- return;
}
- window.speechSynthesis.cancel();
- const utterance = new SpeechSynthesisUtterance(text);
- utterance.lang = String(next.payload.locale || i18n.language);
- utterance.onend = () => setSpeaking(false);
- utterance.onerror = () => setSpeaking(false);
- window.speechSynthesis.speak(utterance);
- setSpeaking(true);
}
} catch (error) {
onError(error instanceof Error ? error.message : String(error));
diff --git a/web/components/reading/use-read-aloud-speech.ts b/web/components/reading/use-read-aloud-speech.ts
new file mode 100644
index 000000000..2a17761bd
--- /dev/null
+++ b/web/components/reading/use-read-aloud-speech.ts
@@ -0,0 +1,96 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { readReadingAloudAudio } from "@/lib/reading-api";
+
+/**
+ * Play server speech for a verified reading unit, with browser speech as the
+ * offline/no-provider fallback. A token keeps late audio responses from
+ * starting after the reader has navigated away or pressed stop.
+ */
+export function useReadAloudSpeech() {
+ const [speaking, setSpeaking] = useState(false);
+ const tokenRef = useRef(0);
+ const audioRef = useRef<HTMLAudioElement | null>(null);
+ const audioUrlRef = useRef<string | null>(null);
+
+ const disposeAudio = useCallback(() => {
+ audioRef.current?.pause();
+ if (audioUrlRef.current) URL.revokeObjectURL(audioUrlRef.current);
+ audioRef.current = null;
+ audioUrlRef.current = null;
+ }, []);
+
+ const stop = useCallback(() => {
+ tokenRef.current += 1;
+ disposeAudio();
+ window.speechSynthesis?.cancel();
+ setSpeaking(false);
+ }, [disposeAudio]);
+
+ useEffect(() => disposeAudio, [disposeAudio]);
+
+ const speak = useCallback(
+ async ({
+ materialId,
+ locator,
+ locale,
+ fallbackText,
+ }: {
+ materialId: string;
+ locator: number;
+ locale: string;
+ fallbackText: string;
+ }) => {
+ const token = ++tokenRef.current;
+ disposeAudio();
+ window.speechSynthesis?.cancel();
+ try {
+ const blob = await readReadingAloudAudio(materialId, { locator });
+ if (tokenRef.current !== token || !blob.size) return false;
+ const url = URL.createObjectURL(blob);
+ const audio = new Audio(url);
+ audioUrlRef.current = url;
+ audioRef.current = audio;
+ audio.onended = () => {
+ if (tokenRef.current === token) {
+ disposeAudio();
+ setSpeaking(false);
+ }
+ };
+ audio.onerror = () => {
+ if (tokenRef.current === token) {
+ disposeAudio();
+ setSpeaking(false);
+ }
+ };
+ await audio.play();
+ if (tokenRef.current !== token) {
+ disposeAudio();
+ return true;
+ }
+ setSpeaking(true);
+ return true;
+ } catch {
+ if (tokenRef.current !== token) return true;
+ }
+
+ if (!("speechSynthesis" in window) || !fallbackText) return false;
+ const utterance = new SpeechSynthesisUtterance(fallbackText);
+ utterance.lang = locale;
+ utterance.onend = () => {
+ if (tokenRef.current === token) setSpeaking(false);
+ };
+ utterance.onerror = () => {
+ if (tokenRef.current === token) setSpeaking(false);
+ };
+ window.speechSynthesis.speak(utterance);
+ setSpeaking(true);
+ return true;
+ },
+ [disposeAudio],
+ );
+
+ return { speak, speaking, stop };
+}
diff --git a/web/lib/reading-api.ts b/web/lib/reading-api.ts
index 38b4e1bbc..2846c92f3 100644
--- a/web/lib/reading-api.ts
+++ b/web/lib/reading-api.ts
@@ -385,6 +385,39 @@ export async function runReadingExtension(
);
}
+/**
+ * Fetch natural speech for a stored reading unit.
+ *
+ * The request deliberately carries no text: the server re-reads the material
+ * unit and is the only side that can decide what restricted learners may hear.
+ */
+export async function readReadingAloudAudio(
+ materialId: string,
+ context: { locator: number },
+): Promise<Blob> {
+ const response = await apiFetch(
+ apiUrl(`${BASE}/materials/${materialId}/read-aloud`),
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(context),
+ },
+ );
+ if (response.ok) return response.blob();
+
+ let detail = `Request failed: ${response.status}`;
+ try {
+ const body = (await response.json()) as { detail?: unknown };
+ if (typeof body?.detail === "string" && body.detail) detail = body.detail;
+ else if (typeof body?.detail === "object" && body.detail !== null && "message" in body.detail) {
+ detail = String((body.detail as { message: unknown }).message);
+ }
+ } catch {
+ // Binary and proxy error bodies both fall back to the status message.
+ }
+ throw new Error(detail);
+}
+
export interface ReadingQuizAnswer {
question_id: string;
selected_index: number;
diff --git a/web/tests/reading-extensions.test.ts b/web/tests/reading-extensions.test.ts
index c428066fb..aef7de8af 100644
--- a/web/tests/reading-extensions.test.ts
+++ b/web/tests/reading-extensions.test.ts
@@ -11,6 +11,10 @@ const pane = readFileSync(
path.resolve(process.cwd(), "components/reading/ReaderPane.tsx"),
"utf8",
);
+const speechHook = readFileSync(
+ path.resolve(process.cwd(), "components/reading/use-read-aloud-speech.ts"),
+ "utf8",
+);
const api = readFileSync(
path.resolve(process.cwd(), "lib/reading-api.ts"),
"utf8",
@@ -69,15 +73,16 @@ test("a malformed extension catalog cannot crash the whole reader", () => {
});
test("browser speech is stoppable and cannot continue after navigation", () => {
+ assert.match(component, /useReadAloudSpeech\(\)/);
assert.match(
component,
- /const \[speaking, setSpeaking\] = useState\(false\)/,
+ /useEffect\(\(\) => stopSpeaking, \[locator, materialId, stopSpeaking\]\)/,
);
- assert.match(component, /function stopSpeaking\(\)/);
- assert.match(component, /window\.speechSynthesis\?\.cancel\(\)/);
- assert.match(component, /utterance\.onend = \(\) => setSpeaking\(false\)/);
- assert.match(component, /utterance\.onerror = \(\) => setSpeaking\(false\)/);
- assert.match(component, /\}, \[locator, materialId\]\);/);
+ assert.match(speechHook, /const \[speaking, setSpeaking\] = useState\(false\)/);
+ assert.match(speechHook, /window\.speechSynthesis\?\.cancel\(\)/);
+ assert.match(speechHook, /utterance\.onend = \(\) => \{/);
+ assert.match(speechHook, /utterance\.onerror = \(\) => \{/);
+ assert.match(component, /\[locator, materialId, stopSpeaking\]/);
assert.match(component, /aria-label=\{t\("Stop reading aloud"\)\}/);
});
diff --git a/web/tests/reading-read-aloud-speech.spec.ts b/web/tests/reading-read-aloud-speech.spec.ts
new file mode 100644
index 000000000..8d2d7b570
--- /dev/null
+++ b/web/tests/reading-read-aloud-speech.spec.ts
@@ -0,0 +1,153 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+
+import { useReadAloudSpeech } from "@/components/reading/use-read-aloud-speech";
+import { readReadingAloudAudio } from "@/lib/reading-api";
+
+vi.mock("@/lib/reading-api", () => ({
+ readReadingAloudAudio: vi.fn(),
+}));
+
+const audioInstances: {
+ pause: ReturnType<typeof vi.fn>;
+ play: ReturnType<typeof vi.fn>;
+}[] = [];
+
+function installAudio() {
+ class FakeAudio {
+ onended: (() => void) | null = null;
+ onerror: (() => void) | null = null;
+ pause = vi.fn();
+ play = vi.fn().mockResolvedValue(undefined);
+
+ constructor() {
+ audioInstances.push(this);
+ }
+ }
+ vi.stubGlobal("Audio", FakeAudio);
+}
+
+function installObjectUrls() {
+ const createObjectURL = vi.fn(() => "blob:reading-audio");
+ const revokeObjectURL = vi.fn();
+ vi.stubGlobal("URL", {
+ ...URL,
+ createObjectURL,
+ revokeObjectURL,
+ });
+ return { createObjectURL, revokeObjectURL };
+}
+
+function installBrowserSpeech() {
+ const speechSynthesis = {
+ cancel: vi.fn(),
+ speak: vi.fn(),
+ };
+ Object.defineProperty(window, "speechSynthesis", {
+ configurable: true,
+ writable: true,
+ value: speechSynthesis,
+ });
+ return speechSynthesis;
+}
+
+function installSpeechUtterance() {
+ vi.stubGlobal(
+ "SpeechSynthesisUtterance",
+ class {
+ lang = "";
+ onend: (() => void) | null = null;
+ onerror: (() => void) | null = null;
+ text = "";
+
+ constructor(text: string) {
+ this.text = text;
+ }
+ },
+ );
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ audioInstances.length = 0;
+});
+
+it("prefers server audio and sends only the material locator and locale", async () => {
+ installAudio();
+ installObjectUrls();
+ vi.mocked(readReadingAloudAudio).mockResolvedValueOnce({
+ size: 5,
+ } as Blob);
+ const speechSynthesis = installBrowserSpeech();
+
+ const { result } = renderHook(() => useReadAloudSpeech());
+ let played = false;
+ await act(async () => {
+ played = await result.current.speak({
+ materialId: "material-1",
+ locator: 3,
+ locale: "zh-CN",
+ fallbackText: "Verified fallback",
+ });
+ });
+ expect(played).toBe(true);
+
+ expect(readReadingAloudAudio).toHaveBeenCalledWith("material-1", { locator: 3 });
+ expect(audioInstances).toHaveLength(1);
+ expect(audioInstances[0].play).toHaveBeenCalledTimes(1);
+ expect(speechSynthesis.speak).not.toHaveBeenCalled();
+ expect(result.current.speaking).toBe(true);
+});
+
+it("falls back to verified browser speech when server audio fails", async () => {
+ installAudio();
+ installSpeechUtterance();
+ const speechSynthesis = installBrowserSpeech();
+ vi.mocked(readReadingAloudAudio).mockRejectedValueOnce(
+ new Error("speech provider unavailable"),
+ );
+
+ const { result } = renderHook(() => useReadAloudSpeech());
+ let played = false;
+ await act(async () => {
+ played = await result.current.speak({
+ materialId: "material-1",
+ locator: 2,
+ locale: "en",
+ fallbackText: "Verified fallback",
+ });
+ });
+ expect(played).toBe(true);
+
+ expect(speechSynthesis.speak).toHaveBeenCalledTimes(1);
+ const utterance = vi.mocked(speechSynthesis.speak).mock.calls[0][0];
+ expect(utterance.text).toBe("Verified fallback");
+ expect(utterance.lang).toBe("en");
+ expect(result.current.speaking).toBe(true);
+});
+
+it("stops server audio and releases its object URL", async () => {
+ installAudio();
+ const { revokeObjectURL } = installObjectUrls();
+ vi.mocked(readReadingAloudAudio).mockResolvedValueOnce({
+ size: 5,
+ } as Blob);
+
+ const { result } = renderHook(() => useReadAloudSpeech());
+ await act(async () => {
+ await result.current.speak({
+ materialId: "material-1",
+ locator: 1,
+ locale: "en",
+ fallbackText: "Verified fallback",
+ });
+ });
+
+ act(() => {
+ result.current.stop();
+ });
+
+ expect(audioInstances[0].pause).toHaveBeenCalledTimes(1);
+ expect(revokeObjectURL).toHaveBeenCalledWith("blob:reading-audio");
+ expect(result.current.speaking).toBe(false);
+});