@pie-players/tts-server-core 0.1.0

package/dist/speech-marks.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Speech marks utilities
+ * @module @pie-players/tts-server-core
+ */
+import type { SpeechMark } from "./types.js";
+/**
+ * Estimate speech marks for text when provider doesn't support them
+ *
+ * Uses average speaking rate to estimate word timing.
+ * Not as accurate as provider-generated marks, but better than nothing.
+ *
+ * @param text - Text to generate marks for
+ * @param avgWordsPerMinute - Average speaking rate (default 150)
+ * @returns Estimated speech marks
+ */
+export declare function estimateSpeechMarks(text: string, avgWordsPerMinute?: number): SpeechMark[];
+/**
+ * Adjust speech marks timing for different speaking rates
+ *
+ * @param marks - Original speech marks
+ * @param rate - Speech rate multiplier (0.25 to 4.0)
+ * @returns Adjusted speech marks
+ */
+export declare function adjustSpeechMarksForRate(marks: SpeechMark[], rate: number): SpeechMark[];
+/**
+ * Validate speech marks
+ * Ensures marks are properly ordered and have valid data
+ *
+ * @param marks - Speech marks to validate
+ * @returns Validation errors (empty array if valid)
+ */
+export declare function validateSpeechMarks(marks: SpeechMark[]): string[];
+/**
+ * Merge overlapping or adjacent speech marks
+ * Useful when combining marks from multiple sources
+ *
+ * @param marks - Speech marks to merge
+ * @returns Merged speech marks
+ */
+export declare function mergeSpeechMarks(marks: SpeechMark[]): SpeechMark[];
+/**
+ * Filter speech marks by type
+ *
+ * @param marks - Speech marks to filter
+ * @param type - Type to filter by
+ * @returns Filtered speech marks
+ */
+export declare function filterSpeechMarksByType(marks: SpeechMark[], type: "word" | "sentence" | "ssml"): SpeechMark[];
+/**
+ * Get speech mark at specific time
+ *
+ * @param marks - Speech marks
+ * @param time - Time in milliseconds
+ * @returns Speech mark at time, or null if none found
+ */
+export declare function getSpeechMarkAtTime(marks: SpeechMark[], time: number): SpeechMark | null;
+/**
+ * Calculate statistics for speech marks
+ *
+ * @param marks - Speech marks
+ * @returns Statistics about the marks
+ */
+export declare function getSpeechMarksStats(marks: SpeechMark[]): {
+    count: number;
+    totalDuration: number;
+    avgWordDuration: number;
+    wordsPerMinute: number;
+    wordCount?: undefined;
+} | {
+    count: number;
+    wordCount: number;
+    totalDuration: number;
+    avgWordDuration: number;
+    wordsPerMinute: number;
+};
+//# sourceMappingURL=speech-marks.d.ts.map

package/dist/speech-marks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech-marks.d.ts","sourceRoot":"","sources":["../src/speech-marks.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,EACZ,iBAAiB,SAAM,GACrB,UAAU,EAAE,CA8Bd;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,KAAK,EAAE,UAAU,EAAE,EACnB,IAAI,EAAE,MAAM,GACV,UAAU,EAAE,CASd;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,CAoCjE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CA0BlE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,UAAU,EAAE,EACnB,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAChC,UAAU,EAAE,CAEd;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,UAAU,EAAE,EACnB,IAAI,EAAE,MAAM,GACV,UAAU,GAAG,IAAI,CAmCnB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE;;;;;;;;;;;;EAsBtD"}

package/dist/speech-marks.js

@@ -0,0 +1,194 @@
+/**
+ * Speech marks utilities
+ * @module @pie-players/tts-server-core
+ */
+/**
+ * Estimate speech marks for text when provider doesn't support them
+ *
+ * Uses average speaking rate to estimate word timing.
+ * Not as accurate as provider-generated marks, but better than nothing.
+ *
+ * @param text - Text to generate marks for
+ * @param avgWordsPerMinute - Average speaking rate (default 150)
+ * @returns Estimated speech marks
+ */
+export function estimateSpeechMarks(text, avgWordsPerMinute = 150) {
+    const words = text.split(/\s+/).filter((w) => w.length > 0);
+    const msPerWord = (60 * 1000) / avgWordsPerMinute;
+    const marks = [];
+    let charIndex = 0;
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        // Find word position in original text (preserves spacing)
+        const wordStart = text.indexOf(word, charIndex);
+        if (wordStart === -1) {
+            // Word not found (shouldn't happen), skip
+            charIndex += word.length + 1;
+            continue;
+        }
+        marks.push({
+            time: Math.round(i * msPerWord),
+            type: "word",
+            start: wordStart,
+            end: wordStart + word.length,
+            value: word,
+        });
+        charIndex = wordStart + word.length;
+    }
+    return marks;
+}
+/**
+ * Adjust speech marks timing for different speaking rates
+ *
+ * @param marks - Original speech marks
+ * @param rate - Speech rate multiplier (0.25 to 4.0)
+ * @returns Adjusted speech marks
+ */
+export function adjustSpeechMarksForRate(marks, rate) {
+    if (rate === 1.0) {
+        return marks; // No adjustment needed
+    }
+    return marks.map((mark) => ({
+        ...mark,
+        time: Math.round(mark.time / rate),
+    }));
+}
+/**
+ * Validate speech marks
+ * Ensures marks are properly ordered and have valid data
+ *
+ * @param marks - Speech marks to validate
+ * @returns Validation errors (empty array if valid)
+ */
+export function validateSpeechMarks(marks) {
+    const errors = [];
+    if (!marks || marks.length === 0) {
+        return errors; // Empty is valid
+    }
+    for (let i = 0; i < marks.length; i++) {
+        const mark = marks[i];
+        // Check required fields
+        if (typeof mark.time !== "number" || mark.time < 0) {
+            errors.push(`Mark ${i}: invalid time (${mark.time})`);
+        }
+        if (typeof mark.start !== "number" || mark.start < 0) {
+            errors.push(`Mark ${i}: invalid start (${mark.start})`);
+        }
+        if (typeof mark.end !== "number" || mark.end <= mark.start) {
+            errors.push(`Mark ${i}: invalid end (${mark.end}, start: ${mark.start})`);
+        }
+        if (!mark.value || typeof mark.value !== "string") {
+            errors.push(`Mark ${i}: invalid value`);
+        }
+        // Check ordering (time should be monotonically increasing)
+        if (i > 0 && mark.time < marks[i - 1].time) {
+            errors.push(`Mark ${i}: time (${mark.time}) is less than previous mark (${marks[i - 1].time})`);
+        }
+    }
+    return errors;
+}
+/**
+ * Merge overlapping or adjacent speech marks
+ * Useful when combining marks from multiple sources
+ *
+ * @param marks - Speech marks to merge
+ * @returns Merged speech marks
+ */
+export function mergeSpeechMarks(marks) {
+    if (marks.length <= 1) {
+        return marks;
+    }
+    // Sort by start position
+    const sorted = [...marks].sort((a, b) => a.start - b.start);
+    const merged = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        const current = sorted[i];
+        const previous = merged[merged.length - 1];
+        // Check if marks overlap or are adjacent
+        if (current.start <= previous.end) {
+            // Merge with previous mark
+            previous.end = Math.max(previous.end, current.end);
+            previous.value = previous.value + " " + current.value;
+            previous.time = Math.min(previous.time, current.time); // Use earlier time
+        }
+        else {
+            // No overlap, add as new mark
+            merged.push(current);
+        }
+    }
+    return merged;
+}
+/**
+ * Filter speech marks by type
+ *
+ * @param marks - Speech marks to filter
+ * @param type - Type to filter by
+ * @returns Filtered speech marks
+ */
+export function filterSpeechMarksByType(marks, type) {
+    return marks.filter((mark) => mark.type === type);
+}
+/**
+ * Get speech mark at specific time
+ *
+ * @param marks - Speech marks
+ * @param time - Time in milliseconds
+ * @returns Speech mark at time, or null if none found
+ */
+export function getSpeechMarkAtTime(marks, time) {
+    // Binary search for efficiency
+    let left = 0;
+    let right = marks.length - 1;
+    let closest = null;
+    while (left <= right) {
+        const mid = Math.floor((left + right) / 2);
+        const mark = marks[mid];
+        if (mark.time === time) {
+            return mark;
+        }
+        // Track closest mark
+        if (!closest ||
+            Math.abs(mark.time - time) < Math.abs(closest.time - time)) {
+            closest = mark;
+        }
+        if (mark.time < time) {
+            left = mid + 1;
+        }
+        else {
+            right = mid - 1;
+        }
+    }
+    // Return closest mark if within reasonable threshold (500ms)
+    if (closest && Math.abs(closest.time - time) <= 500) {
+        return closest;
+    }
+    return null;
+}
+/**
+ * Calculate statistics for speech marks
+ *
+ * @param marks - Speech marks
+ * @returns Statistics about the marks
+ */
+export function getSpeechMarksStats(marks) {
+    if (marks.length === 0) {
+        return {
+            count: 0,
+            totalDuration: 0,
+            avgWordDuration: 0,
+            wordsPerMinute: 0,
+        };
+    }
+    const wordMarks = filterSpeechMarksByType(marks, "word");
+    const totalDuration = marks[marks.length - 1].time;
+    const avgWordDuration = totalDuration / wordMarks.length;
+    const wordsPerMinute = (wordMarks.length / totalDuration) * 60 * 1000;
+    return {
+        count: marks.length,
+        wordCount: wordMarks.length,
+        totalDuration,
+        avgWordDuration,
+        wordsPerMinute,
+    };
+}
+//# sourceMappingURL=speech-marks.js.map

package/dist/speech-marks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech-marks.js","sourceRoot":"","sources":["../src/speech-marks.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,360 @@
+/**
+ * Core types for server-side TTS providers
+ * @module @pie-players/tts-server-core
+ */
+/**
+ * Speech mark representing a timing event in synthesized speech
+ * Unified format across all TTS providers
+ */
+export interface SpeechMark {
+    /** Milliseconds from start of audio */
+    time: number;
+    /** Type of speech mark */
+    type: "word" | "sentence" | "ssml";
+    /** Character index in original text (inclusive) */
+    start: number;
+    /** Character index in original text (exclusive) */
+    end: number;
+    /** The actual word or text */
+    value: string;
+}
+/**
+ * Standard TTS parameters based on W3C Web Speech API and SSML specifications.
+ *
+ * These parameters are widely supported across TTS providers (browsers, cloud services)
+ * and follow established standards:
+ * - W3C Web Speech API (SpeechSynthesisUtterance)
+ * - W3C SSML 1.1 specification
+ * - BCP47 language tags (RFC 5646)
+ *
+ * @see https://w3c.github.io/speech-api/
+ * @see https://www.w3.org/TR/speech-synthesis/
+ */
+export interface StandardTTSParameters {
+    /**
+     * Text to synthesize (plain text or SSML markup)
+     *
+     * @standard W3C Web Speech API
+     */
+    text: string;
+    /**
+     * Voice identifier (provider-specific voice names)
+     * Examples: "Joanna" (Polly), "en-US-Standard-A" (Google), browser voice names
+     *
+     * @standard W3C Web Speech API (concept)
+     * @note Voice names are provider-specific but the concept is standard
+     */
+    voice?: string;
+    /**
+     * Language code using BCP47 format (e.g., 'en-US', 'es-ES', 'fr-FR')
+     *
+     * @standard BCP47 (RFC 5646), W3C Web Speech API
+     * @see https://tools.ietf.org/html/rfc5646
+     */
+    language?: string;
+    /**
+     * Speech rate (speed multiplier)
+     * - Range: 0.25 to 4.0
+     * - Default: 1.0 (normal speed)
+     * - 0.5 = half speed, 2.0 = double speed
+     *
+     * @standard W3C Web Speech API, SSML <prosody rate>
+     */
+    rate?: number;
+    /**
+     * Pitch adjustment
+     * - Range: -20 to +20 semitones (or 0 to 2 as multiplier depending on provider)
+     * - Default: 0 (or 1.0 as multiplier)
+     * - Negative values = lower pitch, positive = higher pitch
+     *
+     * @standard W3C Web Speech API, SSML <prosody pitch>
+     * @note Some providers use semitones (-20 to +20), others use multipliers (0 to 2)
+     */
+    pitch?: number;
+    /**
+     * Volume level
+     * - Range: 0.0 to 1.0
+     * - Default: 1.0 (full volume)
+     * - 0.0 = silent, 0.5 = half volume
+     *
+     * @standard W3C Web Speech API, SSML <prosody volume>
+     */
+    volume?: number;
+}
+/**
+ * Provider-specific extensions for advanced TTS control.
+ *
+ * These parameters are NOT part of W3C standards and have varying support
+ * across providers. Use with caution for portability.
+ *
+ * Common extensions include:
+ * - Audio format selection (mp3, wav, ogg)
+ * - Sample rate control
+ * - Engine selection (neural vs standard)
+ * - Regional endpoints
+ * - Speech marks / word timing
+ *
+ * @note Providers may ignore unsupported extensions silently or throw errors
+ */
+export interface TTSProviderExtensions {
+    /**
+     * Audio format for output
+     *
+     * @extension Common across providers but values vary
+     * @support AWS Polly (mp3, ogg, pcm), Google Cloud TTS (mp3, wav, ogg), Azure (mp3, wav, ogg)
+     */
+    format?: "mp3" | "wav" | "ogg" | "pcm";
+    /**
+     * Sample rate in Hz (e.g., 8000, 16000, 22050, 24000)
+     *
+     * @extension Common audio parameter
+     * @note Higher sample rates = better quality but larger file sizes
+     */
+    sampleRate?: number;
+    /**
+     * Request word-level timing data (speech marks)
+     *
+     * @extension Provider-specific but common pattern
+     * @support AWS Polly (SpeechMarks), Google Cloud TTS (timepoints), Azure (word boundaries)
+     * @default true
+     */
+    includeSpeechMarks?: boolean;
+    /**
+     * Provider-specific options (extensibility point)
+     *
+     * Examples:
+     * - AWS Polly: { engine: 'neural' | 'standard', lexiconNames: string[] }
+     * - Google Cloud TTS: { audioEncoding: string, effectsProfileId: string[] }
+     * - Azure: { voiceType: string, stylesList: string[] }
+     *
+     * @extension Arbitrary provider-specific data
+     */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * Complete synthesis request combining standard parameters and extensions.
+ *
+ * This interface provides the full set of options for text-to-speech synthesis,
+ * clearly separating W3C-standard parameters from provider-specific extensions.
+ *
+ * @example Basic usage (portable across providers)
+ * ```typescript
+ * const request: SynthesizeRequest = {
+ *   text: "Hello world",
+ *   voice: "Joanna",
+ *   rate: 1.0,
+ *   language: "en-US"
+ * };
+ * ```
+ *
+ * @example Advanced usage with extensions (provider-specific)
+ * ```typescript
+ * const request: SynthesizeRequest = {
+ *   text: "Hello world",
+ *   voice: "Joanna",
+ *   rate: 1.0,
+ *   // Extensions - may not be portable
+ *   format: 'mp3',
+ *   sampleRate: 24000,
+ *   includeSpeechMarks: true,
+ *   providerOptions: {
+ *     engine: 'neural'  // AWS Polly specific
+ *   }
+ * };
+ * ```
+ */
+export interface SynthesizeRequest extends StandardTTSParameters, TTSProviderExtensions {
+}
+/**
+ * Response from speech synthesis
+ */
+export interface SynthesizeResponse {
+    /** Audio data (Buffer for server, base64 string for client) */
+    audio: Buffer | string;
+    /** MIME type of audio (e.g., 'audio/mpeg') */
+    contentType: string;
+    /** Speech marks for word-level timing */
+    speechMarks: SpeechMark[];
+    /** Metadata about the synthesis */
+    metadata: SynthesizeMetadata;
+}
+/**
+ * Metadata about synthesized speech
+ */
+export interface SynthesizeMetadata {
+    /** Provider that generated the audio */
+    providerId: string;
+    /** Voice ID used */
+    voice: string;
+    /** Audio duration in seconds */
+    duration: number;
+    /** Character count of input text */
+    charCount: number;
+    /** Whether response was served from cache */
+    cached: boolean;
+    /** ISO timestamp of synthesis */
+    timestamp?: string;
+}
+/**
+ * Voice definition
+ */
+export interface Voice {
+    /** Unique voice identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Language name (e.g., "English", "Spanish") */
+    language: string;
+    /** Language code (e.g., "en-US", "es-ES") */
+    languageCode: string;
+    /** Gender of voice */
+    gender?: "male" | "female" | "neutral";
+    /** Voice quality level */
+    quality: "standard" | "premium" | "neural";
+    /** Supported features */
+    supportedFeatures: VoiceFeatures;
+    /** Provider-specific metadata */
+    providerMetadata?: Record<string, unknown>;
+}
+/**
+ * Voice feature flags
+ */
+export interface VoiceFeatures {
+    /** Supports SSML markup */
+    ssml: boolean;
+    /** Supports emotional expression */
+    emotions: boolean;
+    /** Supports speaking styles */
+    styles: boolean;
+}
+/**
+ * Options for listing voices
+ */
+export interface GetVoicesOptions {
+    /** Filter by language code */
+    language?: string;
+    /** Filter by quality level */
+    quality?: "standard" | "premium" | "neural";
+    /** Filter by gender */
+    gender?: "male" | "female" | "neutral";
+}
+/**
+ * Provider capabilities split into standard features and extensions.
+ *
+ * This interface helps consumers understand what features are universally
+ * supported (W3C standards) vs provider-specific extensions.
+ */
+export interface ServerProviderCapabilities {
+    /**
+     * Standard W3C features that should be widely supported
+     */
+    standard: {
+        /**
+         * Supports SSML markup (W3C SSML 1.1)
+         *
+         * @standard W3C SSML 1.1
+         * @support Most cloud TTS providers, limited browser support
+         */
+        supportsSSML: boolean;
+        /**
+         * Supports pitch control via rate parameter or SSML <prosody>
+         *
+         * @standard W3C Web Speech API, SSML <prosody pitch>
+         * @note May be via API parameter or SSML only
+         */
+        supportsPitch: boolean;
+        /**
+         * Supports rate (speed) control via rate parameter or SSML <prosody>
+         *
+         * @standard W3C Web Speech API, SSML <prosody rate>
+         */
+        supportsRate: boolean;
+        /**
+         * Supports volume control via volume parameter or SSML <prosody>
+         *
+         * @standard W3C Web Speech API, SSML <prosody volume>
+         * @note Often better handled client-side for server TTS
+         */
+        supportsVolume: boolean;
+        /**
+         * Supports multiple voices (voice selection)
+         *
+         * @standard W3C Web Speech API (concept)
+         */
+        supportsMultipleVoices: boolean;
+        /**
+         * Maximum text length in characters
+         *
+         * @note Varies by provider: Polly=3000, Google=5000, browser=~32k
+         */
+        maxTextLength: number;
+    };
+    /**
+     * Provider-specific extensions
+     */
+    extensions: {
+        /**
+         * Supports word-level timing data (speech marks)
+         *
+         * @extension Provider-specific but common
+         * @support AWS Polly ✅, Google Cloud TTS ✅, Azure TTS ✅, Browser ⚠️
+         * @note Format and precision vary by provider
+         */
+        supportsSpeechMarks: boolean;
+        /**
+         * Supported audio output formats
+         *
+         * @extension Common but not standardized
+         */
+        supportedFormats: ("mp3" | "wav" | "ogg" | "pcm")[];
+        /**
+         * Supports sample rate configuration
+         *
+         * @extension Common audio parameter
+         */
+        supportsSampleRate: boolean;
+        /**
+         * Provider-specific features (extensibility point)
+         *
+         * Examples:
+         * - AWS Polly: { engines: ['neural', 'standard'], lexicons: true }
+         * - Google Cloud TTS: { audioProfiles: true, voiceEffects: true }
+         * - Azure: { styles: true, emotions: true }
+         *
+         * @extension Arbitrary provider capabilities
+         */
+        providerSpecific?: Record<string, unknown>;
+    };
+}
+/**
+ * TTS error codes
+ */
+export declare enum TTSErrorCode {
+    INVALID_REQUEST = "INVALID_REQUEST",
+    INVALID_VOICE = "INVALID_VOICE",
+    INVALID_PROVIDER = "INVALID_PROVIDER",
+    TEXT_TOO_LONG = "TEXT_TOO_LONG",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    AUTHENTICATION_ERROR = "AUTHENTICATION_ERROR",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    INITIALIZATION_ERROR = "INITIALIZATION_ERROR"
+}
+/**
+ * TTS error with structured information
+ */
+export declare class TTSError extends Error {
+    code: TTSErrorCode;
+    details?: Record<string, unknown> | undefined;
+    providerId?: string | undefined;
+    constructor(code: TTSErrorCode, message: string, details?: Record<string, unknown> | undefined, providerId?: string | undefined);
+    toJSON(): {
+        error: {
+            code: TTSErrorCode;
+            message: string;
+            details: Record<string, unknown> | undefined;
+            provider: string | undefined;
+        };
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}