use-speech-synthesis

Speak text with the Web Speech API.


Package	`@vizejs/composable/use-speech-synthesis`
Own the source	`vize lib pull composable:use-speech-synthesis`
Runtime exports	`useSpeechSynthesis`
Gzip budget	2560 B

Usage

import { useSpeechSynthesis } from "@vizejs/composable/use-speech-synthesis";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useSpeechSynthesis`	media	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useSpeechSynthesis`

Speak text with the Web Speech API. Each speak creates a fresh utterance from the current reactive text, language, voice, pitch, rate, and volume (validated ranges), and cancels speech previously started by this composable. status follows the utterance lifecycle; interruptions caused by cancel return to "idle" instead of reporting an error. The available voices are kept current via voiceschanged. Speech started by this composable is cancelled and the listener removed when the owning reactive scope stops. Server rendering: nothing is spoken; supported is false, status is "idle", and voices is empty.

function useSpeechSynthesis( text: MaybeRefOrGetter<string>, options: UseSpeechSynthesisOptions = {}, ): SpeechSynthesisControls

const text = ref("Hello, Vize");
const { speak, status } = useSpeechSynthesis(text, { rate: 1.2 });
speak();

Types

`SpeechSynthesisVoiceLike`

Minimal SpeechSynthesisVoice.

Member	Type	Description
`name`	`string`	Human-readable voice name.
`lang`	`string`	BCP 47 language tag.
`voiceURI`	`string`	Stable voice identifier.
`localService`	`boolean`	Whether synthesis runs locally.
`default`	`boolean`	Whether this is the platform default voice.

`SpeechSynthesisUtteranceLike`

Minimal SpeechSynthesisUtterance.

Member	Type	Description
`text`	`string`	Text to speak.
`lang`	`string`	BCP 47 language tag.
`pitch`	`number`	Pitch from 0 to 2.
`rate`	`number`	Rate from 0.1 to 10.
`volume`	`number`	Volume from 0 to 1.
`voice`	`SpeechSynthesisVoiceLike \| null`	Voice, or `null` for the platform default.

`SpeechSynthesisLike`

Minimal speechSynthesis controller.

Member	Type	Description
`speak`	`(utterance: SpeechSynthesisUtteranceLike) => void`	Queue an utterance.
`cancel`	`() => void`	Clear the queue and stop speaking.
`pause`	`() => void`	Pause speaking.
`resume`	`() => void`	Resume speaking.
`getVoices`	`() => readonly SpeechSynthesisVoiceLike[]`	Voices available right now (may be empty until `voiceschanged`).

`SpeechSynthesisHost`

Capabilities used by useSpeechSynthesis.

Member	Type	Description
`synthesis`	`SpeechSynthesisLike`	Synthesis controller (`window.speechSynthesis`).
`Utterance`	`new (text?: string) => SpeechSynthesisUtteranceLike`	Utterance constructor (`window.SpeechSynthesisUtterance`).

`UseSpeechSynthesisOptions`

Options for useSpeechSynthesis.

Member	Type	Description
`lang`?	`MaybeRefOrGetter<string>`	BCP 47 language tag.
`pitch`?	`MaybeRefOrGetter<number>`	Pitch from 0 to 2.
`rate`?	`MaybeRefOrGetter<number>`	Rate from 0.1 to 10.
`volume`?	`MaybeRefOrGetter<number>`	Volume from 0 to 1.
`voice`?	`MaybeRefOrGetter<SpeechSynthesisVoiceLike \| undefined>`	Voice to use; `undefined` uses the platform default for `lang`.
`host`?	`MaybeRefOrGetter<SpeechSynthesisHost \| null \| undefined>`	Synthesis capabilities for alternate runtimes and tests.

`SpeechSynthesisControls`

Reactive state and actions returned by useSpeechSynthesis.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether speech synthesis is available.
`status`	`Readonly<Ref<SpeechSynthesisStatus>>`	Playback state of the utterance spoken by this composable.
`voices`	`Readonly<ShallowRef<readonly SpeechSynthesisVoiceLike[]>>`	Voices offered by the platform, updated on `voiceschanged`.
`error`	`Readonly<ShallowRef<SpeechSynthesisErrorCode \| undefined>>`	Most recent synthesis error, cleared by the next `speak`.
`speak`	`() => boolean`	Speak the current text, cancelling anything this composable is speaking.
`pause`	`() => void`	Pause speaking.
`resume`	`() => void`	Resume paused speech.
`cancel`	`() => void`	Stop speaking and clear the queue.