@pie-players/tts-server-core 0.3.66 → 0.3.68

package/dist/http-error-mapping.d.ts

@@ -0,0 +1,15 @@
+/**
+ * HTTP-status error mapping
+ * @module @pie-players/tts-server-core
+ */
+import { TTSErrorCode } from "./types.js";
+/**
+ * Map a plain HTTP status code to the closest `TTSErrorCode`, for providers
+ * whose wire format is a REST API rather than a vendor SDK with its own
+ * richer error taxonomy (a vendor SDK should map its own exception types
+ * instead — see PollyServerProvider/GoogleCloudTTSProvider). Uses only the
+ * handful of status codes with an unambiguous, universal REST meaning;
+ * anything else is a provider-level failure a caller can't act on more
+ * specifically.
+ */
+export declare function resolveTTSErrorCodeForHttpStatus(status: number): TTSErrorCode;

package/dist/http-error-mapping.js

@@ -0,0 +1,23 @@
+/**
+ * HTTP-status error mapping
+ * @module @pie-players/tts-server-core
+ */
+import { TTSErrorCode } from "./types.js";
+/**
+ * Map a plain HTTP status code to the closest `TTSErrorCode`, for providers
+ * whose wire format is a REST API rather than a vendor SDK with its own
+ * richer error taxonomy (a vendor SDK should map its own exception types
+ * instead — see PollyServerProvider/GoogleCloudTTSProvider). Uses only the
+ * handful of status codes with an unambiguous, universal REST meaning;
+ * anything else is a provider-level failure a caller can't act on more
+ * specifically.
+ */
+export function resolveTTSErrorCodeForHttpStatus(status) {
+    if (status === 401 || status === 403)
+        return TTSErrorCode.AUTHENTICATION_ERROR;
+    if (status === 429)
+        return TTSErrorCode.RATE_LIMIT_EXCEEDED;
+    if (status === 400)
+        return TTSErrorCode.INVALID_REQUEST;
+    return TTSErrorCode.PROVIDER_ERROR;
+}

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export type { CacheKeyComponents, CacheStats, ITTSCache, } from "./cache.js";
 export { generateCacheKey, generateHashedCacheKey, hashText, MemoryCache, } from "./cache.js";
 export type { ITTSServerProvider, TTSServerConfig, } from "./provider.js";
 export { BaseTTSProvider } from "./provider.js";
-export { adjustSpeechMarksForRate, estimateSpeechMarks, filterSpeechMarksByType, getSpeechMarkAtTime, getSpeechMarksStats, mergeSpeechMarks, validateSpeechMarks, } from "./speech-marks.js";
+export { resolveTTSErrorCodeForHttpStatus } from "./http-error-mapping.js";
+export { adjustSpeechMarksForRate, estimateSpeechMarks, filterSpeechMarksByType, getSpeechMarkAtTime, getSpeechMarksStats, mergeSpeechMarks, normalizeSpeechMarks, validateSpeechMarks, } from "./speech-marks.js";
+export { resolveSpeedRateBucket, type SpeedRateBucket, } from "./speed-rate.js";
 export type { GetVoicesOptions, ServerProviderCapabilities, SpeechMark, StandardTTSParameters, SynthesizeMetadata, SynthesizeRequest, SynthesizeResponse, TTSProviderExtensions, Voice, VoiceFeatures, } from "./types.js";
 export { TTSError, TTSErrorCode } from "./types.js";

package/dist/index.js

@@ -4,6 +4,8 @@
  */
 export { generateCacheKey, generateHashedCacheKey, hashText, MemoryCache, } from "./cache.js";
 export { BaseTTSProvider } from "./provider.js";
+export { resolveTTSErrorCodeForHttpStatus } from "./http-error-mapping.js";
 // Export speech marks utilities
-export { adjustSpeechMarksForRate, estimateSpeechMarks, filterSpeechMarksByType, getSpeechMarkAtTime, getSpeechMarksStats, mergeSpeechMarks, validateSpeechMarks, } from "./speech-marks.js";
+export { adjustSpeechMarksForRate, estimateSpeechMarks, filterSpeechMarksByType, getSpeechMarkAtTime, getSpeechMarksStats, mergeSpeechMarks, normalizeSpeechMarks, validateSpeechMarks, } from "./speech-marks.js";
+export { resolveSpeedRateBucket, } from "./speed-rate.js";
 export { TTSError, TTSErrorCode } from "./types.js";

package/dist/provider.d.ts

@@ -120,6 +120,47 @@ export declare abstract class BaseTTSProvider implements ITTSServerProvider {
      * @throws {TTSError} If provider not initialized
      */
     protected ensureInitialized(): void;
+    /**
+     * The SSML elements every provider recognises.
+     *
+     * Vendor extensions are not here: `<amazon:*>` and `<aws-*>` mean nothing to
+     * Google, and a provider that sniffs for tags it cannot synthesize would send
+     * markup to an engine expecting plain text.
+     */
+    private static readonly STANDARD_SSML_TAGS;
+    /**
+     * Whether the text is SSML rather than plain text, which decides how it is
+     * handed to the engine.
+     *
+     * A sniff rather than a parse: callers hand over authored strings that may or
+     * may not be marked up, and the engines themselves take the distinction as a
+     * flag. `extraTags` carries a provider's own vocabulary — Polly's
+     * `<amazon:effect>` among them.
+     */
+    protected detectSSML(text: string, extraTags?: string[]): boolean;
+    /** Escape special XML characters so plain text is safe to embed in SSML. */
+    protected escapeSSML(text: string): string;
+    /**
+     * Build an SSML `<prosody>` attribute string from a request's `rate` /
+     * `pitch`, or `""` if neither differs from its default. `rate` is the
+     * standard 0.25–4.0 speed multiplier, mapped straight to `rate` as a
+     * percentage. `pitch` follows this repo's existing 0–2 multiplier
+     * convention (the TTS settings UI's `normalizePitch`, matching the Web
+     * Speech API default of 1.0), converted to SSML's relative percentage
+     * form: a 1.2 multiplier is `pitch="+20%"`.
+     */
+    protected buildProsodyAttrs(request: SynthesizeRequest): string;
+    /**
+     * Wrap plain text in an SSML `<prosody>` envelope so a request's `rate`
+     * / `pitch` actually reaches the engine instead of being silently
+     * dropped. Already-SSML input (per `detectSSML`) is returned unchanged:
+     * injecting `<prosody>` into markup the caller authored themselves would
+     * require parsing it, which no provider here does.
+     */
+    protected applyProsody(text: string, request: SynthesizeRequest, extraSsmlTags?: string[]): {
+        text: string;
+        isSsml: boolean;
+    };
     /**
      * Validate synthesis request
      * @throws {TTSError} If request is invalid

package/dist/provider.js

@@ -22,6 +22,84 @@ export class BaseTTSProvider {
             throw new Error(`Provider ${this.providerId} not initialized`);
         }
     }
+    /**
+     * The SSML elements every provider recognises.
+     *
+     * Vendor extensions are not here: `<amazon:*>` and `<aws-*>` mean nothing to
+     * Google, and a provider that sniffs for tags it cannot synthesize would send
+     * markup to an engine expecting plain text.
+     */
+    static STANDARD_SSML_TAGS = [
+        "<speak",
+        "<prosody",
+        "<emphasis",
+        "<break",
+        "<phoneme",
+        "<say-as",
+        "<mark",
+    ];
+    /**
+     * Whether the text is SSML rather than plain text, which decides how it is
+     * handed to the engine.
+     *
+     * A sniff rather than a parse: callers hand over authored strings that may or
+     * may not be marked up, and the engines themselves take the distinction as a
+     * flag. `extraTags` carries a provider's own vocabulary — Polly's
+     * `<amazon:effect>` among them.
+     */
+    detectSSML(text, extraTags = []) {
+        const tags = [...BaseTTSProvider.STANDARD_SSML_TAGS, ...extraTags];
+        return tags.some((tag) => text.includes(tag));
+    }
+    /** Escape special XML characters so plain text is safe to embed in SSML. */
+    escapeSSML(text) {
+        return text
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;")
+            .replace(/'/g, "&apos;");
+    }
+    /**
+     * Build an SSML `<prosody>` attribute string from a request's `rate` /
+     * `pitch`, or `""` if neither differs from its default. `rate` is the
+     * standard 0.25–4.0 speed multiplier, mapped straight to `rate` as a
+     * percentage. `pitch` follows this repo's existing 0–2 multiplier
+     * convention (the TTS settings UI's `normalizePitch`, matching the Web
+     * Speech API default of 1.0), converted to SSML's relative percentage
+     * form: a 1.2 multiplier is `pitch="+20%"`.
+     */
+    buildProsodyAttrs(request) {
+        const attrs = [];
+        if (typeof request.rate === "number" && request.rate !== 1) {
+            attrs.push(`rate="${Math.round(request.rate * 100)}%"`);
+        }
+        if (typeof request.pitch === "number" && request.pitch !== 1) {
+            const percent = Math.round((request.pitch - 1) * 100);
+            attrs.push(`pitch="${percent >= 0 ? "+" : ""}${percent}%"`);
+        }
+        return attrs.join(" ");
+    }
+    /**
+     * Wrap plain text in an SSML `<prosody>` envelope so a request's `rate`
+     * / `pitch` actually reaches the engine instead of being silently
+     * dropped. Already-SSML input (per `detectSSML`) is returned unchanged:
+     * injecting `<prosody>` into markup the caller authored themselves would
+     * require parsing it, which no provider here does.
+     */
+    applyProsody(text, request, extraSsmlTags = []) {
+        if (this.detectSSML(text, extraSsmlTags)) {
+            return { text, isSsml: true };
+        }
+        const prosodyAttrs = this.buildProsodyAttrs(request);
+        if (!prosodyAttrs) {
+            return { text, isSsml: false };
+        }
+        return {
+            text: `<speak><prosody ${prosodyAttrs}>${this.escapeSSML(text)}</prosody></speak>`,
+            isSsml: true,
+        };
+    }
     /**
      * Validate synthesis request
      * @throws {TTSError} If request is invalid

package/dist/speech-marks.d.ts

@@ -3,6 +3,16 @@
  * @module @pie-players/tts-server-core
  */
 import type { SpeechMark } from "./types.js";
+/**
+ * Parse and correct a provider's JSONL word-mark response against the text
+ * that was actually requested: normalizes second-vs-millisecond time units,
+ * rebases offsets that drifted from the request text (a provider quirk seen
+ * in production), and clamps ranges to the request text's bounds.
+ *
+ * Shared by every provider/transport that speaks this wire shape so the
+ * correction is applied once rather than reimplemented per caller.
+ */
+export declare function normalizeSpeechMarks(raw: string, requestText: string): SpeechMark[];
 /**
  * Estimate speech marks for text when provider doesn't support them
  *

package/dist/speech-marks.js

@@ -2,6 +2,137 @@
  * Speech marks utilities
  * @module @pie-players/tts-server-core
  */
+const asFiniteNumber = (value) => {
+    const next = Number(value);
+    return Number.isFinite(next) ? next : null;
+};
+const sortWordMarks = (marks) => [...marks].sort((left, right) => {
+    if (left.time !== right.time)
+        return left.time - right.time;
+    if (left.start !== right.start)
+        return left.start - right.start;
+    return left.end - right.end;
+});
+/**
+ * Parse a provider's JSONL word-mark wire format: one `{time, type, start,
+ * end, value}` object per line. Rows missing a numeric `time` are dropped —
+ * that anchor is load-bearing for the timing correction below — but rows
+ * missing `start`/`end` still surface (estimated from the previous mark's
+ * end) rather than being lost outright.
+ */
+const parseWordMarksJsonl = (raw) => {
+    const marks = [];
+    let fallbackIndex = 0;
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.type && parsed.type !== "word")
+                continue;
+            const time = asFiniteNumber(parsed.time);
+            if (time === null)
+                continue;
+            const value = typeof parsed.value === "string" ? parsed.value : "";
+            const start = asFiniteNumber(parsed.start) ?? fallbackIndex;
+            const end = asFiniteNumber(parsed.end) ?? start + Math.max(1, value.length);
+            fallbackIndex = Math.max(end + 1, fallbackIndex);
+            marks.push({ time, type: "word", start, end, value });
+        }
+        catch {
+            // Ignore malformed JSONL rows while preserving valid marks.
+        }
+    }
+    return sortWordMarks(marks);
+};
+const normalizeMarkTimeUnits = (marks) => {
+    if (marks.length < 2)
+        return marks;
+    const times = marks.map((mark) => mark.time).filter((time) => time >= 0);
+    const maxTime = times.length ? Math.max(...times) : 0;
+    const deltas = [];
+    for (let index = 1; index < times.length; index += 1) {
+        const delta = times[index] - times[index - 1];
+        if (delta > 0 && Number.isFinite(delta))
+            deltas.push(delta);
+    }
+    const medianDelta = deltas.length > 0
+        ? [...deltas].sort((a, b) => a - b)[Math.floor(deltas.length / 2)]
+        : 0;
+    const shapeSuggestsSeconds = (maxTime > 0 && maxTime < 100 && marks.length > 3) ||
+        (medianDelta > 0 && medianDelta < 10);
+    if (!shapeSuggestsSeconds)
+        return marks;
+    return marks.map((mark) => ({ ...mark, time: mark.time * 1000 }));
+};
+const estimateOffsetShift = (marks, requestText) => {
+    if (!marks.length || !requestText.length)
+        return 0;
+    const textLower = requestText.toLowerCase();
+    const candidates = [];
+    let cursor = 0;
+    for (const mark of marks) {
+        const token = mark.value.trim().toLowerCase();
+        if (!token)
+            continue;
+        const found = textLower.indexOf(token, cursor);
+        if (found < 0)
+            continue;
+        const delta = mark.start - found;
+        if (delta >= 0)
+            candidates.push(delta);
+        cursor = found + token.length;
+        if (candidates.length >= 8)
+            break;
+    }
+    if (candidates.length > 0) {
+        const ordered = [...candidates].sort((a, b) => a - b);
+        return ordered[Math.floor(ordered.length / 2)];
+    }
+    return Math.max(0, Math.floor(marks[0].start));
+};
+const rebaseOffsetsToRequestText = (marks, requestText) => {
+    if (!marks.length || !requestText.length)
+        return marks;
+    const textLength = requestText.length;
+    const maxEnd = Math.max(...marks.map((mark) => mark.end));
+    if (maxEnd <= textLength + 2)
+        return marks;
+    const shift = estimateOffsetShift(marks, requestText);
+    if (shift <= 0)
+        return marks;
+    return marks.map((mark) => ({
+        ...mark,
+        start: mark.start - shift,
+        end: mark.end - shift,
+    }));
+};
+const clampMarkRanges = (marks, requestText) => {
+    if (!requestText.length)
+        return marks;
+    const textLength = requestText.length;
+    return sortWordMarks(marks.map((mark) => {
+        const start = Math.max(0, Math.min(textLength, Math.floor(mark.start)));
+        const end = Math.max(start + 1, Math.min(textLength, Math.floor(mark.end)));
+        return { ...mark, start, end };
+    }));
+};
+/**
+ * Parse and correct a provider's JSONL word-mark response against the text
+ * that was actually requested: normalizes second-vs-millisecond time units,
+ * rebases offsets that drifted from the request text (a provider quirk seen
+ * in production), and clamps ranges to the request text's bounds.
+ *
+ * Shared by every provider/transport that speaks this wire shape so the
+ * correction is applied once rather than reimplemented per caller.
+ */
+export function normalizeSpeechMarks(raw, requestText) {
+    const parsed = parseWordMarksJsonl(raw);
+    const withTimes = normalizeMarkTimeUnits(parsed);
+    const rebased = rebaseOffsetsToRequestText(withTimes, requestText);
+    return clampMarkRanges(rebased, requestText);
+}
 /**
  * Estimate speech marks for text when provider doesn't support them
  *

package/dist/speed-rate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Speed-rate bucketing utility
+ * @module @pie-players/tts-server-core
+ */
+export type SpeedRateBucket = "slow" | "medium" | "fast";
+/**
+ * Bucket a numeric rate multiplier into the three-value vocabulary some
+ * providers (SchoolCity, and backends modeled on it) accept instead of a
+ * continuous rate. `0.95` / `1.5` is a deliberate tolerance band around the
+ * `1.0` default rather than a strict `<1` / `>1` split, so small rate
+ * perturbations near normal speed still read as `fallback` instead of
+ * immediately flipping to `slow`/`fast`.
+ */
+export declare function resolveSpeedRateBucket(rate: number | undefined, fallback?: SpeedRateBucket): SpeedRateBucket;

package/dist/speed-rate.js

@@ -0,0 +1,22 @@
+/**
+ * Speed-rate bucketing utility
+ * @module @pie-players/tts-server-core
+ */
+/**
+ * Bucket a numeric rate multiplier into the three-value vocabulary some
+ * providers (SchoolCity, and backends modeled on it) accept instead of a
+ * continuous rate. `0.95` / `1.5` is a deliberate tolerance band around the
+ * `1.0` default rather than a strict `<1` / `>1` split, so small rate
+ * perturbations near normal speed still read as `fallback` instead of
+ * immediately flipping to `slow`/`fast`.
+ */
+export function resolveSpeedRateBucket(rate, fallback = "medium") {
+    const value = Number(rate ?? 1);
+    if (!Number.isFinite(value))
+        return fallback;
+    if (value <= 0.95)
+        return "slow";
+    if (value >= 1.5)
+        return "fast";
+    return fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/tts-server-core",
-	"version": "0.3.66",
+	"version": "0.3.68",
 	"author": "PIE Framework",
 	"repository": {
 		"type": "git",