Skip to content

WebSpeechEngine.md

Latest commit

 

History

History
49 lines (33 loc) · 2.86 KB

WebSpeechEngine.md

File metadata and controls

49 lines (33 loc) · 2.86 KB
Raw

WebSpeechEngine

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.

Construction

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() options

async 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: "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.