bodhi-realtime-agent / TTSProvider
Interface: TTSProvider
Defined in: src/types/tts.ts:27
Provider-agnostic interface for pluggable text-to-speech providers.
VoiceSession creates the provider, calls configure() with the preferred output format, then start(). Text flows in via synthesize() with a requestId for turn correlation; audio chunks flow out via onAudio callback tagged with the same requestId. The provider handles streaming, buffering, and chunked delivery internally.
Actor-mode only — not used in legacy orchestration path.
Properties
onAudio?
optionalonAudio?: (base64Pcm,durationMs,requestId) =>void
Defined in: src/types/tts.ts:75
Audio chunk ready for delivery to client.
Parameters
base64Pcm
string
Base64-encoded PCM audio chunk
durationMs
number
Duration of this chunk in milliseconds
requestId
number
The requestId from the synthesize() call that produced this audio
Returns
void
onDone?
optionalonDone?: (requestId) =>void
Defined in: src/types/tts.ts:81
Synthesis completed for a request. Fired after the final audio chunk for the given requestId. VoiceSession uses this to gate turn completion.
Parameters
requestId
number
The requestId that has completed synthesis
Returns
void
onError?
optionalonError?: (error,fatal) =>void
Defined in: src/types/tts.ts:94
Error during synthesis. Non-fatal errors are logged; fatal errors trigger session close (fail-fast in V1).
Parameters
error
Error
fatal
boolean
Returns
void
onWordBoundary?
optionalonWordBoundary?: (word,offsetMs,requestId) =>void
Defined in: src/types/tts.ts:90
Word-level timing for caption synchronization (optional). Providers that support word timestamps (Cartesia, ElevenLabs) fire this for real-time caption alignment on the client. NOTE: This is for timing metadata only, NOT for output transcription.
Parameters
word
string
The spoken word
offsetMs
number
Offset from the start of synthesis for this requestId, in milliseconds
requestId
number
The requestId this word belongs to
Returns
void
Methods
cancel()
cancel():
void
Defined in: src/types/tts.ts:67
Cancel any in-progress synthesis (best-effort). Called when the user interrupts (barge-in). Provider SHOULD stop generating audio as quickly as possible and clear internal buffers. Late-arriving audio chunks after cancel() are safe — VoiceSession filters them via requestId.
Returns
void
configure()
configure(
preferred):TTSAudioConfig
Defined in: src/types/tts.ts:37
Called once before start(). Provider receives the preferred output format (derived from the transport's outputSampleRate) and returns the actual format it will produce. If the provider can emit at the preferred rate natively, it SHOULD do so to avoid resampling overhead.
Parameters
preferred
The ideal output format (sampleRate, bitDepth, channels)
Returns
The actual output format the provider will produce
start()
start():
Promise<void>
Defined in: src/types/tts.ts:40
Open connection (WebSocket for streaming providers).
Returns
Promise<void>
stop()
stop():
Promise<void>
Defined in: src/types/tts.ts:43
Close connection and release resources.
Returns
Promise<void>
synthesize()
synthesize(
text,requestId,options?):void
Defined in: src/types/tts.ts:59
Synthesize text into speech. Called with text chunks as they arrive from the LLM. The provider decides internally whether to buffer for sentence boundaries or stream immediately.
Parameters
text
string
Partial or complete text from LLM response
requestId
number
Monotonic ID correlating this text to a specific turn/response. All onAudio/onDone callbacks for this text MUST carry the same requestId.
options?
flush?
boolean
If true, this is the end of input for requestId: flush any buffered text and finalize the request. The provider MUST eventually emit onDone for requestId unless it is cancelled or fails. VoiceSession issues this from onTextDone (end of the LLM text stream for a turn).
Returns
void