@pie-players/tts-client-server 0.3.68 → 0.3.70

package/dist/ServerTTSProvider.js

@@ -5,7 +5,9 @@
  * providers like AWS Polly, Google Cloud TTS, etc.
  * Returns audio with precise word-level timing (speech marks).
  */
+import { createPieLogger, isGlobalDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { normalizeSpeechMarks, resolveSpeedRateBucket, } from "@pie-players/tts-server-core";
+const logger = createPieLogger("server-tts-provider", () => isGlobalDebugEnabled());
 /**
  * Parse a TTS asset URL (speech marks or audio). Rejects anything that is
  * not an absolute http(s) URL; relative URLs are resolved against
@@ -312,6 +314,12 @@ class ServerTTSProviderImpl {
     pausedState = false;
     wordTimings = [];
     highlightInterval = null;
+    /**
+     * Index of the word timing most recently handed to `onWordBoundary`, or -1
+     * before the first. It survives pause/resume so resuming continues from the
+     * spoken position instead of replaying the passage from its first word.
+     */
+    highlightCursor = -1;
     intentionallyStopped = false;
     activeSynthesisController = null;
     synthesisRunId = 0;
@@ -328,7 +336,7 @@ class ServerTTSProviderImpl {
             await this.telemetryReporter?.(eventName, payload);
         }
         catch (error) {
-            console.warn("[ServerTTSProvider] telemetry callback failed:", error);
+            logger.warn("telemetry callback failed:", error);
         }
     }
     async speak(text) {
@@ -346,6 +354,7 @@ class ServerTTSProviderImpl {
             return;
         }
         this.wordTimings = wordTimings;
+        this.highlightCursor = -1;
         return new Promise((resolve, reject) => {
             // Create audio element
             const audio = new Audio(audioUrl);
@@ -364,7 +373,7 @@ class ServerTTSProviderImpl {
                     this.onPlaybackStart?.();
                 }
                 catch (error) {
-                    console.warn("[ServerTTSProvider] playback-start callback failed:", error);
+                    logger.warn("playback-start callback failed:", error);
                 }
                 // Start word highlighting
                 if (this.onWordBoundary && this.wordTimings.length > 0) {
@@ -376,6 +385,7 @@ class ServerTTSProviderImpl {
                 URL.revokeObjectURL(audioUrl);
                 this.currentAudio = null;
                 this.wordTimings = [];
+                this.highlightCursor = -1;
                 resolve();
             };
             audio.onerror = (event) => {
@@ -383,6 +393,7 @@ class ServerTTSProviderImpl {
                 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) {
@@ -450,14 +461,20 @@ class ServerTTSProviderImpl {
                     errorData = JSON.parse(rawBody);
                 }
                 catch (parseError) {
-                    console.warn("[ServerTTSProvider] non-OK response body was not JSON", {
+                    logger.warn("non-OK response body was not JSON", {
                         status: response.status,
                         url: synthUrl,
-                        rawBodyPreview: rawBody.slice(0, 500),
+                        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, 500),
+                    });
                 }
             }
             const errorMessage = (typeof errorData.message === "string" && errorData.message) ||
@@ -474,14 +491,20 @@ class ServerTTSProviderImpl {
                 errorType: "TTSBackendRequestError",
                 message: errorMessage,
             });
-            const textPreview = text.replace(/\s+/g, " ").trim().slice(0, 120);
-            console.error("[ServerTTSProvider] synthesize request failed", {
+            logger.error("synthesize request failed", {
                 status: response.status,
                 url: synthUrl,
                 backend: this.config.provider || "server",
                 message: errorMessage,
-                responseBody: errorData,
                 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, 120);
+            logger.debug("synthesize request failed for text", {
+                responseBody: errorData,
                 textPreview: textPreview.length < text.length ? `${textPreview}…` : textPreview,
             });
             throw new Error(errorMessage);
@@ -608,39 +631,75 @@ class ServerTTSProviderImpl {
         if (!this.currentAudio ||
             !this.onWordBoundary ||
             this.wordTimings.length === 0) {
-            console.log("[ServerTTSProvider] Cannot start highlighting:", {
+            logger.debug("cannot start word highlighting", {
                 hasAudio: !!this.currentAudio,
                 hasCallback: !!this.onWordBoundary,
                 wordTimingsCount: this.wordTimings.length,
             });
             return;
         }
-        console.log("[ServerTTSProvider] Starting word highlighting with", this.wordTimings.length, "word timings");
-        console.log("[ServerTTSProvider] Playback rate:", this.currentAudio.playbackRate);
-        console.log("[ServerTTSProvider] First 3 timings:", this.wordTimings.slice(0, 3));
-        let lastWordIndex = -1;
-        // Poll every 50ms to check current playback time
+        logger.debug("starting word highlighting", {
+            wordTimingsCount: this.wordTimings.length,
+            playbackRate: this.currentAudio.playbackRate,
+        });
+        // A 50ms interval, chosen over the two alternatives: 50ms is below the
+        // perceptual threshold for word-level sync at a fifth of the wake-ups a
+        // 60Hz `requestAnimationFrame` loop would spend on the same job, and
+        // `timeupdate` fires at browser discretion — commonly 150-250ms — so it
+        // would need a timer behind it to interpolate anyway. The interval also
+        // degrades better while the tab is hidden: browsers clamp it to roughly
+        // 1s where they suspend rAF outright, and because a tick resolves
+        // straight to the word that is current, one clamped tick resyncs the
+        // highlight rather than replaying a backlog.
         this.highlightInterval = window.setInterval(() => {
             if (!this.currentAudio) {
                 this.stopWordHighlighting();
                 return;
             }
-            // Get current playback time in milliseconds
-            const currentTime = this.currentAudio.currentTime * 1000;
-            // Find words that should be highlighted at current time
-            for (let i = 0; i < this.wordTimings.length; i++) {
-                const timing = this.wordTimings[i];
-                if (currentTime >= timing.time && i > lastWordIndex) {
-                    // Fire word boundary callback
-                    if (this.onWordBoundary) {
-                        console.log("[ServerTTSProvider] Highlighting word at charIndex:", timing.charIndex, "length:", timing.length, "time:", timing.time, "currentTime:", currentTime);
-                        this.onWordBoundary(timing.word, timing.charIndex, timing.length);
-                    }
-                    lastWordIndex = i;
-                    break;
-                }
+            const currentTimeMs = this.currentAudio.currentTime * 1000;
+            const index = this.resolveCurrentWordIndex(currentTimeMs, this.highlightCursor);
+            if (index < 0 || index === this.highlightCursor) {
+                return;
             }
-        }, 50); // 50ms polling = 20 times per second
+            // Report only the word that is current now. Words a tick crossed over
+            // are deliberately skipped rather than fired in order: the callback
+            // names the word being spoken and its consumer repaints a single range
+            // per call, so replaying the backlog would paint highlights the learner
+            // never sees and leave the last paint behind the audio. Firing one word
+            // per tick capped highlighting at 20 words/second, which is how the
+            // highlight used to drift off the spoken word and never catch up.
+            this.highlightCursor = index;
+            const timing = this.wordTimings[index];
+            logger.debug("word boundary", {
+                wordIndex: timing.wordIndex,
+                charIndex: timing.charIndex,
+                length: timing.length,
+                timingMs: timing.time,
+                currentTimeMs,
+            });
+            this.onWordBoundary?.(timing.word, timing.charIndex, timing.length);
+        }, 50);
+    }
+    /**
+     * Index of the last timing whose start time has arrived at `currentTimeMs`,
+     * or -1 when playback has not reached the first word yet.
+     *
+     * The scan resumes at `cursor`, so a tick costs the number of words it
+     * crossed instead of the length of the passage. A backward jump — a seek, or
+     * a replay on the same element — invalidates the cursor, and only then does
+     * the scan restart from the beginning.
+     */
+    resolveCurrentWordIndex(currentTimeMs, cursor) {
+        const timings = this.wordTimings;
+        let index = cursor < timings.length ? cursor : -1;
+        if (index >= 0 && currentTimeMs < timings[index].time) {
+            index = -1;
+        }
+        while (index + 1 < timings.length &&
+            timings[index + 1].time <= currentTimeMs) {
+            index++;
+        }
+        return index;
     }
     /**
      * Stop word highlighting
@@ -687,6 +746,7 @@ class ServerTTSProviderImpl {
         }
         this.pausedState = false;
         this.wordTimings = [];
+        this.highlightCursor = -1;
     }
     isPlaying() {
         return this.currentAudio !== null && !this.pausedState;
@@ -737,7 +797,7 @@ export class ServerTTSProvider {
             await this.telemetryReporter?.(eventName, payload);
         }
         catch (error) {
-            console.warn("[ServerTTSProvider] telemetry callback failed:", error);
+            logger.warn("telemetry callback failed:", error);
         }
     }
     /**

package/package.json

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