@ssml-builder-js/azure-tts-client 2.14.0 → 2.15.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/CHANGELOG.md CHANGED
@@ -1,5 +1,16 @@
1
1
  # @ssml-builder-js/azure-tts-client
2
2
 
3
+ ## 2.15.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Add strict audio merge formats, discriminated synthesis errors, per-event source mappings, abortable URL validation, external audio muxers, and live Visual Editor voice capability warnings.
8
+
9
+ ### Patch Changes
10
+
11
+ - Updated dependencies
12
+ - @ssml-builder-js/ssml-core@2.15.0
13
+
3
14
  ## 2.14.0
4
15
 
5
16
  ### Minor Changes
package/dist/index.d.mts CHANGED
@@ -1,4 +1,50 @@
1
- import { SsmlTextRange, SsmlDiagnostic, AzureValidationOptions } from '@ssml-builder-js/ssml-core';
1
+ import { SsmlTextRange, SsmlSourceTextSegment, SsmlSourceMarker, SsmlDiagnostic, AzureValidationOptions } from '@ssml-builder-js/ssml-core';
2
+ import * as SpeechSDK from 'microsoft-cognitiveservices-speech-sdk';
3
+
4
+ declare const DEFAULT_OUTPUT_FORMAT = "audio-16khz-128kbitrate-mono-mp3";
5
+ declare const OUTPUT_FORMATS: {
6
+ "raw-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoMULaw;
7
+ "riff-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16KbpsMonoSiren;
8
+ "audio-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16KbpsMonoSiren;
9
+ "audio-16khz-32kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz32KBitRateMonoMp3;
10
+ "audio-16khz-128kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz128KBitRateMonoMp3;
11
+ "audio-16khz-64kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz64KBitRateMonoMp3;
12
+ "audio-24khz-48kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz48KBitRateMonoMp3;
13
+ "audio-24khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz96KBitRateMonoMp3;
14
+ "audio-24khz-160kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3;
15
+ "raw-16khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoTrueSilk;
16
+ "riff-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16BitMonoPcm;
17
+ "riff-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz16BitMonoPcm;
18
+ "riff-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm;
19
+ "riff-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoMULaw;
20
+ "raw-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoPcm;
21
+ "raw-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoPcm;
22
+ "raw-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz16BitMonoPcm;
23
+ "ogg-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg16Khz16BitMonoOpus;
24
+ "ogg-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg24Khz16BitMonoOpus;
25
+ "raw-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw48Khz16BitMonoPcm;
26
+ "riff-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff48Khz16BitMonoPcm;
27
+ "audio-48khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz96KBitRateMonoMp3;
28
+ "audio-48khz-192kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz192KBitRateMonoMp3;
29
+ "ogg-48khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg48Khz16BitMonoOpus;
30
+ "webm-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm16Khz16BitMonoOpus;
31
+ "webm-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16BitMonoOpus;
32
+ "webm-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16Bit24KbpsMonoOpus;
33
+ "raw-24khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoTrueSilk;
34
+ "raw-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoALaw;
35
+ "riff-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoALaw;
36
+ "audio-16khz-16bit-32kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16Bit32KbpsMonoOpus;
37
+ "audio-24khz-16bit-48kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit48KbpsMonoOpus;
38
+ "audio-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit24KbpsMonoOpus;
39
+ "raw-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw22050Hz16BitMonoPcm;
40
+ "riff-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff22050Hz16BitMonoPcm;
41
+ "raw-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw44100Hz16BitMonoPcm;
42
+ "riff-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff44100Hz16BitMonoPcm;
43
+ "amr-wb-16000hz": SpeechSDK.SpeechSynthesisOutputFormat.AmrWb16000Hz;
44
+ "g722-16khz-64kbps": SpeechSDK.SpeechSynthesisOutputFormat.G72216Khz64Kbps;
45
+ };
46
+ type AzureTtsOutputFormat = keyof typeof OUTPUT_FORMATS;
47
+ declare function resolveMimeType(outputFormat: string): string;
2
48
 
3
49
  interface TtsConfig {
4
50
  signal?: AbortSignal;
@@ -17,6 +63,9 @@ interface TtsConfig {
17
63
  /** Metadata used to map synchronization events back to the source document. */
18
64
  chunkIndex?: number;
19
65
  sourceNodePath?: string[];
66
+ /** Exact source text segments used to map individual Azure events. */
67
+ sourceTextSegments?: SsmlSourceTextSegment[];
68
+ sourceMarkers?: SsmlSourceMarker[];
20
69
  }
21
70
  type SynthesisChunkStatus = "pending" | "synthesizing" | "success" | "failed";
22
71
  interface SsmlSynthesisBoundary {
@@ -81,6 +130,11 @@ interface SsmlSynthesisResult {
81
130
  start: number;
82
131
  end: number;
83
132
  };
133
+ /** MIME type of a result produced by an explicit merge operation. */
134
+ mimeType?: string;
135
+ }
136
+ interface MergedSynthesisResult extends SsmlSynthesisResult {
137
+ mimeType: string;
84
138
  }
85
139
  interface SsmlSynthesisChunk {
86
140
  ssml: string;
@@ -89,9 +143,15 @@ interface SsmlSynthesisChunk {
89
143
  end: number;
90
144
  };
91
145
  sourceNodePath?: string[];
146
+ sourceTextSegments?: SsmlSourceTextSegment[];
147
+ sourceMarkers?: SsmlSourceMarker[];
92
148
  }
93
149
  interface SynthesizeChunksOptions {
94
150
  onProgress?: (event: SynthesisProgressEvent) => void;
151
+ outputFormat?: AzureTtsOutputFormat | string;
152
+ signal?: AbortSignal;
153
+ timeoutMs?: number;
154
+ sourceNodePath?: string[];
95
155
  }
96
156
  interface SynthesisProgressEvent {
97
157
  /** 1-based completed chunk count retained for backward compatibility. */
@@ -121,7 +181,9 @@ interface AzureTtsClientOptions {
121
181
  onProgress?: (event: SynthesisProgressEvent) => void;
122
182
  }
123
183
 
184
+ type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "unsupported-format-error" | "cancelled" | "timeout";
124
185
  declare class AzureTtsError extends Error {
186
+ readonly kind: "azure-api-error";
125
187
  readonly status: number;
126
188
  readonly statusText: string;
127
189
  readonly responseBody: string;
@@ -132,19 +194,35 @@ declare class AzureTtsSdkError extends AzureTtsError {
132
194
  readonly errorDetails: string;
133
195
  constructor(errorDetails: string);
134
196
  }
197
+ declare class SynthesisCancelledError extends Error {
198
+ readonly kind: "cancelled";
199
+ constructor(message?: string);
200
+ }
201
+ declare class SynthesisTimeoutError extends Error {
202
+ readonly kind: "timeout";
203
+ constructor(message: string);
204
+ }
205
+ declare class MergeError extends Error {
206
+ readonly kind: "merge-error";
207
+ readonly cause: unknown;
208
+ constructor(message: string, cause?: unknown);
209
+ }
135
210
  /** Thrown when audio buffers require container re-multiplexing before they can be merged. */
136
211
  declare class UnsupportedMergeFormatError extends Error {
212
+ readonly kind: "unsupported-format-error";
137
213
  readonly format: string;
138
214
  constructor(format: string);
139
215
  }
216
+ type AzureTtsSynthesisError = AzureTtsError | MergeError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
140
217
 
141
218
  interface SsmlValidationError {
142
- readonly kind: "validation";
219
+ readonly kind: "validation-error";
143
220
  readonly message: string;
144
221
  readonly diagnostics: readonly SsmlDiagnostic[];
145
222
  }
223
+ type SsmlSynthesisError = SsmlValidationError | AzureTtsSynthesisError;
146
224
  declare class ChunkValidationError extends Error {
147
- readonly kind: "chunk-validation";
225
+ readonly kind: "validation-error";
148
226
  readonly chunkIndex: number;
149
227
  readonly diagnostics: readonly SsmlDiagnostic[];
150
228
  constructor(chunkIndex: number, diagnostics: readonly SsmlDiagnostic[]);
@@ -154,12 +232,19 @@ type Result<T, E> = {
154
232
  readonly success: true;
155
233
  readonly status: "success";
156
234
  readonly value: T;
157
- } | {
235
+ } | (E extends {
236
+ readonly kind: infer Kind extends SynthesisErrorKind;
237
+ } ? {
158
238
  readonly ok: false;
159
239
  readonly success: false;
160
- readonly status: "validation-error" | "azure-api-error";
240
+ readonly status: Kind;
161
241
  readonly error: E;
162
- };
242
+ } : {
243
+ readonly ok: false;
244
+ readonly success: false;
245
+ readonly status: SynthesisErrorKind;
246
+ readonly error: E;
247
+ });
163
248
  type SynthesisResult<T, E> = Result<T, E>;
164
249
  type Success<T> = Extract<Result<T, never>, {
165
250
  readonly ok: true;
@@ -170,22 +255,24 @@ type ValidationErrorResult = Extract<Result<never, SsmlValidationError>, {
170
255
  type AzureApiErrorResult = Extract<Result<never, AzureTtsError>, {
171
256
  readonly status: "azure-api-error";
172
257
  }>;
173
- type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, AzureTtsError>;
258
+ type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, SsmlSynthesisError>;
174
259
  interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
175
260
  /** Optional nested form for callers that want to keep validation settings grouped. */
176
261
  validation?: AzureValidationOptions;
262
+ signal?: AbortSignal;
177
263
  }
178
264
  interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
179
265
  validation?: AzureValidationOptions;
180
266
  outputFormat?: string;
267
+ signal?: AbortSignal;
268
+ timeoutMs?: number;
269
+ sourceNodePath?: string[];
181
270
  onProgress?: (event: SynthesisProgressEvent) => void;
182
271
  }
183
- type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, AzureTtsError>;
272
+ type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, SsmlSynthesisError | ChunkValidationError>;
184
273
  interface SynthesisClient {
185
- synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
186
- synthesizeChunks?(chunks: readonly (SsmlSynthesisChunk | string)[], options?: {
187
- onProgress?: (event: SynthesisProgressEvent) => void;
188
- }): Promise<SsmlSynthesisResult>;
274
+ synthesizeSsml(ssml: string, options?: Partial<SynthesizeChunksOptions>): Promise<SsmlSynthesisResult>;
275
+ synthesizeChunks?(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
189
276
  }
190
277
  /** Validates SSML before invoking Azure and converts validation/API failures to one result shape. */
191
278
  declare function synthesizeSsmlSafe(client: Pick<AzureTtsClient, "synthesizeSsml"> | SynthesisClient, ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
@@ -196,7 +283,7 @@ declare class AzureTtsClient {
196
283
  #private;
197
284
  constructor(options: AzureTtsClientOptions);
198
285
  synthesize(ssml: string): Promise<ArrayBuffer>;
199
- synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
286
+ synthesizeSsml(ssml: string, options?: Partial<TtsConfig>): Promise<SsmlSynthesisResult>;
200
287
  synthesizeChunks(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
201
288
  synthesizeSsmlSafe(ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
202
289
  synthesizeChunksSafe(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeSsmlChunksSafeOptions): Promise<SsmlSynthesisChunksSafeResult>;
@@ -204,16 +291,25 @@ declare class AzureTtsClient {
204
291
  }
205
292
 
206
293
  type MergeAudioFormat = "wav" | "mp3" | "raw";
294
+ interface MergeAudioOptions {
295
+ format: AzureTtsOutputFormat;
296
+ }
297
+ interface MergeSynthesisOptions extends MergeAudioOptions {
298
+ customMerger?: (buffers: ArrayBuffer[], format: string) => Promise<ArrayBuffer> | ArrayBuffer;
299
+ }
300
+ type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
301
+ customMerger: NonNullable<MergeSynthesisOptions["customMerger"]>;
302
+ };
207
303
  /** Returns whether the named output format can be safely concatenated without re-multiplexing. */
208
304
  declare function resolveMergeAudioFormat(format: string): MergeAudioFormat | undefined;
209
305
  declare function canMergeAudioFormat(format: string): boolean;
210
306
  /** Merges audio buffers while preserving the invariants of supported containers. */
211
- declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], format: string): ArrayBuffer;
307
+ declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], options: MergeAudioOptions): ArrayBuffer;
212
308
  declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
213
309
  /** Synthesizes chunks sequentially, annotates synchronization events, and merges the results. */
214
310
  declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
215
- /** Concatenates audio buffers and shifts all synchronization events by prior chunk durations. */
216
- declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], format?: string): SsmlSynthesisResult;
311
+ declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: AsyncMergeSynthesisOptions): Promise<MergedSynthesisResult>;
312
+ declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: MergeAudioOptions): MergedSynthesisResult;
217
313
  /** Backward-compatible audio-only synthesis helper. */
218
314
  declare function synthesizeSpeech(ssml: string, config: TtsConfig): Promise<ArrayBuffer>;
219
315
 
@@ -245,4 +341,4 @@ interface AzureVoiceCatalog {
245
341
  /** Fetches and deduplicates the current Azure Speech voice catalog for one or more regions. */
246
342
  declare function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOptions): Promise<AzureVoiceCatalog>;
247
343
 
248
- export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, AzureTtsSdkError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, type SynthesisChunkStatus, type SynthesisProgressEvent, type SynthesisResult, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };
344
+ export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisError, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, SynthesisCancelledError, type SynthesisChunkStatus, type SynthesisErrorKind, type SynthesisProgressEvent, type SynthesisResult, SynthesisTimeoutError, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,50 @@
1
- import { SsmlTextRange, SsmlDiagnostic, AzureValidationOptions } from '@ssml-builder-js/ssml-core';
1
+ import { SsmlTextRange, SsmlSourceTextSegment, SsmlSourceMarker, SsmlDiagnostic, AzureValidationOptions } from '@ssml-builder-js/ssml-core';
2
+ import * as SpeechSDK from 'microsoft-cognitiveservices-speech-sdk';
3
+
4
+ declare const DEFAULT_OUTPUT_FORMAT = "audio-16khz-128kbitrate-mono-mp3";
5
+ declare const OUTPUT_FORMATS: {
6
+ "raw-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoMULaw;
7
+ "riff-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16KbpsMonoSiren;
8
+ "audio-16khz-16kbps-mono-siren": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16KbpsMonoSiren;
9
+ "audio-16khz-32kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz32KBitRateMonoMp3;
10
+ "audio-16khz-128kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz128KBitRateMonoMp3;
11
+ "audio-16khz-64kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz64KBitRateMonoMp3;
12
+ "audio-24khz-48kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz48KBitRateMonoMp3;
13
+ "audio-24khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz96KBitRateMonoMp3;
14
+ "audio-24khz-160kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz160KBitRateMonoMp3;
15
+ "raw-16khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoTrueSilk;
16
+ "riff-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff16Khz16BitMonoPcm;
17
+ "riff-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz16BitMonoPcm;
18
+ "riff-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm;
19
+ "riff-8khz-8bit-mono-mulaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoMULaw;
20
+ "raw-16khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw16Khz16BitMonoPcm;
21
+ "raw-24khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoPcm;
22
+ "raw-8khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz16BitMonoPcm;
23
+ "ogg-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg16Khz16BitMonoOpus;
24
+ "ogg-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg24Khz16BitMonoOpus;
25
+ "raw-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw48Khz16BitMonoPcm;
26
+ "riff-48khz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff48Khz16BitMonoPcm;
27
+ "audio-48khz-96kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz96KBitRateMonoMp3;
28
+ "audio-48khz-192kbitrate-mono-mp3": SpeechSDK.SpeechSynthesisOutputFormat.Audio48Khz192KBitRateMonoMp3;
29
+ "ogg-48khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Ogg48Khz16BitMonoOpus;
30
+ "webm-16khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm16Khz16BitMonoOpus;
31
+ "webm-24khz-16bit-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16BitMonoOpus;
32
+ "webm-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Webm24Khz16Bit24KbpsMonoOpus;
33
+ "raw-24khz-16bit-mono-truesilk": SpeechSDK.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoTrueSilk;
34
+ "raw-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Raw8Khz8BitMonoALaw;
35
+ "riff-8khz-8bit-mono-alaw": SpeechSDK.SpeechSynthesisOutputFormat.Riff8Khz8BitMonoALaw;
36
+ "audio-16khz-16bit-32kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio16Khz16Bit32KbpsMonoOpus;
37
+ "audio-24khz-16bit-48kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit48KbpsMonoOpus;
38
+ "audio-24khz-16bit-24kbps-mono-opus": SpeechSDK.SpeechSynthesisOutputFormat.Audio24Khz16Bit24KbpsMonoOpus;
39
+ "raw-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw22050Hz16BitMonoPcm;
40
+ "riff-22050hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff22050Hz16BitMonoPcm;
41
+ "raw-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Raw44100Hz16BitMonoPcm;
42
+ "riff-44100hz-16bit-mono-pcm": SpeechSDK.SpeechSynthesisOutputFormat.Riff44100Hz16BitMonoPcm;
43
+ "amr-wb-16000hz": SpeechSDK.SpeechSynthesisOutputFormat.AmrWb16000Hz;
44
+ "g722-16khz-64kbps": SpeechSDK.SpeechSynthesisOutputFormat.G72216Khz64Kbps;
45
+ };
46
+ type AzureTtsOutputFormat = keyof typeof OUTPUT_FORMATS;
47
+ declare function resolveMimeType(outputFormat: string): string;
2
48
 
3
49
  interface TtsConfig {
4
50
  signal?: AbortSignal;
@@ -17,6 +63,9 @@ interface TtsConfig {
17
63
  /** Metadata used to map synchronization events back to the source document. */
18
64
  chunkIndex?: number;
19
65
  sourceNodePath?: string[];
66
+ /** Exact source text segments used to map individual Azure events. */
67
+ sourceTextSegments?: SsmlSourceTextSegment[];
68
+ sourceMarkers?: SsmlSourceMarker[];
20
69
  }
21
70
  type SynthesisChunkStatus = "pending" | "synthesizing" | "success" | "failed";
22
71
  interface SsmlSynthesisBoundary {
@@ -81,6 +130,11 @@ interface SsmlSynthesisResult {
81
130
  start: number;
82
131
  end: number;
83
132
  };
133
+ /** MIME type of a result produced by an explicit merge operation. */
134
+ mimeType?: string;
135
+ }
136
+ interface MergedSynthesisResult extends SsmlSynthesisResult {
137
+ mimeType: string;
84
138
  }
85
139
  interface SsmlSynthesisChunk {
86
140
  ssml: string;
@@ -89,9 +143,15 @@ interface SsmlSynthesisChunk {
89
143
  end: number;
90
144
  };
91
145
  sourceNodePath?: string[];
146
+ sourceTextSegments?: SsmlSourceTextSegment[];
147
+ sourceMarkers?: SsmlSourceMarker[];
92
148
  }
93
149
  interface SynthesizeChunksOptions {
94
150
  onProgress?: (event: SynthesisProgressEvent) => void;
151
+ outputFormat?: AzureTtsOutputFormat | string;
152
+ signal?: AbortSignal;
153
+ timeoutMs?: number;
154
+ sourceNodePath?: string[];
95
155
  }
96
156
  interface SynthesisProgressEvent {
97
157
  /** 1-based completed chunk count retained for backward compatibility. */
@@ -121,7 +181,9 @@ interface AzureTtsClientOptions {
121
181
  onProgress?: (event: SynthesisProgressEvent) => void;
122
182
  }
123
183
 
184
+ type SynthesisErrorKind = "validation-error" | "azure-api-error" | "merge-error" | "unsupported-format-error" | "cancelled" | "timeout";
124
185
  declare class AzureTtsError extends Error {
186
+ readonly kind: "azure-api-error";
125
187
  readonly status: number;
126
188
  readonly statusText: string;
127
189
  readonly responseBody: string;
@@ -132,19 +194,35 @@ declare class AzureTtsSdkError extends AzureTtsError {
132
194
  readonly errorDetails: string;
133
195
  constructor(errorDetails: string);
134
196
  }
197
+ declare class SynthesisCancelledError extends Error {
198
+ readonly kind: "cancelled";
199
+ constructor(message?: string);
200
+ }
201
+ declare class SynthesisTimeoutError extends Error {
202
+ readonly kind: "timeout";
203
+ constructor(message: string);
204
+ }
205
+ declare class MergeError extends Error {
206
+ readonly kind: "merge-error";
207
+ readonly cause: unknown;
208
+ constructor(message: string, cause?: unknown);
209
+ }
135
210
  /** Thrown when audio buffers require container re-multiplexing before they can be merged. */
136
211
  declare class UnsupportedMergeFormatError extends Error {
212
+ readonly kind: "unsupported-format-error";
137
213
  readonly format: string;
138
214
  constructor(format: string);
139
215
  }
216
+ type AzureTtsSynthesisError = AzureTtsError | MergeError | UnsupportedMergeFormatError | SynthesisCancelledError | SynthesisTimeoutError;
140
217
 
141
218
  interface SsmlValidationError {
142
- readonly kind: "validation";
219
+ readonly kind: "validation-error";
143
220
  readonly message: string;
144
221
  readonly diagnostics: readonly SsmlDiagnostic[];
145
222
  }
223
+ type SsmlSynthesisError = SsmlValidationError | AzureTtsSynthesisError;
146
224
  declare class ChunkValidationError extends Error {
147
- readonly kind: "chunk-validation";
225
+ readonly kind: "validation-error";
148
226
  readonly chunkIndex: number;
149
227
  readonly diagnostics: readonly SsmlDiagnostic[];
150
228
  constructor(chunkIndex: number, diagnostics: readonly SsmlDiagnostic[]);
@@ -154,12 +232,19 @@ type Result<T, E> = {
154
232
  readonly success: true;
155
233
  readonly status: "success";
156
234
  readonly value: T;
157
- } | {
235
+ } | (E extends {
236
+ readonly kind: infer Kind extends SynthesisErrorKind;
237
+ } ? {
158
238
  readonly ok: false;
159
239
  readonly success: false;
160
- readonly status: "validation-error" | "azure-api-error";
240
+ readonly status: Kind;
161
241
  readonly error: E;
162
- };
242
+ } : {
243
+ readonly ok: false;
244
+ readonly success: false;
245
+ readonly status: SynthesisErrorKind;
246
+ readonly error: E;
247
+ });
163
248
  type SynthesisResult<T, E> = Result<T, E>;
164
249
  type Success<T> = Extract<Result<T, never>, {
165
250
  readonly ok: true;
@@ -170,22 +255,24 @@ type ValidationErrorResult = Extract<Result<never, SsmlValidationError>, {
170
255
  type AzureApiErrorResult = Extract<Result<never, AzureTtsError>, {
171
256
  readonly status: "azure-api-error";
172
257
  }>;
173
- type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, AzureTtsError>;
258
+ type SsmlSynthesisSafeResult = Result<SsmlSynthesisResult, never> | Result<never, SsmlValidationError> | Result<never, SsmlSynthesisError>;
174
259
  interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
175
260
  /** Optional nested form for callers that want to keep validation settings grouped. */
176
261
  validation?: AzureValidationOptions;
262
+ signal?: AbortSignal;
177
263
  }
178
264
  interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
179
265
  validation?: AzureValidationOptions;
180
266
  outputFormat?: string;
267
+ signal?: AbortSignal;
268
+ timeoutMs?: number;
269
+ sourceNodePath?: string[];
181
270
  onProgress?: (event: SynthesisProgressEvent) => void;
182
271
  }
183
- type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, AzureTtsError>;
272
+ type SsmlSynthesisChunksSafeResult = Result<SsmlSynthesisResult, never> | Result<never, ChunkValidationError> | Result<never, SsmlSynthesisError | ChunkValidationError>;
184
273
  interface SynthesisClient {
185
- synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
186
- synthesizeChunks?(chunks: readonly (SsmlSynthesisChunk | string)[], options?: {
187
- onProgress?: (event: SynthesisProgressEvent) => void;
188
- }): Promise<SsmlSynthesisResult>;
274
+ synthesizeSsml(ssml: string, options?: Partial<SynthesizeChunksOptions>): Promise<SsmlSynthesisResult>;
275
+ synthesizeChunks?(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
189
276
  }
190
277
  /** Validates SSML before invoking Azure and converts validation/API failures to one result shape. */
191
278
  declare function synthesizeSsmlSafe(client: Pick<AzureTtsClient, "synthesizeSsml"> | SynthesisClient, ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
@@ -196,7 +283,7 @@ declare class AzureTtsClient {
196
283
  #private;
197
284
  constructor(options: AzureTtsClientOptions);
198
285
  synthesize(ssml: string): Promise<ArrayBuffer>;
199
- synthesizeSsml(ssml: string): Promise<SsmlSynthesisResult>;
286
+ synthesizeSsml(ssml: string, options?: Partial<TtsConfig>): Promise<SsmlSynthesisResult>;
200
287
  synthesizeChunks(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeChunksOptions): Promise<SsmlSynthesisResult>;
201
288
  synthesizeSsmlSafe(ssml: string, options?: SynthesizeSsmlSafeOptions): Promise<SsmlSynthesisSafeResult>;
202
289
  synthesizeChunksSafe(chunks: readonly (SsmlSynthesisChunk | string)[], options?: SynthesizeSsmlChunksSafeOptions): Promise<SsmlSynthesisChunksSafeResult>;
@@ -204,16 +291,25 @@ declare class AzureTtsClient {
204
291
  }
205
292
 
206
293
  type MergeAudioFormat = "wav" | "mp3" | "raw";
294
+ interface MergeAudioOptions {
295
+ format: AzureTtsOutputFormat;
296
+ }
297
+ interface MergeSynthesisOptions extends MergeAudioOptions {
298
+ customMerger?: (buffers: ArrayBuffer[], format: string) => Promise<ArrayBuffer> | ArrayBuffer;
299
+ }
300
+ type AsyncMergeSynthesisOptions = MergeSynthesisOptions & {
301
+ customMerger: NonNullable<MergeSynthesisOptions["customMerger"]>;
302
+ };
207
303
  /** Returns whether the named output format can be safely concatenated without re-multiplexing. */
208
304
  declare function resolveMergeAudioFormat(format: string): MergeAudioFormat | undefined;
209
305
  declare function canMergeAudioFormat(format: string): boolean;
210
306
  /** Merges audio buffers while preserving the invariants of supported containers. */
211
- declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], format: string): ArrayBuffer;
307
+ declare function mergeAudioBuffers(buffers: readonly ArrayBuffer[], options: MergeAudioOptions): ArrayBuffer;
212
308
  declare function synthesizeSsml(ssml: string, config: TtsConfig): Promise<SsmlSynthesisResult>;
213
309
  /** Synthesizes chunks sequentially, annotates synchronization events, and merges the results. */
214
310
  declare function synthesizeSsmlChunks(chunks: readonly (SsmlSynthesisChunk | string)[], config: TtsConfig): Promise<SsmlSynthesisResult>;
215
- /** Concatenates audio buffers and shifts all synchronization events by prior chunk durations. */
216
- declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], format?: string): SsmlSynthesisResult;
311
+ declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: AsyncMergeSynthesisOptions): Promise<MergedSynthesisResult>;
312
+ declare function mergeSynthesisResults(results: readonly SsmlSynthesisResult[], options: MergeAudioOptions): MergedSynthesisResult;
217
313
  /** Backward-compatible audio-only synthesis helper. */
218
314
  declare function synthesizeSpeech(ssml: string, config: TtsConfig): Promise<ArrayBuffer>;
219
315
 
@@ -245,4 +341,4 @@ interface AzureVoiceCatalog {
245
341
  /** Fetches and deduplicates the current Azure Speech voice catalog for one or more regions. */
246
342
  declare function fetchAzureVoiceCatalog(options: FetchAzureVoiceCatalogOptions): Promise<AzureVoiceCatalog>;
247
343
 
248
- export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, AzureTtsSdkError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, type SynthesisChunkStatus, type SynthesisProgressEvent, type SynthesisResult, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };
344
+ export { type AzureApiErrorResult, type SsmlValidationError as AzureSsmlValidationError, AzureTtsClient, type AzureTtsClientOptions, AzureTtsError, type AzureTtsLogger, type AzureTtsOutputFormat, AzureTtsSdkError, type AzureTtsSynthesisError, type AzureVoiceCatalog, type AzureVoiceCatalogVoice, ChunkValidationError, DEFAULT_OUTPUT_FORMAT, type FetchAzureVoiceCatalogOptions, type FetchedAzureVoiceCatalogMetadata, type MergeAudioFormat, type MergeAudioOptions, MergeError, type MergeSynthesisOptions, type MergedSynthesisResult, type Result, type SsmlSynthesisBookmark, type SsmlSynthesisBoundary, type SsmlSynthesisChunk, type SsmlSynthesisChunksSafeResult, type SsmlSynthesisError, type SsmlSynthesisResult, type SsmlSynthesisSafeResult, type SsmlSynthesisViseme, type Success, SynthesisCancelledError, type SynthesisChunkStatus, type SynthesisErrorKind, type SynthesisProgressEvent, type SynthesisResult, SynthesisTimeoutError, type SynthesizeChunksOptions, type SynthesizeSsmlChunksSafeOptions, type SynthesizeSsmlSafeOptions, type TtsConfig, UnsupportedMergeFormatError, type ValidationErrorResult, canMergeAudioFormat, fetchAzureVoiceCatalog, mergeAudioBuffers, mergeSynthesisResults, resolveMergeAudioFormat, resolveMimeType, synthesizeSpeech, synthesizeSsml, synthesizeSsmlChunks, synthesizeSsmlChunksSafe, synthesizeSsmlSafe };