oneringaiv2
Documentation/Text-to-Speech (TTS)
v2.0.0-beta.1Snapshot bebdcd1Markdown ↗

Text-to-Speech (TTS)

Text-to-Speech (TTS)

Convert text to spoken audio

TextToSpeech class

📍 src/core/TextToSpeech.ts:55

TextToSpeech capability class Provides text-to-speech synthesis with model introspection

Example:

typescript
const tts = TextToSpeech.create({
  connector: 'openai',
  model: 'tts-1-hd',
  voice: 'nova',
});

const audio = await tts.synthesize('Hello, world!');
await tts.toFile('Hello', './output.mp3');
Static Methods

static create()

Create a new TextToSpeech instance

typescript
static create(config: TextToSpeechConfig): TextToSpeech

Parameters:

  • config: TextToSpeechConfig

Returns: TextToSpeech

Methods

synthesize()

Synthesize speech from text

typescript
async synthesize(
    text: string,
    options?: Partial<Omit<TTSOptions, 'model' | 'input'>>
  ): Promise<TTSResponse>

Parameters:

  • text: string
  • options: Partial<Omit<TTSOptions, "model" | "input">> | undefined (optional)

Returns: Promise<TTSResponse>

toFile()

Synthesize speech and save to file

typescript
async toFile(
    text: string,
    filePath: string,
    options?: Partial<Omit<TTSOptions, 'model' | 'input'>>
  ): Promise<void>

Parameters:

  • text: string
  • filePath: string
  • options: Partial<Omit<TTSOptions, "model" | "input">> | undefined (optional)

Returns: Promise<void>

supportsStreaming()

Check if the underlying provider supports streaming TTS

typescript
supportsStreaming(format?: AudioFormat): boolean

Parameters:

  • format: AudioFormat | undefined (optional)

Returns: boolean

synthesizeStream()

Stream TTS audio chunks as they arrive from the API. Falls back to buffered synthesis yielding a single chunk if provider doesn't support streaming.

typescript
async *synthesizeStream(
    text: string,
    options?: Partial<Omit<TTSOptions, 'model' | 'input'>>
  ): AsyncIterableIterator<TTSStreamChunk>

Parameters:

  • text: string
  • options: Partial<Omit<TTSOptions, "model" | "input">> | undefined (optional)

Returns: AsyncIterableIterator<TTSStreamChunk>

getModelInfo()

Get model information for current or specified model

typescript
getModelInfo(model?: string): ITTSModelDescription

Parameters:

  • model: string | undefined (optional)

Returns: ITTSModelDescription

getModelCapabilities()

Get model capabilities

typescript
getModelCapabilities(model?: string)

Parameters:

  • model: string | undefined (optional)

Returns: TTSModelCapabilities

listVoices()

List all available voices for current model For dynamic voice providers (e.g., ElevenLabs), fetches from API For static providers (e.g., OpenAI), returns from registry

typescript
async listVoices(model?: string): Promise<IVoiceInfo[]>

Parameters:

  • model: string | undefined (optional)

Returns: Promise<IVoiceInfo[]>

listAvailableModels()

List all available models for this provider's vendor

typescript
listAvailableModels(): ITTSModelDescription[]

Returns: ITTSModelDescription[]

supportsFeature()

Check if a specific feature is supported by the model

typescript
supportsFeature(
    feature: keyof ITTSModelDescription['capabilities']['features'],
    model?: string
  ): boolean

Parameters:

  • feature: "streaming" | "ssml" | "emotions" | "voiceCloning" | "wordTimestamps" | "instructionSteering"
  • model: string | undefined (optional)

Returns: boolean

getSupportedFormats()

Get supported audio formats for the model

typescript
getSupportedFormats(model?: string): readonly AudioFormat[] | AudioFormat[]

Parameters:

  • model: string | undefined (optional)

Returns: readonly AudioFormat[] | AudioFormat[]

getSupportedLanguages()

Get supported languages for the model

typescript
getSupportedLanguages(model?: string): readonly string[] | string[]

Parameters:

  • model: string | undefined (optional)

Returns: readonly string[] | string[]

supportsSpeedControl()

Check if speed control is supported

typescript
supportsSpeedControl(model?: string): boolean

Parameters:

  • model: string | undefined (optional)

Returns: boolean

setModel()

Update default model

typescript
setModel(model: string): void

Parameters:

  • model: string

Returns: void

setVoice()

Update default voice

typescript
setVoice(voice: string): void

Parameters:

  • voice: string

Returns: void

setFormat()

Update default format

typescript
setFormat(format: AudioFormat): void

Parameters:

  • format: AudioFormat

Returns: void

setSpeed()

Update default speed

typescript
setSpeed(speed: number): void

Parameters:

  • speed: number

Returns: void

ITTSModelDescription interface

📍 src/domain/entities/TTSModel.ts:82

Complete TTS model description

Properties
Property Type Description
capabilities capabilities: TTSModelCapabilities; -
pricing? pricing?: TTSModelPricing; -

STTStreamEvent interface

📍 src/domain/interfaces/IAudioProvider.ts:225

Normalized event emitted by a live transcription session.

Properties
Property Type Description
type `type: 'created' 'transcript'
text? text?: string; -
isFinal? isFinal?: boolean; -
speechFinal? speechFinal?: boolean; -
channel? channel?: number; -
durationSeconds? durationSeconds?: number; -
words? words?: WordTimestamp[]; -
endOfTurnConfidence? endOfTurnConfidence?: number; End-of-turn confidence when the provider's semantic turn detector is enabled.
raw raw: Record<string, unknown>; Original provider event for fields not represented by the normalized contract.

STTStreamOptions interface

📍 src/domain/interfaces/IAudioProvider.ts:213

Audio source and normalized controls for a live transcription session.

Properties
Property Type Description
audio `audio: AsyncIterable<STTStreamInput> Iterable<STTStreamInput>;`
sampleRate? `sampleRate?: 8000 16000
encoding? `encoding?: 'pcm' 'mulaw'
interimResults? interimResults?: boolean; Emit mutable interim transcript events in addition to finalized chunks.

TextToSpeechConfig interface

📍 src/core/TextToSpeech.ts:22

Configuration for TextToSpeech capability

Properties
Property Type Description
connector `connector: string Connector;`
model? model?: string; Default model to use
voice? voice?: string; Default voice to use
format? format?: AudioFormat; Default audio format
speed? speed?: number; Default speed (0.25 to 4.0)

TTSModelCapabilities interface

📍 src/domain/entities/TTSModel.ts:20

TTS model capabilities

Properties
Property Type Description
voices voices: IVoiceInfo[]; Available voices (empty array means fetch dynamically via API)
formats `formats: readonly AudioFormat[] AudioFormat[];`
languages `languages: readonly string[] string[];`
speed `speed: { 
supported: boolean;
min?: number;
max?: number;
default?: number;

};| Speed control support | |features|features: { /** Real-time streaming support / streaming: boolean; /* SSML markup support / ssml: boolean; /* Emotion/style control / emotions: boolean; /* Custom voice cloning / voiceCloning: boolean; /* Word-level timestamps / wordTimestamps: boolean; /* Instruction steering (prompt-based style control) / instructionSteering?: boolean; };| Feature support flags | |limits|limits: { /* Maximum input length in characters / maxInputLength: number; /* Rate limit (requests per minute) */ maxRequestsPerMinute?: number; };| Model limits | |vendorOptions?|vendorOptions?: Record<string, VendorOptionSchema>;` | Vendor-specific options schema |

TTSOptions interface

📍 src/domain/interfaces/IAudioProvider.ts:16

Options for text-to-speech synthesis

Properties
Property Type Description
model model: string; Model to use (e.g., 'tts-1', 'gpt-4o-mini-tts')
input input: string; Text to synthesize
voice voice: string; Voice ID to use.
For OpenAI: a built-in name (alloy, ash, ballad, coral, echo,
fable, onyx, nova, sage, shimmer, verse, marin, cedar) or
a custom-voice ID with the voice_ prefix (e.g. voice_1234). Custom IDs
are forwarded to the SDK as { id } automatically.
format? format?: AudioFormat; Audio output format
speed? speed?: number; Speech speed (0.25 to 4.0, vendor-dependent)
vendorOptions? vendorOptions?: Record&lt;string, unknown&gt;; Vendor-specific options passthrough

TTSResponse interface

📍 src/domain/interfaces/IAudioProvider.ts:45

Response from text-to-speech synthesis

Properties
Property Type Description
audio audio: Buffer; Audio data as Buffer
format format: AudioFormat; Format of the audio
durationSeconds? durationSeconds?: number; Duration in seconds (if available)
charactersUsed? charactersUsed?: number; Number of characters used (for billing)
characterTimestamps? characterTimestamps?: Array&lt;{ character: string; start: number; end: number }&gt;; Optional provider-supplied character alignment data.

TTSStreamChunk interface

📍 src/domain/interfaces/IAudioProvider.ts:80

A single chunk of streamed TTS audio

Properties
Property Type Description
audio audio: Buffer; Audio data for this chunk
isFinal isFinal: boolean; True when this is the last chunk

STTStreamInput type

📍 src/domain/interfaces/IAudioProvider.ts:210

Input frame for live STT. finalize ends the current utterance without closing the session.

typescript
type STTStreamInput = Buffer | { type: 'finalize'; channel?: number }

calculateTTSCost function

📍 src/domain/entities/TTSModel.ts:460

Calculate estimated cost for TTS For OpenAI models: based on character count For Google models: based on input/output token count

typescript
export function calculateTTSCost(
  modelName: string,
  characterCount: number,
  options?: { inputTokens?: number; outputTokens?: number }
): number | null

getTTSModelsWithFeature function

📍 src/domain/entities/TTSModel.ts:447

Get TTS models that support a specific feature

typescript
export function getTTSModelsWithFeature(
  feature: keyof ITTSModelDescription['capabilities']['features']
): ITTSModelDescription[]

TTS_MODEL_REGISTRY const

📍 src/domain/entities/TTSModel.ts:140

Complete TTS model registry Last full audit: October 2026

Properties
Property Type Description
'gpt-4o-mini-tts' `{ 
name: 'gpt-4o-mini-tts',
displayName: 'GPT-4o Mini TTS',
provider: Vendor.OpenAI,
description: 'Instruction-steerable TTS with emotional control via prompts',
isActive: true,
releaseDate: '2025-03-01',
sources: {
  documentation: 'https://platform.openai.com/docs/guides/text-to-speech',
  pricing: 'https://openai.com/pricing',
  lastVerified: '2026-08-30',
},
capabilities: {
  ...OPENAI_TTS_BASE,
  features: {
    streaming: false, // Not implementing streaming in v1
    ssml: false,
    emotions: true, // Via instruction steering
    voiceCloning: true,
    wordTimestamps: false,
    instructionSteering: true,
  },
  limits: { maxInputLength: 2000 },
  vendorOptions: {
    instructions: {
      type: 'string',
      description: 'Natural language instructions for voice style (e.g., "speak like a calm meditation guide")',
    },
  },
},
pricing: { per1kCharacters: 0.015, currency: 'USD' },

}| - | |'tts-1'|{ name: 'tts-1', displayName: 'TTS-1', provider: Vendor.OpenAI, description: 'Fast, low-latency text-to-speech optimized for real-time use', isActive: true, releaseDate: '2023-11-06', sources: { documentation: 'https://platform.openai.com/docs/guides/text-to-speech', pricing: 'https://openai.com/pricing', lastVerified: '2026-08-30', }, capabilities: { ...OPENAI_TTS_BASE, features: { streaming: false, // Not implementing streaming in v1 ssml: false, emotions: false, voiceCloning: false, wordTimestamps: false, }, limits: { maxInputLength: 4096 }, }, pricing: { per1kCharacters: 0.015, currency: 'USD' }, }| - | |'tts-1-hd'|{ name: 'tts-1-hd', displayName: 'TTS-1 HD', provider: Vendor.OpenAI, description: 'High-definition text-to-speech with improved audio quality', isActive: true, releaseDate: '2023-11-06', sources: { documentation: 'https://platform.openai.com/docs/guides/text-to-speech', pricing: 'https://openai.com/pricing', lastVerified: '2026-08-30', }, capabilities: { ...OPENAI_TTS_BASE, features: { streaming: false, // Not implementing streaming in v1 ssml: false, emotions: false, voiceCloning: false, wordTimestamps: false, }, limits: { maxInputLength: 4096 }, }, pricing: { per1kCharacters: 0.030, currency: 'USD' }, }| - | |'gemini-3.8-flash-tts'|{ name: 'gemini-3.8-flash-tts', displayName: 'Gemini 3.8 Flash TTS', provider: Vendor.Google, description: 'Flagship creative TTS for studio-grade fidelity, expressive acting, regional dialects, voice design, and replication', isActive: true, lifecycle: 'active', availability: 'public', preferred: true, endpoints: ['audio_speech', 'generate_content', 'batch'], releaseDate: '2026-09-22', sources: { documentation: 'https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash-tts', pricing: 'https://ai.google.dev/gemini-api/docs/pricing', lastVerified: '2026-10-07' }, capabilities: { voices: GEMINI_VOICES, formats: ['wav'], languages: [...GEMINI_TTS_LANGUAGES], speed: { supported: false }, features: { streaming: false, ssml: false, emotions: true, voiceCloning: true, wordTimestamps: false, instructionSteering: true }, limits: { maxInputLength: 8192 }, vendorOptions: { stylePrompt: { type: 'string', description: 'Natural-language narration and delivery instructions' }, voiceId: { type: 'string', description: 'Extended-library, designed, or replicated voice resource ID' }, }, }, pricing: { perMInputTokens: 1, perMOutputTokens: 20, currency: 'USD' }, }| - | |'gemini-3.8-flash-lite-tts'|{ name: 'gemini-3.8-flash-lite-tts', displayName: 'Gemini 3.8 Flash-Lite TTS', provider: Vendor.Google, description: 'Fast, cost-efficient TTS for high-throughput speech, voice-agent cascades, and voice replication', isActive: true, lifecycle: 'active', availability: 'public', preferred: true, endpoints: ['audio_speech', 'generate_content', 'batch'], releaseDate: '2026-09-22', sources: { documentation: 'https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash-lite-tts', pricing: 'https://ai.google.dev/gemini-api/docs/pricing', lastVerified: '2026-10-07' }, capabilities: { voices: GEMINI_VOICES, formats: ['wav'], languages: [...GEMINI_TTS_LANGUAGES], speed: { supported: false }, features: { streaming: false, ssml: false, emotions: true, voiceCloning: true, wordTimestamps: false, instructionSteering: true }, limits: { maxInputLength: 8192 }, vendorOptions: { stylePrompt: { type: 'string', description: 'Natural-language narration and delivery instructions' }, voiceId: { type: 'string', description: 'Extended-library, designed, or replicated voice resource ID' }, }, }, pricing: { perMInputTokens: 0.5, perMOutputTokens: 6, currency: 'USD' }, }| - | |'gemini-3.1-flash-tts-preview'|{ name: 'gemini-3.1-flash-tts-preview', displayName: 'Gemini 3.1 Flash TTS Preview', provider: Vendor.Google, description: 'Current low-latency Gemini speech model with steerable prompts and expressive audio tags', isActive: true, lifecycle: 'legacy', availability: 'public', replacementModel: 'gemini-3.8-flash-lite-tts', endpoints: ['audio_speech', 'generate_content', 'batch'], releaseDate: '2026-04-01', sources: { documentation: 'https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-tts-preview', pricing: 'https://ai.google.dev/gemini-api/docs/pricing', lastVerified: '2026-08-30', }, capabilities: { voices: GEMINI_VOICES, formats: ['wav'], languages: [...GEMINI_TTS_LANGUAGES], speed: { supported: false }, features: { streaming: false, ssml: false, emotions: true, voiceCloning: false, wordTimestamps: false, instructionSteering: true, }, limits: { maxInputLength: 8192 }, vendorOptions: { stylePrompt: { type: 'string', description: 'Natural-language narration and delivery instructions' }, }, }, pricing: { perMInputTokens: 1, perMOutputTokens: 20, currency: 'USD' }, }| - | |'gemini-2.5-flash-preview-tts'|{ name: 'gemini-2.5-flash-preview-tts', displayName: 'Gemini 2.5 Flash TTS', provider: Vendor.Google, description: 'Google Gemini 2.5 Flash TTS - optimized for low latency, 30 voices, 70+ languages', isActive: true, lifecycle: 'deprecated', deprecationDate: '2026-09-22', retirementDate: '2026-11-17', replacementModel: 'gemini-3.8-flash-lite-tts', releaseDate: '2025-01-01', sources: { documentation: 'https://ai.google.dev/gemini-api/docs/speech-generation', pricing: 'https://ai.google.dev/pricing', lastVerified: '2026-08-30', }, capabilities: { voices: GEMINI_VOICES, formats: ['wav'] as const, // PCM output, 24kHz 16-bit mono languages: [...GEMINI_TTS_LANGUAGES], speed: { supported: false }, // Speed not directly configurable features: { streaming: false, // Not implementing streaming in v1 ssml: false, emotions: true, // Supports affective dialogue voiceCloning: false, wordTimestamps: false, }, limits: { maxInputLength: 32000 }, // 32k token context window }, pricing: { perMInputTokens: 0.50, // $0.50 per 1M input tokens perMOutputTokens: 10.00, // $10.00 per 1M output tokens currency: 'USD', }, }| - | |'gemini-2.5-pro-preview-tts'|{ name: 'gemini-2.5-pro-preview-tts', displayName: 'Gemini 2.5 Pro TTS', provider: Vendor.Google, description: 'Google Gemini 2.5 Pro TTS - optimized for quality, 30 voices, 70+ languages', isActive: true, lifecycle: 'deprecated', deprecationDate: '2026-09-22', retirementDate: '2026-11-17', replacementModel: 'gemini-3.8-flash-tts', releaseDate: '2025-01-01', sources: { documentation: 'https://ai.google.dev/gemini-api/docs/speech-generation', pricing: 'https://ai.google.dev/pricing', lastVerified: '2026-08-30', }, capabilities: { voices: GEMINI_VOICES, formats: ['wav'] as const, // PCM output, 24kHz 16-bit mono languages: [...GEMINI_TTS_LANGUAGES], speed: { supported: false }, // Speed not directly configurable features: { streaming: false, // Not implementing streaming in v1 ssml: false, emotions: true, // Supports affective dialogue voiceCloning: false, wordTimestamps: false, }, limits: { maxInputLength: 32000 }, // 32k token context window }, pricing: { perMInputTokens: 1.00, // $1.00 per 1M input tokens perMOutputTokens: 20.00, // $20.00 per 1M output tokens currency: 'USD', }, }| - | |'xai-tts'|{ name: 'xai-tts', displayName: 'xAI Text to Speech', provider: Vendor.Grok, description: 'Expressive multilingual xAI speech synthesis with inline speech tags and telephony codecs', isActive: true, lifecycle: 'active', availability: 'public', preferred: true, endpoints: ['audio_speech'], releaseDate: '2026-07-23', sources: { documentation: 'https://docs.x.ai/developers/model-capabilities/audio/text-to-speech', pricing: 'https://docs.x.ai/developers/pricing', lastVerified: '2026-08-30', }, capabilities: { voices: XAI_VOICES, formats: ['mp3', 'wav', 'pcm', 'mulaw', 'alaw'], languages: ['auto', ...COMMON_LANGUAGES.CORE], speed: { supported: true, min: 0.7, max: 1.5, default: 1 }, features: { streaming: true, ssml: false, emotions: true, voiceCloning: true, wordTimestamps: true, instructionSteering: true, }, limits: { maxInputLength: 15000 }, vendorOptions: { language: { type: 'string', description: 'BCP-47 language code or automatic detection', default: 'auto' }, output_format: { type: 'object', description: 'xAI codec, sample-rate, and bitrate configuration' }, optimize_streaming_latency: { type: 'number', description: 'Latency optimization level', min: 0, max: 2, default: 0 }, text_normalization: { type: 'boolean', description: 'Normalize numbers and symbols before synthesis', default: false }, with_timestamps: { type: 'boolean', description: 'Return character-level timing metadata', default: false }, }, }, pricing: { per1kCharacters: 0.015, currency: 'USD' }, }` | - |

Documentation snapshot · 2026-11-02Suggest a correction ↗

Search documentation

Type to search the v2 documentation.

↑ ↓ to navigate Esc to close