OpenAITTS

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

OpenAI TTS provider using the official OpenAI SDK 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.

The lifecycle is:

1. Construct with OpenAITTSConfig
2. Call initialize() to load the OpenAI SDK and create the client
3. Call synthesize(text) to convert text to audio
4. Call dispose() to release resources

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

Creates a new OpenAITTS provider instance.

Parameters

Returns

OpenAITTS

Example

const tts = new OpenAITTS({
  apiKey: 'sk-xxxxxxxxxxxx',
  voice: 'alloy',
});

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

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

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

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

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

Disposes the provider and releases the OpenAI client.

Returns

Promise<void>

Overrides

RestTTSProvider.onDispose

onInitialize()

protected onInitialize(): Promise<void>;

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

Initializes the OpenAI client by dynamically importing the SDK.

Returns

Promise<void>

Remarks

The openai package is loaded dynamically as a peer dependency. If using proxyUrl, the client is configured with a placeholder API key and the proxy URL as the base URL. The client is created with dangerouslyAllowBrowser: true to enable browser usage.

Throws

ProviderInitializationError if neither apiKey nor proxyUrl is configured.

Throws

ProviderInitializationError if the openai package is not installed.

Throws

ProviderInitializationError if any other initialization error occurs.

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

synthesize()

synthesize(text): Promise<Blob>;

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

Synthesizes text to audio using the OpenAI TTS REST API.

Parameters

Returns

Promise<Blob>

A Blob containing the synthesized audio in the configured format.

Remarks

Makes a single HTTP POST request to the OpenAI audio.speech.create endpoint. The complete audio response is returned as a Blob with the appropriate MIME type based on the configured responseFormat.

Throws

Error if the provider is not initialized or the OpenAI client is null.

Throws

Error if the OpenAI API request fails (network error, rate limit, etc.).

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