@charivo/tts 0.5.1 → 0.6.0

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/README.md CHANGED
@@ -6,10 +6,23 @@ This package coordinates a `TTSPlayer`, audio playback lifecycle, and lip-sync
6
6
  events. It works with browser-native speech, remote TTS APIs, and direct OpenAI
7
7
  players.
8
8
 
9
+ For `"audio"` playback mode, the manager analyzes the `<audio>` element it
10
+ creates from the generated bytes using the shared core lip-sync analyzer
11
+ (`createLipSyncAnalyzer` from `@charivo/core`) and emits `tts:lipsync:update`.
12
+ For `"web-speech"` mode, lip-sync is simulated from the spoken text instead —
13
+ there is no audio to analyze.
14
+
9
15
  Concrete players should declare `playbackMode` (`"audio"` or `"web-speech"`)
10
16
  and can optionally declare `audioMimeType` so the manager does not need to rely
11
17
  on constructor-name inference.
12
18
 
19
+ `"audio"` playback mode requires the player to implement `generateAudio()`,
20
+ since the manager needs the raw audio bytes to build the element it plays and
21
+ analyzes; `createTTSManager(player)` throws an explicit error if a player
22
+ declares `"audio"` mode without it. Players that only implement `speak()` (no
23
+ `generateAudio()`, e.g. the Web Speech API) must use `"web-speech"` mode
24
+ instead.
25
+
13
26
  ## Install
14
27
 
15
28
  ```bash
@@ -47,3 +60,14 @@ When connected, the manager emits:
47
60
  - `tts:audio:start`
48
61
  - `tts:lipsync:update`
49
62
  - `tts:audio:end`
63
+
64
+ ## Audio Lifecycle
65
+
66
+ - `prepareAudio?.()` — creates the lip-sync `AudioContext` up front. Call it
67
+ from a user-gesture handler before the first `speak()` so mobile browsers
68
+ that require audio to start from a gesture do not block playback.
69
+ - `dispose?.()` — releases lip-sync audio resources and unsubscribes browser
70
+ lifecycle listeners. Call `stop()` first if speech is in-flight; `dispose()`
71
+ does not stop playback. `Charivo.dispose()` calls this automatically for an
72
+ attached TTS manager — call it directly only if your app tears a
73
+ `TTSManager` down outside `Charivo.dispose()`.
package/dist/index.js CHANGED
@@ -115,11 +115,22 @@ var TTSManagerImpl = class {
115
115
  currentAudioUrl = null;
116
116
  playbackMode;
117
117
  isAudioSessionActive = false;
118
+ teardownBrowserLifecycle;
118
119
  // Only the Web Speech lip-sync simulation is needed
119
120
  webSimulator;
121
+ // Reads the emitter at emit time, so a later setEventEmitter() still applies.
122
+ lipSync = (0, import_core.createLipSyncAnalyzer)({
123
+ onRms: (rms) => this.eventEmitter?.emit("tts:lipsync:update", { rms }),
124
+ onError: (error) => console.error("TTS Manager: lip-sync analysis failed:", error)
125
+ });
120
126
  constructor(ttsPlayer) {
121
127
  this.ttsPlayer = ttsPlayer;
122
128
  this.playbackMode = getTTSPlaybackMode(ttsPlayer);
129
+ if (this.playbackMode === "audio" && !supportsGenerateAudio(ttsPlayer)) {
130
+ throw new import_core.CharivoStateError(
131
+ '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".'
132
+ );
133
+ }
123
134
  this.webSimulator = new WebSpeechLipSyncSimulator();
124
135
  }
125
136
  /**
@@ -140,7 +151,7 @@ var TTSManagerImpl = class {
140
151
  if (this.playbackMode === "web-speech") {
141
152
  return await this.handleWebSpeech(text, options);
142
153
  } else {
143
- return await this.handleAudioSpeech(text, options);
154
+ return await this.handleStatelessAudio(text, options);
144
155
  }
145
156
  } catch (error) {
146
157
  throw (0, import_core.toCharivoError)("provider", error, "Failed to speak text");
@@ -167,6 +178,7 @@ var TTSManagerImpl = class {
167
178
  URL.revokeObjectURL(this.currentAudioUrl);
168
179
  this.currentAudioUrl = null;
169
180
  }
181
+ this.lipSync.stop();
170
182
  this.endAudioSession();
171
183
  }
172
184
  }
@@ -183,32 +195,41 @@ var TTSManagerImpl = class {
183
195
  return this.ttsPlayer.isSupported();
184
196
  }
185
197
  /**
186
- * Handle the Web Speech API (simulated lip-sync)
198
+ * Create the audio analysis context up front, typically from a user gesture
199
+ * handler so browsers allow playback later. Throws on unsupported browsers.
187
200
  */
188
- async handleWebSpeech(text, options) {
189
- const dummyAudio = document.createElement("audio");
190
- dummyAudio.preload = "none";
191
- this.startAudioSession(dummyAudio);
192
- const effectiveRate = options?.rate !== void 0 ? Math.max(0.1, Math.min(10, options.rate)) : 1;
193
- this.webSimulator.startSimulation(text, effectiveRate);
201
+ async prepareAudio() {
202
+ this.ensureLifecycleBound();
203
+ await this.lipSync.prepare();
204
+ }
205
+ /**
206
+ * Release audio resources. Call stop() first: dispose() does not stop playback.
207
+ */
208
+ async dispose() {
209
+ this.webSimulator.dispose();
210
+ this.teardownBrowserLifecycle?.();
211
+ this.teardownBrowserLifecycle = void 0;
194
212
  try {
195
- await this.ttsPlayer.speak(text, options);
196
- } finally {
197
- this.webSimulator.stopSimulation();
198
- this.endAudioSession();
213
+ await this.lipSync.cleanup();
214
+ } catch (error) {
215
+ throw (0, import_core.toCharivoError)(
216
+ "dispose",
217
+ error,
218
+ "Failed to release TTS audio resources"
219
+ );
199
220
  }
200
221
  }
201
222
  /**
202
- * Handle audio-based TTS (real-time audio analysis)
223
+ * Handle the Web Speech API (simulated lip-sync)
203
224
  */
204
- async handleAudioSpeech(text, options) {
205
- if (supportsGenerateAudio(this.ttsPlayer)) {
206
- return this.handleStatelessAudio(text, options);
207
- }
225
+ async handleWebSpeech(text, options) {
208
226
  this.startAudioSession();
227
+ const effectiveRate = options?.rate !== void 0 ? Math.max(0.1, Math.min(10, options.rate)) : 1;
228
+ this.webSimulator.startSimulation(text, effectiveRate);
209
229
  try {
210
230
  await this.ttsPlayer.speak(text, options);
211
231
  } finally {
232
+ this.webSimulator.stopSimulation();
212
233
  this.endAudioSession();
213
234
  }
214
235
  }
@@ -231,7 +252,9 @@ var TTSManagerImpl = class {
231
252
  if (options?.volume !== void 0) {
232
253
  audio.volume = Math.max(0, Math.min(1, options.volume));
233
254
  }
234
- this.startAudioSession(audio);
255
+ this.ensureLifecycleBound();
256
+ this.lipSync.attachMediaElement(audio);
257
+ this.startAudioSession();
235
258
  let isFinalized = false;
236
259
  const finalize = (next) => {
237
260
  if (isFinalized) return;
@@ -241,6 +264,7 @@ var TTSManagerImpl = class {
241
264
  this.currentAudioUrl = null;
242
265
  }
243
266
  this.currentAudio = null;
267
+ this.lipSync.stop();
244
268
  this.endAudioSession();
245
269
  next();
246
270
  };
@@ -259,12 +283,28 @@ var TTSManagerImpl = class {
259
283
  });
260
284
  });
261
285
  }
262
- startAudioSession(audioElement) {
286
+ /**
287
+ * Subscribes to browser lifecycle events once; the teardown is released in
288
+ * dispose(). Pausing analysis while the tab is hidden closes the mouth
289
+ * instead of freezing on the last frame.
290
+ */
291
+ ensureLifecycleBound() {
292
+ if (this.teardownBrowserLifecycle) {
293
+ return;
294
+ }
295
+ this.teardownBrowserLifecycle = (0, import_core.subscribeBrowserLifecycle)({
296
+ onHidden: () => this.lipSync.pause(),
297
+ onPageHide: () => this.lipSync.pause(),
298
+ onVisible: () => this.lipSync.resume(),
299
+ onPageShow: () => this.lipSync.resume()
300
+ });
301
+ }
302
+ startAudioSession() {
263
303
  if (this.isAudioSessionActive) {
264
304
  return;
265
305
  }
266
306
  this.isAudioSessionActive = true;
267
- this.eventEmitter?.emit("tts:audio:start", { audioElement });
307
+ this.eventEmitter?.emit("tts:audio:start", {});
268
308
  }
269
309
  endAudioSession() {
270
310
  if (!this.isAudioSessionActive) {
package/dist/index.mjs CHANGED
@@ -1,5 +1,8 @@
1
1
  // src/tts-manager.ts
2
2
  import {
3
+ CharivoStateError,
4
+ createLipSyncAnalyzer,
5
+ subscribeBrowserLifecycle,
3
6
  toCharivoError
4
7
  } from "@charivo/core";
5
8
 
@@ -91,11 +94,22 @@ var TTSManagerImpl = class {
91
94
  currentAudioUrl = null;
92
95
  playbackMode;
93
96
  isAudioSessionActive = false;
97
+ teardownBrowserLifecycle;
94
98
  // Only the Web Speech lip-sync simulation is needed
95
99
  webSimulator;
100
+ // Reads the emitter at emit time, so a later setEventEmitter() still applies.
101
+ lipSync = createLipSyncAnalyzer({
102
+ onRms: (rms) => this.eventEmitter?.emit("tts:lipsync:update", { rms }),
103
+ onError: (error) => console.error("TTS Manager: lip-sync analysis failed:", error)
104
+ });
96
105
  constructor(ttsPlayer) {
97
106
  this.ttsPlayer = ttsPlayer;
98
107
  this.playbackMode = getTTSPlaybackMode(ttsPlayer);
108
+ if (this.playbackMode === "audio" && !supportsGenerateAudio(ttsPlayer)) {
109
+ throw new CharivoStateError(
110
+ '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".'
111
+ );
112
+ }
99
113
  this.webSimulator = new WebSpeechLipSyncSimulator();
100
114
  }
101
115
  /**
@@ -116,7 +130,7 @@ var TTSManagerImpl = class {
116
130
  if (this.playbackMode === "web-speech") {
117
131
  return await this.handleWebSpeech(text, options);
118
132
  } else {
119
- return await this.handleAudioSpeech(text, options);
133
+ return await this.handleStatelessAudio(text, options);
120
134
  }
121
135
  } catch (error) {
122
136
  throw toCharivoError("provider", error, "Failed to speak text");
@@ -143,6 +157,7 @@ var TTSManagerImpl = class {
143
157
  URL.revokeObjectURL(this.currentAudioUrl);
144
158
  this.currentAudioUrl = null;
145
159
  }
160
+ this.lipSync.stop();
146
161
  this.endAudioSession();
147
162
  }
148
163
  }
@@ -159,32 +174,41 @@ var TTSManagerImpl = class {
159
174
  return this.ttsPlayer.isSupported();
160
175
  }
161
176
  /**
162
- * Handle the Web Speech API (simulated lip-sync)
177
+ * Create the audio analysis context up front, typically from a user gesture
178
+ * handler so browsers allow playback later. Throws on unsupported browsers.
163
179
  */
164
- async handleWebSpeech(text, options) {
165
- const dummyAudio = document.createElement("audio");
166
- dummyAudio.preload = "none";
167
- this.startAudioSession(dummyAudio);
168
- const effectiveRate = options?.rate !== void 0 ? Math.max(0.1, Math.min(10, options.rate)) : 1;
169
- this.webSimulator.startSimulation(text, effectiveRate);
180
+ async prepareAudio() {
181
+ this.ensureLifecycleBound();
182
+ await this.lipSync.prepare();
183
+ }
184
+ /**
185
+ * Release audio resources. Call stop() first: dispose() does not stop playback.
186
+ */
187
+ async dispose() {
188
+ this.webSimulator.dispose();
189
+ this.teardownBrowserLifecycle?.();
190
+ this.teardownBrowserLifecycle = void 0;
170
191
  try {
171
- await this.ttsPlayer.speak(text, options);
172
- } finally {
173
- this.webSimulator.stopSimulation();
174
- this.endAudioSession();
192
+ await this.lipSync.cleanup();
193
+ } catch (error) {
194
+ throw toCharivoError(
195
+ "dispose",
196
+ error,
197
+ "Failed to release TTS audio resources"
198
+ );
175
199
  }
176
200
  }
177
201
  /**
178
- * Handle audio-based TTS (real-time audio analysis)
202
+ * Handle the Web Speech API (simulated lip-sync)
179
203
  */
180
- async handleAudioSpeech(text, options) {
181
- if (supportsGenerateAudio(this.ttsPlayer)) {
182
- return this.handleStatelessAudio(text, options);
183
- }
204
+ async handleWebSpeech(text, options) {
184
205
  this.startAudioSession();
206
+ const effectiveRate = options?.rate !== void 0 ? Math.max(0.1, Math.min(10, options.rate)) : 1;
207
+ this.webSimulator.startSimulation(text, effectiveRate);
185
208
  try {
186
209
  await this.ttsPlayer.speak(text, options);
187
210
  } finally {
211
+ this.webSimulator.stopSimulation();
188
212
  this.endAudioSession();
189
213
  }
190
214
  }
@@ -207,7 +231,9 @@ var TTSManagerImpl = class {
207
231
  if (options?.volume !== void 0) {
208
232
  audio.volume = Math.max(0, Math.min(1, options.volume));
209
233
  }
210
- this.startAudioSession(audio);
234
+ this.ensureLifecycleBound();
235
+ this.lipSync.attachMediaElement(audio);
236
+ this.startAudioSession();
211
237
  let isFinalized = false;
212
238
  const finalize = (next) => {
213
239
  if (isFinalized) return;
@@ -217,6 +243,7 @@ var TTSManagerImpl = class {
217
243
  this.currentAudioUrl = null;
218
244
  }
219
245
  this.currentAudio = null;
246
+ this.lipSync.stop();
220
247
  this.endAudioSession();
221
248
  next();
222
249
  };
@@ -235,12 +262,28 @@ var TTSManagerImpl = class {
235
262
  });
236
263
  });
237
264
  }
238
- startAudioSession(audioElement) {
265
+ /**
266
+ * Subscribes to browser lifecycle events once; the teardown is released in
267
+ * dispose(). Pausing analysis while the tab is hidden closes the mouth
268
+ * instead of freezing on the last frame.
269
+ */
270
+ ensureLifecycleBound() {
271
+ if (this.teardownBrowserLifecycle) {
272
+ return;
273
+ }
274
+ this.teardownBrowserLifecycle = subscribeBrowserLifecycle({
275
+ onHidden: () => this.lipSync.pause(),
276
+ onPageHide: () => this.lipSync.pause(),
277
+ onVisible: () => this.lipSync.resume(),
278
+ onPageShow: () => this.lipSync.resume()
279
+ });
280
+ }
281
+ startAudioSession() {
239
282
  if (this.isAudioSessionActive) {
240
283
  return;
241
284
  }
242
285
  this.isAudioSessionActive = true;
243
- this.eventEmitter?.emit("tts:audio:start", { audioElement });
286
+ this.eventEmitter?.emit("tts:audio:start", {});
244
287
  }
245
288
  endAudioSession() {
246
289
  if (!this.isAudioSessionActive) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@charivo/tts",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "TTS manager and browser adapters for Charivo",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -36,7 +36,7 @@
36
36
  ],
37
37
  "dependencies": {
38
38
  "openai": "^4.47.1",
39
- "@charivo/core": "0.15.0"
39
+ "@charivo/core": "0.16.0"
40
40
  },
41
41
  "devDependencies": {
42
42
  "tsup": "^8.5.0",