@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 +24 -0
- package/dist/index.js +60 -20
- package/dist/index.mjs +63 -20
- package/package.json +2 -2
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.
|
|
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
|
-
*
|
|
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
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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.
|
|
196
|
-
}
|
|
197
|
-
|
|
198
|
-
|
|
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
|
|
223
|
+
* Handle the Web Speech API (simulated lip-sync)
|
|
203
224
|
*/
|
|
204
|
-
async
|
|
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.
|
|
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
|
-
|
|
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", {
|
|
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.
|
|
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
|
-
*
|
|
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
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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.
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
|
|
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
|
|
202
|
+
* Handle the Web Speech API (simulated lip-sync)
|
|
179
203
|
*/
|
|
180
|
-
async
|
|
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.
|
|
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
|
-
|
|
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", {
|
|
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.
|
|
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.
|
|
39
|
+
"@charivo/core": "0.16.0"
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
42
|
"tsup": "^8.5.0",
|