@pie-players/tts-server-core 0.1.0

package/dist/types.js

@@ -0,0 +1,49 @@
+/**
+ * Core types for server-side TTS providers
+ * @module @pie-players/tts-server-core
+ */
+/**
+ * TTS error codes
+ */
+export var TTSErrorCode;
+(function (TTSErrorCode) {
+    TTSErrorCode["INVALID_REQUEST"] = "INVALID_REQUEST";
+    TTSErrorCode["INVALID_VOICE"] = "INVALID_VOICE";
+    TTSErrorCode["INVALID_PROVIDER"] = "INVALID_PROVIDER";
+    TTSErrorCode["TEXT_TOO_LONG"] = "TEXT_TOO_LONG";
+    TTSErrorCode["PROVIDER_ERROR"] = "PROVIDER_ERROR";
+    TTSErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    TTSErrorCode["AUTHENTICATION_ERROR"] = "AUTHENTICATION_ERROR";
+    TTSErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+    TTSErrorCode["INITIALIZATION_ERROR"] = "INITIALIZATION_ERROR";
+})(TTSErrorCode || (TTSErrorCode = {}));
+/**
+ * TTS error with structured information
+ */
+export class TTSError extends Error {
+    code;
+    details;
+    providerId;
+    constructor(code, message, details, providerId) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.providerId = providerId;
+        this.name = "TTSError";
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TTSError);
+        }
+    }
+    toJSON() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                details: this.details,
+                provider: this.providerId,
+            },
+        };
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyXH;;GAEG;AACH,MAAM,CAAN,IAAY,YAUX;AAVD,WAAY,YAAY;IACvB,mDAAmC,CAAA;IACnC,+CAA+B,CAAA;IAC/B,qDAAqC,CAAA;IACrC,+CAA+B,CAAA;IAC/B,iDAAiC,CAAA;IACjC,+CAA+B,CAAA;IAC/B,6DAA6C,CAAA;IAC7C,2DAA2C,CAAA;IAC3C,6DAA6C,CAAA;AAC9C,CAAC,EAVW,YAAY,KAAZ,YAAY,QAUvB;AAED;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAE1B;IAEA;IACA;IAJR,YACQ,IAAkB,EACzB,OAAe,EACR,OAAiC,EACjC,UAAmB;QAE1B,KAAK,CAAC,OAAO,CAAC,CAAC;QALR,SAAI,GAAJ,IAAI,CAAc;QAElB,YAAO,GAAP,OAAO,CAA0B;QACjC,eAAU,GAAV,UAAU,CAAS;QAG1B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QAEvB,oEAAoE;QACpE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC7B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC;IACF,CAAC;IAED,MAAM;QACL,OAAO;YACN,KAAK,EAAE;gBACN,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,QAAQ,EAAE,IAAI,CAAC,UAAU;aACzB;SACD,CAAC;IACH,CAAC;CACD"}

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@pie-players/tts-server-core",
+	"version": "0.1.0",
+	"description": "Core interfaces and types for server-side TTS providers",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"test": "vitest",
+		"test:coverage": "vitest --coverage"
+	},
+	"keywords": [
+		"tts",
+		"text-to-speech",
+		"speech-synthesis",
+		"server-side",
+		"speech-marks"
+	],
+	"author": "PIE Framework",
+	"license": "MIT",
+	"devDependencies": {
+		"typescript": "^5.3.3",
+		"vitest": "^1.0.4"
+	}
+}

package/src/cache.ts

@@ -0,0 +1,273 @@
+/**
+ * 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 function generateCacheKey(components: CacheKeyComponents): string {
+	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: string): Promise<string> {
+	// 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: CacheKeyComponents,
+): Promise<string> {
+	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 implements ITTSCache {
+	private cache = new Map<
+		string,
+		{ value: SynthesizeResponse; expires: number }
+	>();
+	private hits = 0;
+	private misses = 0;
+	private maxSize: number;
+
+	constructor(maxSize = 100) {
+		this.maxSize = maxSize;
+	}
+
+	async get(key: string): Promise<SynthesizeResponse | null> {
+		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: string,
+		value: SynthesizeResponse,
+		ttl = 86400,
+	): Promise<void> {
+		// 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: string): Promise<boolean> {
+		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: string): Promise<void> {
+		this.cache.delete(key);
+	}
+
+	async clear(): Promise<void> {
+		this.cache.clear();
+		this.hits = 0;
+		this.misses = 0;
+	}
+
+	async getStats(): Promise<CacheStats> {
+		const total = this.hits + this.misses;
+		return {
+			hits: this.hits,
+			misses: this.misses,
+			hitRate: total > 0 ? this.hits / total : 0,
+			keyCount: this.cache.size,
+		};
+	}
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Core types and interfaces for server-side TTS providers
+ * @module @pie-players/tts-server-core
+ */
+
+// Export cache interfaces
+export type {
+	CacheKeyComponents,
+	CacheStats,
+	ITTSCache,
+} from "./cache.js";
+export {
+	generateCacheKey,
+	generateHashedCacheKey,
+	hashText,
+	MemoryCache,
+} from "./cache.js";
+
+// Export provider interfaces
+export type {
+	ITTSServerProvider,
+	TTSServerConfig,
+} from "./provider.js";
+
+export { BaseTTSProvider } from "./provider.js";
+
+// Export speech marks utilities
+export {
+	adjustSpeechMarksForRate,
+	estimateSpeechMarks,
+	filterSpeechMarksByType,
+	getSpeechMarkAtTime,
+	getSpeechMarksStats,
+	mergeSpeechMarks,
+	validateSpeechMarks,
+} from "./speech-marks.js";
+// Export types
+export type {
+	GetVoicesOptions,
+	ServerProviderCapabilities,
+	SpeechMark,
+	StandardTTSParameters,
+	SynthesizeMetadata,
+	SynthesizeRequest,
+	SynthesizeResponse,
+	TTSProviderExtensions,
+	Voice,
+	VoiceFeatures,
+} from "./types.js";
+export { TTSError, TTSErrorCode } from "./types.js";

package/src/provider.ts

@@ -0,0 +1,200 @@
+/**
+ * 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 abstract class BaseTTSProvider implements ITTSServerProvider {
+	abstract readonly providerId: string;
+	abstract readonly providerName: string;
+	abstract readonly version: string;
+
+	protected config: TTSServerConfig = {};
+	protected initialized = false;
+
+	abstract initialize(config: TTSServerConfig): Promise<void>;
+	abstract synthesize(request: SynthesizeRequest): Promise<SynthesizeResponse>;
+	abstract getVoices(options?: GetVoicesOptions): Promise<Voice[]>;
+	abstract getCapabilities(): ServerProviderCapabilities;
+
+	async destroy(): Promise<void> {
+		this.initialized = false;
+		this.config = {};
+	}
+
+	/**
+	 * Ensure provider is initialized before operations
+	 * @throws {TTSError} If provider not initialized
+	 */
+	protected ensureInitialized(): void {
+		if (!this.initialized) {
+			throw new Error(`Provider ${this.providerId} not initialized`);
+		}
+	}
+
+	/**
+	 * Validate synthesis request
+	 * @throws {TTSError} If request is invalid
+	 */
+	protected validateRequest(
+		request: SynthesizeRequest,
+		capabilities: ServerProviderCapabilities,
+	): void {
+		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");
+		}
+	}
+}