@pie-players/tts-client-server 0.3.75 → 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
 
@@ -38,7 +36,7 @@ import { TTSService } from '@pie-players/pie-assessment-toolkit';
 
 const provider = new ServerTTSProvider();
 const config: ServerTTSProviderConfig = {
-  apiEndpoint: '/api/tts',  // Your SvelteKit API route
+  apiEndpoint: '/api/tts',  // the host's TTS API route
   provider: 'polly',         // Server-side provider to use
   voice: 'Joanna',
   language: 'en-US',
@@ -52,7 +50,8 @@ await ttsService.initialize(provider, config);
 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`
@@ -77,11 +76,21 @@ 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:**
@@ -115,18 +124,6 @@ await ttsService.speak(document.getElementById('content'));
 }
 ```
 
-### 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
@@ -162,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:
 ```
@@ -181,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
@@ -236,33 +232,35 @@ for the host-wide contract this provider fits into.
 
 ## How It Works
 
-1. **Client calls** `speak(element)`
+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
 
@@ -280,16 +278,17 @@ try {
   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:
 
@@ -298,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,8 +4,15 @@
  * 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, TTSConfig, TTSProviderCapabilities, TTSProviderOptions } from "@pie-players/pie-tts";
+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
@@ -20,8 +27,11 @@ export interface ServerTTSProviderOptions extends TTSProviderOptions {
     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;
+    /**
+     * 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.
@@ -62,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";
     /**
@@ -93,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
@@ -110,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;
@@ -119,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>;
     /**

package/dist/ServerTTSProvider.js

@@ -4,13 +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, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
-import { normalizeSpeechMarks, resolveSpeedRateBucket, } from "@pie-players/tts-server-core";
+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
@@ -119,6 +133,13 @@ const getTelemetryReporter = (config) => {
     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,
@@ -164,14 +185,18 @@ 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 speedRate = config.providerOptions?.speedRate;
-    if (typeof speedRate === "string")
+    if (SPEED_RATE_BUCKETS.has(speedRate))
         return speedRate;
     return resolveSpeedRateBucket(config.rate);
 };
@@ -253,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: {
@@ -261,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)
+                : [],
         };
     },
 };
@@ -378,14 +405,11 @@ 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
         let synthesized;
         try {
             synthesized = await this.synthesizeSpeech(text, synthesisController.signal, runId);
@@ -410,10 +434,8 @@ 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));
             }
@@ -427,12 +449,13 @@ class ServerTTSProviderImpl {
                     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();
                 }
@@ -479,16 +502,11 @@ class ServerTTSProviderImpl {
      */
     async synthesizeSpeech(text, signal, runId) {
         const synthStartedAt = Date.now();
-        await this.emitTelemetry("pie-tool-backend-call-start", {
-            toolId: TOOL_ID,
-            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}`;
         }
@@ -507,14 +525,11 @@ class ServerTTSProviderImpl {
             catch (error) {
                 if (signal.aborted)
                     throw error;
-                await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: TOOL_ID,
-                    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,
                     errorType: "TTSBackendNetworkError",
                     message: error instanceof Error ? error.message : String(error),
-                });
+                }));
                 throw error;
             }
         })();
@@ -538,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),
                     });
                 }
             }
@@ -547,15 +562,12 @@ class ServerTTSProviderImpl {
                     ? errorData.error.message
                     : undefined) ||
                 `Server returned ${response.status}`;
-            await this.emitTelemetry("pie-tool-backend-call-error", {
-                toolId: TOOL_ID,
-                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,
@@ -567,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,
@@ -585,22 +600,15 @@ class ServerTTSProviderImpl {
         else {
             const audioAssetUrl = normalized.audio.url;
             const assetFetchStartedAt = Date.now();
-            await this.emitTelemetry("pie-tool-backend-call-start", {
-                toolId: TOOL_ID,
-                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: TOOL_ID,
-                    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);
@@ -619,46 +627,33 @@ class ServerTTSProviderImpl {
                 catch (error) {
                     if (signal.aborted)
                         throw error;
-                    await this.emitTelemetry("pie-tool-backend-call-error", {
-                        toolId: TOOL_ID,
-                        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: "TTSAssetNetworkError",
                         message: error instanceof Error ? error.message : String(error),
-                    });
+                    }));
                     throw error;
                 }
             })();
             if (!audioResponse.ok) {
-                await this.emitTelemetry("pie-tool-backend-call-error", {
-                    toolId: TOOL_ID,
-                    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: TOOL_ID,
-                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: TOOL_ID,
-            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 };
     }
     /**
@@ -742,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`,
@@ -826,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 = {
@@ -848,11 +836,9 @@ 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
@@ -874,8 +860,6 @@ class ServerTTSProviderImpl {
  */
 export class ServerTTSProvider {
     providerId = "server-tts";
-    providerName = "Server TTS";
-    version = "1.0.0";
     config = null;
     adapter = null;
     telemetryReporter;
@@ -890,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;
@@ -904,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: TOOL_ID,
-                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: TOOL_ID,
-                    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: TOOL_ID,
-                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);
     }
@@ -938,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 {
@@ -946,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)];
@@ -987,12 +953,9 @@ export class ServerTTSProvider {
     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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/tts-client-server",
-	"version": "0.3.75",
+	"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.75",
-		"@pie-players/pie-tts": "0.3.75",
-		"@pie-players/tts-server-core": "0.3.75"
+		"@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",