@charivo/tts 0.8.0 → 0.9.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.
@@ -24,47 +24,192 @@ __export(remote_exports, {
24
24
  });
25
25
  module.exports = __toCommonJS(remote_exports);
26
26
  var import_core = require("@charivo/core");
27
+ var STREAM_INACTIVITY_TIMEOUT_MS = 1e4;
28
+ var DEFAULT_STREAM_SAMPLE_RATE = 24e3;
29
+ var DEFAULT_STREAM_CHANNELS = 1;
27
30
  var RemoteTTSPlayer = class {
28
31
  playbackMode = "audio";
32
+ /**
33
+ * The container of the buffered `generateAudio` path only -- the streaming
34
+ * path carries its layout in `TTSPcmStream.format` instead.
35
+ *
36
+ * Follows what the server said it sent, because the endpoint decides the
37
+ * container: the demo's OpenAI route answers with MPEG and its Gemini one
38
+ * with WAV. Naming either here would mislabel the other. Until a response
39
+ * has been seen this is WAV, matching the manager's own fallback.
40
+ */
29
41
  audioMimeType = "audio/wav";
42
+ /**
43
+ * Present only on a streaming player: the manager selects the streaming
44
+ * path with `typeof player.generateAudioStream === "function"`, so an
45
+ * unflagged player must not carry the method at all.
46
+ */
47
+ generateAudioStream;
30
48
  apiEndpoint;
31
49
  defaultVoice;
32
50
  constructor(config = {}) {
33
51
  this.apiEndpoint = config.apiEndpoint || "/api/tts";
34
52
  this.defaultVoice = config.defaultVoice || "marin";
53
+ if (config.streaming) {
54
+ this.generateAudioStream = (text, options, signal) => this.requestAudioStream(text, options, signal);
55
+ }
35
56
  }
36
57
  /**
37
58
  * Stateless audio generation (used by the TTS Manager)
38
59
  */
39
60
  async generateAudio(text, options) {
40
- const response = await (0, import_core.fetchWithTimeout)(
61
+ return (0, import_core.fetchWithTimeout)(
41
62
  this.apiEndpoint,
42
63
  {
43
64
  method: "POST",
44
65
  headers: { "Content-Type": "application/json" },
45
- body: JSON.stringify({
46
- text,
47
- voice: options?.voice || this.defaultVoice,
48
- speed: options?.rate || 1,
49
- format: "wav"
50
- })
66
+ body: this.buildRequestBody(text, options)
51
67
  },
52
68
  {
53
69
  timeoutMessage: `TTS request timed out after ${import_core.DEFAULT_FETCH_TIMEOUT_MS}ms`,
54
70
  failureMessage: "TTS request failed"
71
+ },
72
+ // Consume the body while cancellation is still wired up, so a route that
73
+ // sends headers and then stalls -- on the error path too, where the
74
+ // message is read off the body -- still hits the deadline.
75
+ async (response) => {
76
+ if (!response.ok) {
77
+ throw new import_core.CharivoProviderError(
78
+ `TTS API failed: ${await (0, import_core.readResponseErrorMessage)(response)}`
79
+ );
80
+ }
81
+ const contentType = response.headers.get("content-type");
82
+ if (contentType) {
83
+ this.audioMimeType = contentType.split(";")[0].trim();
84
+ }
85
+ return response.arrayBuffer();
86
+ }
87
+ );
88
+ }
89
+ /** The one request payload both paths send; only the Accept header differs. */
90
+ buildRequestBody(text, options) {
91
+ return JSON.stringify({
92
+ text,
93
+ voice: options?.voice || this.defaultVoice,
94
+ speed: options?.rate || 1,
95
+ format: "wav"
96
+ });
97
+ }
98
+ async requestAudioStream(text, options, signal) {
99
+ const response = await (0, import_core.fetchWithTimeout)(
100
+ this.apiEndpoint,
101
+ {
102
+ method: "POST",
103
+ headers: {
104
+ "Content-Type": "application/json",
105
+ // A streaming route answers `audio/pcm`; a route that ignores this
106
+ // answers its usual container, which is rejected below.
107
+ Accept: "audio/pcm"
108
+ },
109
+ body: this.buildRequestBody(text, options)
110
+ },
111
+ {
112
+ timeoutMessage: `TTS request timed out after ${import_core.DEFAULT_FETCH_TIMEOUT_MS}ms`,
113
+ failureMessage: "TTS request failed",
114
+ signal
115
+ },
116
+ // Returns the Response itself rather than draining it: the helper's
117
+ // deadline covers connecting, the headers and an error body, and then
118
+ // clears. Everything after that is the inactivity timer's business.
119
+ async (settled) => {
120
+ if (!settled.ok) {
121
+ throw new import_core.CharivoProviderError(
122
+ `TTS API failed: ${await (0, import_core.readResponseErrorMessage)(settled)}`
123
+ );
124
+ }
125
+ return settled;
55
126
  }
56
127
  );
57
- if (!response.ok) {
58
- throw new import_core.CharivoProviderError(`TTS API failed: ${response.statusText}`);
128
+ const rejectAnswer = (reason) => {
129
+ void response.body?.cancel().catch(() => void 0);
130
+ throw new import_core.CharivoProviderError(
131
+ `Streaming TTS is enabled, but ${this.apiEndpoint} ${reason}`
132
+ );
133
+ };
134
+ const contentType = response.headers.get("content-type");
135
+ const format = parsePcmContentType(contentType);
136
+ if (!format) {
137
+ return rejectAnswer(
138
+ `answered "${contentType ?? "no content type"}" instead of audio/pcm`
139
+ );
140
+ }
141
+ if (format.channels !== 1) {
142
+ return rejectAnswer(
143
+ `answered ${format.channels} audio channels; the manager plays mono only`
144
+ );
145
+ }
146
+ const upstream = response.body;
147
+ if (!upstream) {
148
+ return rejectAnswer("answered audio/pcm with no body to read");
149
+ }
150
+ const reader = upstream.getReader();
151
+ let inactivityTimer;
152
+ let stopped = false;
153
+ let streamController;
154
+ const stopUpstream = () => {
155
+ stopped = true;
156
+ clearTimeout(inactivityTimer);
157
+ signal?.removeEventListener("abort", onCallerAbort);
158
+ void reader.cancel().catch(() => void 0);
159
+ };
160
+ const onCallerAbort = () => {
161
+ stopUpstream();
162
+ streamController?.error(signal.reason);
163
+ };
164
+ const body = new ReadableStream({
165
+ start(controller) {
166
+ streamController = controller;
167
+ },
168
+ async pull(controller) {
169
+ const read = reader.read();
170
+ const stalled = new Promise((_, reject) => {
171
+ inactivityTimer = setTimeout(() => {
172
+ reject(
173
+ new import_core.CharivoTimeoutError(
174
+ `TTS stream stalled for ${STREAM_INACTIVITY_TIMEOUT_MS}ms`
175
+ )
176
+ );
177
+ }, STREAM_INACTIVITY_TIMEOUT_MS);
178
+ });
179
+ try {
180
+ const result = await Promise.race([read, stalled]);
181
+ clearTimeout(inactivityTimer);
182
+ if (stopped) {
183
+ return;
184
+ }
185
+ if (result.done) {
186
+ stopUpstream();
187
+ controller.close();
188
+ return;
189
+ }
190
+ controller.enqueue(result.value);
191
+ } catch (error) {
192
+ stopUpstream();
193
+ throw error;
194
+ }
195
+ },
196
+ cancel() {
197
+ stopUpstream();
198
+ }
199
+ });
200
+ if (signal?.aborted) {
201
+ onCallerAbort();
202
+ } else {
203
+ signal?.addEventListener("abort", onCallerAbort);
59
204
  }
60
- return response.arrayBuffer();
205
+ return { format, body };
61
206
  }
62
207
  /**
63
208
  * Legacy speak method (kept for compatibility)
64
209
  */
65
210
  async speak(text, options) {
66
211
  const audioBuffer = await this.generateAudio(text, options);
67
- const blob = new Blob([audioBuffer], { type: "audio/wav" });
212
+ const blob = new Blob([audioBuffer], { type: this.audioMimeType });
68
213
  const audioUrl = URL.createObjectURL(blob);
69
214
  return new Promise((resolve, reject) => {
70
215
  const audio = new Audio(audioUrl);
@@ -91,6 +236,28 @@ var RemoteTTSPlayer = class {
91
236
  return typeof window !== "undefined" && typeof fetch !== "undefined";
92
237
  }
93
238
  };
239
+ function parsePcmContentType(header) {
240
+ const [mediaType, ...parameters] = (header ?? "").split(";");
241
+ if (mediaType?.trim().toLowerCase() !== "audio/pcm") {
242
+ return null;
243
+ }
244
+ let sampleRate = DEFAULT_STREAM_SAMPLE_RATE;
245
+ let channels = DEFAULT_STREAM_CHANNELS;
246
+ for (const parameter of parameters) {
247
+ const [rawName, rawValue] = parameter.split("=");
248
+ const name = rawName?.trim().toLowerCase();
249
+ const value = Number(rawValue?.trim());
250
+ if (!Number.isInteger(value) || value <= 0) {
251
+ continue;
252
+ }
253
+ if (name === "rate") {
254
+ sampleRate = value;
255
+ } else if (name === "channels") {
256
+ channels = value;
257
+ }
258
+ }
259
+ return { encoding: "pcm-s16le", sampleRate, channels };
260
+ }
94
261
  function createRemoteTTSPlayer(config) {
95
262
  return new RemoteTTSPlayer(config);
96
263
  }
@@ -1,51 +1,198 @@
1
1
  // src/remote/index.ts
2
2
  import {
3
3
  CharivoProviderError,
4
+ CharivoTimeoutError,
4
5
  CharivoTransportError,
5
6
  DEFAULT_FETCH_TIMEOUT_MS,
6
- fetchWithTimeout
7
+ fetchWithTimeout,
8
+ readResponseErrorMessage
7
9
  } from "@charivo/core";
10
+ var STREAM_INACTIVITY_TIMEOUT_MS = 1e4;
11
+ var DEFAULT_STREAM_SAMPLE_RATE = 24e3;
12
+ var DEFAULT_STREAM_CHANNELS = 1;
8
13
  var RemoteTTSPlayer = class {
9
14
  playbackMode = "audio";
15
+ /**
16
+ * The container of the buffered `generateAudio` path only -- the streaming
17
+ * path carries its layout in `TTSPcmStream.format` instead.
18
+ *
19
+ * Follows what the server said it sent, because the endpoint decides the
20
+ * container: the demo's OpenAI route answers with MPEG and its Gemini one
21
+ * with WAV. Naming either here would mislabel the other. Until a response
22
+ * has been seen this is WAV, matching the manager's own fallback.
23
+ */
10
24
  audioMimeType = "audio/wav";
25
+ /**
26
+ * Present only on a streaming player: the manager selects the streaming
27
+ * path with `typeof player.generateAudioStream === "function"`, so an
28
+ * unflagged player must not carry the method at all.
29
+ */
30
+ generateAudioStream;
11
31
  apiEndpoint;
12
32
  defaultVoice;
13
33
  constructor(config = {}) {
14
34
  this.apiEndpoint = config.apiEndpoint || "/api/tts";
15
35
  this.defaultVoice = config.defaultVoice || "marin";
36
+ if (config.streaming) {
37
+ this.generateAudioStream = (text, options, signal) => this.requestAudioStream(text, options, signal);
38
+ }
16
39
  }
17
40
  /**
18
41
  * Stateless audio generation (used by the TTS Manager)
19
42
  */
20
43
  async generateAudio(text, options) {
21
- const response = await fetchWithTimeout(
44
+ return fetchWithTimeout(
22
45
  this.apiEndpoint,
23
46
  {
24
47
  method: "POST",
25
48
  headers: { "Content-Type": "application/json" },
26
- body: JSON.stringify({
27
- text,
28
- voice: options?.voice || this.defaultVoice,
29
- speed: options?.rate || 1,
30
- format: "wav"
31
- })
49
+ body: this.buildRequestBody(text, options)
32
50
  },
33
51
  {
34
52
  timeoutMessage: `TTS request timed out after ${DEFAULT_FETCH_TIMEOUT_MS}ms`,
35
53
  failureMessage: "TTS request failed"
54
+ },
55
+ // Consume the body while cancellation is still wired up, so a route that
56
+ // sends headers and then stalls -- on the error path too, where the
57
+ // message is read off the body -- still hits the deadline.
58
+ async (response) => {
59
+ if (!response.ok) {
60
+ throw new CharivoProviderError(
61
+ `TTS API failed: ${await readResponseErrorMessage(response)}`
62
+ );
63
+ }
64
+ const contentType = response.headers.get("content-type");
65
+ if (contentType) {
66
+ this.audioMimeType = contentType.split(";")[0].trim();
67
+ }
68
+ return response.arrayBuffer();
69
+ }
70
+ );
71
+ }
72
+ /** The one request payload both paths send; only the Accept header differs. */
73
+ buildRequestBody(text, options) {
74
+ return JSON.stringify({
75
+ text,
76
+ voice: options?.voice || this.defaultVoice,
77
+ speed: options?.rate || 1,
78
+ format: "wav"
79
+ });
80
+ }
81
+ async requestAudioStream(text, options, signal) {
82
+ const response = await fetchWithTimeout(
83
+ this.apiEndpoint,
84
+ {
85
+ method: "POST",
86
+ headers: {
87
+ "Content-Type": "application/json",
88
+ // A streaming route answers `audio/pcm`; a route that ignores this
89
+ // answers its usual container, which is rejected below.
90
+ Accept: "audio/pcm"
91
+ },
92
+ body: this.buildRequestBody(text, options)
93
+ },
94
+ {
95
+ timeoutMessage: `TTS request timed out after ${DEFAULT_FETCH_TIMEOUT_MS}ms`,
96
+ failureMessage: "TTS request failed",
97
+ signal
98
+ },
99
+ // Returns the Response itself rather than draining it: the helper's
100
+ // deadline covers connecting, the headers and an error body, and then
101
+ // clears. Everything after that is the inactivity timer's business.
102
+ async (settled) => {
103
+ if (!settled.ok) {
104
+ throw new CharivoProviderError(
105
+ `TTS API failed: ${await readResponseErrorMessage(settled)}`
106
+ );
107
+ }
108
+ return settled;
36
109
  }
37
110
  );
38
- if (!response.ok) {
39
- throw new CharivoProviderError(`TTS API failed: ${response.statusText}`);
111
+ const rejectAnswer = (reason) => {
112
+ void response.body?.cancel().catch(() => void 0);
113
+ throw new CharivoProviderError(
114
+ `Streaming TTS is enabled, but ${this.apiEndpoint} ${reason}`
115
+ );
116
+ };
117
+ const contentType = response.headers.get("content-type");
118
+ const format = parsePcmContentType(contentType);
119
+ if (!format) {
120
+ return rejectAnswer(
121
+ `answered "${contentType ?? "no content type"}" instead of audio/pcm`
122
+ );
123
+ }
124
+ if (format.channels !== 1) {
125
+ return rejectAnswer(
126
+ `answered ${format.channels} audio channels; the manager plays mono only`
127
+ );
128
+ }
129
+ const upstream = response.body;
130
+ if (!upstream) {
131
+ return rejectAnswer("answered audio/pcm with no body to read");
132
+ }
133
+ const reader = upstream.getReader();
134
+ let inactivityTimer;
135
+ let stopped = false;
136
+ let streamController;
137
+ const stopUpstream = () => {
138
+ stopped = true;
139
+ clearTimeout(inactivityTimer);
140
+ signal?.removeEventListener("abort", onCallerAbort);
141
+ void reader.cancel().catch(() => void 0);
142
+ };
143
+ const onCallerAbort = () => {
144
+ stopUpstream();
145
+ streamController?.error(signal.reason);
146
+ };
147
+ const body = new ReadableStream({
148
+ start(controller) {
149
+ streamController = controller;
150
+ },
151
+ async pull(controller) {
152
+ const read = reader.read();
153
+ const stalled = new Promise((_, reject) => {
154
+ inactivityTimer = setTimeout(() => {
155
+ reject(
156
+ new CharivoTimeoutError(
157
+ `TTS stream stalled for ${STREAM_INACTIVITY_TIMEOUT_MS}ms`
158
+ )
159
+ );
160
+ }, STREAM_INACTIVITY_TIMEOUT_MS);
161
+ });
162
+ try {
163
+ const result = await Promise.race([read, stalled]);
164
+ clearTimeout(inactivityTimer);
165
+ if (stopped) {
166
+ return;
167
+ }
168
+ if (result.done) {
169
+ stopUpstream();
170
+ controller.close();
171
+ return;
172
+ }
173
+ controller.enqueue(result.value);
174
+ } catch (error) {
175
+ stopUpstream();
176
+ throw error;
177
+ }
178
+ },
179
+ cancel() {
180
+ stopUpstream();
181
+ }
182
+ });
183
+ if (signal?.aborted) {
184
+ onCallerAbort();
185
+ } else {
186
+ signal?.addEventListener("abort", onCallerAbort);
40
187
  }
41
- return response.arrayBuffer();
188
+ return { format, body };
42
189
  }
43
190
  /**
44
191
  * Legacy speak method (kept for compatibility)
45
192
  */
46
193
  async speak(text, options) {
47
194
  const audioBuffer = await this.generateAudio(text, options);
48
- const blob = new Blob([audioBuffer], { type: "audio/wav" });
195
+ const blob = new Blob([audioBuffer], { type: this.audioMimeType });
49
196
  const audioUrl = URL.createObjectURL(blob);
50
197
  return new Promise((resolve, reject) => {
51
198
  const audio = new Audio(audioUrl);
@@ -72,6 +219,28 @@ var RemoteTTSPlayer = class {
72
219
  return typeof window !== "undefined" && typeof fetch !== "undefined";
73
220
  }
74
221
  };
222
+ function parsePcmContentType(header) {
223
+ const [mediaType, ...parameters] = (header ?? "").split(";");
224
+ if (mediaType?.trim().toLowerCase() !== "audio/pcm") {
225
+ return null;
226
+ }
227
+ let sampleRate = DEFAULT_STREAM_SAMPLE_RATE;
228
+ let channels = DEFAULT_STREAM_CHANNELS;
229
+ for (const parameter of parameters) {
230
+ const [rawName, rawValue] = parameter.split("=");
231
+ const name = rawName?.trim().toLowerCase();
232
+ const value = Number(rawValue?.trim());
233
+ if (!Number.isInteger(value) || value <= 0) {
234
+ continue;
235
+ }
236
+ if (name === "rate") {
237
+ sampleRate = value;
238
+ } else if (name === "channels") {
239
+ channels = value;
240
+ }
241
+ }
242
+ return { encoding: "pcm-s16le", sampleRate, channels };
243
+ }
75
244
  function createRemoteTTSPlayer(config) {
76
245
  return new RemoteTTSPlayer(config);
77
246
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@charivo/tts",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "TTS manager and browser adapters for Charivo",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -40,8 +40,8 @@
40
40
  "lipsync"
41
41
  ],
42
42
  "dependencies": {
43
- "openai": "^4.47.1",
44
- "@charivo/core": "^0.33.0"
43
+ "@charivo/core": "^0.35.0",
44
+ "openai": "^4.47.1"
45
45
  },
46
46
  "devDependencies": {
47
47
  "tsup": "^8.5.0",