|
| 1 | +/** |
| 2 | + * @file AdaptiveSentenceChunker.ts |
| 3 | + * @description Buffers LLM token stream and emits complete sentence chunks. |
| 4 | + * |
| 5 | + * {@link AdaptiveSentenceChunker} sits between the LLM token stream and the |
| 6 | + * TTS synthesis pipeline. Rather than synthesising each tiny token fragment |
| 7 | + * individually, it accumulates tokens and emits a `'sentence'` event whenever |
| 8 | + * a sentence boundary is detected (`.`, `?`, `!`, `;` followed by whitespace |
| 9 | + * or end-of-input). A fallback flush timer ensures audio is never blocked |
| 10 | + * indefinitely on fragments that lack terminal punctuation. |
| 11 | + * |
| 12 | + * @module streaming-tts-openai/AdaptiveSentenceChunker |
| 13 | + */ |
| 14 | + |
| 15 | +import { EventEmitter } from 'node:events'; |
| 16 | + |
| 17 | +// --------------------------------------------------------------------------- |
| 18 | +// Regex — compiled once at module load |
| 19 | +// --------------------------------------------------------------------------- |
| 20 | + |
| 21 | +/** |
| 22 | + * Matches the first complete sentence within a string. |
| 23 | + * |
| 24 | + * Capture group 1: the sentence (including its terminal punctuation mark). |
| 25 | + * Capture group 2: remaining text after the inter-sentence whitespace. |
| 26 | + * |
| 27 | + * The `s` flag enables `.` to match newlines so multi-line inputs work. |
| 28 | + */ |
| 29 | +const SENTENCE_BOUNDARY = /^(.*?[.?!;])\s(.*)/s; |
| 30 | + |
| 31 | +// --------------------------------------------------------------------------- |
| 32 | +// Class |
| 33 | +// --------------------------------------------------------------------------- |
| 34 | + |
| 35 | +/** |
| 36 | + * Token accumulator that splits LLM output into TTS-friendly sentence chunks. |
| 37 | + * |
| 38 | + * ### Events |
| 39 | + * |
| 40 | + * | Event | Payload | Description | |
| 41 | + * |--------------|----------|------------------------------------------------| |
| 42 | + * | `'sentence'` | `string` | A complete sentence ready for TTS synthesis | |
| 43 | + * |
| 44 | + * ### Usage |
| 45 | + * ```ts |
| 46 | + * const chunker = new AdaptiveSentenceChunker(2000); |
| 47 | + * chunker.on('sentence', (text) => tts.synthesise(text)); |
| 48 | + * |
| 49 | + * llm.on('token', (tok) => chunker.pushTokens(tok)); |
| 50 | + * llm.on('end', () => chunker.flush()); |
| 51 | + * ``` |
| 52 | + */ |
| 53 | +export class AdaptiveSentenceChunker extends EventEmitter { |
| 54 | + /** Accumulated text waiting for a sentence boundary. */ |
| 55 | + private buffer: string = ''; |
| 56 | + |
| 57 | + /** Handle for the fallback flush timer; `null` when inactive. */ |
| 58 | + private flushTimer: NodeJS.Timeout | null = null; |
| 59 | + |
| 60 | + /** |
| 61 | + * @param maxBufferMs - Maximum time in milliseconds to hold buffered text |
| 62 | + * before forcing a word-boundary flush. Defaults to 2 000 ms. |
| 63 | + */ |
| 64 | + constructor(private readonly maxBufferMs: number = 2000) { |
| 65 | + super(); |
| 66 | + } |
| 67 | + |
| 68 | + // ------------------------------------------------------------------------- |
| 69 | + // Public API |
| 70 | + // ------------------------------------------------------------------------- |
| 71 | + |
| 72 | + /** |
| 73 | + * Append one or more LLM output tokens to the internal buffer and check for |
| 74 | + * sentence boundaries. |
| 75 | + * |
| 76 | + * If a boundary is found (`[.?!;]` followed by whitespace), the text up to |
| 77 | + * and including the punctuation is emitted as a `'sentence'` event and the |
| 78 | + * remainder stays in the buffer. The method recurses to catch multiple |
| 79 | + * boundaries in a single push (e.g. when a large chunk arrives at once). |
| 80 | + * |
| 81 | + * The fallback flush timer is reset on every call so that the 2 s window |
| 82 | + * always starts from the most recent token activity. |
| 83 | + * |
| 84 | + * @param text - Token fragment(s) to append. May be an empty string (used |
| 85 | + * internally to trigger boundary re-checks without appending new text). |
| 86 | + */ |
| 87 | + pushTokens(text: string): void { |
| 88 | + this.buffer += text; |
| 89 | + this.resetFlushTimer(); |
| 90 | + |
| 91 | + // Check for sentence boundaries: [.?!;] followed by whitespace |
| 92 | + const match = this.buffer.match(SENTENCE_BOUNDARY); |
| 93 | + if (match) { |
| 94 | + const sentence = match[1]!; |
| 95 | + this.buffer = match[2]!; |
| 96 | + this.emit('sentence', sentence); |
| 97 | + |
| 98 | + // Recurse to handle multiple consecutive sentences in the buffer. |
| 99 | + if (this.buffer.length > 0) { |
| 100 | + this.pushTokens(''); |
| 101 | + } |
| 102 | + } |
| 103 | + } |
| 104 | + |
| 105 | + /** |
| 106 | + * Flush any remaining buffered text immediately, without waiting for the |
| 107 | + * fallback timer. |
| 108 | + * |
| 109 | + * Call this when the LLM stream has ended to ensure the final fragment is |
| 110 | + * synthesised even if it lacks terminal punctuation. |
| 111 | + * |
| 112 | + * Emits a `'sentence'` event with the trimmed buffer contents if non-empty. |
| 113 | + * Cancels the fallback timer. |
| 114 | + */ |
| 115 | + flush(): void { |
| 116 | + if (this.flushTimer) { |
| 117 | + clearTimeout(this.flushTimer); |
| 118 | + this.flushTimer = null; |
| 119 | + } |
| 120 | + |
| 121 | + const remaining = this.buffer.trim(); |
| 122 | + if (remaining.length > 0) { |
| 123 | + this.buffer = ''; |
| 124 | + this.emit('sentence', remaining); |
| 125 | + } |
| 126 | + } |
| 127 | + |
| 128 | + /** |
| 129 | + * Immediately cancel the chunker: cancel the fallback timer, clear the |
| 130 | + * buffer, and return whatever text was pending. |
| 131 | + * |
| 132 | + * No `'sentence'` event is emitted. The caller receives the raw remaining |
| 133 | + * text so it can report it as unsynthesised content in a `'cancelled'` event. |
| 134 | + * |
| 135 | + * @returns The text that was in the buffer at the time of cancellation. |
| 136 | + */ |
| 137 | + cancel(): string { |
| 138 | + if (this.flushTimer) { |
| 139 | + clearTimeout(this.flushTimer); |
| 140 | + this.flushTimer = null; |
| 141 | + } |
| 142 | + |
| 143 | + const remaining = this.buffer; |
| 144 | + this.buffer = ''; |
| 145 | + return remaining; |
| 146 | + } |
| 147 | + |
| 148 | + // ------------------------------------------------------------------------- |
| 149 | + // Private helpers |
| 150 | + // ------------------------------------------------------------------------- |
| 151 | + |
| 152 | + /** |
| 153 | + * Reset the fallback flush timer. |
| 154 | + * |
| 155 | + * If text remains in the buffer after {@link maxBufferMs} milliseconds of |
| 156 | + * inactivity, the timer breaks the accumulated text at the last word |
| 157 | + * boundary (space) and emits the portion before that boundary as a sentence. |
| 158 | + * If there is no word boundary, the entire buffer is emitted verbatim. |
| 159 | + * |
| 160 | + * This prevents TTS from stalling indefinitely on bullet points, code |
| 161 | + * snippets, or other text that lacks standard sentence-ending punctuation. |
| 162 | + */ |
| 163 | + private resetFlushTimer(): void { |
| 164 | + if (this.flushTimer) { |
| 165 | + clearTimeout(this.flushTimer); |
| 166 | + } |
| 167 | + |
| 168 | + this.flushTimer = setTimeout(() => { |
| 169 | + this.flushTimer = null; |
| 170 | + |
| 171 | + if (this.buffer.length === 0) return; |
| 172 | + |
| 173 | + // Prefer a clean word boundary over splitting mid-token. |
| 174 | + const lastSpace = this.buffer.lastIndexOf(' '); |
| 175 | + if (lastSpace > 0) { |
| 176 | + const chunk = this.buffer.slice(0, lastSpace); |
| 177 | + this.buffer = this.buffer.slice(lastSpace + 1); |
| 178 | + this.emit('sentence', chunk); |
| 179 | + } else { |
| 180 | + // No word boundary found — emit everything. |
| 181 | + const chunk = this.buffer; |
| 182 | + this.buffer = ''; |
| 183 | + this.emit('sentence', chunk); |
| 184 | + } |
| 185 | + }, this.maxBufferMs); |
| 186 | + } |
| 187 | +} |
0 commit comments