OpenAITTS

Defined in: src/providers/tts/openai/OpenAITTS.ts:174

OpenAI TTS provider using native fetch for text-to-speech synthesis.

Remarks

This is a REST-based provider: each synthesize() call makes a single HTTP request to the OpenAI TTS API and returns the complete audio response as a Blob. It supports both the standard tts-1 (fast) and tts-1-hd (high quality) models, with six available voices and five audio formats.

Audio flow: Text -> OpenAI REST API -> Complete audio Blob

Example

import { OpenAITTS } from 'composite-voice';

const tts = new OpenAITTS({
  apiKey: 'sk-xxxxxxxxxxxx',
  model: 'tts-1',
  voice: 'nova',
  responseFormat: 'mp3',
});

await tts.initialize();
const audioBlob = await tts.synthesize('Hello, world!');
// Play the audio blob, e.g., via an <audio> element

See

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

Extends

• RestTTSProvider

Constructors

Constructor

new OpenAITTS(config, logger?): OpenAITTS;

Defined in: src/providers/tts/openai/OpenAITTS.ts:184

Creates a new OpenAITTS provider instance.

Parameters

Returns

OpenAITTS

Overrides

RestTTSProvider.constructor

Properties

Accessors

isProxyMode

Get Signature

get protected isProxyMode(): boolean;

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

Whether the provider is in proxy mode.

Returns

boolean

true when proxyUrl is set.

Inherited from

RestTTSProvider.isProxyMode

Methods

assertAuth()

protected assertAuth(): void;

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

Validate that auth is configured (either apiKey or proxyUrl).

Returns

void

Remarks

Call this in onInitialize() for any provider that requires external authentication. Native providers (NativeSTT, NativeTTS) and in-browser providers (WebLLM) should NOT call this method.

Throws

ProviderInitializationError Thrown when neither apiKey nor proxyUrl is set.

Inherited from

RestTTSProvider.assertAuth

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

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:190

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:206

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

finalize()

finalize(): Promise<void>;

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

Finalize synthesis by sending the accumulated text to the REST API.

Returns

Promise<void>

Remarks

Calls synthesize with the full accumulated text. The buffer is cleared after synthesis completes (or on error).

Inherited from

RestTTSProvider.finalize

getConfig()

getConfig(): TTSProviderConfig;

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

Get a shallow copy of the current TTS configuration.

Returns

TTSProviderConfig

A new TTSProviderConfig object.

Inherited from

RestTTSProvider.getConfig

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

isAudioReady()

isAudioReady(chunk): boolean;

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

Is this audio chunk ready for playback?

Parameters

Returns

boolean

true when the chunk has valid audio data.

Remarks

The orchestrator calls this to validate audio chunks before passing them to the audio player. The default implementation checks that the chunk has non-zero data.

Inherited from

RestTTSProvider.isAudioReady

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

onAudio()

onAudio(callback): void;

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

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/openai/OpenAITTS.ts:234

Disposes the provider and releases the HTTP client.

Returns

Promise<void>

Overrides

RestTTSProvider.onDispose

onInitialize()

protected onInitialize(): Promise<void>;

Defined in: src/providers/tts/openai/OpenAITTS.ts:193

Initializes the HTTP client for the OpenAI TTS API.

Returns

Promise<void>

Throws

ProviderInitializationError if neither apiKey nor proxyUrl is configured.

Overrides

RestTTSProvider.onInitialize

onMetadata()

onMetadata(callback): void;

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

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

processChunk()

processChunk(text): void;

Defined in: src/providers/base/RestTTSProvider.ts:98

Process a text chunk by accumulating it into the buffer.

Parameters

Returns

void

Remarks

For REST providers, text is buffered until finalize is called, at which point the full text is sent to synthesize.

Inherited from

RestTTSProvider.processChunk

resolveApiKey()

protected resolveApiKey(): string;

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

Resolve the API key for this provider.

Returns

string

The configured API key, or 'proxy' in proxy mode.

Remarks

Returns 'proxy' in proxy mode so that SDK clients (which require a non-empty API key string) can be instantiated without the real key.

Inherited from

RestTTSProvider.resolveApiKey

resolveAuthHeader()

protected resolveAuthHeader(defaultAuthType?): string | undefined;

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

Resolve Authorization header value for the configured auth type.

Parameters

Returns

string | undefined

The Authorization header value, or undefined in proxy mode.

Remarks

Returns the header value for REST or server-side WebSocket connections:

• 'token' → 'Token <apiKey>'
• 'bearer' → 'Bearer <apiKey>'

Returns undefined in proxy mode.

Inherited from

RestTTSProvider.resolveAuthHeader

resolveBaseUrl()

protected resolveBaseUrl(defaultUrl?): string | undefined;

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

Resolve the base URL for this provider.

Parameters

Returns

string | undefined

The resolved URL, or undefined when all sources are unset.

Remarks

Priority: proxyUrl > endpoint > defaultUrl.

For WebSocket providers (this.type === 'websocket'), the proxy URL’s http(s) scheme is automatically converted to ws(s).

When no URL is configured and defaultUrl is undefined, the return value is undefined — this lets SDK-based providers (Anthropic, OpenAI) fall back to their own built-in defaults.

Inherited from

RestTTSProvider.resolveBaseUrl

resolveWsProtocols()

protected resolveWsProtocols(defaultAuthType?): string[] | undefined;

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

Resolve WebSocket subprotocol for authentication.

Parameters

Returns

string[] | undefined

Subprotocol array for new WebSocket(url, protocols), or undefined.

Remarks

Returns the subprotocol array for direct mode based on authType:

• 'token' → ['token', apiKey] (Deepgram default)
• 'bearer' → ['bearer', apiKey] (OAuth/Bearer tokens)

Returns undefined in proxy mode (no client-side auth needed).

Inherited from

RestTTSProvider.resolveWsProtocols

synthesize()

synthesize(text): Promise<Blob>;

Defined in: src/providers/tts/openai/OpenAITTS.ts:248

Synthesizes text to audio using the OpenAI TTS REST API.

Parameters

Returns

Promise<Blob>

A Blob containing the synthesized audio in the configured format.

Throws

Error if the provider is not initialized.

Throws

Error if the OpenAI API request fails.

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