@pie-players/tts-client-server 0.3.73 → 0.3.75

package/README.md

@@ -30,36 +30,33 @@ npm install @pie-players/tts-client-server
 ### Basic Setup
 
 ```typescript
-import { ServerTTSProvider } from '@pie-players/tts-client-server';
+import {
+  ServerTTSProvider,
+  type ServerTTSProviderConfig,
+} from '@pie-players/tts-client-server';
 import { TTSService } from '@pie-players/pie-assessment-toolkit';
 
 const provider = new ServerTTSProvider();
-
-const ttsService = new TTSService();
-await ttsService.initialize(provider, {
+const config: ServerTTSProviderConfig = {
   apiEndpoint: '/api/tts',  // Your SvelteKit API route
   provider: 'polly',         // Server-side provider to use
-  voiceId: 'Joanna',
+  voice: 'Joanna',
   language: 'en-US',
-});
+};
 
-// Note: `apiEndpoint`, `provider`, and `voiceId` are server-provider-specific
-// options. When using TTSConfig, pass these inside `providerOptions` rather
-// than as top-level fields:
-//
-//   const config: TTSConfig = {
-//     providerOptions: {
-//       apiEndpoint: '/api/tts',
-//       provider: 'polly',
-//       voiceId: 'Joanna',
-//     },
-//     language: 'en-US',
-//   };
+const ttsService = new TTSService();
+await ttsService.initialize(provider, config);
 ```
 
-`apiEndpoint` is required when using `ServerTTSProvider` directly. Toolkit-level
-`tools.providers.textToSpeech` integration may provide a default endpoint for
-server-backed backends, but direct client usage should pass this explicitly.
+`apiEndpoint`, `provider`, `voice` and `language` are top-level fields; the
+provider reads none of them from `providerOptions`. `providerOptions` carries
+request extras: the PIE transport forwards its `engine` (when no top-level
+`engine` is set), `sampleRate`, `format` and `speechMarkTypes`, and the custom
+transport reads its `speedRate`.
+
+`apiEndpoint` is required when using `ServerTTSProvider` directly, and
+`initialize` throws without it. Toolkit-level `tools.providers.textToSpeech`
+integration defaults it to `/api/tts` for server-backed backends.
 
 ### With Authentication
 
@@ -67,8 +64,7 @@ server-backed backends, but direct client usage should pass this explicitly.
 await ttsService.initialize(provider, {
   apiEndpoint: '/api/tts',
   provider: 'polly',
-  authToken: 'your-jwt-token',
-  organizationId: 'org-123',
+  authToken: 'your-jwt-token', // sent as `Authorization: Bearer <token>`
 });
 ```
 
@@ -76,9 +72,7 @@ await ttsService.initialize(provider, {
 
 ```typescript
 // The provider automatically coordinates word highlighting
-await ttsService.speak('Hello world, this is a test.', {
-  contentElement: document.getElementById('content'),
-});
+await ttsService.speak(document.getElementById('content'));
 ```
 
 ## Transport Modes
@@ -140,10 +134,17 @@ await ttsService.speak('Hello world, this is a test.', {
   "text": "Hello world",
   "speedRate": "medium",
   "lang_id": "en-US",
+  "langId": "en-US",
   "cache": true
 }
 ```
 
+The language travels under both `lang_id` and `langId`, so a server that binds
+JSON in camelCase reads it without a mapping of its own. It is the host's
+`providerOptions.lang_id`, else the language a speak names, else `language`,
+else `en-US`. In PIE mode, `language` is the language a speak names, else the
+configured one.
+
 ### Custom mode response
 
 ```json
@@ -157,7 +158,7 @@ Speech marks are fetched from the `word` URL and parsed as JSONL.
 
 ### Optional voices endpoint
 
-`GET ${apiEndpoint}/voices` remains optional and is only used when endpoint validation is configured with `endpointValidationMode: "voices"`.
+`GET ${apiEndpoint}/voices` remains optional and is only used when endpoint validation is configured with `endpointValidationMode: "voices"`. With `provider: "polly"` or `"google"` the probe tries `${apiEndpoint}/<provider>/voices` first and falls back to `${apiEndpoint}/voices` when that route returns 404. A failed probe makes the toolkit switch to browser TTS.
 
 ## SvelteKit Implementation Example
 
@@ -181,15 +182,18 @@ interface ServerTTSProviderConfig {
   transportMode?: 'pie' | 'custom';
   endpointMode?: 'synthesizePath' | 'rootPost';
   endpointValidationMode?: 'voices' | 'endpoint' | 'none';
+  validateEndpoint?: boolean; // Probe the endpoint during initialize()
   authToken?: string;         // JWT or API key
   includeAuthOnAssetFetch?: boolean;
   assetOrigins?: string[];    // Trusted origins for Authorization header
-  organizationId?: string;    // For multi-tenant setups
+  credentials?: 'omit' | 'same-origin' | 'include'; // Fetch credentials mode
   headers?: Record<string, string>;  // Custom headers
-  voiceId?: string;           // Voice ID
+  voice?: string;             // Voice ID, e.g. 'Joanna'
+  engine?: 'standard' | 'neural';    // Polly engine
   language?: string;          // Language code
   rate?: number;              // Speech rate (0.25-4.0)
   volume?: number;            // Volume (0-1)
+  providerOptions?: Record<string, unknown>; // Request extras (see Basic Setup)
 }
 ```
 
@@ -218,6 +222,13 @@ server that fall outside a trusted origin set.
   origins in `assetOrigins`; off-allow-list origins are fetched without
   auth. Leave at the default unless your CDN / storage backend actually
   requires the bearer token to read assets.
+- **`credentials`** — the fetch `credentials` mode, unset by default, which
+  leaves the browser default (`"same-origin"`). Set `"include"` when the TTS
+  server sits on another origin and authenticates by cookie; the server must
+  answer CORS with `Access-Control-Allow-Credentials: true` and an explicit
+  origin. Speech-mark and audio fetches to an origin outside `assetOrigins`
+  keep the browser default, so cookies follow the same allow-list as the
+  bearer token.
 
 See
 [`docs/tools-and-accomodations/tool_host_contract.md#backend-endpoints-for-tool-providers`](../../docs/tools-and-accomodations/tool_host_contract.md#backend-endpoints-for-tool-providers)
@@ -225,7 +236,7 @@ for the host-wide contract this provider fits into.
 
 ## How It Works
 
-1. **Client calls** `speak(text)`
+1. **Client calls** `speak(element)`
 2. **Adapter builds** backend-specific request payload
 3. **Provider POSTs** to resolved synthesis endpoint (`/synthesize` or root POST)
 4. **Adapter normalizes** response into audio + speech marks
@@ -266,7 +277,7 @@ The provider automatically manages Blob URLs:
 
 ```typescript
 try {
-  await ttsService.speak('Hello world');
+  await ttsService.speak(document.getElementById('content'));
 } catch (error) {
   console.error('TTS failed:', error.message);
   // Fallback to browser TTS or show error

package/dist/ServerTTSProvider.d.ts

@@ -5,11 +5,36 @@
  * providers like AWS Polly, Google Cloud TTS, etc.
  * Returns audio with precise word-level timing (speech marks).
  */
-import type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSFeature, TTSProviderCapabilities } from "@pie-players/pie-tts";
+import type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSProviderCapabilities, TTSProviderOptions } from "@pie-players/pie-tts";
+/**
+ * The provider options the server provider reads. `contentLanguage`, set per
+ * speak, names the language synthesized: it wins over `language`, and a
+ * `lang_id` the host sets wins over it.
+ */
+export interface ServerTTSProviderOptions extends TTSProviderOptions {
+    /** Polly engine, on the pie transport, when `engine` is not set. */
+    engine?: "standard" | "neural";
+    /** Output sample rate, on the pie transport. */
+    sampleRate?: number;
+    /** Audio format, on the pie transport. */
+    format?: "mp3" | "ogg" | "pcm";
+    /** Speech mark types requested, on the pie transport. */
+    speechMarkTypes?: Array<"word" | "sentence" | "ssml">;
+    /** Speed bucket, on the custom transport; derived from `rate` when unset. */
+    speedRate?: string;
+    /**
+     * Language id, on the custom transport. Without it, the language a speak
+     * names, then `language`, then en-US.
+     */
+    lang_id?: string;
+    /** Server-side caching, on the custom transport. Defaults to true. */
+    cache?: boolean;
+}
 /**
  * Configuration for ServerTTSProvider
  */
 export interface ServerTTSProviderConfig extends TTSConfig {
+    providerOptions?: ServerTTSProviderOptions;
     /** API endpoint base URL (e.g., '/api/tts' or 'https://api.example.com/tts') */
     apiEndpoint: string;
     /** Provider to use on server ('polly', 'google', 'elevenlabs', etc.) */
@@ -44,8 +69,9 @@ export interface ServerTTSProviderConfig extends TTSConfig {
      */
     endpointValidationMode?: "voices" | "endpoint" | "none";
     /**
-     * Include auth headers when fetching custom-transport speech marks and audio URLs.
-     * Defaults to false for compatibility.
+     * Send the synthesis request's `Authorization` header, whether it comes from
+     * `headers` or `authToken`, with the custom-transport speech-mark and audio
+     * fetches. Defaults to false for compatibility.
      */
     includeAuthOnAssetFetch?: boolean;
     /**
@@ -59,6 +85,14 @@ export interface ServerTTSProviderConfig extends TTSConfig {
      * responses keep working without explicit configuration.
      */
     assetOrigins?: string[];
+    /**
+     * Fetch `credentials` mode for requests to the TTS server, so a
+     * cookie-authenticated endpoint on another origin receives its cookies.
+     * Speech-mark and audio fetches use it only for an origin trusted with auth
+     * (see `assetOrigins`); others keep the browser default. Unset leaves every
+     * fetch on the browser default, `"same-origin"`.
+     */
+    credentials?: "omit" | "same-origin" | "include";
     /**
      * Validate API endpoint availability during initialization (slower but safer)
      *
@@ -97,7 +131,6 @@ export declare class ServerTTSProvider implements ITTSProvider {
      * @performance 100-500ms depending on network
      */
     private testAPIAvailability;
-    supportsFeature(feature: TTSFeature): boolean;
     getCapabilities(): TTSProviderCapabilities;
     destroy(): void;
 }

package/dist/ServerTTSProvider.js

@@ -5,9 +5,12 @@
  * providers like AWS Polly, Google Cloud TTS, etc.
  * Returns audio with precise word-level timing (speech marks).
  */
-import { createPieLogger, isGlobalDebugEnabled, } from "@pie-players/pie-players-shared/pie";
+import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { normalizeSpeechMarks, resolveSpeedRateBucket, } from "@pie-players/tts-server-core";
-const logger = createPieLogger("server-tts-provider", () => isGlobalDebugEnabled());
+// Debug lines need PIE_TTS_DEBUG=1 or globalThis.__PIE_TTS_DEBUG__ = true.
+const logger = createPieLogger("server-tts-provider", isTtsDebugEnabled);
+// Telemetry names the tool by its canonical id, as the toolkit does.
+const TOOL_ID = "textToSpeech";
 /**
  * Parse a TTS asset URL (speech marks or audio). Rejects anything that is
  * not an absolute http(s) URL; relative URLs are resolved against
@@ -85,14 +88,36 @@ function scrubAuthHeaders(headers) {
     }
     return cleaned;
 }
+/**
+ * The `credentials` init for a fetch, spread into it. A cookie leaves the page
+ * for an untrusted asset origin only as the browser default would send it.
+ */
+function fetchCredentials(config, trustedForAuth = true) {
+    if (!config.credentials)
+        return {};
+    if (!trustedForAuth && config.credentials === "include")
+        return {};
+    return { credentials: config.credentials };
+}
+/**
+ * The headers a custom-transport speech-mark or audio fetch starts from: the
+ * synthesis request's `Authorization` header under `includeAuthOnAssetFetch`,
+ * nothing otherwise.
+ */
+function assetFetchHeaders(requestHeaders, config) {
+    const assetHeaders = {};
+    if (!config.includeAuthOnAssetFetch)
+        return assetHeaders;
+    for (const [key, value] of Object.entries(requestHeaders)) {
+        if (key.toLowerCase() === "authorization") {
+            assetHeaders[key] = value;
+        }
+    }
+    return assetHeaders;
+}
 const getTelemetryReporter = (config) => {
-    const providerOptions = config.providerOptions && typeof config.providerOptions === "object"
-        ? config.providerOptions
-        : {};
-    const reporter = providerOptions.__pieTelemetry;
-    return typeof reporter === "function"
-        ? reporter
-        : undefined;
+    const reporter = config.providerOptions?.__pieTelemetry;
+    return typeof reporter === "function" ? reporter : undefined;
 };
 const MAX_TEXT_LENGTH_BY_MODE = {
     pie: 3000,
@@ -117,13 +142,15 @@ const resolveSupportsSSML = (config) => {
     return SSML_CAPABLE_PIE_PROVIDERS.has(provider);
 };
 const trimTrailingSlash = (value) => value.replace(/\/+$/, "");
-const resolveVoicesValidationUrl = (config) => {
+// Polly and Google probe their provider route first, then the generic
+// `${apiEndpoint}/voices` the integration guides have hosts create.
+const resolveVoicesValidationUrls = (config) => {
     const base = trimTrailingSlash(config.apiEndpoint);
     const provider = (config.provider || "").toLowerCase();
     if (provider === "polly" || provider === "google") {
-        return `${base}/${provider}/voices`;
+        return [`${base}/${provider}/voices`, `${base}/voices`];
     }
-    return `${base}/voices`;
+    return [`${base}/voices`];
 };
 const resolveTransportMode = (config) => {
     if (config.transportMode === "custom")
@@ -143,12 +170,18 @@ const resolveValidationMode = (config, mode) => {
     return mode === "custom" ? "none" : "voices";
 };
 const resolveSpeedRate = (config) => {
-    const providerOptions = (config.providerOptions || {});
-    if (typeof providerOptions.speedRate === "string") {
-        return providerOptions.speedRate;
-    }
+    const speedRate = config.providerOptions?.speedRate;
+    if (typeof speedRate === "string")
+        return speedRate;
     return resolveSpeedRateBucket(config.rate);
 };
+/** The language a speak named for its content, if any. */
+const contentLanguageOf = (config) => {
+    const language = config.providerOptions?.contentLanguage;
+    return typeof language === "string" && language.trim()
+        ? language.trim()
+        : undefined;
+};
 const parseInlineSpeechMarks = (input) => {
     if (!Array.isArray(input))
         return [];
@@ -189,7 +222,7 @@ const pieAdapter = {
         return endpointMode === "rootPost" ? base : `${base}/synthesize`;
     },
     buildRequestBody: (text, config) => {
-        const providerOptions = (config.providerOptions || {});
+        const providerOptions = config.providerOptions || {};
         const engine = typeof config.engine === "string"
             ? config.engine
             : typeof providerOptions.engine === "string"
@@ -211,7 +244,7 @@ const pieAdapter = {
             text,
             provider: config.provider || "polly",
             voice: config.voice,
-            language: config.language,
+            language: contentLanguageOf(config) ?? config.language,
             rate: config.rate,
             engine,
             sampleRate,
@@ -240,28 +273,27 @@ const customAdapter = {
         return endpointMode === "synthesizePath" ? `${base}/synthesize` : base;
     },
     buildRequestBody: (text, config) => {
-        const providerOptions = (config.providerOptions || {});
-        const langId = typeof providerOptions.lang_id === "string"
+        const providerOptions = config.providerOptions || {};
+        // A host's `lang_id` names a locale from the service's own roster, which a
+        // content tag such as `es` is not: SchoolCity reads one it lacks as en-US.
+        const pinned = typeof providerOptions.lang_id === "string" &&
+            providerOptions.lang_id.trim()
             ? providerOptions.lang_id
-            : config.language || "en-US";
+            : undefined;
+        const langId = pinned ?? contentLanguageOf(config) ?? (config.language || "en-US");
         const cache = typeof providerOptions.cache === "boolean" ? providerOptions.cache : true;
         return {
             text,
             speedRate: resolveSpeedRate(config),
+            // Both spellings: servers that bind JSON camelCase never see `lang_id`.
             lang_id: langId,
+            langId,
             cache,
         };
     },
     parseResponse: async (response, config, headers, signal, text) => {
         const data = await response.json();
-        const marksHeaders = {};
-        if (config.includeAuthOnAssetFetch) {
-            for (const [key, value] of Object.entries(headers)) {
-                if (key.toLowerCase() === "authorization") {
-                    marksHeaders[key] = value;
-                }
-            }
-        }
+        const marksHeaders = assetFetchHeaders(headers, config);
         let speechMarks = [];
         const inlineSpeechMarks = parseInlineSpeechMarks(data.speechMarks);
         if (inlineSpeechMarks.length > 0) {
@@ -270,11 +302,13 @@ const customAdapter = {
         else if (typeof data.word === "string" && data.word.length > 0) {
             const marksUrl = parseAssetUrl(data.word, config);
             if (marksUrl !== null) {
-                const effectiveMarksHeaders = isOriginTrustedForAuth(marksUrl, config)
+                const marksTrusted = isOriginTrustedForAuth(marksUrl, config);
+                const effectiveMarksHeaders = marksTrusted
                     ? marksHeaders
                     : scrubAuthHeaders(marksHeaders);
                 const marksResponse = await fetch(marksUrl.toString(), {
                     headers: effectiveMarksHeaders,
+                    ...fetchCredentials(config, marksTrusted),
                     signal,
                     // Fail loud on redirects; the origin allow-list decision
                     // is made pre-redirect and a silent hop could leak auth
@@ -321,7 +355,11 @@ class ServerTTSProviderImpl {
      */
     highlightCursor = -1;
     intentionallyStopped = false;
+    // Set while a synthesis request is in flight.
     activeSynthesisController = null;
+    // Starts the current audio element; a pause before it sounds leaves the
+    // start to resume.
+    startCurrentAudio = null;
     synthesisRunId = 0;
     telemetryReporter;
     onPlaybackStart;
@@ -348,7 +386,23 @@ class ServerTTSProviderImpl {
         const synthesisController = new AbortController();
         this.activeSynthesisController = synthesisController;
         // Call server API to synthesize speech
-        const { audioUrl, wordTimings } = await this.synthesizeSpeech(text, synthesisController.signal, runId);
+        let synthesized;
+        try {
+            synthesized = await this.synthesizeSpeech(text, synthesisController.signal, runId);
+        }
+        catch (error) {
+            // A stop or a newer speak aborted this synthesis: not a failure.
+            if (runId !== this.synthesisRunId || synthesisController.signal.aborted) {
+                return;
+            }
+            throw error;
+        }
+        finally {
+            if (this.activeSynthesisController === synthesisController) {
+                this.activeSynthesisController = null;
+            }
+        }
+        const { audioUrl, wordTimings } = synthesized;
         if (runId !== this.synthesisRunId) {
             URL.revokeObjectURL(audioUrl);
             return;
@@ -363,11 +417,14 @@ class ServerTTSProviderImpl {
             if (this.config.volume !== undefined) {
                 audio.volume = Math.max(0, Math.min(1, this.config.volume));
             }
-            // Setup event handlers
-            audio.onplay = () => {
-                if (runId !== this.synthesisRunId || this.currentAudio !== audio) {
+            // A stop or a newer speak supersedes this audio: its late events must
+            // neither clear the current audio's state nor fail the current speak.
+            const superseded = () => runId !== this.synthesisRunId || this.currentAudio !== audio;
+            // `playing`, not `play`: `play` fires when playback is requested, before
+            // the audio has buffered and sounds.
+            audio.onplaying = () => {
+                if (superseded())
                     return;
-                }
                 this.pausedState = false;
                 try {
                     this.onPlaybackStart?.();
@@ -381,35 +438,40 @@ class ServerTTSProviderImpl {
                 }
             };
             audio.onended = () => {
-                this.stopWordHighlighting();
                 URL.revokeObjectURL(audioUrl);
-                this.currentAudio = null;
-                this.wordTimings = [];
-                this.highlightCursor = -1;
+                if (!superseded())
+                    this.clearCurrentAudio();
                 resolve();
             };
-            audio.onerror = (event) => {
-                this.stopWordHighlighting();
+            audio.onerror = () => {
                 URL.revokeObjectURL(audioUrl);
-                this.currentAudio = null;
-                this.wordTimings = [];
-                this.highlightCursor = -1;
-                void event;
-                // Only reject if this wasn't an intentional stop
-                if (!this.intentionallyStopped) {
-                    reject(new Error("Failed to play audio from server"));
-                }
-                else {
-                    // Intentional stop, resolve normally
+                if (superseded() || this.intentionallyStopped) {
                     resolve();
+                    return;
                 }
+                this.clearCurrentAudio();
+                reject(new Error("Failed to play audio from server"));
             };
             audio.onpause = () => {
+                if (superseded())
+                    return;
                 this.stopWordHighlighting();
                 this.pausedState = true;
             };
-            // Start playback
-            audio.play().catch(reject);
+            const start = () => {
+                audio.play().catch((error) => {
+                    // A pause before the audio sounds aborts its play; resume starts it.
+                    const aborted = error?.name === "AbortError";
+                    if (aborted && this.pausedState && this.currentAudio === audio) {
+                        return;
+                    }
+                    reject(error);
+                });
+            };
+            this.startCurrentAudio = start;
+            // A pause during synthesis holds the audio until resume.
+            if (!this.pausedState)
+                start();
         });
     }
     /**
@@ -418,7 +480,7 @@ class ServerTTSProviderImpl {
     async synthesizeSpeech(text, signal, runId) {
         const synthStartedAt = Date.now();
         await this.emitTelemetry("pie-tool-backend-call-start", {
-            toolId: "tts",
+            toolId: TOOL_ID,
             backend: this.config.provider || "server",
             operation: "synthesize-speech",
         });
@@ -439,11 +501,14 @@ class ServerTTSProviderImpl {
                     headers,
                     body: JSON.stringify(requestBody),
                     signal,
+                    ...fetchCredentials(this.config),
                 });
             }
             catch (error) {
+                if (signal.aborted)
+                    throw error;
                 await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: "tts",
+                    toolId: TOOL_ID,
                     backend: this.config.provider || "server",
                     operation: "synthesize-speech",
                     duration: Date.now() - synthStartedAt,
@@ -483,7 +548,7 @@ class ServerTTSProviderImpl {
                     : undefined) ||
                 `Server returned ${response.status}`;
             await this.emitTelemetry("pie-tool-backend-call-error", {
-                toolId: "tts",
+                toolId: TOOL_ID,
                 backend: this.config.provider || "server",
                 operation: "synthesize-speech",
                 duration: Date.now() - synthStartedAt,
@@ -521,20 +586,15 @@ class ServerTTSProviderImpl {
             const audioAssetUrl = normalized.audio.url;
             const assetFetchStartedAt = Date.now();
             await this.emitTelemetry("pie-tool-backend-call-start", {
-                toolId: "tts",
+                toolId: TOOL_ID,
                 backend: this.config.provider || "server",
                 operation: "fetch-synthesized-audio-asset",
             });
-            const assetHeaders = {};
-            if (this.config.includeAuthOnAssetFetch) {
-                if (this.config.authToken) {
-                    assetHeaders["Authorization"] = `Bearer ${this.config.authToken}`;
-                }
-            }
+            const assetHeaders = assetFetchHeaders(headers, this.config);
             const parsedAssetUrl = parseAssetUrl(audioAssetUrl, this.config);
             if (parsedAssetUrl === null) {
                 await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: "tts",
+                    toolId: TOOL_ID,
                     backend: this.config.provider || "server",
                     operation: "fetch-synthesized-audio-asset",
                     duration: Date.now() - assetFetchStartedAt,
@@ -543,7 +603,8 @@ class ServerTTSProviderImpl {
                 });
                 throw new Error("TTS asset URL rejected (non-http(s) or malformed)");
             }
-            const effectiveAssetHeaders = isOriginTrustedForAuth(parsedAssetUrl, this.config)
+            const assetTrusted = isOriginTrustedForAuth(parsedAssetUrl, this.config);
+            const effectiveAssetHeaders = assetTrusted
                 ? assetHeaders
                 : scrubAuthHeaders(assetHeaders);
             const audioResponse = await (async () => {
@@ -551,12 +612,15 @@ class ServerTTSProviderImpl {
                     return await fetch(parsedAssetUrl.toString(), {
                         headers: effectiveAssetHeaders,
                         signal,
+                        ...fetchCredentials(this.config, assetTrusted),
                         redirect: "error",
                     });
                 }
                 catch (error) {
+                    if (signal.aborted)
+                        throw error;
                     await this.emitTelemetry("pie-tool-backend-call-error", {
-                        toolId: "tts",
+                        toolId: TOOL_ID,
                         backend: this.config.provider || "server",
                         operation: "fetch-synthesized-audio-asset",
                         duration: Date.now() - assetFetchStartedAt,
@@ -568,7 +632,7 @@ class ServerTTSProviderImpl {
             })();
             if (!audioResponse.ok) {
                 await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: "tts",
+                    toolId: TOOL_ID,
                     backend: this.config.provider || "server",
                     operation: "fetch-synthesized-audio-asset",
                     duration: Date.now() - assetFetchStartedAt,
@@ -580,7 +644,7 @@ class ServerTTSProviderImpl {
             }
             audioBlob = await audioResponse.blob();
             await this.emitTelemetry("pie-tool-backend-call-success", {
-                toolId: "tts",
+                toolId: TOOL_ID,
                 backend: this.config.provider || "server",
                 operation: "fetch-synthesized-audio-asset",
                 duration: Date.now() - assetFetchStartedAt,
@@ -590,7 +654,7 @@ class ServerTTSProviderImpl {
         // Convert speech marks to word timings
         const wordTimings = this.parseSpeechMarks(normalized.speechMarks);
         await this.emitTelemetry("pie-tool-backend-call-success", {
-            toolId: "tts",
+            toolId: TOOL_ID,
             backend: this.config.provider || "server",
             operation: "synthesize-speech",
             duration: Date.now() - synthStartedAt,
@@ -710,25 +774,39 @@ class ServerTTSProviderImpl {
             this.highlightInterval = null;
         }
     }
+    /** Pause playback, or, while synthesis is in flight, hold its audio. */
     pause() {
-        if (this.currentAudio && !this.pausedState) {
+        if (this.pausedState)
+            return;
+        if (this.currentAudio) {
             this.currentAudio.pause();
             this.stopWordHighlighting();
-            this.pausedState = true;
         }
+        else if (!this.activeSynthesisController) {
+            return;
+        }
+        this.pausedState = true;
     }
     resume() {
-        if (this.currentAudio && this.pausedState) {
-            this.currentAudio.play();
-            this.pausedState = false;
-            // Resume word highlighting
-            if (this.onWordBoundary && this.wordTimings.length > 0) {
-                this.startWordHighlighting();
-            }
+        if (!this.pausedState)
+            return;
+        this.pausedState = false;
+        if (!this.currentAudio)
+            return;
+        this.startCurrentAudio?.();
+        if (this.onWordBoundary && this.wordTimings.length > 0) {
+            this.startWordHighlighting();
         }
     }
+    clearCurrentAudio() {
+        this.stopWordHighlighting();
+        this.currentAudio = null;
+        this.wordTimings = [];
+        this.highlightCursor = -1;
+    }
     stop() {
         this.synthesisRunId += 1;
+        this.startCurrentAudio = null;
         if (this.activeSynthesisController) {
             this.activeSynthesisController.abort();
             this.activeSynthesisController = null;
@@ -777,6 +855,15 @@ class ServerTTSProviderImpl {
             // Voice change requires resynthesis, affects next speak()
             this.config.voice = settings.voice;
         }
+        // Only the per-speak language: the toolkit's other options would replace
+        // the speed bucket a rate change set above.
+        if (settings.providerOptions &&
+            "contentLanguage" in settings.providerOptions) {
+            this.config.providerOptions = {
+                ...this.config.providerOptions,
+                contentLanguage: settings.providerOptions.contentLanguage,
+            };
+        }
     }
 }
 /**
@@ -821,14 +908,14 @@ export class ServerTTSProvider {
         if (serverConfig.validateEndpoint) {
             const validationStartedAt = Date.now();
             await this.emitTelemetry("pie-tool-backend-call-start", {
-                toolId: "tts",
+                toolId: TOOL_ID,
                 backend: serverConfig.provider || "server",
                 operation: "validate-endpoint",
             });
             const available = await this.testAPIAvailability();
             if (!available) {
                 await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: "tts",
+                    toolId: TOOL_ID,
                     backend: serverConfig.provider || "server",
                     operation: "validate-endpoint",
                     duration: Date.now() - validationStartedAt,
@@ -838,7 +925,7 @@ export class ServerTTSProvider {
                 throw new Error(`Server TTS API not available at ${serverConfig.apiEndpoint}`);
             }
             await this.emitTelemetry("pie-tool-backend-call-success", {
-                toolId: "tts",
+                toolId: TOOL_ID,
                 backend: serverConfig.provider || "server",
                 operation: "validate-endpoint",
                 duration: Date.now() - validationStartedAt,
@@ -867,19 +954,26 @@ export class ServerTTSProvider {
                 clearTimeout(timeoutId);
                 return true;
             }
-            const validationUrl = mode === "voices"
-                ? resolveVoicesValidationUrl(this.config)
-                : this.adapter.resolveSynthesisUrl(this.config);
+            const validationUrls = mode === "voices"
+                ? resolveVoicesValidationUrls(this.config)
+                : [this.adapter.resolveSynthesisUrl(this.config)];
             const method = mode === "voices" ? "GET" : "OPTIONS";
             try {
-                const response = await fetch(validationUrl, {
-                    method,
-                    headers,
-                    signal: controller.signal,
-                });
+                let reachable = false;
+                for (const validationUrl of validationUrls) {
+                    const response = await fetch(validationUrl, {
+                        method,
+                        headers,
+                        signal: controller.signal,
+                        ...fetchCredentials(this.config),
+                    });
+                    // Some endpoints may not accept OPTIONS; treat 405 as reachable.
+                    reachable = response.ok || response.status === 405;
+                    if (reachable || response.status !== 404)
+                        break;
+                }
                 clearTimeout(timeoutId);
-                // Some endpoints may not accept OPTIONS; treat 405 as reachable.
-                return response.ok || response.status === 405;
+                return reachable;
             }
             catch {
                 clearTimeout(timeoutId);
@@ -890,21 +984,6 @@ export class ServerTTSProvider {
             return false;
         }
     }
-    supportsFeature(feature) {
-        switch (feature) {
-            case "pause":
-            case "resume":
-            case "wordBoundary":
-            case "voiceSelection":
-            case "rateControl":
-                return true;
-            case "pitchControl":
-                // Depends on server provider, assume no for safety
-                return false;
-            default:
-                return false;
-        }
-    }
     getCapabilities() {
         const mode = this.config ? resolveTransportMode(this.config) : "pie";
         return {

package/dist/index.d.ts

@@ -2,5 +2,5 @@
  * Client-side TTS provider for calling server APIs
  * @module @pie-players/tts-client-server
  */
-export type { ServerTTSProviderConfig } from "./ServerTTSProvider.js";
+export type { ServerTTSProviderConfig, ServerTTSProviderOptions, } from "./ServerTTSProvider.js";
 export { ServerTTSProvider } from "./ServerTTSProvider.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/tts-client-server",
-	"version": "0.3.73",
+	"version": "0.3.75",
 	"description": "Client-side TTS provider that calls server API for synthesis",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -38,13 +38,13 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@pie-players/pie-players-shared": "0.3.73",
-		"@pie-players/pie-tts": "0.3.73",
-		"@pie-players/tts-server-core": "0.3.73"
+		"@pie-players/pie-players-shared": "0.3.75",
+		"@pie-players/pie-tts": "0.3.75",
+		"@pie-players/tts-server-core": "0.3.75"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",
-		"vitest": "^4.1.11"
+		"vitest": "^5.0.3"
 	},
 	"sideEffects": false,
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/tts-client-server#readme",