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

package/README.md

@@ -30,18 +30,22 @@ 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
   voice: 'Joanna',
   language: 'en-US',
-});
+};
+
+const ttsService = new TTSService();
+await ttsService.initialize(provider, config);
 ```
 
 `apiEndpoint`, `provider`, `voice` and `language` are top-level fields; the
@@ -68,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
@@ -138,7 +140,10 @@ await ttsService.speak('Hello world, this is a test.', {
 ```
 
 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.
+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
 
@@ -231,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
@@ -272,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.) */
@@ -106,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
@@ -113,13 +116,8 @@ function assetFetchHeaders(requestHeaders, config) {
     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,
@@ -172,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 [];
@@ -218,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"
@@ -240,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,
@@ -269,10 +273,14 @@ 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,
@@ -347,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;
@@ -374,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;
@@ -389,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?.();
@@ -407,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();
         });
     }
     /**
@@ -444,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",
         });
@@ -469,8 +505,10 @@ class ServerTTSProviderImpl {
                 });
             }
             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,
@@ -510,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,
@@ -548,7 +586,7 @@ 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",
             });
@@ -556,7 +594,7 @@ class ServerTTSProviderImpl {
             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,
@@ -579,8 +617,10 @@ class ServerTTSProviderImpl {
                     });
                 }
                 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,
@@ -592,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,
@@ -604,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,
@@ -614,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,
@@ -734,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;
@@ -801,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,
+            };
+        }
     }
 }
 /**
@@ -845,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,
@@ -862,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,
@@ -921,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.74",
+	"version": "0.3.75",
 	"description": "Client-side TTS provider that calls server API for synthesis",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -38,9 +38,9 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@pie-players/pie-players-shared": "0.3.74",
-		"@pie-players/pie-tts": "0.3.74",
-		"@pie-players/tts-server-core": "0.3.74"
+		"@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",