@pie-players/tts-server-core 0.1.0 → 0.1.3

package/package.json

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

package/.turbo/turbo-build.log

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

package/src/cache.ts

@@ -1,273 +0,0 @@
-/**
- * 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

@@ -1,50 +0,0 @@
-/**
- * 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

@@ -1,200 +0,0 @@
-/**
- * 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");
-		}
-	}
-}

package/src/speech-marks.ts

@@ -1,243 +0,0 @@
-/**
- * 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 function estimateSpeechMarks(
-	text: string,
-	avgWordsPerMinute = 150,
-): SpeechMark[] {
-	const words = text.split(/\s+/).filter((w) => w.length > 0);
-	const msPerWord = (60 * 1000) / avgWordsPerMinute;
-
-	const marks: SpeechMark[] = [];
-	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: SpeechMark[],
-	rate: number,
-): SpeechMark[] {
-	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: SpeechMark[]): string[] {
-	const errors: string[] = [];
-
-	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: SpeechMark[]): SpeechMark[] {
-	if (marks.length <= 1) {
-		return marks;
-	}
-
-	// Sort by start position
-	const sorted = [...marks].sort((a, b) => a.start - b.start);
-	const merged: SpeechMark[] = [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: SpeechMark[],
-	type: "word" | "sentence" | "ssml",
-): SpeechMark[] {
-	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: SpeechMark[],
-	time: number,
-): SpeechMark | null {
-	// Binary search for efficiency
-	let left = 0;
-	let right = marks.length - 1;
-	let closest: SpeechMark | null = 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: SpeechMark[]) {
-	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,
-	};
-}

package/src/types.ts

@@ -1,425 +0,0 @@
-/**
- * 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 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 class TTSError extends Error {
-	constructor(
-		public code: TTSErrorCode,
-		message: string,
-		public details?: Record<string, unknown>,
-		public providerId?: string,
-	) {
-		super(message);
-		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,
-			},
-		};
-	}
-}

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "ES2022",
-		"module": "ESNext",
-		"lib": ["ES2022"],
-		"moduleResolution": "bundler",
-		"outDir": "./dist",
-		"rootDir": "./src",
-		"declaration": true,
-		"declarationMap": true,
-		"sourceMap": true,
-		"strict": true,
-		"esModuleInterop": true,
-		"skipLibCheck": true,
-		"forceConsistentCasingInFileNames": true,
-		"resolveJsonModule": true
-	},
-	"include": ["src/**/*"],
-	"exclude": ["node_modules", "dist", "**/*.test.ts"]
-}