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

package/README.md

@@ -1,23 +1,21 @@
 # @pie-players/tts-client-server
 
-Client-side TTS provider that calls a server API for synthesis with speech marks support.
-
-For the cross-package TTS architecture and provider layering, see
-[TTS Architecture](../../docs/accessibility/tts-architecture.md). This README
-focuses on the browser-side server provider API.
-
-## Overview
-
-This package provides a browser-side TTS provider that offloads synthesis to a server API. The server handles provider selection (AWS Polly, Google Cloud TTS, etc.) and credential management, while the client plays audio and coordinates word highlighting.
+`ServerTTSProvider`, the browser-side text-to-speech (TTS) provider that sends
+synthesis to a server API the host runs. The server picks the vendor (AWS Polly,
+Google Cloud TTS, or any provider built on `@pie-players/tts-server-core`) and
+holds its credentials; the client plays the returned audio and reports word
+boundaries from the server's speech marks. This README covers the provider's API
+for host integrators adding server-backed read-aloud. For the package layering,
+see [TTS Architecture](../../docs/accessibility/tts-architecture.md); for the
+runtime flow, the [TTS deep dive](../../docs/accessibility/tts-deep-dive.md).
 
 ## Features
 
-- ✅ **Server-Side Synthesis** - Keeps credentials secure on server
-- ✅ **Speech Marks** - Precise word-level timing from server
-- ✅ **Multiple Providers** - Server can use Polly, Google, ElevenLabs, etc.
-- ✅ **Word Highlighting** - 50ms polling for smooth synchronization
-- ✅ **Audio Playback** - HTMLAudioElement with pause/resume
-- ✅ **Blob URLs** - Efficient memory management
+- **Server-side synthesis**: vendor credentials stay on the server
+- **Speech marks**: word timings from the server drive highlighting
+- **Word highlighting**: the audio clock is polled every 50ms
+- **Audio playback**: an `HTMLAudioElement` playing a Blob URL, with pause and
+  resume
 
 ## Installation
 
@@ -30,25 +28,30 @@ 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, {
-  apiEndpoint: '/api/tts',  // Your SvelteKit API route
+const config: ServerTTSProviderConfig = {
+  apiEndpoint: '/api/tts',  // the host's TTS 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
 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`.
+transport reads its `speedRate` (else a bucket from `rate`), `lang_id` (else the
+content language, else `language`, else `en-US`) and `cache` (default `true`).
 
 `apiEndpoint` is required when using `ServerTTSProvider` directly, and
 `initialize` throws without it. Toolkit-level `tools.providers.textToSpeech`
@@ -68,18 +71,26 @@ 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
 
-`ServerTTSProvider` now supports two transport modes:
+`ServerTTSProvider` supports two transport modes:
 
-- `pie` (default): POST `${apiEndpoint}/synthesize`, inline base64 audio + inline speech marks
+- `pie`: POST `${apiEndpoint}/synthesize`, inline base64 audio + inline speech marks
 - `custom`: POST to root endpoint, then fetch `audioContent` and JSONL marks URLs
 
+With `transportMode` unset, the transport is `custom` when `provider` is
+`"custom"` and `pie` otherwise. `endpointMode` defaults to `synthesizePath` for
+`pie` and `rootPost` for `custom`. The toolkit's `tools.providers.textToSpeech`
+applies the same default from `serverProvider`.
+
+The provider reports SSML support only on the `pie` transport with `provider`
+`polly` (the default) or `google`. There the toolkit voices generated math as
+SSML; everywhere else, the custom transport included, generated speech is plain
+text.
+
 ### PIE mode request
 
 **Request:**
@@ -113,18 +124,6 @@ await ttsService.speak('Hello world, this is a test.', {
 }
 ```
 
-### PIE mode response
-
-```json
-{
-  "audio": "base64-encoded-audio",
-  "contentType": "audio/mpeg",
-  "speechMarks": [
-    { "time": 0, "type": "word", "start": 0, "end": 5, "value": "Hello" }
-  ]
-}
-```
-
 ### Custom mode request
 
 ```json
@@ -138,7 +137,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
 
@@ -157,7 +159,7 @@ Speech marks are fetched from the `word` URL and parsed as JSONL.
 
 ## SvelteKit Implementation Example
 
-See the implementation guide in [tts-architecture.md](../../docs/accessibility/tts-architecture.md).
+The [`@pie-players/tts-server-polly` integration guide](../tts-server-polly/examples/INTEGRATION-GUIDE.md) builds these routes for Polly, and the [`@pie-players/tts-server-google` integration guide](../tts-server-google/examples/INTEGRATION-GUIDE.md) for Google.
 
 Example route structure:
 ```
@@ -176,8 +178,7 @@ interface ServerTTSProviderConfig {
   provider?: string;          // Server provider ('polly', 'google', etc.)
   transportMode?: 'pie' | 'custom';
   endpointMode?: 'synthesizePath' | 'rootPost';
-  endpointValidationMode?: 'voices' | 'endpoint' | 'none';
-  validateEndpoint?: boolean; // Probe the endpoint during initialize()
+  endpointValidationMode?: 'voices' | 'endpoint' | 'none'; // Probe run by initialize(); default 'none'
   authToken?: string;         // JWT or API key
   includeAuthOnAssetFetch?: boolean;
   assetOrigins?: string[];    // Trusted origins for Authorization header
@@ -231,33 +232,35 @@ for the host-wide contract this provider fits into.
 
 ## How It Works
 
-1. **Client calls** `speak(text)`
+1. **TTSService calls** `speak(text)` with the text it resolved from the element or range
 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
 5. **Client loads** audio as Blob URL
 6. **Client plays** audio via HTMLAudioElement
 7. **Client polls** audio time every 50ms
-8. **Client fires** word boundary callbacks at correct times
+8. **Client reports** the word at the current audio time through the word-boundary callback
 9. **TTSService** highlights words in DOM
 
 ## Word Highlighting Synchronization
 
-The provider uses a polling-based approach for reliable synchronization:
+Every 50ms the provider reads the audio's current time and reports the last
+word whose start time has arrived, once:
 
 ```typescript
-// Every 50ms, check current audio time
-const currentTime = audio.currentTime * 1000; // Convert to ms
-
-// Find words that should be highlighted
-for (const timing of wordTimings) {
-  if (currentTime >= timing.time) {
-    onWordBoundary('', timing.charIndex, timing.length);
-  }
+const currentTimeMs = audio.currentTime * 1000;
+const index = lastTimingAtOrBefore(wordTimings, currentTimeMs);
+if (index >= 0 && index !== lastReported) {
+  lastReported = index;
+  const timing = wordTimings[index];
+  onWordBoundary(timing.word, timing.charIndex, timing.length);
 }
 ```
 
-This is **much more reliable** than browser's `onboundary` events (which are broken in Safari and unreliable in Chrome).
+Words a tick crossed are skipped: the callback names the word being spoken, so
+replaying them would paint highlights the learner never sees and leave the
+highlight behind the audio. A background tab's clamped timer resyncs on its next
+tick for the same reason.
 
 ## Memory Management
 
@@ -272,19 +275,20 @@ 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
+  // A failed read rejects without switching provider; the toolkit coordinator
+  // falls back to browser TTS only when a provider fails to start.
 }
 ```
 
 ## Browser Compatibility
 
-- ✅ Chrome/Edge (latest)
-- ✅ Firefox (latest)
-- ✅ Safari (latest)
-- ✅ Mobile browsers
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers
 
 Requires:
 
@@ -293,12 +297,11 @@ Requires:
 - `URL.createObjectURL`
 - `atob` for base64 decoding
 
-## Performance
+## Caching
 
-- **Audio caching:** Server-side (Redis)
-- **Blob URLs:** Efficient memory usage
-- **50ms polling:** Smooth highlighting without jank
-- **Parallel requests:** Audio + marks fetched together
+The client keeps no audio cache. Caching is server-side, through the host's
+`ITTSCache` (`@pie-players/tts-server-core`); the custom transport also sends a
+`cache` flag, `true` unless `providerOptions.cache` is `false`.
 
 ## License
 

package/dist/ServerTTSProvider.d.ts

@@ -4,12 +4,47 @@
  * Provides high-quality TTS by calling a server-side API that uses
  * providers like AWS Polly, Google Cloud TTS, etc.
  * Returns audio with precise word-level timing (speech marks).
+ *
+ * Layout: config types; the asset-URL and auth helpers that guard fetches of
+ * server-returned URLs; wire types; mode resolvers; the `pie` and `custom`
+ * transport adapters (`ADAPTERS`); `ServerTTSProviderImpl`, which owns one
+ * playback (synthesis, audio element, word highlighting); and
+ * `ServerTTSProvider`, which picks the adapter, runs the optional endpoint probe
+ * and hands out implementations.
+ */
+import type { ITTSProvider, ITTSProviderImplementation, SpeedRateBucket, 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.
  */
-import type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSFeature, TTSProviderCapabilities } from "@pie-players/pie-tts";
+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 or
+     * not one of the three buckets.
+     */
+    speedRate?: SpeedRateBucket;
+    /**
+     * 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.) */
@@ -37,10 +72,12 @@ export interface ServerTTSProviderConfig extends TTSConfig {
      */
     endpointMode?: "synthesizePath" | "rootPost";
     /**
-     * Endpoint validation mode used during initialize(validateEndpoint=true).
-     * - voices: probe {apiEndpoint}/voices
-     * - endpoint: probe resolved synthesis endpoint
-     * - none: skip endpoint probe
+     * The probe `initialize()` runs before it resolves; a failed probe rejects it.
+     * - voices: GET {apiEndpoint}/voices, trying the provider's own route first
+     * - endpoint: OPTIONS on the resolved synthesis endpoint
+     * - none: no probe, so an unreachable server fails at the first synthesis
+     *
+     * @default "none"
      */
     endpointValidationMode?: "voices" | "endpoint" | "none";
     /**
@@ -68,14 +105,6 @@ export interface ServerTTSProviderConfig extends TTSConfig {
      * fetch on the browser default, `"same-origin"`.
      */
     credentials?: "omit" | "same-origin" | "include";
-    /**
-     * Validate API endpoint availability during initialization (slower but safer)
-     *
-     * @extension Performance vs safety tradeoff
-     * @default false (fast initialization, fail on first synthesis if unavailable)
-     * @note When true, adds 100-500ms to initialization time
-     */
-    validateEndpoint?: boolean;
 }
 /**
  * Server TTS Provider
@@ -85,8 +114,6 @@ export interface ServerTTSProviderConfig extends TTSConfig {
  */
 export declare class ServerTTSProvider implements ITTSProvider {
     readonly providerId = "server-tts";
-    readonly providerName = "Server TTS";
-    readonly version = "1.0.0";
     private config;
     private adapter;
     private telemetryReporter;
@@ -94,10 +121,8 @@ export declare class ServerTTSProvider implements ITTSProvider {
     /**
      * Initialize the server TTS provider.
      *
-     * This is designed to be fast by default (no API calls).
-     * Set validateEndpoint: true in config to test API availability during initialization.
-     *
-     * @performance Default: <10ms, With validation: 100-500ms
+     * Makes no request unless `endpointValidationMode` names a probe, which
+     * adds 100-500ms.
      */
     initialize(config: TTSConfig): Promise<ITTSProviderImplementation>;
     /**
@@ -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

@@ -4,10 +4,27 @@
  * Provides high-quality TTS by calling a server-side API that uses
  * providers like AWS Polly, Google Cloud TTS, etc.
  * Returns audio with precise word-level timing (speech marks).
+ *
+ * Layout: config types; the asset-URL and auth helpers that guard fetches of
+ * server-returned URLs; wire types; mode resolvers; the `pie` and `custom`
+ * transport adapters (`ADAPTERS`); `ServerTTSProviderImpl`, which owns one
+ * playback (synthesis, audio element, word highlighting); and
+ * `ServerTTSProvider`, which picks the adapter, runs the optional endpoint probe
+ * and hands out implementations.
  */
-import { createPieLogger, isGlobalDebugEnabled, } from "@pie-players/pie-players-shared/pie";
-import { normalizeSpeechMarks, resolveSpeedRateBucket, } from "@pie-players/tts-server-core";
-const logger = createPieLogger("server-tts-provider", () => isGlobalDebugEnabled());
+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.
+const TOOL_ID = "textToSpeech";
+// Word-highlight polling period; `startWordHighlighting` gives the reasons.
+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
@@ -113,14 +130,16 @@ 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;
 };
+/** The payload of a `pie-tool-backend-call-*` telemetry event. */
+const backendTelemetry = (config, operation, extra) => ({
+    toolId: TOOL_ID,
+    backend: config.provider || "server",
+    operation,
+    ...extra,
+});
 const MAX_TEXT_LENGTH_BY_MODE = {
     pie: 3000,
     custom: 3000,
@@ -166,18 +185,28 @@ const resolveEndpointMode = (config, mode) => {
         return config.endpointMode;
     return mode === "custom" ? "rootPost" : "synthesizePath";
 };
-const resolveValidationMode = (config, mode) => {
-    if (config.endpointValidationMode)
-        return config.endpointValidationMode;
-    return mode === "custom" ? "none" : "voices";
-};
+const resolveValidationMode = (config) => config.endpointValidationMode === "voices" ||
+    config.endpointValidationMode === "endpoint"
+    ? config.endpointValidationMode
+    : "none";
+const SPEED_RATE_BUCKETS = new Set([
+    "slow",
+    "medium",
+    "fast",
+]);
 const resolveSpeedRate = (config) => {
-    const providerOptions = (config.providerOptions || {});
-    if (typeof providerOptions.speedRate === "string") {
-        return providerOptions.speedRate;
-    }
+    const speedRate = config.providerOptions?.speedRate;
+    if (SPEED_RATE_BUCKETS.has(speedRate))
+        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 +247,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 +269,7 @@ const pieAdapter = {
             text,
             provider: config.provider || "polly",
             voice: config.voice,
-            language: config.language,
+            language: contentLanguageOf(config) ?? config.language,
             rate: config.rate,
             engine,
             sampleRate,
@@ -249,7 +278,7 @@ const pieAdapter = {
             includeSpeechMarks: true,
         };
     },
-    parseResponse: async (response, _config, _headers, _signal, _text) => {
+    parseResponse: async (response, _config, _headers, _signal, text) => {
         const data = await response.json();
         return {
             audio: {
@@ -257,7 +286,9 @@ const pieAdapter = {
                 data: data.audio,
                 contentType: data.contentType,
             },
-            speechMarks: Array.isArray(data.speechMarks) ? data.speechMarks : [],
+            speechMarks: Array.isArray(data.speechMarks)
+                ? anchorSpeechMarks(data.speechMarks, text)
+                : [],
         };
     },
 };
@@ -269,10 +300,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 +382,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;
@@ -366,15 +405,28 @@ class ServerTTSProviderImpl {
         }
     }
     async speak(text) {
-        // Stop any current playback
         this.stop();
-        // Reset intentionally stopped flag for new playback
         this.intentionallyStopped = false;
         const runId = ++this.synthesisRunId;
         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;
@@ -382,60 +434,67 @@ class ServerTTSProviderImpl {
         this.wordTimings = wordTimings;
         this.highlightCursor = -1;
         return new Promise((resolve, reject) => {
-            // Create audio element
             const audio = new Audio(audioUrl);
             this.currentAudio = audio;
-            // Apply volume from config
             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?.();
+                    this.onPlaybackStart?.({
+                        wordBoundaries: this.wordTimings.length > 0,
+                    });
                 }
                 catch (error) {
                     logger.warn("playback-start callback failed:", error);
                 }
-                // Start word highlighting
                 if (this.onWordBoundary && this.wordTimings.length > 0) {
                     this.startWordHighlighting();
                 }
             };
             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();
         });
     }
     /**
@@ -443,16 +502,11 @@ class ServerTTSProviderImpl {
      */
     async synthesizeSpeech(text, signal, runId) {
         const synthStartedAt = Date.now();
-        await this.emitTelemetry("pie-tool-backend-call-start", {
-            toolId: "tts",
-            backend: this.config.provider || "server",
-            operation: "synthesize-speech",
-        });
+        await this.emitTelemetry("pie-tool-backend-call-start", backendTelemetry(this.config, "synthesize-speech"));
         const headers = {
             "Content-Type": "application/json",
             ...this.config.headers,
         };
-        // Add authentication if provided
         if (this.config.authToken) {
             headers["Authorization"] = `Bearer ${this.config.authToken}`;
         }
@@ -469,14 +523,13 @@ class ServerTTSProviderImpl {
                 });
             }
             catch (error) {
-                await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: "tts",
-                    backend: this.config.provider || "server",
-                    operation: "synthesize-speech",
+                if (signal.aborted)
+                    throw error;
+                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),
-                });
+                }));
                 throw error;
             }
         })();
@@ -500,7 +553,7 @@ class ServerTTSProviderImpl {
                     // 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, 500),
+                        rawBodyPreview: rawBody.slice(0, RAW_BODY_PREVIEW_LENGTH),
                     });
                 }
             }
@@ -509,15 +562,12 @@ class ServerTTSProviderImpl {
                     ? errorData.error.message
                     : undefined) ||
                 `Server returned ${response.status}`;
-            await this.emitTelemetry("pie-tool-backend-call-error", {
-                toolId: "tts",
-                backend: this.config.provider || "server",
-                operation: "synthesize-speech",
+            await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "synthesize-speech", {
                 duration: Date.now() - synthStartedAt,
                 statusCode: response.status,
                 errorType: "TTSBackendRequestError",
                 message: errorMessage,
-            });
+            }));
             logger.error("synthesize request failed", {
                 status: response.status,
                 url: synthUrl,
@@ -529,7 +579,10 @@ class ServerTTSProviderImpl {
             // 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, 120);
+            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,
@@ -547,22 +600,15 @@ class ServerTTSProviderImpl {
         else {
             const audioAssetUrl = normalized.audio.url;
             const assetFetchStartedAt = Date.now();
-            await this.emitTelemetry("pie-tool-backend-call-start", {
-                toolId: "tts",
-                backend: this.config.provider || "server",
-                operation: "fetch-synthesized-audio-asset",
-            });
+            await this.emitTelemetry("pie-tool-backend-call-start", backendTelemetry(this.config, "fetch-synthesized-audio-asset"));
             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",
-                    backend: this.config.provider || "server",
-                    operation: "fetch-synthesized-audio-asset",
+                await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "fetch-synthesized-audio-asset", {
                     duration: Date.now() - assetFetchStartedAt,
                     errorType: "TTSAssetInvalidUrl",
                     message: "TTS asset URL rejected (non-http(s) or malformed)",
-                });
+                }));
                 throw new Error("TTS asset URL rejected (non-http(s) or malformed)");
             }
             const assetTrusted = isOriginTrustedForAuth(parsedAssetUrl, this.config);
@@ -579,46 +625,35 @@ class ServerTTSProviderImpl {
                     });
                 }
                 catch (error) {
-                    await this.emitTelemetry("pie-tool-backend-call-error", {
-                        toolId: "tts",
-                        backend: this.config.provider || "server",
-                        operation: "fetch-synthesized-audio-asset",
+                    if (signal.aborted)
+                        throw error;
+                    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),
-                    });
+                    }));
                     throw error;
                 }
             })();
             if (!audioResponse.ok) {
-                await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: "tts",
-                    backend: this.config.provider || "server",
-                    operation: "fetch-synthesized-audio-asset",
+                await this.emitTelemetry("pie-tool-backend-call-error", backendTelemetry(this.config, "fetch-synthesized-audio-asset", {
                     duration: Date.now() - assetFetchStartedAt,
                     statusCode: audioResponse.status,
                     errorType: "TTSAssetFetchError",
                     message: `Failed to download synthesized audio (${audioResponse.status})`,
-                });
+                }));
                 throw new Error(`Failed to download synthesized audio (${audioResponse.status})`);
             }
             audioBlob = await audioResponse.blob();
-            await this.emitTelemetry("pie-tool-backend-call-success", {
-                toolId: "tts",
-                backend: this.config.provider || "server",
-                operation: "fetch-synthesized-audio-asset",
+            await this.emitTelemetry("pie-tool-backend-call-success", backendTelemetry(this.config, "fetch-synthesized-audio-asset", {
                 duration: Date.now() - assetFetchStartedAt,
-            });
+            }));
         }
         const audioUrl = URL.createObjectURL(audioBlob);
-        // Convert speech marks to word timings
         const wordTimings = this.parseSpeechMarks(normalized.speechMarks);
-        await this.emitTelemetry("pie-tool-backend-call-success", {
-            toolId: "tts",
-            backend: this.config.provider || "server",
-            operation: "synthesize-speech",
+        await this.emitTelemetry("pie-tool-backend-call-success", backendTelemetry(this.config, "synthesize-speech", {
             duration: Date.now() - synthStartedAt,
-        });
+        }));
         return { audioUrl, wordTimings };
     }
     /**
@@ -702,7 +737,7 @@ class ServerTTSProviderImpl {
                 currentTimeMs,
             });
             this.onWordBoundary?.(timing.word, timing.charIndex, timing.length);
-        }, 50);
+        }, HIGHLIGHT_INTERVAL_MS);
     }
     /**
      * Index of the last timing whose start time has arrived at `currentTimeMs`,
@@ -734,25 +769,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;
@@ -772,20 +821,13 @@ class ServerTTSProviderImpl {
         this.wordTimings = [];
         this.highlightCursor = -1;
     }
-    isPlaying() {
-        return this.currentAudio !== null && !this.pausedState;
-    }
-    isPaused() {
-        return this.pausedState;
-    }
     /**
-     * Update settings dynamically (rate, pitch, voice)
-     * Note: Server-side synthesis bakes rate, pitch, and voice into the audio and
-     * speech marks. Settings updates are stored for the next synthesis; active
-     * speed changes are handled by TTSService replaying from the current segment.
+     * 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.
      */
     updateSettings(settings) {
-        // Update config
         if (settings.rate !== undefined) {
             this.config.rate = settings.rate;
             this.config.providerOptions = {
@@ -794,13 +836,20 @@ class ServerTTSProviderImpl {
             };
         }
         if (settings.pitch !== undefined) {
-            // Server-side pitch is baked into audio, so this only affects next speak()
             this.config.pitch = settings.pitch;
         }
         if (settings.voice !== undefined) {
-            // 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,
+            };
+        }
     }
 }
 /**
@@ -811,8 +860,6 @@ class ServerTTSProviderImpl {
  */
 export class ServerTTSProvider {
     providerId = "server-tts";
-    providerName = "Server TTS";
-    version = "1.0.0";
     config = null;
     adapter = null;
     telemetryReporter;
@@ -827,10 +874,8 @@ export class ServerTTSProvider {
     /**
      * Initialize the server TTS provider.
      *
-     * This is designed to be fast by default (no API calls).
-     * Set validateEndpoint: true in config to test API availability during initialization.
-     *
-     * @performance Default: <10ms, With validation: 100-500ms
+     * Makes no request unless `endpointValidationMode` names a probe, which
+     * adds 100-500ms.
      */
     async initialize(config) {
         const serverConfig = config;
@@ -841,32 +886,22 @@ export class ServerTTSProvider {
         this.telemetryReporter = getTelemetryReporter(serverConfig);
         const transportMode = resolveTransportMode(serverConfig);
         this.adapter = ADAPTERS[transportMode];
-        // Only test API availability if explicitly requested (slower but safer)
-        if (serverConfig.validateEndpoint) {
+        const validationMode = resolveValidationMode(serverConfig);
+        if (validationMode !== "none") {
             const validationStartedAt = Date.now();
-            await this.emitTelemetry("pie-tool-backend-call-start", {
-                toolId: "tts",
-                backend: serverConfig.provider || "server",
-                operation: "validate-endpoint",
-            });
-            const available = await this.testAPIAvailability();
+            await this.emitTelemetry("pie-tool-backend-call-start", backendTelemetry(serverConfig, "validate-endpoint"));
+            const available = await this.testAPIAvailability(validationMode);
             if (!available) {
-                await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: "tts",
-                    backend: serverConfig.provider || "server",
-                    operation: "validate-endpoint",
+                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}`,
-                });
+                }));
                 throw new Error(`Server TTS API not available at ${serverConfig.apiEndpoint}`);
             }
-            await this.emitTelemetry("pie-tool-backend-call-success", {
-                toolId: "tts",
-                backend: serverConfig.provider || "server",
-                operation: "validate-endpoint",
+            await this.emitTelemetry("pie-tool-backend-call-success", backendTelemetry(serverConfig, "validate-endpoint", {
                 duration: Date.now() - validationStartedAt,
-            });
+            }));
         }
         return new ServerTTSProviderImpl(serverConfig, this.adapter);
     }
@@ -875,7 +910,7 @@ export class ServerTTSProvider {
      *
      * @performance 100-500ms depending on network
      */
-    async testAPIAvailability() {
+    async testAPIAvailability(mode) {
         if (!this.config || !this.adapter)
             return false;
         try {
@@ -883,14 +918,8 @@ export class ServerTTSProvider {
             if (this.config.authToken) {
                 headers["Authorization"] = `Bearer ${this.config.authToken}`;
             }
-            // Create abort controller for timeout
             const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 second timeout
-            const mode = resolveValidationMode(this.config, this.adapter.id);
-            if (mode === "none") {
-                clearTimeout(timeoutId);
-                return true;
-            }
+            const timeoutId = setTimeout(() => controller.abort(), ENDPOINT_PROBE_TIMEOUT_MS);
             const validationUrls = mode === "voices"
                 ? resolveVoicesValidationUrls(this.config)
                 : [this.adapter.resolveSynthesisUrl(this.config)];
@@ -921,30 +950,12 @@ 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 {
-            supportsPause: true,
-            supportsResume: true,
-            supportsWordBoundary: true, // ✅ Via speech marks from server
-            supportsVoiceSelection: true,
-            supportsRateControl: true,
-            supportsPitchControl: false, // Depends on server provider
+            // Word boundaries come from the server's speech marks; a response
+            // without them reports so at its playback start.
+            supportsWordBoundary: true,
             supportsSSML: resolveSupportsSSML(this.config),
             maxTextLength: MAX_TEXT_LENGTH_BY_MODE[mode],
         };

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": "1.0.0-beta.0",
 	"description": "Client-side TTS provider that calls server API for synthesis",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -17,8 +17,7 @@
 	"scripts": {
 		"build": "tsc",
 		"dev": "tsc --watch",
-		"test": "vitest run --passWithNoTests",
-		"test:coverage": "vitest --coverage"
+		"test": "vitest run"
 	},
 	"keywords": [
 		"tts",
@@ -38,9 +37,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": "1.0.0-beta.0",
+		"@pie-players/pie-tts": "1.0.0-beta.0",
+		"@pie-players/tts-server-core": "1.0.0-beta.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",