@supertone/supertone 0.1.1 → 0.1.3

package/src/sdk/texttospeech.ts

@@ -21,9 +21,23 @@ import {
   detectAudioFormat,
   mergeMp3Binary,
   mergeWavBinary,
+  applyPronunciationDictionary,
+  type PronunciationDictionaryEntry,
   removeMp3Header,
   removeWavHeader,
 } from "../lib/custom_utils/index.js";
+
+type CreateSpeechOptions = RequestOptions & {
+  acceptHeaderOverride?: CreateSpeechAcceptEnum;
+  maxTextLength?: number;
+  pronunciationDictionary?: PronunciationDictionaryEntry[];
+};
+
+type StreamSpeechOptions = RequestOptions & {
+  acceptHeaderOverride?: StreamSpeechAcceptEnum;
+  maxTextLength?: number;
+  pronunciationDictionary?: PronunciationDictionaryEntry[];
+};
 // #endregion imports
 
 export { CreateSpeechAcceptEnum } from "../funcs/textToSpeechCreateSpeech.js";
@@ -53,11 +67,22 @@ export class TextToSpeech extends ClientSDK {
     return text.length > maxLength;
   }
 
+  /**
+   * Apply pronunciation dictionary before chunking (opt-in).
+   */
+  private applyPronunciationDictionary(
+    text: string,
+    pronunciationDictionary?: PronunciationDictionaryEntry[]
+  ): string {
+    if (!pronunciationDictionary) return text;
+    return applyPronunciationDictionary(text, pronunciationDictionary);
+  }
+
   /**
    * Extract audio data from response
    */
   private async extractAudioFromResponse(
-    response: operations.CreateSpeechResponse | operations.StreamSpeechResponse,
+    response: operations.CreateSpeechResponse | operations.StreamSpeechResponse
   ): Promise<Uint8Array> {
     const result = response.result;
 
@@ -74,9 +99,9 @@ export class TextToSpeech extends ClientSDK {
     }
 
     if (
-      typeof result === "object"
-      && result !== null
-      && "getReader" in result
+      typeof result === "object" &&
+      result !== null &&
+      "getReader" in result
     ) {
       // ReadableStream
       const reader = (result as ReadableStream<Uint8Array>).getReader();
@@ -131,14 +156,15 @@ export class TextToSpeech extends ClientSDK {
     // Enhanced error message with object inspection
     const resultType = typeof result;
     const resultConstructor = result?.constructor?.name || "unknown";
-    const resultKeys = result && typeof result === "object"
-      ? Object.keys(result).join(", ")
-      : "N/A";
+    const resultKeys =
+      result && typeof result === "object"
+        ? Object.keys(result).join(", ")
+        : "N/A";
 
     throw new Error(
-      `Unsupported result type: ${resultType}, `
-        + `constructor: ${resultConstructor}, `
-        + `keys: [${resultKeys}]`,
+      `Unsupported result type: ${resultType}, ` +
+        `constructor: ${resultConstructor}, ` +
+        `keys: [${resultKeys}]`
     );
   }
 
@@ -146,7 +172,7 @@ export class TextToSpeech extends ClientSDK {
    * Merge multiple audio responses into one
    */
   private async mergeAudioResponses(
-    responses: operations.CreateSpeechResponse[],
+    responses: operations.CreateSpeechResponse[]
   ): Promise<operations.CreateSpeechResponse> {
     if (responses.length === 0) {
       throw new Error("No responses to merge");
@@ -163,7 +189,7 @@ export class TextToSpeech extends ClientSDK {
 
     // Extract audio data from all responses
     const audioChunks: Uint8Array[] = await Promise.all(
-      responses.map((r) => this.extractAudioFromResponse(r)),
+      responses.map((r) => this.extractAudioFromResponse(r))
     );
 
     const firstChunk = audioChunks[0];
@@ -208,14 +234,14 @@ export class TextToSpeech extends ClientSDK {
     originalRequest: operations.StreamSpeechRequest,
     options?: RequestOptions & {
       acceptHeaderOverride?: StreamSpeechAcceptEnum;
-    },
+    }
   ): operations.StreamSpeechResponse {
     let audioFormat: "wav" | "mp3" | null = null;
     let isFirstAudioChunk = true;
 
     // Use arrow function to preserve 'this' context
     const processStream = async (
-      controller: ReadableStreamDefaultController<Uint8Array>,
+      controller: ReadableStreamDefaultController<Uint8Array>
     ) => {
       try {
         // Stream first response (first text chunk)
@@ -263,7 +289,7 @@ export class TextToSpeech extends ClientSDK {
           }
           const chunkResponse = await this._streamSpeechOriginal(
             chunkRequest,
-            options,
+            options
           );
 
           // Stream this text chunk's audio
@@ -323,40 +349,51 @@ export class TextToSpeech extends ClientSDK {
    */
   private async createSpeechWithChunking(
     request: operations.CreateSpeechRequest,
-    options?: RequestOptions & {
-      acceptHeaderOverride?: CreateSpeechAcceptEnum;
-      maxTextLength?: number;
-    },
+    options?: CreateSpeechOptions
   ): Promise<operations.CreateSpeechResponse> {
+    const { pronunciationDictionary, ...restOptions } = options ?? {};
     const maxLength = options?.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH;
-    const text = request.apiConvertTextToSpeechUsingCharacterRequest?.text
-      ?? "";
+    const text =
+      request.apiConvertTextToSpeechUsingCharacterRequest?.text ?? "";
+    const normalizedText = this.applyPronunciationDictionary(
+      text,
+      pronunciationDictionary
+    );
+
+    const baseRequest: operations.CreateSpeechRequest = {
+      ...request,
+      apiConvertTextToSpeechUsingCharacterRequest: {
+        ...request.apiConvertTextToSpeechUsingCharacterRequest,
+        text: normalizedText,
+      },
+    };
 
     // Short text: call original method directly
-    if (!this.shouldChunkText(text, maxLength)) {
+    if (!this.shouldChunkText(normalizedText, maxLength)) {
       if (!this._createSpeechOriginal) {
         throw new Error("Original createSpeech method not found");
       }
-      return this._createSpeechOriginal(request, options);
+      return this._createSpeechOriginal(baseRequest, restOptions);
     }
 
     // Long text: chunk, process sequentially (to avoid schema parsing issues), and merge
-    const textChunks = chunkText(text, maxLength);
+    const textChunks = chunkText(normalizedText, maxLength);
 
     // Determine Accept header based on output format
-    const outputFormat = request.apiConvertTextToSpeechUsingCharacterRequest
-      ?.outputFormat;
-    const acceptHeader: CreateSpeechAcceptEnum = outputFormat === "mp3"
-      ? CreateSpeechAcceptEnum.audioMpeg
-      : CreateSpeechAcceptEnum.audioWav;
+    const outputFormat =
+      baseRequest.apiConvertTextToSpeechUsingCharacterRequest?.outputFormat;
+    const acceptHeader: CreateSpeechAcceptEnum =
+      outputFormat === "mp3"
+        ? CreateSpeechAcceptEnum.audioMpeg
+        : CreateSpeechAcceptEnum.audioWav;
 
     // Process chunks sequentially to avoid race conditions in schema parsing
     const responses: operations.CreateSpeechResponse[] = [];
     for (const chunk of textChunks) {
       const chunkRequest: operations.CreateSpeechRequest = {
-        ...request,
+        ...baseRequest,
         apiConvertTextToSpeechUsingCharacterRequest: {
-          ...request.apiConvertTextToSpeechUsingCharacterRequest,
+          ...baseRequest.apiConvertTextToSpeechUsingCharacterRequest,
           text: chunk,
         },
       };
@@ -364,7 +401,7 @@ export class TextToSpeech extends ClientSDK {
         throw new Error("Original createSpeech method not found");
       }
       const response = await this._createSpeechOriginal(chunkRequest, {
-        ...options,
+        ...restOptions,
         acceptHeaderOverride: acceptHeader,
       });
       responses.push(response);
@@ -378,25 +415,35 @@ export class TextToSpeech extends ClientSDK {
    */
   private async streamSpeechWithChunking(
     request: operations.StreamSpeechRequest,
-    options?: RequestOptions & {
-      acceptHeaderOverride?: StreamSpeechAcceptEnum;
-      maxTextLength?: number;
-    },
+    options?: StreamSpeechOptions
   ): Promise<operations.StreamSpeechResponse> {
+    const { pronunciationDictionary, ...restOptions } = options ?? {};
     const maxLength = options?.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH;
-    const text = request.apiConvertTextToSpeechUsingCharacterRequest?.text
-      ?? "";
+    const text =
+      request.apiConvertTextToSpeechUsingCharacterRequest?.text ?? "";
+    const normalizedText = this.applyPronunciationDictionary(
+      text,
+      pronunciationDictionary
+    );
+
+    const baseRequest: operations.StreamSpeechRequest = {
+      ...request,
+      apiConvertTextToSpeechUsingCharacterRequest: {
+        ...request.apiConvertTextToSpeechUsingCharacterRequest,
+        text: normalizedText,
+      },
+    };
 
     // Short text: call original method directly
-    if (!this.shouldChunkText(text, maxLength)) {
+    if (!this.shouldChunkText(normalizedText, maxLength)) {
       if (!this._streamSpeechOriginal) {
         throw new Error("Original streamSpeech method not found");
       }
-      return this._streamSpeechOriginal(request, options);
+      return this._streamSpeechOriginal(baseRequest, restOptions);
     }
 
     // Long text: chunk and stream sequentially
-    const textChunks = chunkText(text, maxLength);
+    const textChunks = chunkText(normalizedText, maxLength);
 
     if (textChunks.length === 0) {
       throw new Error("No text chunks to process");
@@ -409,9 +456,9 @@ export class TextToSpeech extends ClientSDK {
 
     // Get first response to start streaming
     const firstChunkRequest: operations.StreamSpeechRequest = {
-      ...request,
+      ...baseRequest,
       apiConvertTextToSpeechUsingCharacterRequest: {
-        ...request.apiConvertTextToSpeechUsingCharacterRequest,
+        ...baseRequest.apiConvertTextToSpeechUsingCharacterRequest,
         text: firstChunk,
       },
     };
@@ -421,7 +468,7 @@ export class TextToSpeech extends ClientSDK {
     }
     const firstResponse = await this._streamSpeechOriginal(
       firstChunkRequest,
-      options,
+      restOptions
     );
 
     // Single chunk: return as-is
@@ -434,8 +481,8 @@ export class TextToSpeech extends ClientSDK {
     return this.createExtendedStreamingResponse(
       firstResponse,
       remainingChunks,
-      request,
-      options,
+      baseRequest,
+      restOptions
     );
   }
   // #endregion sdk-class-body
@@ -448,15 +495,9 @@ export class TextToSpeech extends ClientSDK {
    */
   async createSpeech(
     request: operations.CreateSpeechRequest,
-    options?: RequestOptions & {
-      acceptHeaderOverride?: CreateSpeechAcceptEnum;
-    },
+    options?: CreateSpeechOptions
   ): Promise<operations.CreateSpeechResponse> {
-    return unwrapAsync(textToSpeechCreateSpeech(
-      this,
-      request,
-      options,
-    ));
+    return unwrapAsync(textToSpeechCreateSpeech(this, request, options));
   }
 
   /**
@@ -467,15 +508,9 @@ export class TextToSpeech extends ClientSDK {
    */
   async streamSpeech(
     request: operations.StreamSpeechRequest,
-    options?: RequestOptions & {
-      acceptHeaderOverride?: StreamSpeechAcceptEnum;
-    },
+    options?: StreamSpeechOptions
   ): Promise<operations.StreamSpeechResponse> {
-    return unwrapAsync(textToSpeechStreamSpeech(
-      this,
-      request,
-      options,
-    ));
+    return unwrapAsync(textToSpeechStreamSpeech(this, request, options));
   }
 
   /**
@@ -486,12 +521,8 @@ export class TextToSpeech extends ClientSDK {
    */
   async predictDuration(
     request: operations.PredictDurationRequest,
-    options?: RequestOptions,
+    options?: RequestOptions
   ): Promise<operations.PredictDurationResponse> {
-    return unwrapAsync(textToSpeechPredictDuration(
-      this,
-      request,
-      options,
-    ));
+    return unwrapAsync(textToSpeechPredictDuration(this, request, options));
   }
 }