tts-queue

TTS audio streaming manager with sentence-boundary queuing, gapless playback, and fast interruption handling.

---

Description

tts-queue is the orchestration layer between text that needs to be spoken and audio that the user hears. It accepts text -- either as complete strings or as streaming token sequences from an LLM -- splits it into sentence-sized segments, sends each segment to a pluggable TTS provider for audio synthesis, and plays the resulting audio back-to-back through a pluggable audio sink.

The package handles every concern that sits between those two endpoints: sentence boundary detection (abbreviations, decimals, ellipsis, URLs), ordered FIFO playback queuing, per-segment lifecycle state management, cancellation of in-flight synthesis calls via AbortController, pause/resume, and error recovery. It replaces the 200-400 lines of async queue management, timer coordination, and provider-specific plumbing that every voice AI application otherwise implements from scratch.

Zero runtime dependencies. TypeScript-first. Provider-agnostic.

---

Installation

npm install tts-queue

Requires Node.js 18 or later.

---

Quick Start

import{createQueue}from'tts-queue';importtype{TTSProvider,AudioSink,AudioData,SegmentInfo}from'tts-queue';// 1. Define a TTS provider (wrap any TTS SDK)constprovider: TTSProvider={asyncsynthesize(text: string): Promise<AudioData>{constresponse=awaityourTTSClient.synthesize(text);return{buffer: response.audioBuffer,format: 'mp3',sizeBytes: response.audioBuffer.length,durationMs: response.durationMs,};},};// 2. Define an audio sink (where audio goes)constsink: AudioSink={asyncplay(audio: AudioData,segment: SegmentInfo): Promise<void>{awaitspeaker.play(audio.buffer);},};// 3. Create the queue and push textconstqueue=createQueue({ provider, sink });awaitqueue.push('Hello there. How are you doing today? The weather is nice.');// Sentences are split, synthesized, and played in order automatically.// 4. Wait for all segments to finishawaitqueue.drain();// 5. Clean upawaitqueue.close();

---

Features

• Sentence-boundary splitting -- Automatically segments text at sentence boundaries with handling for abbreviations (Dr., Mr., Mrs., etc.), decimal numbers, ellipsis, and URLs/domains.
• Clause-boundary fallback -- Long sentences exceeding maxChars are split at semicolons, em dashes, and commas.
• Short segment filtering -- Segments shorter than minChars are filtered to prevent choppy single-word synthesis.
• Provider-agnostic -- Works with any TTS provider through a simple TTSProvider interface. Swap providers without rewriting queue logic.
• Pluggable audio sinks -- Route audio to speakers, files, WebSockets, or test buffers via the AudioSink interface.
• Ordered FIFO playback -- Segments play in strict sequential order.
• Pause / Resume -- Suspend and resume playback without losing queue position. Calls through to sink pause() / resume() when available.
• Fast interruption -- cancel() aborts all in-flight synthesis calls via AbortController and transitions the queue to idle.
• Priority insertion -- pushImmediate() cancels pending segments and inserts new text at the front of the queue.
• Per-segment lifecycle -- Each segment progresses through pending, synthesizing, synthesized, playing, played (or failed / cancelled) with timestamp tracking at every transition.
• Typed events -- Subscribe to segment:start, segment:end, segment:error, queue:empty, queue:drain, and state:change events with full TypeScript typing.
• Callback hooks -- Optional onSegmentStart, onSegmentEnd, onSegmentError, and onQueueEmpty callbacks on QueueOptions.
• Queue statistics -- getStats() returns total, completed, failed, cancelled, and pending segment counts, total duration, and total characters processed.
• Custom splitting -- Provide a custom splitting.custom function to override the built-in sentence splitter.
• Zero runtime dependencies -- Only dev dependencies for TypeScript, ESLint, and Vitest.

---

API Reference

createQueue(options: QueueOptions): TTSQueue

Factory function that creates and returns a TTSQueue instance.

import{createQueue}from'tts-queue';constqueue=createQueue({
provider,// Required: TTSProvider
sink,// Required: AudioSinksplitting: {// Optional: splitting configurationmaxChars: 200,minChars: 10,on: 'sentence',custom: (text)=>text.split('\n'),},concurrency: 1,// Optional: concurrent synthesis limitprefetchCount: 2,// Optional: segments to pre-fetchonSegmentStart: (segment)=>{/* ... */},onSegmentEnd: (segment)=>{/* ... */},onSegmentError: (error,segment)=>{/* ... */},onQueueEmpty: ()=>{/* ... */},});

---

TTSQueue

The queue instance returned by createQueue. Implements the TTSQueue interface.

queue.push(text: string): Promise<SegmentInfo[]>

Split text into sentences and append segments to the queue. Returns the created SegmentInfo objects. Processing begins immediately.

constsegments=awaitqueue.push('First sentence. Second sentence. Third sentence.');console.log(segments.length);// 3

queue.pushImmediate(text: string): Promise<SegmentInfo[]>

Cancel all pending and in-progress segments, then insert new text at the front of the queue. Use this for interruption-and-replace patterns (e.g., the user asks a new question while the previous answer is still playing).

constsegments=awaitqueue.pushImmediate('Interrupting with new content.');

queue.pause(): Promise<void>

Pause playback. The queue transitions to paused state. If the sink implements pause(), it is called.

awaitqueue.pause();console.log(queue.getState());// 'paused'

queue.resume(): Promise<void>

Resume playback after a pause. The queue transitions back to playing state. If the sink implements resume(), it is called. Segment processing resumes automatically.

awaitqueue.resume();console.log(queue.getState());// 'playing'

queue.cancel(ids?: string[]): Promise<CancelResult>

Cancel segments. When called with no arguments, cancels all non-terminal segments, aborts in-flight synthesis via AbortController, and resets the queue to idle. When called with specific segment IDs, cancels only those segments.

// Cancel everythingconstresult=awaitqueue.cancel();console.log(result.cancelled);// number of segments cancelledconsole.log(result.ids);// IDs of cancelled segments// Cancel specific segmentsconstresult2=awaitqueue.cancel(['segment-id-1','segment-id-2']);

queue.drain(): Promise<void>

Wait for all segments to finish processing. Transitions the queue to draining state while segments complete, then resolves when the queue reaches idle.

awaitqueue.push('Some text to speak.');awaitqueue.drain();// resolves when all audio has finished playing

queue.close(): Promise<void>

Cancel all activity and permanently close the queue. Transitions to closed state. No more pushes are accepted after this call.

awaitqueue.close();console.log(queue.getState());// 'closed'

queue.getState(): QueueState

Returns the current queue state: 'idle', 'playing', 'paused', 'draining', or 'closed'.

queue.getStats(): QueueStats

Returns cumulative statistics for all segments processed by the queue.

conststats=queue.getStats();// {// totalSegments: 5,// completedSegments: 3,// failedSegments: 0,// cancelledSegments: 2,// pendingSegments: 0,// totalDurationMs: 4500,// totalChars: 312,// }

queue.getSegments(): SegmentInfo[]

Returns a snapshot (copy) of all segments and their current state.

queue.on<K>(event: K, listener: TTSQueueEvents[K]): void

Subscribe to a typed queue event.

queue.off<K>(event: K, listener: TTSQueueEvents[K]): void

Unsubscribe from a typed queue event.

---

Events

Event	Payload	Description
segment:start	SegmentInfo	Fired when synthesis begins for a segment
segment:end	SegmentInfo	Fired when a segment finishes playing
segment:error	TTSQueueError, SegmentInfo	Fired on synthesis or playback error
queue:empty	--	Fired when all segments have been played
queue:drain	--	Fired when the queue has been drained
state:change	QueueState	Fired on every queue state transition

---

splitSentences(text: string, options?: SplitOptions): string[]

Standalone sentence splitter. Used internally by createQueue, but also exported for direct use.

import{splitSentences}from'tts-queue';splitSentences('Dr. Smith went to the store. She bought apples.');// ['Dr. Smith went to the store.', 'She bought apples.']splitSentences('Hello. World.',{minLength: 1});// ['Hello.', 'World.']splitSentences('');// []

SplitOptions

Property	Type	Default	Description
minLength	number	10	Minimum segment length in characters. Shorter segments are filtered out.
maxLength	number	200	Maximum segment length. Longer segments are split at clause boundaries.
preserveWhitespace	boolean	false	When true, preserves leading/trailing whitespace in segments.

The built-in splitter handles:

• Abbreviations: Mr., Mrs., Ms., Dr., Prof., St., Jr., Sr., vs., etc., e.g., i.e., Fig., Approx., Dept., Est., Govt., Inc., Corp., Ltd., Co., U.S., U.K., U.N.
• Decimal numbers: 98.6, 3.14, $9.99 -- periods between digits are not treated as boundaries.
• Ellipsis: ... -- consecutive periods are not treated as boundaries.
• URLs and domains: example.com -- periods followed immediately by a letter or digit (no space) are not treated as boundaries.
• Single-letter initials: A. B. Smith -- single uppercase letters followed by a period are not treated as boundaries.
• Quoted strings: Sentence boundaries inside quoted strings (double quotes, smart quotes) are ignored.
• Long sentence fallback: Sentences exceeding maxLength are split at semicolons, em dashes (---, unicode em dash), then commas (only when both halves meet minLength).

---

createSegment(text: string, index: number): SegmentInfo

Create a new segment in pending state with a unique UUID, timestamp, and the given text and index.

import{createSegment}from'tts-queue';constsegment=createSegment('Hello world.',0);// { id: 'uuid', text: 'Hello world.', index: 0, state: 'pending', addedAt: Date }

---

transitionSegment(segment: SegmentInfo, newState: SegmentState, extra?: Partial<SegmentInfo>): SegmentInfo

Immutably transition a segment to a new state. Enforces the valid state transition graph and sets appropriate timestamps (synthesisStartedAt, synthesisCompletedAt, playbackStartedAt, playbackCompletedAt). Throws TTSQueueError on invalid transitions. The original segment object is never mutated.

Valid transitions:

pending -> synthesizing | cancelled
synthesizing -> synthesized | failed | cancelled
synthesized -> playing | cancelled
playing -> played | failed | cancelled
played -> (terminal)
failed -> (terminal)
cancelled -> (terminal)

---

TTSQueueError

Custom error class for all errors originating from the queue. Extends Error with additional context fields.

import{TTSQueueError}from'tts-queue';try{// ...}catch(err){if(errinstanceofTTSQueueError){console.log(err.name);// 'TTSQueueError'console.log(err.stage);// 'synthesis' | 'playback' | 'splitting' | 'internal'console.log(err.cause);// underlying Error, if anyconsole.log(err.segment);// SegmentInfo, if associated with a segment}}

Error Factory Functions

Function	Stage	Description
synthError	synthesis	TTS provider synthesis failure
playbackError	playback	Audio sink playback failure
splittingError	splitting	Text splitting failure
internalError	internal	Queue internal error (invalid state)

Each factory accepts (message: string, cause?: Error, segment?: SegmentInfo) and returns a TTSQueueError.

import{synthError}from'tts-queue';consterr=synthError('Provider timeout',newError('ETIMEDOUT'),segmentInfo);

---

Configuration

QueueOptions

Property	Type	Required	Default	Description
provider	TTSProvider	Yes	--	TTS synthesis provider
sink	AudioSink	Yes	--	Audio output destination
splitting	SplittingOptions	No	{}	Sentence splitting configuration
concurrency	number	No	1	Maximum concurrent synthesis calls
prefetchCount	number	No	2	Number of segments to pre-fetch ahead of playback
onSegmentStart	(segment: SegmentInfo) => void	No	--	Callback when a segment begins synthesis
onSegmentEnd	(segment: SegmentInfo) => void	No	--	Callback when a segment finishes playback
onSegmentError	(error: TTSQueueError, segment) => void	No	--	Callback on segment-level errors
onQueueEmpty	() => void	No	--	Callback when all segments have completed

SplittingOptions

Property	Type	Default	Description
maxChars	number	200	Maximum segment length before clause-boundary split
minChars	number	10	Minimum segment length; shorter segments are filtered
on	'sentence' | 'word' | 'paragraph'	'sentence'	Splitting strategy hint
custom	(text: string) => string[]	--	Custom splitter function; overrides built-in logic

TTSProvider Interface

interfaceTTSProvider{synthesize(text: string,options?: SynthesisOptions): Promise<AudioData>;synthesizeStream?(text: string,options?: SynthesisOptions): AsyncIterable<AudioChunk>;}

Method	Required	Description
synthesize	Yes	Synthesize text into a complete audio buffer
synthesizeStream	No	Synthesize text as a stream of audio chunks

SynthesisOptions

Property	Type	Description
voice	string	Voice identifier for the TTS engine
speed	number	Playback speed multiplier
format	AudioFormat	Desired output audio format
sampleRate	number	Desired output sample rate in Hz

AudioSink Interface

interfaceAudioSink{play(audio: AudioData,segment: SegmentInfo): Promise<void>;pause?(): Promise<void>;resume?(): Promise<void>;stop?(): Promise<void>;}

Method	Required	Description
play	Yes	Play audio data for a given segment
pause	No	Pause current playback
resume	No	Resume paused playback
stop	No	Immediately stop all playback

AudioData

Property	Type	Required	Description
buffer	Buffer	Yes	Raw audio bytes
format	AudioFormat	Yes	Audio codec: 'mp3' | 'wav' | 'ogg' | 'pcm' | 'aac' | 'opus'
sizeBytes	number	Yes	Size of the audio buffer in bytes
sampleRate	number	No	Sample rate in Hz
channels	number	No	Number of audio channels
durationMs	number	No	Duration of the audio in milliseconds

SegmentInfo

Property	Type	Description
id	string	Unique UUID for the segment
text	string	Source text for the segment
index	number	0-based position in the queue
state	SegmentState	Current lifecycle state
addedAt	Date	Timestamp when the segment was created
synthesisStartedAt	Date	Timestamp when synthesis began (optional)
synthesisCompletedAt	Date	Timestamp when synthesis completed (optional)
playbackStartedAt	Date	Timestamp when playback began (optional)
playbackCompletedAt	Date	Timestamp when playback completed (optional)
durationMs	number	Audio duration in milliseconds (optional)
error	Error	Error that caused failure (optional)

---

Error Handling

All errors emitted by the queue are instances of TTSQueueError with a stage property indicating where the error originated.

Synthesis Errors

When a TTS provider's synthesize() call throws or rejects, the segment transitions to failed, a segment:error event is emitted with stage: 'synthesis', and the queue advances to the next segment. The queue does not stop.

queue.on('segment:error',(error,segment)=>{if(error.stage==='synthesis'){console.error(`Synthesis failed for "${segment.text}":`,error.cause);}});

Playback Errors

When the audio sink's play() method throws, the segment transitions to failed, a segment:error event is emitted with stage: 'playback', and the queue advances to the next segment.

Cancellation Errors

If a synthesis call is aborted via cancel(), the AbortController signal fires and the segment transitions to cancelled without emitting an error event. This is the expected path for interruptions.

Closed Queue

Calling push() or pushImmediate() on a closed queue throws a TTSQueueError with stage: 'internal' and the message "Queue is closed".

Invalid State Transitions

Attempting an invalid segment state transition (e.g., pending to played) throws a TTSQueueError with stage: 'internal'. This guards against programming errors in provider or sink implementations.

---

Advanced Usage

Priority Interruption

Replace the current playback with new content immediately:

// User asks a new question while the previous answer is playingawaitqueue.pushImmediate('Here is the answer to your new question.');// All pending/in-progress segments are cancelled, new text takes priority

Selective Cancellation

Cancel specific segments by ID while allowing others to continue:

constsegments=awaitqueue.push('Sentence one. Sentence two. Sentence three.');// Cancel only the last segmentawaitqueue.cancel([segments[2].id]);

Custom Sentence Splitting

Override the built-in splitter with your own logic:

constqueue=createQueue({
provider,
sink,splitting: {custom: (text)=>text.split(/\n\n/),// Split on double newlines},});

Event-Driven Progress Tracking

queue.on('segment:start',(segment)=>{console.log(`Synthesizing: "${segment.text}" (segment ${segment.index})`);});queue.on('segment:end',(segment)=>{console.log(`Finished: "${segment.text}" (${segment.durationMs}ms)`);});queue.on('state:change',(state)=>{console.log(`Queue state: ${state}`);});queue.on('queue:empty',()=>{console.log('All segments processed');});

Monitoring with Callbacks

constqueue=createQueue({
provider,
sink,onSegmentStart: (seg)=>metrics.trackSynthesisStart(seg.id),onSegmentEnd: (seg)=>metrics.trackSynthesisEnd(seg.id,seg.durationMs),onSegmentError: (err,seg)=>logger.error({ err,segmentId: seg.id}),onQueueEmpty: ()=>logger.info('Queue drained'),});

OpenAI TTS Provider Example

importOpenAIfrom'openai';importtype{TTSProvider,AudioData}from'tts-queue';constopenai=newOpenAI();constopenaiProvider: TTSProvider={asyncsynthesize(text: string): Promise<AudioData>{constresponse=awaitopenai.audio.speech.create({model: 'tts-1',voice: 'alloy',input: text,response_format: 'mp3',});constarrayBuffer=awaitresponse.arrayBuffer();constbuffer=Buffer.from(arrayBuffer);return{
buffer,format: 'mp3',sizeBytes: buffer.length,};},};

ElevenLabs TTS Provider Example

importtype{TTSProvider,AudioData}from'tts-queue';constelevenLabsProvider: TTSProvider={asyncsynthesize(text: string): Promise<AudioData>{constresponse=awaitfetch(`https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,{method: 'POST',headers: {'xi-api-key': process.env.ELEVENLABS_API_KEY!,'Content-Type': 'application/json',},body: JSON.stringify({ text,model_id: 'eleven_monolingual_v1'}),},);constarrayBuffer=awaitresponse.arrayBuffer();constbuffer=Buffer.from(arrayBuffer);return{
buffer,format: 'mp3',sizeBytes: buffer.length,};},};

Test Buffer Sink

Collect all audio data in memory for assertions:

importtype{AudioSink,AudioData,SegmentInfo}from'tts-queue';functioncreateTestSink(): AudioSink&{played: SegmentInfo[]}{constplayed: SegmentInfo[]=[];return{
played,asyncplay(audio: AudioData,segment: SegmentInfo): Promise<void>{played.push(segment);},};}

---

TypeScript

tts-queue is written in TypeScript and ships with full type declarations (dist/index.d.ts). All exports are fully typed.

Exported Types

importtype{// Core interfacesTTSQueue,TTSProvider,AudioSink,QueueOptions,// Data typesAudioData,AudioChunk,AudioFormat,// 'mp3' | 'wav' | 'ogg' | 'pcm' | 'aac' | 'opus'SynthesisOptions,// Segment typesSegmentInfo,SegmentState,// 'pending' | 'synthesizing' | 'synthesized' | 'playing'// | 'played' | 'cancelled' | 'failed'// Queue typesQueueState,// 'idle' | 'playing' | 'paused' | 'draining' | 'closed'QueueStats,CancelResult,TTSQueueEvents,// SplittingSplittingOptions,SplitOptions,// ErrorsTTSQueueStage,// 'synthesis' | 'playback' | 'splitting' | 'internal'}from'tts-queue';

Exported Values

import{createQueue,splitSentences,createSegment,transitionSegment,TTSQueueError,synthError,playbackError,splittingError,internalError,}from'tts-queue';

---

License

MIT