@pie-players/tts-client-server 1.0.0-beta.0 → 1.0.0-beta.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PIE Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ServerTTSProvider.d.ts

@@ -57,8 +57,6 @@ export interface ServerTTSProviderConfig extends TTSConfig {
     language?: string;
     /** Polly engine selection when provider is AWS Polly */
     engine?: "standard" | "neural";
-    /** Volume level 0-1 */
-    volume?: number;
     /**
      * Transport mode determines request/response translation strategy.
      * - pie: POST {apiEndpoint}/synthesize, expects inline base64 audio + speech marks

package/dist/ServerTTSProvider.js

@@ -12,8 +12,9 @@
  * `ServerTTSProvider`, which picks the adapter, runs the optional endpoint probe
  * and hands out implementations.
  */
+import { anchorSpeechMarks, normalizeSpeechMarks, resolveSpeedRateBucket, } from "@pie-players/pie-tts";
+import { languageTagWithoutVariants } from "@pie-players/pie-players-shared/i18n/language-tags";
 import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
-import { anchorSpeechMarks, normalizeSpeechMarks, resolveSpeedRateBucket, } from "@pie-players/tts-server-core";
 // 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.
@@ -22,9 +23,6 @@ const TOOL_ID = "textToSpeech";
 const HIGHLIGHT_INTERVAL_MS = 50;
 // How long the endpoint probe waits before reporting the server unreachable.
 const ENDPOINT_PROBE_TIMEOUT_MS = 5000;
-// Debug-log previews of an error body and of the text under synthesis.
-const RAW_BODY_PREVIEW_LENGTH = 500;
-const TEXT_PREVIEW_LENGTH = 120;
 /**
  * Parse a TTS asset URL (speech marks or audio). Rejects anything that is
  * not an absolute http(s) URL; relative URLs are resolved against
@@ -200,11 +198,15 @@ const resolveSpeedRate = (config) => {
         return speedRate;
     return resolveSpeedRateBucket(config.rate);
 };
-/** The language a speak named for its content, if any. */
+/**
+ * The language a speak named for its content, if any, without variant or
+ * private-use subtags: voices are keyed by language and region, so
+ * `en-GB-x-gulf` is read by an `en-GB` voice.
+ */
 const contentLanguageOf = (config) => {
     const language = config.providerOptions?.contentLanguage;
     return typeof language === "string" && language.trim()
-        ? language.trim()
+        ? languageTagWithoutVariants(language)
         : undefined;
 };
 const parseInlineSpeechMarks = (input) => {
@@ -271,6 +273,7 @@ const pieAdapter = {
             voice: config.voice,
             language: contentLanguageOf(config) ?? config.language,
             rate: config.rate,
+            ...(config.pitch !== undefined ? { pitch: config.pitch } : {}),
             engine,
             sampleRate,
             format,
@@ -365,6 +368,28 @@ const ADAPTERS = {
     pie: pieAdapter,
     custom: customAdapter,
 };
+/** Release a rejected response without waiting for its underlying stream. */
+function cancelResponseBody(response) {
+    try {
+        void response.body?.cancel().catch(() => { });
+    }
+    catch {
+        // Cleanup must not replace the status-only failure.
+    }
+}
+/**
+ * A fixed-message error that keeps the original's standard name, such as
+ * `NotAllowedError` for blocked autoplay, so hosts can still branch on it. The
+ * original message and cause are dropped: they can carry signed URLs.
+ */
+function redactedError(message, original) {
+    const error = new Error(message);
+    const name = original?.name;
+    if (typeof name === "string" && /^[A-Z][A-Za-z]*Error$/.test(name)) {
+        error.name = name;
+    }
+    return error;
+}
 /**
  * Provider implementation that handles audio playback
  */
@@ -381,12 +406,12 @@ class ServerTTSProviderImpl {
      * spoken position instead of replaying the passage from its first word.
      */
     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;
+    settleActivePlayback = null;
     synthesisRunId = 0;
     telemetryReporter;
     onPlaybackStart;
@@ -400,13 +425,17 @@ class ServerTTSProviderImpl {
         try {
             await this.telemetryReporter?.(eventName, payload);
         }
-        catch (error) {
-            logger.warn("telemetry callback failed:", error);
+        catch {
+            logger.warn("telemetry callback failed");
+        }
+    }
+    assertSynthesisActive(signal, runId) {
+        if (signal.aborted || runId !== this.synthesisRunId) {
+            throw new DOMException("TTS request was aborted", "AbortError");
         }
     }
     async speak(text) {
         this.stop();
-        this.intentionallyStopped = false;
         const runId = ++this.synthesisRunId;
         const synthesisController = new AbortController();
         this.activeSynthesisController = synthesisController;
@@ -436,6 +465,32 @@ class ServerTTSProviderImpl {
         return new Promise((resolve, reject) => {
             const audio = new Audio(audioUrl);
             this.currentAudio = audio;
+            let settled = false;
+            const settle = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                audio.onplaying = null;
+                audio.onended = null;
+                audio.onerror = null;
+                audio.onpause = null;
+                audio.pause();
+                audio.src = "";
+                URL.revokeObjectURL(audioUrl);
+                if (this.currentAudio === audio) {
+                    this.clearCurrentAudio();
+                    this.pausedState = false;
+                    this.startCurrentAudio = null;
+                }
+                if (this.settleActivePlayback === settle) {
+                    this.settleActivePlayback = null;
+                }
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            this.settleActivePlayback = settle;
             if (this.config.volume !== undefined) {
                 audio.volume = Math.max(0, Math.min(1, this.config.volume));
             }
@@ -453,27 +508,18 @@ class ServerTTSProviderImpl {
                         wordBoundaries: this.wordTimings.length > 0,
                     });
                 }
-                catch (error) {
-                    logger.warn("playback-start callback failed:", error);
+                catch {
+                    logger.warn("playback-start callback failed");
                 }
                 if (this.onWordBoundary && this.wordTimings.length > 0) {
                     this.startWordHighlighting();
                 }
             };
-            audio.onended = () => {
-                URL.revokeObjectURL(audioUrl);
-                if (!superseded())
-                    this.clearCurrentAudio();
-                resolve();
-            };
+            audio.onended = () => settle();
             audio.onerror = () => {
-                URL.revokeObjectURL(audioUrl);
-                if (superseded() || this.intentionallyStopped) {
-                    resolve();
-                    return;
-                }
-                this.clearCurrentAudio();
-                reject(new Error("Failed to play audio from server"));
+                settle(superseded()
+                    ? undefined
+                    : new Error("Failed to play audio from server"));
             };
             audio.onpause = () => {
                 if (superseded())
@@ -488,7 +534,9 @@ class ServerTTSProviderImpl {
                     if (aborted && this.pausedState && this.currentAudio === audio) {
                         return;
                     }
-                    reject(error);
+                    settle(superseded()
+                        ? undefined
+                        : redactedError("Failed to start audio playback", error));
                 });
             };
             this.startCurrentAudio = start;
@@ -503,6 +551,7 @@ class ServerTTSProviderImpl {
     async synthesizeSpeech(text, signal, runId) {
         const synthStartedAt = Date.now();
         await this.emitTelemetry("pie-tool-backend-call-start", backendTelemetry(this.config, "synthesize-speech"));
+        this.assertSynthesisActive(signal, runId);
         const headers = {
             "Content-Type": "application/json",
             ...this.config.headers,
@@ -523,76 +572,51 @@ class ServerTTSProviderImpl {
                 });
             }
             catch (error) {
-                if (signal.aborted)
-                    throw error;
+                this.assertSynthesisActive(signal, runId);
                 await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "synthesize-speech", {
                     duration: Date.now() - synthStartedAt,
                     errorType: "TTSBackendNetworkError",
-                    message: error instanceof Error ? error.message : String(error),
+                    message: "TTS synthesis network request failed",
                 }));
-                throw error;
+                this.assertSynthesisActive(signal, runId);
+                throw redactedError("TTS synthesis network request failed", error);
             }
         })();
         if (!response.ok) {
-            const rawBody = await response.text().catch(() => "");
-            let errorData = {};
-            if (rawBody) {
-                try {
-                    errorData = JSON.parse(rawBody);
-                }
-                catch (parseError) {
-                    logger.warn("non-OK response body was not JSON", {
-                        status: response.status,
-                        url: synthUrl,
-                        bodyLength: rawBody.length,
-                        parseError: parseError instanceof Error
-                            ? parseError.message
-                            : String(parseError),
-                    });
-                    // A provider's error body can echo the SSML it rejected, so the body
-                    // itself stays behind the debug gate; the length above is what says
-                    // a body arrived and was not JSON.
-                    logger.debug("non-OK response body", {
-                        rawBodyPreview: rawBody.slice(0, RAW_BODY_PREVIEW_LENGTH),
-                    });
-                }
-            }
-            const errorMessage = (typeof errorData.message === "string" && errorData.message) ||
-                (typeof errorData.error?.message === "string"
-                    ? errorData.error.message
-                    : undefined) ||
-                `Server returned ${response.status}`;
+            // A provider can echo request text or signed URLs in its body. Do not
+            // read it, or wait for a stalled stream before reporting the status.
+            cancelResponseBody(response);
+            const errorMessage = `Server returned ${response.status}`;
             await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "synthesize-speech", {
                 duration: Date.now() - synthStartedAt,
                 statusCode: response.status,
                 errorType: "TTSBackendRequestError",
                 message: errorMessage,
             }));
+            this.assertSynthesisActive(signal, runId);
             logger.error("synthesize request failed", {
                 status: response.status,
-                url: synthUrl,
                 backend: this.config.provider || "server",
-                message: errorMessage,
                 textLength: text.length,
             });
-            // The text under synthesis is item content and the provider's error body
-            // can echo it, so both stay behind the debug gate. `errorMessage` above is
-            // thrown to the caller regardless, and `textLength` is what correlates a
-            // failure with a payload without publishing what the learner is reading.
-            const textPreview = text
-                .replace(/\s+/g, " ")
-                .trim()
-                .slice(0, TEXT_PREVIEW_LENGTH);
-            logger.debug("synthesize request failed for text", {
-                responseBody: errorData,
-                textPreview: textPreview.length < text.length ? `${textPreview}…` : textPreview,
-            });
             throw new Error(errorMessage);
         }
-        const normalized = await this.adapter.parseResponse(response, this.config, headers, signal, text);
-        if (runId !== this.synthesisRunId || signal.aborted) {
-            throw new Error("Synthesis superseded by a newer request");
+        let normalized;
+        try {
+            normalized = await this.adapter.parseResponse(response, this.config, headers, signal, text);
+        }
+        catch {
+            this.assertSynthesisActive(signal, runId);
+            const message = "TTS synthesis response could not be processed";
+            await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "synthesize-speech", {
+                duration: Date.now() - synthStartedAt,
+                errorType: "TTSBackendResponseError",
+                message,
+            }));
+            this.assertSynthesisActive(signal, runId);
+            throw new Error(message);
         }
+        this.assertSynthesisActive(signal, runId);
         let audioBlob;
         if (normalized.audio.kind === "base64") {
             audioBlob = this.base64ToBlob(normalized.audio.data, normalized.audio.contentType);
@@ -601,6 +625,7 @@ class ServerTTSProviderImpl {
             const audioAssetUrl = normalized.audio.url;
             const assetFetchStartedAt = Date.now();
             await this.emitTelemetry("pie-tool-backend-call-start", backendTelemetry(this.config, "fetch-synthesized-audio-asset"));
+            this.assertSynthesisActive(signal, runId);
             const assetHeaders = assetFetchHeaders(headers, this.config);
             const parsedAssetUrl = parseAssetUrl(audioAssetUrl, this.config);
             if (parsedAssetUrl === null) {
@@ -625,17 +650,18 @@ class ServerTTSProviderImpl {
                     });
                 }
                 catch (error) {
-                    if (signal.aborted)
-                        throw error;
+                    this.assertSynthesisActive(signal, runId);
                     await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "fetch-synthesized-audio-asset", {
                         duration: Date.now() - assetFetchStartedAt,
                         errorType: "TTSAssetNetworkError",
-                        message: error instanceof Error ? error.message : String(error),
+                        message: "TTS synthesized audio request failed",
                     }));
-                    throw error;
+                    this.assertSynthesisActive(signal, runId);
+                    throw redactedError("TTS synthesized audio request failed", error);
                 }
             })();
             if (!audioResponse.ok) {
+                cancelResponseBody(audioResponse);
                 await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "fetch-synthesized-audio-asset", {
                     duration: Date.now() - assetFetchStartedAt,
                     statusCode: audioResponse.status,
@@ -644,16 +670,30 @@ class ServerTTSProviderImpl {
                 }));
                 throw new Error(`Failed to download synthesized audio (${audioResponse.status})`);
             }
-            audioBlob = await audioResponse.blob();
+            try {
+                audioBlob = await audioResponse.blob();
+            }
+            catch {
+                this.assertSynthesisActive(signal, runId);
+                const message = "TTS synthesized audio response could not be read";
+                await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "fetch-synthesized-audio-asset", {
+                    duration: Date.now() - assetFetchStartedAt,
+                    errorType: "TTSAssetResponseError",
+                    message,
+                }));
+                this.assertSynthesisActive(signal, runId);
+                throw new Error(message);
+            }
             await this.emitTelemetry("pie-tool-backend-call-success", backendTelemetry(this.config, "fetch-synthesized-audio-asset", {
                 duration: Date.now() - assetFetchStartedAt,
             }));
         }
-        const audioUrl = URL.createObjectURL(audioBlob);
         const wordTimings = this.parseSpeechMarks(normalized.speechMarks);
         await this.emitTelemetry("pie-tool-backend-call-success", backendTelemetry(this.config, "synthesize-speech", {
             duration: Date.now() - synthStartedAt,
         }));
+        this.assertSynthesisActive(signal, runId);
+        const audioUrl = URL.createObjectURL(audioBlob);
         return { audioUrl, wordTimings };
     }
     /**
@@ -807,25 +847,17 @@ class ServerTTSProviderImpl {
             this.activeSynthesisController = null;
         }
         this.stopWordHighlighting();
-        if (this.currentAudio) {
-            // Mark as intentionally stopped to prevent error handler from rejecting
-            this.intentionallyStopped = true;
-            this.currentAudio.pause();
-            if (this.currentAudio.src) {
-                URL.revokeObjectURL(this.currentAudio.src);
-            }
-            this.currentAudio.src = "";
-            this.currentAudio = null;
-        }
+        this.settleActivePlayback?.();
+        this.clearCurrentAudio();
         this.pausedState = false;
         this.wordTimings = [];
         this.highlightCursor = -1;
     }
     /**
      * Store rate, pitch, voice and the per-speak language for the next
-     * synthesis. Server-side synthesis bakes them into the audio and speech
-     * marks, so an active speed change is TTSService's job: it replays from the
-     * current segment.
+     * synthesis, and volume for the next playback. Server-side synthesis bakes
+     * the first four into the audio and speech marks, so an active speed change
+     * is TTSService's job: it replays from the current segment.
      */
     updateSettings(settings) {
         if (settings.rate !== undefined) {
@@ -838,6 +870,9 @@ class ServerTTSProviderImpl {
         if (settings.pitch !== undefined) {
             this.config.pitch = settings.pitch;
         }
+        if (settings.volume !== undefined) {
+            this.config.volume = settings.volume;
+        }
         if (settings.voice !== undefined) {
             this.config.voice = settings.voice;
         }
@@ -867,8 +902,8 @@ export class ServerTTSProvider {
         try {
             await this.telemetryReporter?.(eventName, payload);
         }
-        catch (error) {
-            logger.warn("telemetry callback failed:", error);
+        catch {
+            logger.warn("telemetry callback failed");
         }
     }
     /**
@@ -895,9 +930,9 @@ export class ServerTTSProvider {
                 await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(serverConfig, "validate-endpoint", {
                     duration: Date.now() - validationStartedAt,
                     errorType: "TTSEndpointValidationError",
-                    message: `Server TTS API not available at ${serverConfig.apiEndpoint}`,
+                    message: "Server TTS API is not available",
                 }));
-                throw new Error(`Server TTS API not available at ${serverConfig.apiEndpoint}`);
+                throw new Error("Server TTS API is not available");
             }
             await this.emitTelemetry("pie-tool-backend-call-success", backendTelemetry(serverConfig, "validate-endpoint", {
                 duration: Date.now() - validationStartedAt,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/tts-client-server",
-	"version": "1.0.0-beta.0",
+	"version": "1.0.0-beta.10",
 	"description": "Client-side TTS provider that calls server API for synthesis",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -8,8 +8,10 @@
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		}
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
 	},
 	"files": [
 		"dist"
@@ -37,13 +39,12 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@pie-players/pie-players-shared": "1.0.0-beta.0",
-		"@pie-players/pie-tts": "1.0.0-beta.0",
-		"@pie-players/tts-server-core": "1.0.0-beta.0"
+		"@pie-players/pie-players-shared": "1.0.0-beta.10",
+		"@pie-players/pie-tts": "1.0.0-beta.10"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",
-		"vitest": "^5.0.3"
+		"vitest": "^5.0.5"
 	},
 	"sideEffects": false,
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/tts-client-server#readme",