@framers/agentos 0.1.110 → 0.1.112

package/dist/speech/providers/AzureSpeechSTTProvider.js

@@ -1,52 +1,156 @@
-/** Converts Azure 100-nanosecond ticks to seconds. */
+/**
+ * Converts Azure's 100-nanosecond tick unit to seconds.
+ *
+ * Azure Cognitive Services uses "ticks" (100-nanosecond units) for all
+ * timing fields. One second = 10,000,000 ticks.
+ *
+ * @param ticks - Duration in 100-nanosecond Azure ticks.
+ * @returns Duration in seconds.
+ *
+ * @example
+ * ```ts
+ * ticksToSeconds(30_000_000); // 3.0 seconds
+ * ticksToSeconds(15_000_000); // 1.5 seconds
+ * ```
+ */
 function ticksToSeconds(ticks) {
     return ticks / 10000000;
 }
 /**
  * Speech-to-text provider that uses the Azure Cognitive Services Speech REST API.
  *
- * Sends WAV audio as a raw binary body and returns a normalised
- * {@link SpeechTranscriptionResult}. A `RecognitionStatus` of `'NoMatch'`
- * is mapped to an empty text result rather than an error, matching the
- * Azure SDK behaviour.
+ * ## Azure REST Endpoint Format
+ *
+ * The endpoint URL follows this pattern:
+ * ```
+ * https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language={lang}
+ * ```
+ *
+ * - `{region}` — The Azure region from config (e.g. `eastus`, `westeurope`).
+ * - `{lang}` — BCP-47 language code from options or `'en-US'` default.
+ * - The `/conversation/` path segment selects the conversation recognition mode
+ *   (as opposed to `/interactive/` or `/dictation/`).
+ *
+ * ## Authentication: `Ocp-Apim-Subscription-Key`
+ *
+ * Azure Cognitive Services uses the `Ocp-Apim-Subscription-Key` HTTP header
+ * for authentication, which differs from the typical `Authorization: Bearer`
+ * pattern. The subscription key is sent as a plain-text header value — no
+ * "Bearer" or "Token" prefix.
+ *
+ * An alternative is to use a short-lived token from the token endpoint, but
+ * this provider uses the simpler key-based approach for reliability.
+ *
+ * ## NoMatch Handling
+ *
+ * When Azure's recognizer detects audio but cannot identify any speech, it
+ * returns `RecognitionStatus: 'NoMatch'` instead of raising an HTTP error.
+ * This provider maps `NoMatch` to an empty-text result (`text: ''`) with
+ * `isFinal: true`, matching the Azure Speech SDK's behaviour. This prevents
+ * the fallback proxy from unnecessarily trying another provider when the
+ * audio genuinely contains no speech.
+ *
+ * ## Limitations
+ *
+ * - Audio must be PCM WAV format. The `Content-Type` is hardcoded to
+ *   `audio/wav` regardless of the `audio.mimeType` value.
+ * - Streaming is not supported — use the Azure Speech SDK for real-time STT.
+ * - Speaker diarization is not available via the REST API.
+ *
+ * @see {@link AzureSpeechSTTProviderConfig} for configuration options
+ * @see {@link AzureSpeechTTSProvider} for the corresponding TTS provider
  *
  * @example
  * ```ts
- * const provider = new AzureSpeechSTTProvider({ key: process.env.AZURE_SPEECH_KEY!, region: 'eastus' });
- * const result = await provider.transcribe({ data: wavBuffer });
- * console.log(result.text);
+ * const provider = new AzureSpeechSTTProvider({
+ *   key: process.env.AZURE_SPEECH_KEY!,
+ *   region: 'eastus',
+ * });
+ * const result = await provider.transcribe(
+ *   { data: wavBuffer, mimeType: 'audio/wav' },
+ *   { language: 'de-DE' },
+ * );
+ * console.log(result.text); // '' if no speech detected
  * ```
  */
 export class AzureSpeechSTTProvider {
+    /**
+     * Creates a new AzureSpeechSTTProvider.
+     *
+     * @param config - Provider configuration including the subscription key and region.
+     *
+     * @example
+     * ```ts
+     * const provider = new AzureSpeechSTTProvider({
+     *   key: 'your-azure-subscription-key',
+     *   region: 'eastus',
+     * });
+     * ```
+     */
     constructor(config) {
         this.config = config;
+        /** Unique provider identifier used for registration and resolution. */
         this.id = 'azure-speech-stt';
+        /** Human-readable display name for UI and logging. */
         this.displayName = 'Azure Speech (STT)';
+        /** This provider uses synchronous HTTP requests, not WebSocket streaming. */
         this.supportsStreaming = false;
         this.fetchImpl = config.fetchImpl ?? fetch;
     }
-    /** Returns the human-readable provider name. */
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'Azure Speech (STT)'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'Azure Speech (STT)'
+     * ```
+     */
     getProviderName() {
         return this.displayName;
     }
     /**
      * Transcribes an audio buffer using the Azure Speech recognition REST endpoint.
      *
-     * @param audio - Raw audio data. Azure expects PCM WAV; pass `mimeType: 'audio/wav'`.
-     * @param options - Optional transcription settings (language…).
-     * @returns A promise resolving to the normalised transcription result.
-     * @throws When the Azure API returns a non-2xx status.
+     * Sends the raw audio as PCM WAV and returns a normalized result. Azure's
+     * `NoMatch` status is treated as an empty transcript (not an error).
+     *
+     * @param audio - Raw audio data. Azure expects PCM WAV format; the
+     *   Content-Type header is always set to `'audio/wav'` regardless of
+     *   `audio.mimeType`.
+     * @param options - Optional transcription settings. Only `language` is
+     *   supported by the Azure REST endpoint.
+     * @returns A promise resolving to the normalized transcription result.
+     * @throws {Error} When the Azure API returns a non-2xx HTTP status code.
+     *   The error message includes the status and response body text.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.transcribe(
+     *   { data: wavBuffer, durationSeconds: 5 },
+     *   { language: 'fr-FR' },
+     * );
+     * if (result.text === '') {
+     *   console.log('No speech detected in the audio');
+     * }
+     * ```
      */
     async transcribe(audio, options = {}) {
         const lang = options.language ?? 'en-US';
         const { key, region } = this.config;
+        // Build the Azure STT REST endpoint URL.
+        // The /conversation/ path selects conversation recognition mode which is
+        // the most general-purpose mode for varied audio content.
         const url = `https://${region}.stt.speech.microsoft.com` +
             `/speech/recognition/conversation/cognitiveservices/v1` +
             `?language=${encodeURIComponent(lang)}`;
         const response = await this.fetchImpl(url, {
             method: 'POST',
             headers: {
+                // Azure uses this non-standard header for subscription key auth
                 'Ocp-Apim-Subscription-Key': key,
+                // Hardcoded to audio/wav because Azure's REST endpoint requires WAV format
                 'Content-Type': 'audio/wav',
             },
             body: audio.data,
@@ -56,7 +160,9 @@ export class AzureSpeechSTTProvider {
             throw new Error(`Azure Speech STT failed (${response.status}): ${message}`);
         }
         const payload = (await response.json());
-        // NoMatch means the recognizer found no speech — return empty text gracefully.
+        // NoMatch means the recognizer detected audio but found no speech content.
+        // Return an empty result instead of throwing — this is the expected behaviour
+        // for silence or noise-only audio, matching the Azure Speech SDK pattern.
         if (payload.RecognitionStatus === 'NoMatch') {
             return {
                 text: '',
@@ -70,6 +176,8 @@ export class AzureSpeechSTTProvider {
                 },
             };
         }
+        // Convert Azure's 100-nanosecond ticks to seconds, falling back to the
+        // client-provided duration estimate if the API doesn't return Duration.
         const durationSeconds = typeof payload.Duration === 'number'
             ? ticksToSeconds(payload.Duration)
             : audio.durationSeconds;

package/dist/speech/providers/AzureSpeechSTTProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"AzureSpeechSTTProvider.js","sourceRoot":"","sources":["../../../src/speech/providers/AzureSpeechSTTProvider.ts"],"names":[],"mappings":"AAiCA,sDAAsD;AACtD,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,KAAK,GAAG,QAAU,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,sBAAsB;IAOjC,YAA6B,MAAoC;QAApC,WAAM,GAAN,MAAM,CAA8B;QANjD,OAAE,GAAG,kBAAkB,CAAC;QACxB,gBAAW,GAAG,oBAAoB,CAAC;QACnC,sBAAiB,GAAG,KAAK,CAAC;QAKxC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,CAAC;IAED,gDAAgD;IAChD,eAAe;QACb,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,UAAU,CACd,KAAuB,EACvB,UAAsC,EAAE;QAExC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC;QACzC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QAEpC,MAAM,GAAG,GACP,WAAW,MAAM,2BAA2B;YAC5C,uDAAuD;YACvD,aAAa,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAE1C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;YACzC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,2BAA2B,EAAE,GAAG;gBAChC,cAAc,EAAE,WAAW;aAC5B;YACD,IAAI,EAAE,KAAK,CAAC,IAA2B;SACxC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,CAAC,MAAM,MAAM,OAAO,EAAE,CAAC,CAAC;QAC9E,CAAC;QAED,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAwB,CAAC;QAE/D,+EAA+E;QAC/E,IAAI,OAAO,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YAC5C,OAAO;gBACL,IAAI,EAAE,EAAE;gBACR,QAAQ,EAAE,IAAI;gBACd,IAAI,EAAE,CAAC;gBACP,OAAO,EAAE,IAAI;gBACb,gBAAgB,EAAE,OAAO;gBACzB,KAAK,EAAE;oBACL,eAAe,EAAE,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,EAAE;oBAClD,SAAS,EAAE,kBAAkB;iBAC9B;aACF,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GACnB,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;YAClC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC;YAClC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;QAE5B,OAAO;YACL,IAAI,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;YAC/B,QAAQ,EAAE,IAAI;YACd,eAAe;YACf,IAAI,EAAE,CAAC;YACP,gBAAgB,EAAE,OAAO;YACzB,OAAO,EAAE,IAAI;YACb,KAAK,EAAE;gBACL,eAAe,EAAE,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,EAAE;gBAC5C,SAAS,EAAE,kBAAkB;aAC9B;SACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"AzureSpeechSTTProvider.js","sourceRoot":"","sources":["../../../src/speech/providers/AzureSpeechSTTProvider.ts"],"names":[],"mappings":"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"}

package/dist/speech/providers/AzureSpeechTTSProvider.d.ts

@@ -1,59 +1,174 @@
 import type { SpeechSynthesisOptions, SpeechSynthesisResult, SpeechVoice, TextToSpeechProvider } from '../types.js';
-/** Configuration for the AzureSpeechTTSProvider. */
+/**
+ * Configuration for the {@link AzureSpeechTTSProvider}.
+ *
+ * @see {@link AzureSpeechTTSProvider} for usage examples
+ * @see https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech
+ */
 export interface AzureSpeechTTSProviderConfig {
-    /** Azure Cognitive Services subscription key. */
+    /**
+     * Azure Cognitive Services subscription key.
+     * Sent as the `Ocp-Apim-Subscription-Key` header value.
+     *
+     * @see {@link AzureSpeechSTTProviderConfig.key} for the same pattern on STT
+     */
     key: string;
-    /** Azure region, e.g. `'eastus'` or `'westeurope'`. */
+    /**
+     * Azure region where the Speech resource is deployed, e.g. `'eastus'`,
+     * `'westeurope'`, `'southeastasia'`.
+     *
+     * The region determines the REST endpoint hostname:
+     * `https://{region}.tts.speech.microsoft.com`
+     */
     region: string;
     /**
      * Default voice name to use when none is specified per-request.
+     * Must be a valid Azure voice short-name (e.g. `'en-US-JennyNeural'`).
+     *
      * @default 'en-US-JennyNeural'
+     * @see https://learn.microsoft.com/azure/ai-services/speech-service/language-support#prebuilt-neural-voices
      */
     defaultVoice?: string;
     /**
-     * Custom fetch implementation, useful for testing.
-     * Defaults to the global `fetch`.
+     * Custom fetch implementation for dependency injection in tests.
+     * @default globalThis.fetch
      */
     fetchImpl?: typeof fetch;
 }
 /**
  * Text-to-speech provider that uses the Azure Cognitive Services Speech REST API.
  *
- * Generates audio via SSML synthesis and returns the raw MP3 buffer. Streaming
- * is supported in the sense that the provider can be used inside a streaming
- * pipeline — the actual HTTP request is a single synchronous call.
+ * ## SSML Generation
+ *
+ * Azure's TTS REST endpoint requires SSML (Speech Synthesis Markup Language) as
+ * the request body — it does not accept plain text. This provider generates
+ * minimal SSML via {@link buildSsml} that wraps the input text in `<speak>`
+ * and `<voice>` elements. Special XML characters in the text are escaped via
+ * {@link escapeXml} to prevent malformed XML.
+ *
+ * ## `X-Microsoft-OutputFormat` Options
+ *
+ * The `X-Microsoft-OutputFormat` header controls the audio encoding. This
+ * provider uses `'audio-24khz-96kbitrate-mono-mp3'` which provides:
+ * - 24 kHz sample rate (high quality for speech)
+ * - 96 kbps bitrate (good balance of quality and file size)
+ * - Mono channel (sufficient for speech synthesis)
+ * - MP3 format (universally supported)
+ *
+ * Other available formats include:
+ * - `'audio-16khz-128kbitrate-mono-mp3'` — Lower sample rate, higher bitrate
+ * - `'audio-24khz-160kbitrate-mono-mp3'` — Higher bitrate for better quality
+ * - `'riff-24khz-16bit-mono-pcm'` — Uncompressed WAV
+ * - `'ogg-24khz-16bit-mono-opus'` — Opus codec in OGG container
+ *
+ * @see https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs
+ *
+ * ## Voice Listing
+ *
+ * The {@link listAvailableVoices} method fetches the full list of neural voices
+ * available in the configured Azure region via
+ * `GET /cognitiveservices/voices/list`. Results are mapped to the normalized
+ * {@link SpeechVoice} shape.
+ *
+ * @see {@link AzureSpeechTTSProviderConfig} for configuration options
+ * @see {@link AzureSpeechSTTProvider} for the corresponding STT provider
  *
  * @example
  * ```ts
- * const provider = new AzureSpeechTTSProvider({ key: process.env.AZURE_SPEECH_KEY!, region: 'eastus' });
+ * const provider = new AzureSpeechTTSProvider({
+ *   key: process.env.AZURE_SPEECH_KEY!,
+ *   region: 'eastus',
+ *   defaultVoice: 'en-US-GuyNeural',
+ * });
  * const result = await provider.synthesize('Hello world');
  * // result.audioBuffer contains MP3 bytes
+ * // result.mimeType === 'audio/mpeg'
  * ```
  */
 export declare class AzureSpeechTTSProvider implements TextToSpeechProvider {
     private readonly config;
+    /** Unique provider identifier used for registration and resolution. */
     readonly id = "azure-speech-tts";
+    /** Human-readable display name for UI and logging. */
     readonly displayName = "Azure Speech (TTS)";
+    /**
+     * Marked as streaming-capable because the provider can be used within a
+     * streaming pipeline — though the actual HTTP request is a single
+     * synchronous call that returns the complete audio buffer.
+     */
     readonly supportsStreaming = true;
+    /** Fetch implementation — injected for testability, defaults to global fetch. */
     private readonly fetchImpl;
+    /** Resolved default voice name used when no voice is specified per-request. */
     private readonly defaultVoice;
+    /**
+     * Creates a new AzureSpeechTTSProvider.
+     *
+     * @param config - Provider configuration including the subscription key,
+     *   region, and optional default voice.
+     *
+     * @example
+     * ```ts
+     * const provider = new AzureSpeechTTSProvider({
+     *   key: 'your-azure-subscription-key',
+     *   region: 'westeurope',
+     *   defaultVoice: 'de-DE-ConradNeural',
+     * });
+     * ```
+     */
     constructor(config: AzureSpeechTTSProviderConfig);
-    /** Returns the human-readable provider name. */
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'Azure Speech (TTS)'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'Azure Speech (TTS)'
+     * ```
+     */
     getProviderName(): string;
     /**
      * Synthesizes speech from plain text using the Azure TTS REST endpoint.
      *
-     * @param text - The utterance to convert to audio.
-     * @param options - Optional synthesis settings (voice override…).
+     * The text is wrapped in SSML, sent to Azure, and the response audio buffer
+     * (MP3 format) is returned along with metadata.
+     *
+     * @param text - The plain-text utterance to convert to audio. XML special
+     *   characters are automatically escaped.
+     * @param options - Optional synthesis settings. Use `options.voice` to
+     *   override the default voice with any valid Azure voice short-name.
      * @returns A promise resolving to the MP3 audio buffer and metadata.
-     * @throws When the Azure API returns a non-2xx status.
+     * @throws {Error} When the Azure API returns a non-2xx status code.
+     *   Common causes: invalid subscription key (401), region mismatch (404),
+     *   invalid SSML (400), or quota exceeded (429).
+     *
+     * @example
+     * ```ts
+     * const result = await provider.synthesize('Guten Tag!', {
+     *   voice: 'de-DE-ConradNeural',
+     * });
+     * fs.writeFileSync('output.mp3', result.audioBuffer);
+     * ```
      */
     synthesize(text: string, options?: SpeechSynthesisOptions): Promise<SpeechSynthesisResult>;
     /**
      * Retrieves the list of available neural voices from the Azure region.
      *
-     * @returns A promise resolving to an array of normalised {@link SpeechVoice} entries.
-     * @throws When the Azure API returns a non-2xx status.
+     * Fetches from `GET /cognitiveservices/voices/list` and maps each entry
+     * to the normalized {@link SpeechVoice} shape. The list includes all
+     * neural and standard voices available in the configured region.
+     *
+     * @returns A promise resolving to an array of normalized voice entries.
+     * @throws {Error} When the Azure API returns a non-2xx status code
+     *   (e.g. invalid key, network error).
+     *
+     * @example
+     * ```ts
+     * const voices = await provider.listAvailableVoices();
+     * const englishVoices = voices.filter(v => v.lang.startsWith('en-'));
+     * console.log(`Found ${englishVoices.length} English voices`);
+     * ```
      */
     listAvailableVoices(): Promise<SpeechVoice[]>;
 }

package/dist/speech/providers/AzureSpeechTTSProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AzureSpeechTTSProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/AzureSpeechTTSProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,MAAM,WAAW,4BAA4B;IAC3C,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAyDD;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IAQrD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPnC,SAAgB,EAAE,sBAAsB;IACxC,SAAgB,WAAW,wBAAwB;IACnD,SAAgB,iBAAiB,QAAQ;IAEzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAET,MAAM,EAAE,4BAA4B;IAKjE,gDAAgD;IAChD,eAAe,IAAI,MAAM;IAIzB;;;;;;;OAOG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC;IAsCjC;;;;;OAKG;IACG,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAgBpD"}
+{"version":3,"file":"AzureSpeechTTSProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/AzureSpeechTTSProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAmHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IAmCrD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAlCnC,uEAAuE;IACvE,SAAgB,EAAE,sBAAsB;IAExC,sDAAsD;IACtD,SAAgB,WAAW,wBAAwB;IAEnD;;;;OAIG;IACH,SAAgB,iBAAiB,QAAQ;IAEzC,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;;;;;;;;;;;OAcG;gBAC0B,MAAM,EAAE,4BAA4B;IAKjE;;;;;;;;;OASG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC;IA4CjC;;;;;;;;;;;;;;;;;OAiBG;IACG,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAgBpD"}

package/dist/speech/providers/AzureSpeechTTSProvider.js

@@ -1,21 +1,56 @@
 /**
  * Escapes special XML characters in text before embedding it in SSML.
- * Azure's TTS endpoint expects well-formed XML; unescaped `<`, `>`, or `&`
- * characters in the input text would cause a 400 error.
+ *
+ * Azure's TTS endpoint expects well-formed XML in the request body. Unescaped
+ * `<`, `>`, `&`, `"`, or `'` characters in the input text would cause a 400
+ * Bad Request error because they break the XML structure.
+ *
+ * The five standard XML entity replacements are applied:
+ * - `&` -> `&amp;` (must be first to avoid double-escaping)
+ * - `<` -> `&lt;`
+ * - `>` -> `&gt;`
+ * - `"` -> `&quot;`
+ * - `'` -> `&apos;`
+ *
+ * @param text - Raw plain text to escape for safe XML embedding.
+ * @returns The XML-safe escaped string.
+ *
+ * @example
+ * ```ts
+ * escapeXml('Hello & <world>'); // 'Hello &amp; &lt;world&gt;'
+ * ```
  */
 function escapeXml(text) {
     return text
-        .replace(/&/g, '&amp;')
+        .replace(/&/g, '&amp;') // Must be first to avoid double-escaping
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;')
         .replace(/"/g, '&quot;')
         .replace(/'/g, '&apos;');
 }
 /**
- * Builds the SSML payload sent to the Azure TTS REST endpoint.
+ * Builds the SSML (Speech Synthesis Markup Language) payload for the Azure
+ * TTS REST endpoint.
+ *
+ * The generated SSML wraps the escaped text in a `<voice>` element with the
+ * specified voice name. The outer `<speak>` element declares SSML version 1.0
+ * and the W3C synthesis namespace.
  *
- * @param text - Plain-text utterance to synthesize.
+ * More advanced SSML features (prosody, emphasis, break) could be added here
+ * but are not currently needed for basic synthesis.
+ *
+ * @param text - Plain-text utterance to synthesize (will be XML-escaped).
  * @param voice - Azure voice short-name, e.g. `'en-US-JennyNeural'`.
+ * @returns Well-formed SSML string ready to send as the request body.
+ *
+ * @see {@link escapeXml} for the XML escaping logic
+ * @see https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup
+ *
+ * @example
+ * ```ts
+ * buildSsml('Hello world', 'en-US-JennyNeural');
+ * // '<speak version="1.0" xmlns="..."><voice name="en-US-JennyNeural">Hello world</voice></speak>'
+ * ```
  */
 function buildSsml(text, voice) {
     return (`<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">` +
@@ -23,7 +58,17 @@ function buildSsml(text, voice) {
         `</speak>`);
 }
 /**
- * Maps an Azure voice list entry to the normalised {@link SpeechVoice} shape.
+ * Maps an Azure voice list entry to the normalized {@link SpeechVoice} shape.
+ *
+ * The gender field is lowercased and validated against known values. Unknown
+ * gender strings (if Azure adds new values) are passed through as-is since
+ * the {@link SpeechVoice.gender} type accepts `string`.
+ *
+ * @param entry - A single voice entry from the Azure voices/list endpoint.
+ * @returns The normalized voice object.
+ *
+ * @see {@link AzureVoiceEntry} for the input shape
+ * @see {@link SpeechVoice} for the output shape
  */
 function mapVoice(entry) {
     const gender = entry.Gender?.toLowerCase();
@@ -40,48 +85,135 @@ function mapVoice(entry) {
 /**
  * Text-to-speech provider that uses the Azure Cognitive Services Speech REST API.
  *
- * Generates audio via SSML synthesis and returns the raw MP3 buffer. Streaming
- * is supported in the sense that the provider can be used inside a streaming
- * pipeline — the actual HTTP request is a single synchronous call.
+ * ## SSML Generation
+ *
+ * Azure's TTS REST endpoint requires SSML (Speech Synthesis Markup Language) as
+ * the request body — it does not accept plain text. This provider generates
+ * minimal SSML via {@link buildSsml} that wraps the input text in `<speak>`
+ * and `<voice>` elements. Special XML characters in the text are escaped via
+ * {@link escapeXml} to prevent malformed XML.
+ *
+ * ## `X-Microsoft-OutputFormat` Options
+ *
+ * The `X-Microsoft-OutputFormat` header controls the audio encoding. This
+ * provider uses `'audio-24khz-96kbitrate-mono-mp3'` which provides:
+ * - 24 kHz sample rate (high quality for speech)
+ * - 96 kbps bitrate (good balance of quality and file size)
+ * - Mono channel (sufficient for speech synthesis)
+ * - MP3 format (universally supported)
+ *
+ * Other available formats include:
+ * - `'audio-16khz-128kbitrate-mono-mp3'` — Lower sample rate, higher bitrate
+ * - `'audio-24khz-160kbitrate-mono-mp3'` — Higher bitrate for better quality
+ * - `'riff-24khz-16bit-mono-pcm'` — Uncompressed WAV
+ * - `'ogg-24khz-16bit-mono-opus'` — Opus codec in OGG container
+ *
+ * @see https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs
+ *
+ * ## Voice Listing
+ *
+ * The {@link listAvailableVoices} method fetches the full list of neural voices
+ * available in the configured Azure region via
+ * `GET /cognitiveservices/voices/list`. Results are mapped to the normalized
+ * {@link SpeechVoice} shape.
+ *
+ * @see {@link AzureSpeechTTSProviderConfig} for configuration options
+ * @see {@link AzureSpeechSTTProvider} for the corresponding STT provider
  *
  * @example
  * ```ts
- * const provider = new AzureSpeechTTSProvider({ key: process.env.AZURE_SPEECH_KEY!, region: 'eastus' });
+ * const provider = new AzureSpeechTTSProvider({
+ *   key: process.env.AZURE_SPEECH_KEY!,
+ *   region: 'eastus',
+ *   defaultVoice: 'en-US-GuyNeural',
+ * });
  * const result = await provider.synthesize('Hello world');
  * // result.audioBuffer contains MP3 bytes
+ * // result.mimeType === 'audio/mpeg'
  * ```
  */
 export class AzureSpeechTTSProvider {
+    /**
+     * Creates a new AzureSpeechTTSProvider.
+     *
+     * @param config - Provider configuration including the subscription key,
+     *   region, and optional default voice.
+     *
+     * @example
+     * ```ts
+     * const provider = new AzureSpeechTTSProvider({
+     *   key: 'your-azure-subscription-key',
+     *   region: 'westeurope',
+     *   defaultVoice: 'de-DE-ConradNeural',
+     * });
+     * ```
+     */
     constructor(config) {
         this.config = config;
+        /** Unique provider identifier used for registration and resolution. */
         this.id = 'azure-speech-tts';
+        /** Human-readable display name for UI and logging. */
         this.displayName = 'Azure Speech (TTS)';
+        /**
+         * Marked as streaming-capable because the provider can be used within a
+         * streaming pipeline — though the actual HTTP request is a single
+         * synchronous call that returns the complete audio buffer.
+         */
         this.supportsStreaming = true;
         this.fetchImpl = config.fetchImpl ?? fetch;
         this.defaultVoice = config.defaultVoice ?? 'en-US-JennyNeural';
     }
-    /** Returns the human-readable provider name. */
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'Azure Speech (TTS)'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'Azure Speech (TTS)'
+     * ```
+     */
     getProviderName() {
         return this.displayName;
     }
     /**
      * Synthesizes speech from plain text using the Azure TTS REST endpoint.
      *
-     * @param text - The utterance to convert to audio.
-     * @param options - Optional synthesis settings (voice override…).
+     * The text is wrapped in SSML, sent to Azure, and the response audio buffer
+     * (MP3 format) is returned along with metadata.
+     *
+     * @param text - The plain-text utterance to convert to audio. XML special
+     *   characters are automatically escaped.
+     * @param options - Optional synthesis settings. Use `options.voice` to
+     *   override the default voice with any valid Azure voice short-name.
      * @returns A promise resolving to the MP3 audio buffer and metadata.
-     * @throws When the Azure API returns a non-2xx status.
+     * @throws {Error} When the Azure API returns a non-2xx status code.
+     *   Common causes: invalid subscription key (401), region mismatch (404),
+     *   invalid SSML (400), or quota exceeded (429).
+     *
+     * @example
+     * ```ts
+     * const result = await provider.synthesize('Guten Tag!', {
+     *   voice: 'de-DE-ConradNeural',
+     * });
+     * fs.writeFileSync('output.mp3', result.audioBuffer);
+     * ```
      */
     async synthesize(text, options = {}) {
         const voice = options.voice ?? this.defaultVoice;
         const { key, region } = this.config;
+        // Azure TTS endpoint — note it uses tts.speech.microsoft.com (not stt.)
         const url = `https://${region}.tts.speech.microsoft.com/cognitiveservices/v1`;
         const ssml = buildSsml(text, voice);
         const response = await this.fetchImpl(url, {
             method: 'POST',
             headers: {
+                // Azure's standard subscription key authentication header
                 'Ocp-Apim-Subscription-Key': key,
+                // SSML content type — Azure rejects plain text
                 'Content-Type': 'application/ssml+xml',
+                // Output format header — determines the audio encoding, sample rate,
+                // and container format of the response body
                 'X-Microsoft-OutputFormat': 'audio-24khz-96kbitrate-mono-mp3',
             },
             body: ssml,
@@ -90,12 +222,13 @@ export class AzureSpeechTTSProvider {
             const message = await response.text();
             throw new Error(`Azure Speech TTS failed (${response.status}): ${message}`);
         }
+        // Read the complete audio response into a Buffer
         const arrayBuffer = await response.arrayBuffer();
         const audioBuffer = Buffer.from(arrayBuffer);
         return {
             audioBuffer,
-            mimeType: 'audio/mpeg',
-            cost: 0,
+            mimeType: 'audio/mpeg', // Matches the X-Microsoft-OutputFormat MP3 selection
+            cost: 0, // Cost tracking is handled at a higher layer
             voiceUsed: voice,
             providerName: this.displayName,
             usage: {
@@ -107,8 +240,20 @@ export class AzureSpeechTTSProvider {
     /**
      * Retrieves the list of available neural voices from the Azure region.
      *
-     * @returns A promise resolving to an array of normalised {@link SpeechVoice} entries.
-     * @throws When the Azure API returns a non-2xx status.
+     * Fetches from `GET /cognitiveservices/voices/list` and maps each entry
+     * to the normalized {@link SpeechVoice} shape. The list includes all
+     * neural and standard voices available in the configured region.
+     *
+     * @returns A promise resolving to an array of normalized voice entries.
+     * @throws {Error} When the Azure API returns a non-2xx status code
+     *   (e.g. invalid key, network error).
+     *
+     * @example
+     * ```ts
+     * const voices = await provider.listAvailableVoices();
+     * const englishVoices = voices.filter(v => v.lang.startsWith('en-'));
+     * console.log(`Found ${englishVoices.length} English voices`);
+     * ```
      */
     async listAvailableVoices() {
         const { key, region } = this.config;