@charivo/tts 0.8.1 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -96,6 +96,95 @@ var WebSpeechLipSyncSimulator = class {
96
96
  }
97
97
  };
98
98
 
99
+ // src/pcm-playback.ts
100
+ function createPcmPlaybackGraph(context) {
101
+ const output = context.createGain();
102
+ output.connect(context.destination);
103
+ const tap = context.createMediaStreamDestination();
104
+ output.connect(tap);
105
+ return { output, lipSyncStream: tap.stream };
106
+ }
107
+ var PcmPlaybackScheduler = class {
108
+ constructor(context, destination, format, callbacks) {
109
+ this.context = context;
110
+ this.destination = destination;
111
+ this.format = format;
112
+ this.callbacks = callbacks;
113
+ }
114
+ nextStartTime = 0;
115
+ /**
116
+ * Bumped by `flush()`. Every source captures the value it was scheduled
117
+ * under, so a discarded utterance's late `onended` cannot report against the
118
+ * one that replaced it.
119
+ */
120
+ generation = 0;
121
+ active = /* @__PURE__ */ new Set();
122
+ /**
123
+ * Whether the scheduler has nothing left to play — nothing sounding, and
124
+ * nothing queued behind it. Derived from the live source set on
125
+ * every call rather than remembered: `enqueue()` clears idleness by adding to
126
+ * that set, so a caller cannot be holding a "drained" answer that the next
127
+ * chunk already invalidated.
128
+ */
129
+ isIdle() {
130
+ return this.active.size === 0;
131
+ }
132
+ /** Schedule one chunk of the declared format after everything already queued. */
133
+ enqueue(pcm) {
134
+ const sampleCount = Math.floor(pcm.byteLength / 2);
135
+ if (sampleCount === 0) {
136
+ return;
137
+ }
138
+ const generation = this.generation;
139
+ const view = new DataView(pcm.buffer, pcm.byteOffset, pcm.byteLength);
140
+ const buffer = this.context.createBuffer(
141
+ 1,
142
+ sampleCount,
143
+ this.format.sampleRate
144
+ );
145
+ const channel = buffer.getChannelData(0);
146
+ for (let index = 0; index < sampleCount; index += 1) {
147
+ channel[index] = view.getInt16(index * 2, true) / 32768;
148
+ }
149
+ const source = this.context.createBufferSource();
150
+ source.buffer = buffer;
151
+ source.connect(this.destination);
152
+ source.onended = () => {
153
+ this.active.delete(source);
154
+ if (generation !== this.generation || this.active.size > 0) {
155
+ return;
156
+ }
157
+ this.callbacks.onPlayingChange(false);
158
+ this.callbacks.onDrain();
159
+ };
160
+ const wasIdle = this.isIdle();
161
+ const startAt = Math.max(this.context.currentTime, this.nextStartTime);
162
+ this.active.add(source);
163
+ source.start(startAt);
164
+ this.nextStartTime = startAt + buffer.duration;
165
+ if (wasIdle) {
166
+ this.callbacks.onPlayingChange(true);
167
+ }
168
+ }
169
+ /** Discard everything scheduled, audible or merely queued. */
170
+ flush() {
171
+ this.generation += 1;
172
+ const wasPlaying = !this.isIdle();
173
+ for (const source of this.active) {
174
+ source.onended = null;
175
+ try {
176
+ source.stop();
177
+ } catch {
178
+ }
179
+ }
180
+ this.active.clear();
181
+ this.nextStartTime = 0;
182
+ if (wasPlaying) {
183
+ this.callbacks.onPlayingChange(false);
184
+ }
185
+ }
186
+ };
187
+
99
188
  // src/tts-utils.ts
100
189
  function getTTSPlaybackMode(player) {
101
190
  return player.playbackMode || "audio";
@@ -106,10 +195,19 @@ function getTTSAudioMimeType(player) {
106
195
  function supportsGenerateAudio(player) {
107
196
  return typeof player.generateAudio === "function";
108
197
  }
198
+ function supportsGenerateAudioStream(player) {
199
+ return typeof player.generateAudioStream === "function";
200
+ }
109
201
 
110
202
  // src/tts-manager.ts
111
203
  var STARTUP_CANCELLED = Symbol("charivo.tts.startupCancelled");
112
204
  var noop = () => void 0;
205
+ function joinChunks(carry, chunk) {
206
+ const joined = new Uint8Array(carry.byteLength + chunk.byteLength);
207
+ joined.set(carry);
208
+ joined.set(chunk, carry.byteLength);
209
+ return joined;
210
+ }
113
211
  var TTSManagerImpl = class {
114
212
  ttsPlayer;
115
213
  eventEmitter;
@@ -118,12 +216,14 @@ var TTSManagerImpl = class {
118
216
  playbackMode;
119
217
  isAudioSessionActive = false;
120
218
  teardownBrowserLifecycle;
121
- // Settles the stateless-audio Promise that handleStatelessAudio() is
122
- // currently awaiting, if any. stop() clears currentAudio's onended/onerror
123
- // handlers so they can never fire on their own; without this, stopping a
124
- // still-playing stateless-audio utterance would strand that speak() call's
125
- // promise forever.
126
- pendingStatelessStop = null;
219
+ // Settles the Promise whichever audio path is currently awaiting -- the
220
+ // buffered one in handleStatelessAudio(), or the streamed one in
221
+ // handleStreamingAudio(). Neither can settle itself once stop() has torn its
222
+ // playback down: stop() clears currentAudio's onended/onerror handlers so
223
+ // they can never fire, and it flushes the scheduler so no source's onended
224
+ // is left to report a drain. Without this nudge, stopping a still-playing
225
+ // utterance would strand that speak() call's promise forever.
226
+ pendingAudioStop = null;
127
227
  // Settles the web-speech Promise handleWebSpeech() is currently awaiting,
128
228
  // if any. Unlike the stateless path, the manager can't sever the
129
229
  // TTSPlayer's own onend/onerror handlers directly -- its completion is
@@ -157,6 +257,16 @@ var TTSManagerImpl = class {
157
257
  // requests share one player stop and one cleanup, and no new utterance can
158
258
  // dispatch until it has fully settled.
159
259
  pendingStopPlayback = null;
260
+ // The Web Audio side, built only for streamed playback -- the buffered path
261
+ // plays through an <audio> element and never touches these. Both outlive a
262
+ // single utterance: one context per manager, one graph per context.
263
+ playbackContext = null;
264
+ playbackGraph = null;
265
+ // The streamed utterance in flight, if any: the three handles needed to
266
+ // reach it -- the queue to discard, the request to abort, and the body to
267
+ // cancel through (never through the body itself, which is locked to this
268
+ // reader).
269
+ currentStream = null;
160
270
  // Only the Web Speech lip-sync simulation is needed
161
271
  webSimulator;
162
272
  // Reads the emitter at emit time, so a later setEventEmitter() still applies.
@@ -167,9 +277,9 @@ var TTSManagerImpl = class {
167
277
  constructor(ttsPlayer) {
168
278
  this.ttsPlayer = ttsPlayer;
169
279
  this.playbackMode = getTTSPlaybackMode(ttsPlayer);
170
- if (this.playbackMode === "audio" && !supportsGenerateAudio(ttsPlayer)) {
280
+ if (this.playbackMode === "audio" && !supportsGenerateAudio(ttsPlayer) && !supportsGenerateAudioStream(ttsPlayer)) {
171
281
  throw new import_core.CharivoStateError(
172
- 'TTS playback mode "audio" requires the player to implement generateAudio() so the manager can create and analyze playback for lip-sync. Implement generateAudio() or set playbackMode: "web-speech".'
282
+ 'TTS playback mode "audio" requires the player to implement generateAudio() or generateAudioStream() so the manager can create and analyze playback for lip-sync. Implement one of them or set playbackMode: "web-speech".'
173
283
  );
174
284
  }
175
285
  this.webSimulator = new WebSpeechLipSyncSimulator();
@@ -186,10 +296,16 @@ var TTSManagerImpl = class {
186
296
  *
187
297
  * Resolves when the utterance finishes -- or silently, without speaking, if
188
298
  * stop() or a newer speak() lands while this call is still starting up (the
189
- * pre-speech stop, or synthesis). A cancelled call never begins playback,
190
- * whether or not it had already opened an audio session (a reentrant stop
191
- * from the tts:audio:start listener still sees the session close), so a
192
- * resolved speak() is not proof audio played.
299
+ * pre-speech stop, or synthesis), so a resolved speak() is not proof audio
300
+ * played.
301
+ *
302
+ * On the buffered path a cancelled call never begins playback, whether or
303
+ * not it had already opened an audio session: a reentrant stop from the
304
+ * tts:audio:start listener still sees the session close before anything is
305
+ * handed to the speakers. Streamed playback cannot promise that much,
306
+ * because there tts:audio:start follows the first scheduled sample -- a stop
307
+ * from that listener can land after a few milliseconds of sound. It still
308
+ * settles the call and emits exactly one tts:audio:end.
193
309
  */
194
310
  async speak(text, options) {
195
311
  const generation = ++this.speakGeneration;
@@ -209,6 +325,8 @@ var TTSManagerImpl = class {
209
325
  }
210
326
  if (this.playbackMode === "web-speech") {
211
327
  return await this.handleWebSpeech(text, options, startup);
328
+ } else if (supportsGenerateAudioStream(this.ttsPlayer)) {
329
+ return await this.handleStreamingAudio(text, options, startup);
212
330
  } else {
213
331
  return await this.handleStatelessAudio(text, options, startup);
214
332
  }
@@ -272,9 +390,14 @@ var TTSManagerImpl = class {
272
390
  URL.revokeObjectURL(this.currentAudioUrl);
273
391
  this.currentAudioUrl = null;
274
392
  }
393
+ const streaming = this.currentStream;
394
+ if (streaming) {
395
+ streaming.scheduler.flush();
396
+ this.abandonStream(streaming.abort, streaming.reader);
397
+ }
275
398
  this.lipSync.stop();
276
399
  this.endAudioSession();
277
- this.pendingStatelessStop?.();
400
+ this.pendingAudioStop?.();
278
401
  const settleWebSpeech = this.pendingWebSpeechStop;
279
402
  this.pendingWebSpeechStop = null;
280
403
  settleWebSpeech?.();
@@ -293,22 +416,35 @@ var TTSManagerImpl = class {
293
416
  return this.ttsPlayer.isSupported();
294
417
  }
295
418
  /**
296
- * Create the audio analysis context up front, typically from a user gesture
419
+ * Create the audio contexts up front -- the analyzer's, plus a playback
420
+ * context for a player that streams -- typically from a user gesture
297
421
  * handler so browsers allow playback later. Throws on unsupported browsers.
298
422
  */
299
423
  async prepareAudio() {
300
424
  this.ensureLifecycleBound();
425
+ if (this.playbackMode !== "web-speech" && supportsGenerateAudioStream(this.ttsPlayer)) {
426
+ this.ensurePlaybackContext();
427
+ }
301
428
  await this.lipSync.prepare();
302
429
  }
303
430
  /**
304
- * Release audio resources. Call stop() first: dispose() does not stop playback.
431
+ * Release audio resources. Call stop() first: dispose() does not stop
432
+ * buffered playback -- an <audio> element outlives this manager and settles
433
+ * its own speak() on its own onended. A streamed utterance cannot survive
434
+ * this call, so it is torn down here.
305
435
  */
306
436
  async dispose() {
307
437
  this.webSimulator.dispose();
308
438
  this.teardownBrowserLifecycle?.();
309
439
  this.teardownBrowserLifecycle = void 0;
440
+ if (this.currentStream) {
441
+ this.pendingAudioStop?.();
442
+ }
443
+ const playbackContext = this.playbackContext;
444
+ this.playbackContext = null;
445
+ this.playbackGraph = null;
310
446
  try {
311
- await this.lipSync.cleanup();
447
+ await Promise.all([this.lipSync.cleanup(), playbackContext?.close()]);
312
448
  } catch (error) {
313
449
  throw (0, import_core.toCharivoError)(
314
450
  "dispose",
@@ -449,7 +585,7 @@ var TTSManagerImpl = class {
449
585
  const finalize = (next) => {
450
586
  if (isFinalized) return;
451
587
  isFinalized = true;
452
- this.pendingStatelessStop = null;
588
+ this.pendingAudioStop = null;
453
589
  if (this.currentAudioUrl) {
454
590
  URL.revokeObjectURL(this.currentAudioUrl);
455
591
  this.currentAudioUrl = null;
@@ -466,7 +602,7 @@ var TTSManagerImpl = class {
466
602
  finalize(() => reject(new Error("Audio playback failed")));
467
603
  };
468
604
  const dispatch = this.beginUtterance(() => {
469
- this.pendingStatelessStop = () => finalize(resolve);
605
+ this.pendingAudioStop = () => finalize(resolve);
470
606
  }, startup);
471
607
  if (!dispatch) {
472
608
  finalize(resolve);
@@ -481,6 +617,164 @@ var TTSManagerImpl = class {
481
617
  });
482
618
  });
483
619
  }
620
+ /**
621
+ * Streamed audio handling: PCM is scheduled into Web Audio as it arrives,
622
+ * instead of waiting for one finished buffer.
623
+ */
624
+ async handleStreamingAudio(text, options, startup) {
625
+ const context = this.ensurePlaybackContext();
626
+ const abort = new AbortController();
627
+ const opening = this.ttsPlayer.generateAudioStream(
628
+ text,
629
+ options,
630
+ abort.signal
631
+ ).catch(
632
+ (error) => Promise.reject(
633
+ (0, import_core.toCharivoError)("provider", error, "Failed to generate TTS audio")
634
+ )
635
+ );
636
+ const stream = await this.raceStartup(
637
+ opening,
638
+ startup.cancelled,
639
+ startup.isCancelled
640
+ );
641
+ if (stream === STARTUP_CANCELLED) {
642
+ abort.abort();
643
+ void opening.then((late) => void late.body.cancel().catch(noop), noop);
644
+ return;
645
+ }
646
+ if (stream.format.channels !== 1) {
647
+ void stream.body.cancel().catch(noop);
648
+ abort.abort();
649
+ throw new import_core.CharivoStateError(
650
+ `Streamed TTS audio must be mono, but the player answered ${stream.format.channels} channels.`
651
+ );
652
+ }
653
+ const graph = this.ensurePlaybackGraph(context);
654
+ graph.output.gain.value = options?.volume !== void 0 ? Math.max(0, Math.min(1, options.volume)) : 1;
655
+ this.ensureLifecycleBound();
656
+ this.lipSync.attachMediaStream(graph.lipSyncStream);
657
+ const reader = stream.body.getReader();
658
+ return new Promise((resolve, reject) => {
659
+ let bodyEnded = false;
660
+ let isFinalized = false;
661
+ const scheduler = new PcmPlaybackScheduler(
662
+ context,
663
+ graph.output,
664
+ stream.format,
665
+ {
666
+ onDrain: () => {
667
+ if (bodyEnded) {
668
+ finalize(resolve);
669
+ }
670
+ },
671
+ onPlayingChange: (playing) => {
672
+ if (playing) {
673
+ this.startAudioSession();
674
+ }
675
+ }
676
+ }
677
+ );
678
+ const finalize = (next) => {
679
+ if (isFinalized) return;
680
+ isFinalized = true;
681
+ this.pendingAudioStop = null;
682
+ this.currentStream = null;
683
+ scheduler.flush();
684
+ this.abandonStream(abort, reader);
685
+ this.lipSync.stop();
686
+ this.endAudioSession();
687
+ next();
688
+ };
689
+ this.currentStream = { scheduler, abort, reader };
690
+ this.pendingAudioStop = () => finalize(resolve);
691
+ if (startup.isCancelled()) {
692
+ finalize(resolve);
693
+ return;
694
+ }
695
+ const pump = async () => {
696
+ let carry = null;
697
+ let hasScheduled = false;
698
+ for (; ; ) {
699
+ const { done, value } = await reader.read();
700
+ if (done) {
701
+ bodyEnded = true;
702
+ if (scheduler.isIdle()) {
703
+ finalize(resolve);
704
+ }
705
+ return;
706
+ }
707
+ if (isFinalized) {
708
+ return;
709
+ }
710
+ const chunk = carry ? joinChunks(carry, value) : value;
711
+ const whole = chunk.byteLength - chunk.byteLength % 2;
712
+ carry = whole < chunk.byteLength ? chunk.slice(whole) : null;
713
+ if (whole > 0) {
714
+ if (!hasScheduled && context.state !== "running") {
715
+ finalize(
716
+ () => reject(
717
+ new import_core.CharivoStateError(
718
+ "The TTS playback audio context is blocked, so streamed audio cannot start. Call prepareAudio() from a user gesture handler before speak()."
719
+ )
720
+ )
721
+ );
722
+ return;
723
+ }
724
+ hasScheduled = true;
725
+ scheduler.enqueue(chunk.subarray(0, whole));
726
+ }
727
+ }
728
+ };
729
+ void pump().catch((error) => {
730
+ finalize(() => reject(error));
731
+ });
732
+ });
733
+ }
734
+ /**
735
+ * Stop the route synthesizing and throw the body away.
736
+ *
737
+ * Through the reader, never the body: past getReader() the body is locked
738
+ * and cancelling it throws. An aborted stream errors, so its own cancel()
739
+ * rejects with the reason raised here -- ours, and already handled.
740
+ */
741
+ abandonStream(abort, reader) {
742
+ abort.abort();
743
+ void reader.cancel().catch(noop);
744
+ }
745
+ /**
746
+ * The AudioContext streamed PCM is scheduled into, created on first use and
747
+ * then only nudged back towards running: a context created inside a user
748
+ * gesture is the one browsers let play, so a replacement built later would
749
+ * be refused. It does not promise a running context on return.
750
+ */
751
+ ensurePlaybackContext() {
752
+ const existing = this.playbackContext;
753
+ if (existing) {
754
+ if (existing.state !== "running") {
755
+ void existing.resume().catch(
756
+ (error) => console.error(
757
+ "TTS Manager: failed to resume the playback audio context:",
758
+ error
759
+ )
760
+ );
761
+ }
762
+ return existing;
763
+ }
764
+ const constructor = window.AudioContext || window.webkitAudioContext;
765
+ if (!constructor) {
766
+ throw new import_core.CharivoStateError(
767
+ "AudioContext is not supported in this browser, so streamed TTS audio cannot be played."
768
+ );
769
+ }
770
+ const context = new constructor();
771
+ this.playbackContext = context;
772
+ return context;
773
+ }
774
+ ensurePlaybackGraph(context) {
775
+ this.playbackGraph ??= createPcmPlaybackGraph(context);
776
+ return this.playbackGraph;
777
+ }
484
778
  /**
485
779
  * Subscribes to browser lifecycle events once; the teardown is released in
486
780
  * dispose(). Pausing analysis while the tab is hidden closes the mouth