NativeTTS

Defined in: src/providers/tts/native/NativeTTS.ts:125

Native browser TTS provider using the Web Speech API (SpeechSynthesis).

Remarks

This provider uses the browser’s built-in speech synthesis capabilities. It plays audio directly through the browser’s audio output — CompositeVoice does NOT receive audio data. The synthesize() method returns an empty Blob because the Web Speech API does not expose raw audio buffers.

Key characteristics:

• Zero setup required — no API keys or external services needed
• Audio is played directly by the browser (not routed through the SDK)
• Voice selection supports name matching, language filtering, and local preference
• Supports pause, resume, and cancel operations
• Pitch is normalized from semitones (-20 to 20) to Web Speech range (0 to 2)

Audio flow: Text -> SpeechSynthesis.speak() -> Device Speakers

Example

import { NativeTTS } from 'composite-voice';

const tts = new NativeTTS({
  voiceName: 'Google US English',
  rate: 1.0,
  pitch: 0,
  preferLocal: true,
});

await tts.initialize();
await tts.synthesize('Hello, world!');

See

• RestTTSProvider - The base class this provider extends.
• NativeTTSConfig - Configuration options for this provider.

Extends

• RestTTSProvider

Constructors

Constructor

new NativeTTS(config?, logger?): NativeTTS;

Defined in: src/providers/tts/native/NativeTTS.ts:163

Creates a new NativeTTS provider instance.

Parameters

Returns

NativeTTS

Example

const tts = new NativeTTS({
  voiceName: 'Samantha',
  rate: 1.0,
  pitch: 0,
});

Overrides

RestTTSProvider.constructor

Properties

Methods

assertReady()

protected assertReady(): void;

Defined in: src/providers/base/BaseProvider.ts:255

Guard that throws if the provider has not been initialized.

Returns

void

Remarks

Call at the start of any method that requires the provider to be ready.

Throws

Error Thrown with a descriptive message when initialized is false.

Inherited from

RestTTSProvider.assertReady

cancel()

cancel(): void;

Defined in: src/providers/tts/native/NativeTTS.ts:370

Cancels any ongoing speech synthesis immediately.

Returns

void

Remarks

Removes all utterances from the utterance queue and stops the currently speaking utterance, if any.

configure()

configure(_metadata): void;

Defined in: src/providers/tts/native/NativeTTS.ts:490

No-op — NativeTTS uses the browser’s SpeechSynthesis API which manages its own audio format internally.

Parameters

Returns

void

Remarks

This method exists to satisfy the AudioOutputProvider interface for duck-type validation. The browser handles audio format configuration for SpeechSynthesis internally.

See

AudioOutputProvider.configure

dispose()

dispose(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:154

Clean up resources and dispose of the provider.

Returns

Promise<void>

Remarks

Delegates to the subclass hook onDispose and resets the initialized flag. If the provider is not initialized, the call is a no-op.

Throws

Re-throws any error raised by onDispose.

Inherited from

RestTTSProvider.dispose

emitAudio()

protected emitAudio(chunk): void;

Defined in: src/providers/base/BaseTTSProvider.ts:138

Emit a synthesized audio chunk to the registered callback.

Parameters

Returns

void

Remarks

Subclasses call this method for each chunk of audio produced during synthesis. If no callback has been registered the chunk is silently dropped.

Inherited from

RestTTSProvider.emitAudio

emitMetadata()

protected emitMetadata(metadata): void;

Defined in: src/providers/base/BaseTTSProvider.ts:154

Emit audio metadata to the registered callback.

Parameters

Returns

void

Remarks

Typically called once at the start of synthesis when the provider knows the output format. If no callback has been registered the metadata is silently dropped.

Inherited from

RestTTSProvider.emitMetadata

enqueue()

enqueue(_chunk): void;

Defined in: src/providers/tts/native/NativeTTS.ts:507

No-op — NativeTTS synthesizes and plays audio internally via the browser’s SpeechSynthesis API. External audio chunks are not accepted.

Parameters

Returns

void

Remarks

This method exists to satisfy the AudioOutputProvider interface. Audio output is handled entirely by SpeechSynthesis.speak() in the synthesize() method.

See

AudioOutputProvider.enqueue

flush()

flush(): Promise<void>;

Defined in: src/providers/tts/native/NativeTTS.ts:522

No-op — resolves immediately since SpeechSynthesis manages playback.

Returns

Promise<void>

Remarks

This method exists to satisfy the AudioOutputProvider interface. The actual wait-for-completion is handled within synthesize(), which resolves its promise when the utterance finishes.

See

AudioOutputProvider.flush

getAvailableVoices()

getAvailableVoices(): SpeechSynthesisVoice[];

Defined in: src/providers/tts/native/NativeTTS.ts:427

Returns a copy of all voices available in the browser.

Returns

SpeechSynthesisVoice[]

An array of SpeechSynthesisVoice objects available in the browser.

Remarks

The returned array is a shallow copy; modifying it does not affect the provider’s internal voice list.

getConfig()

getConfig(): TTSProviderConfig;

Defined in: src/providers/base/BaseTTSProvider.ts:165

Get a shallow copy of the current TTS configuration.

Returns

TTSProviderConfig

A new TTSProviderConfig object.

Inherited from

RestTTSProvider.getConfig

getSelectedVoice()

getSelectedVoice(): SpeechSynthesisVoice | null;

Defined in: src/providers/tts/native/NativeTTS.ts:436

Returns the currently selected voice, if any.

Returns

SpeechSynthesisVoice | null

The selected SpeechSynthesisVoice, or null if no voice is selected.

initialize()

initialize(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:127

Initialize the provider, making it ready for use.

Returns

Promise<void>

Remarks

Calls the subclass hook onInitialize. If the provider has already been initialized the call is a no-op.

Throws

ProviderInitializationError Thrown when onInitialize rejects. The original error is wrapped with the provider class name for diagnostics.

Inherited from

RestTTSProvider.initialize

isPaused()

isPaused(): boolean;

Defined in: src/providers/tts/native/NativeTTS.ts:414

Checks whether speech is currently paused.

Returns

boolean

true if the SpeechSynthesis engine is paused, false otherwise.

isPlaying()

isPlaying(): boolean;

Defined in: src/providers/tts/native/NativeTTS.ts:550

Check whether the browser is currently playing synthesized speech.

Returns

boolean

true when the SpeechSynthesis engine is actively speaking.

Remarks

Delegates to isSpeaking().

See

AudioOutputProvider.isPlaying

isReady()

isReady(): boolean;

Defined in: src/providers/base/BaseProvider.ts:178

Check whether the provider has been initialized and is ready.

Returns

boolean

true when initialize has completed successfully and dispose has not yet been called.

Inherited from

RestTTSProvider.isReady

isSpeaking()

isSpeaking(): boolean;

Defined in: src/providers/tts/native/NativeTTS.ts:405

Checks whether the browser is currently speaking.

Returns

boolean

true if the SpeechSynthesis engine is actively speaking, false otherwise.

onAudio()

onAudio(callback): void;

Defined in: src/providers/base/BaseTTSProvider.ts:109

Register a callback to receive synthesized audio chunks.

Parameters

Returns

void

Remarks

All TTS providers — regardless of transport — deliver audio through this callback. CompositeVoice registers it during pipeline setup so that audio data flows into the AudioPlayer.

Inherited from

RestTTSProvider.onAudio

onConfigUpdate()

protected onConfigUpdate(_config): void;

Defined in: src/providers/base/BaseProvider.ts:242

Hook called after updateConfig merges new values.

Parameters

Returns

void

Remarks

The default implementation is a no-op. Override in subclasses to react to runtime configuration changes (e.g. reconnect with a new API key).

Inherited from

RestTTSProvider.onConfigUpdate

onDispose()

protected onDispose(): Promise<void>;

Defined in: src/providers/tts/native/NativeTTS.ts:208

Disposes the provider and cancels any ongoing speech.

Returns

Promise<void>

Overrides

RestTTSProvider.onDispose

onInitialize()

protected onInitialize(): Promise<void>;

Defined in: src/providers/tts/native/NativeTTS.ts:188

Initializes the provider by loading browser voices and selecting the best match.

Returns

Promise<void>

Remarks

Waits for the browser to populate the voice list (which may be asynchronous in some browsers), then selects a voice based on the configured preferences.

Throws

Error if the SpeechSynthesis API is not supported in the current browser.

Overrides

RestTTSProvider.onInitialize

onMetadata()

onMetadata(callback): void;

Defined in: src/providers/base/BaseTTSProvider.ts:124

Register a callback to receive audio metadata.

Parameters

Returns

void

Remarks

Metadata (sample rate, encoding, channels, etc.) helps the AudioPlayer configure playback correctly. Providers may emit metadata once at the start of synthesis but are not required to.

Inherited from

RestTTSProvider.onMetadata

onPlaybackEnd()

onPlaybackEnd(callback): void;

Defined in: src/providers/tts/native/NativeTTS.ts:580

Register a callback invoked when speech playback finishes.

Parameters

Returns

void

Remarks

The callback is fired from the SpeechSynthesisUtterance.onend event within synthesize().

See

AudioOutputProvider.onPlaybackEnd

onPlaybackError()

onPlaybackError(callback): void;

Defined in: src/providers/tts/native/NativeTTS.ts:595

Register a callback invoked when a playback error occurs.

Parameters

Returns

void

Remarks

The callback is fired from the SpeechSynthesisUtterance.onerror event within synthesize().

See

AudioOutputProvider.onPlaybackError

onPlaybackStart()

onPlaybackStart(callback): void;

Defined in: src/providers/tts/native/NativeTTS.ts:565

Register a callback invoked when speech playback begins.

Parameters

Returns

void

Remarks

The callback is fired from the SpeechSynthesisUtterance.onstart event within synthesize().

See

AudioOutputProvider.onPlaybackStart

pause()

pause(): void;

Defined in: src/providers/tts/native/NativeTTS.ts:382

Pauses the currently speaking utterance.

Returns

void

Remarks

The utterance can be resumed later with NativeTTS.resume. If nothing is currently being spoken, this is a no-op.

resume()

resume(): void;

Defined in: src/providers/tts/native/NativeTTS.ts:395

Resumes a previously paused utterance.

Returns

void

Remarks

Has no effect if speech is not currently paused.

See

NativeTTS.pause

setVoice()

setVoice(voiceName): boolean;

Defined in: src/providers/tts/native/NativeTTS.ts:459

Changes the active voice by name.

Parameters

Returns

boolean

true if a matching voice was found and selected, false otherwise.

Remarks

Performs a case-insensitive partial match against available voice names. If the voice is found, it becomes the active voice for subsequent synthesize() calls.

Example

const success = tts.setVoice('Google US English');
if (!success) {
  console.warn('Voice not found, using default');
}

stop()

stop(): void;

Defined in: src/providers/tts/native/NativeTTS.ts:536

Stop playback immediately by cancelling all speech.

Returns

void

Remarks

Delegates to cancel(), which calls SpeechSynthesis.cancel() to remove all utterances from the queue and stop the currently speaking utterance.

See

AudioOutputProvider.stop

synthesize()

synthesize(text): Promise<Blob>;

Defined in: src/providers/tts/native/NativeTTS.ts:324

Synthesizes text to speech using the browser’s SpeechSynthesis API.

Parameters

Returns

Promise<Blob>

An empty Blob (audio is played directly by the browser and cannot be captured).

Remarks

Unlike other TTS providers, NativeTTS plays audio directly through the browser’s audio output. The returned Blob is always empty because the Web Speech API does not expose raw audio buffers. This provider does NOT emit audio via onAudio() callbacks.

Audio flow: Text -> SpeechSynthesisUtterance -> SpeechSynthesis.speak() -> Speakers

Pitch is converted from semitones (-20 to 20) to the Web Speech API range (0 to 2) using the formula: 1 + pitch / 20.

Throws

Error if the provider is not initialized.

Throws

Error if the speech synthesis encounters an error (e.g., network or voice failure).

Overrides

RestTTSProvider.synthesize

updateConfig()

updateConfig(config): void;

Defined in: src/providers/base/BaseProvider.ts:201

Merge partial configuration updates into the current config.

Parameters

Returns

void

Remarks

After merging, the subclass hook onConfigUpdate is called so providers can react to changed values at runtime.

Inherited from

RestTTSProvider.updateConfig