@pie-players/tts-server-core 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc

package/README.md

@@ -0,0 +1,154 @@
+# @pie-players/tts-server-core
+
+Core types, interfaces, and utilities for server-side Text-to-Speech (TTS) providers.
+
+## Overview
+
+This package provides the foundation for building server-side TTS providers that return audio with precise word-level timing metadata (speech marks) for synchronized highlighting.
+
+## Features
+
+- **Provider Interface** - Standard interface for all TTS providers
+- **Speech Marks** - Unified format for word-level timing across providers
+- **Caching** - Interface and utilities for caching synthesis results
+- **Type Safety** - Full TypeScript support with comprehensive types
+- **Utilities** - Helper functions for speech marks manipulation
+
+## Installation
+
+```bash
+npm install @pie-players/tts-server-core
+```
+
+## Usage
+
+### Implementing a Provider
+
+```typescript
+import { BaseTTSProvider, type SynthesizeRequest, type SynthesizeResponse } from '@pie-players/tts-server-core';
+
+export class MyTTSProvider extends BaseTTSProvider {
+  readonly providerId = 'my-tts';
+  readonly providerName = 'My TTS Service';
+  readonly version = '1.0.0';
+
+  async initialize(config: TTSServerConfig): Promise<void> {
+    this.config = config;
+    this.initialized = true;
+  }
+
+  async synthesize(request: SynthesizeRequest): Promise<SynthesizeResponse> {
+    this.ensureInitialized();
+
+    // Your synthesis logic here
+    const audio = await this.callTTSAPI(request.text);
+    const speechMarks = await this.getSpeechMarks(request.text);
+
+    return {
+      audio,
+      contentType: 'audio/mpeg',
+      speechMarks,
+      metadata: {
+        providerId: this.providerId,
+        voice: request.voice || 'default',
+        duration: 0,
+        charCount: request.text.length,
+        cached: false,
+      },
+    };
+  }
+
+  // ... implement other required methods
+}
+```
+
+### Using Speech Marks Utilities
+
+```typescript
+import { estimateSpeechMarks, adjustSpeechMarksForRate } from '@pie-players/tts-server-core';
+
+// Generate estimated marks when provider doesn't support them
+const marks = estimateSpeechMarks('Hello world');
+
+// Adjust timing for different speech rates
+const fasterMarks = adjustSpeechMarksForRate(marks, 1.5);
+```
+
+### Using Cache
+
+```typescript
+import { MemoryCache, generateHashedCacheKey } from '@pie-players/tts-server-core';
+
+const cache = new MemoryCache();
+
+// Generate cache key
+const cacheKey = await generateHashedCacheKey({
+  providerId: 'my-tts',
+  text: 'Hello world',
+  voice: 'default',
+});
+
+// Check cache
+const cached = await cache.get(cacheKey);
+if (cached) {
+  return cached;
+}
+
+// Store in cache (24 hour TTL)
+await cache.set(cacheKey, result, 86400);
+```
+
+## API Reference
+
+### Types
+
+- `SpeechMark` - Word timing information
+- `SynthesizeRequest` - Synthesis request parameters
+- `SynthesizeResponse` - Synthesis result with audio and marks
+- `Voice` - Voice definition
+- `ServerProviderCapabilities` - Provider feature flags
+
+### Interfaces
+
+- `ITTSServerProvider` - Provider interface
+- `ITTSCache` - Cache interface
+
+### Classes
+
+- `BaseTTSProvider` - Abstract base class for providers
+- `MemoryCache` - In-memory cache implementation
+- `TTSError` - Structured error class
+
+### Functions
+
+- `estimateSpeechMarks()` - Generate estimated timing
+- `adjustSpeechMarksForRate()` - Adjust for speech rate
+- `validateSpeechMarks()` - Validate marks
+- `generateCacheKey()` - Create cache key
+- `hashText()` - SHA-256 hash for cache keys
+
+## Speech Marks Format
+
+All providers return speech marks in this unified format:
+
+```typescript
+interface SpeechMark {
+  time: number;      // Milliseconds from audio start
+  type: 'word' | 'sentence' | 'ssml';
+  start: number;     // Character index (inclusive)
+  end: number;       // Character index (exclusive)
+  value: string;     // The word text
+}
+```
+
+Example:
+```json
+[
+  { "time": 0, "type": "word", "start": 0, "end": 5, "value": "Hello" },
+  { "time": 340, "type": "word", "start": 6, "end": 11, "value": "world" }
+]
+```
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Caching interface for TTS results
+ * @module @pie-players/tts-server-core
+ */
+import type { SynthesizeResponse } from "./types.js";
+/**
+ * Cache key components for TTS synthesis
+ */
+export interface CacheKeyComponents {
+    /** Provider identifier */
+    providerId: string;
+    /** Text to synthesize */
+    text: string;
+    /** Voice ID */
+    voice: string;
+    /** Language code */
+    language?: string;
+    /** Speech rate */
+    rate?: number;
+    /** Audio format */
+    format?: string;
+}
+/**
+ * Cache interface for TTS providers
+ */
+export interface ITTSCache {
+    /**
+     * Get cached synthesis result
+     *
+     * @param key - Cache key
+     * @returns Cached result or null if not found
+     */
+    get(key: string): Promise<SynthesizeResponse | null>;
+    /**
+     * Store synthesis result in cache
+     *
+     * @param key - Cache key
+     * @param value - Synthesis response to cache
+     * @param ttl - Time to live in seconds (optional)
+     */
+    set(key: string, value: SynthesizeResponse, ttl?: number): Promise<void>;
+    /**
+     * Check if key exists in cache
+     *
+     * @param key - Cache key
+     * @returns True if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete cached result
+     *
+     * @param key - Cache key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cached results
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats?(): Promise<CacheStats>;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+    /** Hit rate (0.0 to 1.0) */
+    hitRate: number;
+    /** Number of keys in cache */
+    keyCount: number;
+    /** Total size in bytes (if available) */
+    sizeBytes?: number;
+}
+/**
+ * Generate cache key from components
+ *
+ * @param components - Cache key components
+ * @returns Cache key string
+ */
+export declare function generateCacheKey(components: CacheKeyComponents): string;
+/**
+ * Generate SHA-256 hash for cache key
+ * Useful for creating shorter keys from long text
+ *
+ * @param text - Text to hash
+ * @returns Hex string hash
+ */
+export declare function hashText(text: string): Promise<string>;
+/**
+ * Generate short cache key using hash
+ *
+ * @param components - Cache key components
+ * @returns Promise resolving to cache key
+ */
+export declare function generateHashedCacheKey(components: CacheKeyComponents): Promise<string>;
+/**
+ * In-memory cache implementation
+ * Simple LRU cache for development/testing
+ */
+export declare class MemoryCache implements ITTSCache {
+    private cache;
+    private hits;
+    private misses;
+    private maxSize;
+    constructor(maxSize?: number);
+    get(key: string): Promise<SynthesizeResponse | null>;
+    set(key: string, value: SynthesizeResponse, ttl?: number): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    getStats(): Promise<CacheStats>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IAEnB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IAEb,eAAe;IACf,KAAK,EAAE,MAAM,CAAC;IAEd,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,mBAAmB;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAErD;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IAEb,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IAEf,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAwBvE;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO5D;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC3C,UAAU,EAAE,kBAAkB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED;;;GAGG;AACH,qBAAa,WAAY,YAAW,SAAS;IAC5C,OAAO,CAAC,KAAK,CAGT;IACJ,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,SAAM;IAInB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAwBpD,GAAG,CACR,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,kBAAkB,EACzB,GAAG,SAAQ,GACT,OAAO,CAAC,IAAI,CAAC;IAgBV,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAalC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;CASrC"}

package/dist/cache.js

@@ -0,0 +1,136 @@
+/**
+ * Caching interface for TTS results
+ * @module @pie-players/tts-server-core
+ */
+/**
+ * Generate cache key from components
+ *
+ * @param components - Cache key components
+ * @returns Cache key string
+ */
+export function generateCacheKey(components) {
+    const { providerId, text, voice, language = "", rate = 1.0, format = "mp3", } = components;
+    // Create deterministic key from components
+    const keyParts = [
+        "tts",
+        providerId,
+        voice,
+        language,
+        rate.toFixed(2),
+        format,
+        text,
+    ];
+    // Use simple concatenation with delimiter
+    // In production, consider using a hash function for shorter keys
+    return keyParts.join(":");
+}
+/**
+ * Generate SHA-256 hash for cache key
+ * Useful for creating shorter keys from long text
+ *
+ * @param text - Text to hash
+ * @returns Hex string hash
+ */
+export async function hashText(text) {
+    // Use Web Crypto API (available in modern Node.js and browsers)
+    const encoder = new TextEncoder();
+    const data = encoder.encode(text);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Generate short cache key using hash
+ *
+ * @param components - Cache key components
+ * @returns Promise resolving to cache key
+ */
+export async function generateHashedCacheKey(components) {
+    const { providerId, text, voice, language = "", rate = 1.0, format = "mp3", } = components;
+    // Hash the text to keep key length reasonable
+    const textHash = await hashText(text);
+    const keyParts = [
+        "tts",
+        providerId,
+        voice,
+        language,
+        rate.toFixed(2),
+        format,
+        textHash,
+    ];
+    return keyParts.join(":");
+}
+/**
+ * In-memory cache implementation
+ * Simple LRU cache for development/testing
+ */
+export class MemoryCache {
+    cache = new Map();
+    hits = 0;
+    misses = 0;
+    maxSize;
+    constructor(maxSize = 100) {
+        this.maxSize = maxSize;
+    }
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.misses++;
+            return null;
+        }
+        // Check expiration
+        if (Date.now() > entry.expires) {
+            this.cache.delete(key);
+            this.misses++;
+            return null;
+        }
+        this.hits++;
+        // Update metadata to mark as served from cache
+        const result = { ...entry.value };
+        result.metadata = { ...result.metadata, cached: true };
+        return result;
+    }
+    async set(key, value, ttl = 86400) {
+        // Enforce max size (simple LRU)
+        if (this.cache.size >= this.maxSize) {
+            // Delete oldest entry (first key)
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, {
+            value,
+            expires: Date.now() + ttl * 1000,
+        });
+    }
+    async has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        // Check expiration
+        if (Date.now() > entry.expires) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    async delete(key) {
+        this.cache.delete(key);
+    }
+    async clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+    }
+    async getStats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: total > 0 ? this.hits / total : 0,
+            keyCount: this.cache.size,
+        };
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Core types and interfaces for server-side TTS providers
+ * @module @pie-players/tts-server-core
+ */
+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 type { GetVoicesOptions, ServerProviderCapabilities, SpeechMark, StandardTTSParameters, SynthesizeMetadata, SynthesizeRequest, SynthesizeResponse, TTSProviderExtensions, Voice, VoiceFeatures, } from "./types.js";
+export { TTSError, TTSErrorCode } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACX,kBAAkB,EAClB,UAAU,EACV,SAAS,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,gBAAgB,EAChB,sBAAsB,EACtB,QAAQ,EACR,WAAW,GACX,MAAM,YAAY,CAAC;AAGpB,YAAY,EACX,kBAAkB,EAClB,eAAe,GACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EACN,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACX,gBAAgB,EAChB,0BAA0B,EAC1B,UAAU,EACV,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,EACL,aAAa,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Core types and interfaces for server-side TTS providers
+ * @module @pie-players/tts-server-core
+ */
+export { generateCacheKey, generateHashedCacheKey, hashText, MemoryCache, } from "./cache.js";
+export { BaseTTSProvider } from "./provider.js";
+// Export speech marks utilities
+export { adjustSpeechMarksForRate, estimateSpeechMarks, filterSpeechMarksByType, getSpeechMarkAtTime, getSpeechMarksStats, mergeSpeechMarks, validateSpeechMarks, } from "./speech-marks.js";
+export { TTSError, TTSErrorCode } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EACN,gBAAgB,EAChB,sBAAsB,EACtB,QAAQ,EACR,WAAW,GACX,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,gCAAgC;AAChC,OAAO,EACN,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAc3B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Server-side TTS Provider interface
+ * @module @pie-players/tts-server-core
+ */
+import type { GetVoicesOptions, ServerProviderCapabilities, SynthesizeRequest, SynthesizeResponse, Voice } from "./types.js";
+/**
+ * Base configuration for TTS providers
+ */
+export interface TTSServerConfig {
+    /** Provider-specific configuration */
+    [key: string]: unknown;
+}
+/**
+ * Server-side TTS Provider interface
+ *
+ * All server-side TTS providers must implement this interface.
+ * Providers handle synthesis requests and return audio with speech marks.
+ *
+ * ## Initialization Performance
+ *
+ * The `initialize()` method MUST be fast and lightweight:
+ * - Should only validate config and create API clients
+ * - MUST NOT fetch voices or make expensive API calls
+ * - MUST NOT perform test synthesis requests
+ *
+ * Use `getVoices()` explicitly when voice discovery is needed (e.g., in demo/admin UIs).
+ * Runtime synthesis should work with hardcoded voice IDs without querying available voices.
+ *
+ * @example Fast initialization (runtime)
+ * ```typescript
+ * const provider = new PollyServerProvider();
+ * await provider.initialize({ region: 'us-east-1', defaultVoice: 'Joanna' });
+ * // Ready to synthesize immediately - no voices query
+ * await provider.synthesize({ text: 'Hello', voice: 'Joanna' });
+ * ```
+ *
+ * @example Explicit voice discovery (admin/demo UIs)
+ * ```typescript
+ * const provider = new PollyServerProvider();
+ * await provider.initialize({ region: 'us-east-1' });
+ * const voices = await provider.getVoices(); // Explicit, separate call
+ * ```
+ */
+export interface ITTSServerProvider {
+    /**
+     * Unique provider identifier (e.g., 'aws-polly', 'google-cloud-tts')
+     */
+    readonly providerId: string;
+    /**
+     * Human-readable provider name
+     */
+    readonly providerName: string;
+    /**
+     * Provider version
+     */
+    readonly version: string;
+    /**
+     * Initialize the provider with configuration.
+     *
+     * MUST be fast and lightweight - only validates config and creates clients.
+     * MUST NOT fetch voices or make expensive API calls during initialization.
+     *
+     * @param config - Provider-specific configuration
+     * @throws {TTSError} If initialization fails
+     * @performance Should complete in <100ms
+     */
+    initialize(config: TTSServerConfig): Promise<void>;
+    /**
+     * Synthesize speech from text
+     *
+     * @param request - Synthesis request parameters
+     * @returns Audio data and speech marks
+     * @throws {TTSError} If synthesis fails
+     */
+    synthesize(request: SynthesizeRequest): Promise<SynthesizeResponse>;
+    /**
+     * Get available voices (explicit, secondary query).
+     *
+     * This is an EXPLICIT operation for voice discovery in demo/admin UIs.
+     * NOT called during initialization - call separately when needed.
+     *
+     * @param options - Optional filters for voices
+     * @returns List of available voices
+     * @throws {TTSError} If voice listing fails
+     * @note May take 200-500ms depending on provider
+     */
+    getVoices(options?: GetVoicesOptions): Promise<Voice[]>;
+    /**
+     * Get provider capabilities (synchronous, fast).
+     *
+     * Returns static capability information without API calls.
+     *
+     * @returns Provider feature support
+     * @performance Should complete in <1ms (synchronous)
+     */
+    getCapabilities(): ServerProviderCapabilities;
+    /**
+     * Clean up provider resources
+     * Called when provider is no longer needed
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * Abstract base class for TTS providers
+ * Provides common functionality and helpers
+ */
+export declare abstract class BaseTTSProvider implements ITTSServerProvider {
+    abstract readonly providerId: string;
+    abstract readonly providerName: string;
+    abstract readonly version: string;
+    protected config: TTSServerConfig;
+    protected initialized: boolean;
+    abstract initialize(config: TTSServerConfig): Promise<void>;
+    abstract synthesize(request: SynthesizeRequest): Promise<SynthesizeResponse>;
+    abstract getVoices(options?: GetVoicesOptions): Promise<Voice[]>;
+    abstract getCapabilities(): ServerProviderCapabilities;
+    destroy(): Promise<void>;
+    /**
+     * Ensure provider is initialized before operations
+     * @throws {TTSError} If provider not initialized
+     */
+    protected ensureInitialized(): void;
+    /**
+     * Validate synthesis request
+     * @throws {TTSError} If request is invalid
+     */
+    protected validateRequest(request: SynthesizeRequest, capabilities: ServerProviderCapabilities): void;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACX,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,sCAAsC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,kBAAkB;IAClC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;OASG;IACH,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAEpE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAExD;;;;;;;OAOG;IACH,eAAe,IAAI,0BAA0B,CAAC;IAE9C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;GAGG;AACH,8BAAsB,eAAgB,YAAW,kBAAkB;IAClE,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAElC,SAAS,CAAC,MAAM,EAAE,eAAe,CAAM;IACvC,SAAS,CAAC,WAAW,UAAS;IAE9B,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3D,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAC5E,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAChE,QAAQ,CAAC,eAAe,IAAI,0BAA0B;IAEhD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;;OAGG;IACH,SAAS,CAAC,iBAAiB,IAAI,IAAI;IAMnC;;;OAGG;IACH,SAAS,CAAC,eAAe,CACxB,OAAO,EAAE,iBAAiB,EAC1B,YAAY,EAAE,0BAA0B,GACtC,IAAI;CAyCP"}

package/dist/provider.js

@@ -0,0 +1,54 @@
+/**
+ * Server-side TTS Provider interface
+ * @module @pie-players/tts-server-core
+ */
+/**
+ * Abstract base class for TTS providers
+ * Provides common functionality and helpers
+ */
+export class BaseTTSProvider {
+    config = {};
+    initialized = false;
+    async destroy() {
+        this.initialized = false;
+        this.config = {};
+    }
+    /**
+     * Ensure provider is initialized before operations
+     * @throws {TTSError} If provider not initialized
+     */
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error(`Provider ${this.providerId} not initialized`);
+        }
+    }
+    /**
+     * Validate synthesis request
+     * @throws {TTSError} If request is invalid
+     */
+    validateRequest(request, capabilities) {
+        if (!request.text || request.text.trim().length === 0) {
+            throw new Error("Text is required and cannot be empty");
+        }
+        if (request.text.length > capabilities.standard.maxTextLength) {
+            throw new Error(`Text length (${request.text.length}) exceeds maximum (${capabilities.standard.maxTextLength})`);
+        }
+        if (request.format &&
+            !capabilities.extensions.supportedFormats.includes(request.format)) {
+            throw new Error(`Format '${request.format}' not supported. Supported formats: ${capabilities.extensions.supportedFormats.join(", ")}`);
+        }
+        if (request.rate !== undefined &&
+            (request.rate < 0.25 || request.rate > 4.0)) {
+            throw new Error("Rate must be between 0.25 and 4.0");
+        }
+        if (request.pitch !== undefined &&
+            (request.pitch < -20 || request.pitch > 20)) {
+            throw new Error("Pitch must be between -20 and 20");
+        }
+        if (request.volume !== undefined &&
+            (request.volume < 0 || request.volume > 1)) {
+            throw new Error("Volume must be between 0 and 1");
+        }
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoHH;;;GAGG;AACH,MAAM,OAAgB,eAAe;IAK1B,MAAM,GAAoB,EAAE,CAAC;IAC7B,WAAW,GAAG,KAAK,CAAC;IAO9B,KAAK,CAAC,OAAO;QACZ,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IAClB,CAAC;IAED;;;OAGG;IACO,iBAAiB;QAC1B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,UAAU,kBAAkB,CAAC,CAAC;QAChE,CAAC;IACF,CAAC;IAED;;;OAGG;IACO,eAAe,CACxB,OAA0B,EAC1B,YAAwC;QAExC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;YAC/D,MAAM,IAAI,KAAK,CACd,gBAAgB,OAAO,CAAC,IAAI,CAAC,MAAM,sBAAsB,YAAY,CAAC,QAAQ,CAAC,aAAa,GAAG,CAC/F,CAAC;QACH,CAAC;QAED,IACC,OAAO,CAAC,MAAM;YACd,CAAC,YAAY,CAAC,UAAU,CAAC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EACjE,CAAC;YACF,MAAM,IAAI,KAAK,CACd,WAAW,OAAO,CAAC,MAAM,uCAAuC,YAAY,CAAC,UAAU,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACrH,CAAC;QACH,CAAC;QAED,IACC,OAAO,CAAC,IAAI,KAAK,SAAS;YAC1B,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC,EAC1C,CAAC;YACF,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACtD,CAAC;QAED,IACC,OAAO,CAAC,KAAK,KAAK,SAAS;YAC3B,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC,EAC1C,CAAC;YACF,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACrD,CAAC;QAED,IACC,OAAO,CAAC,MAAM,KAAK,SAAS;YAC5B,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,EACzC,CAAC;YACF,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACnD,CAAC;IACF,CAAC;CACD"}