WebSpeechEngine implements ReadiumSpeechPlaybackEngine (see Playback.md) against the browser’s built-in Web Speech API. WebSpeechEngineProvider wraps it for use with a single provider or ReadiumSpeechProviderRegistry.
For platform-specific quirks and voice behavior across browsers/OSes, see WebSpeech.md.
Via the provider — always calls initialize() with no options, so use this only when you’re fine with the defaults below:
import { WebSpeechEngineProvider } from "@readium/speech";
const provider = new WebSpeechEngineProvider();
const engine = await provider.createEngine();
Directly, when you need to pass options:
import { WebSpeechEngine } from "@readium/speech";
const engine = new WebSpeechEngine();
await engine.initialize({
languages: ["en", "fr"],
maxLengthExceeded: "error" // default is "warn" — override to fail fast instead
});
initialize() optionsasync initialize(options?: {
languages?: string[];
maxTimeout?: number;
interval?: number;
maxLengthExceeded?: "error" | "none" | "warn";
}): Promise<boolean>
languages, maxTimeout, and interval are forwarded as-is to WebSpeechVoiceManager.initialize() — see VoiceManagement.md for what each does.
languages are also the content’s languages, in order, that the default voice is picked for when no voice is set: the best voice of the first one with voices, preferring one with boundary events. Without languages, it uses the user’s preferred languages (navigator.languages) instead. getCurrentVoice() returns that default until a voice is set with setVoice(), given a voice or its id, matched by voiceURI, then name.
Each utterance is spoken with its own voice when the browser has it, else with the current voice, whatever the utterance’s language. ReadiumSpeechNavigator gives each utterance a voice for its language (see Playback.md).
maxLengthExceeded (default "warn") controls what happens when an utterance’s text exceeds the Web Speech API’s practical length limit, 4096 UTF-8 bytes: "warn" logs a console warning and speaks anyway, "error" throws, "none" does nothing and speaks anyway. Unlike SpeechServerEngine’s overLengthText: "split" (see SpeechServerEngine.md), there is no splitting behavior here — the Web Speech API has no equivalent server-side request-size constraint to work around, just an engine-dependent practical ceiling.
Calling initialize() again on an already-initialized engine is a no-op (false). A call made while another is still running shares it, and its options are ignored.
The Web Speech API has no SSML support: an utterance is spoken from its plain text, else from its ssml with tags stripped and entities decoded. < and > are replaced with zero-width spaces, since some engines take them for markup; boundary charIndexes don’t shift.
For platform quirks, see WebSpeech.md. The engine works around these:
"pause" and "resume" itself.pause() cancels speech, and resume() speaks the current utterance again from its start. The "interrupted" error from that cancel isn’t reported.end for a cancelled utterance: an end within 100 ms of a cancel is ignored.