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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/tts-server-polly",
-	"version": "0.1.0",
+	"version": "0.1.3",
 	"description": "AWS Polly provider for server-side TTS with speech marks support",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -11,10 +11,13 @@
 			"import": "./dist/index.js"
 		}
 	},
+	"files": [
+		"dist"
+	],
 	"scripts": {
 		"build": "tsc",
 		"dev": "tsc --watch",
-		"test": "vitest",
+		"test": "vitest run --passWithNoTests",
 		"test:coverage": "vitest --coverage"
 	},
 	"keywords": [
@@ -28,7 +31,7 @@
 	"license": "MIT",
 	"dependencies": {
 		"@aws-sdk/client-polly": "^3.700.0",
-		"@pie-players/tts-server-core": "workspace:*"
+		"@pie-players/tts-server-core": "0.1.3"
 	},
 	"devDependencies": {
 		"typescript": "^5.3.3",

package/.turbo/turbo-build.log

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

package/examples/INTEGRATION-GUIDE.md

@@ -1,603 +0,0 @@
-# TTS Server API Integration Guide
-
-This guide shows how to integrate the server-side TTS with speech marks into your SvelteKit application.
-
-## Overview
-
-The integration has three parts:
-
-1. **Server-side packages** - Handle AWS Polly API calls
-2. **SvelteKit API routes** - Expose TTS endpoints
-3. **Client-side provider** - Call API from browser
-
-## Architecture
-
-```
-Browser (Client)
-    ↓
-ServerTTSProvider (@pie-players/tts-client-server)
-    ↓ HTTP POST
-SvelteKit API Route (/api/tts/synthesize/+server.ts)
-    ↓
-PollyServerProvider (@pie-players/tts-server-polly)
-    ↓
-AWS Polly API (audio + speech marks)
-```
-
-## Step 1: Install Packages
-
-```bash
-cd your-sveltekit-app
-
-# Install server-side packages
-bun add @pie-players/tts-server-core
-bun add @pie-players/tts-server-polly
-
-# Install client-side provider
-bun add @pie-players/tts-client-server
-```
-
-## Step 2: Configure Environment Variables
-
-Create or update `.env`:
-
-```bash
-# AWS Polly credentials
-AWS_REGION=us-east-1
-AWS_ACCESS_KEY_ID=your_access_key_id
-AWS_SECRET_ACCESS_KEY=your_secret_access_key
-
-# Optional: Redis for caching
-REDIS_URL=redis://localhost:6379
-```
-
-**Important:** Never commit `.env` to git. Add to `.gitignore`:
-
-```
-.env
-.env.local
-```
-
-## Step 3: Create SvelteKit API Routes
-
-### Create Directory Structure
-
-```bash
-mkdir -p src/routes/api/tts/synthesize
-mkdir -p src/routes/api/tts/voices
-```
-
-### Synthesize Endpoint
-
-Copy the example to: **`src/routes/api/tts/synthesize/+server.ts`**
-
-```typescript
-import { json, error } from '@sveltejs/kit';
-import type { RequestHandler } from './$types';
-import { PollyServerProvider } from '@pie-players/tts-server-polly';
-
-// Singleton provider instance
-let pollyProvider: PollyServerProvider | null = null;
-
-async function getPollyProvider(): Promise<PollyServerProvider> {
-  if (!pollyProvider) {
-    pollyProvider = new PollyServerProvider();
-    await pollyProvider.initialize({
-      region: process.env.AWS_REGION || 'us-east-1',
-      credentials: {
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      },
-      engine: 'neural',
-      defaultVoice: 'Joanna',
-    });
-  }
-  return pollyProvider;
-}
-
-export const POST: RequestHandler = async ({ request }) => {
-  try {
-    const body = await request.json();
-    const { text, voice, language, rate, includeSpeechMarks = true } = body;
-
-    if (!text || typeof text !== 'string') {
-      throw error(400, { message: 'Text is required' });
-    }
-
-    if (text.length > 3000) {
-      throw error(400, { message: 'Text too long (max 3000 characters)' });
-    }
-
-    const polly = await getPollyProvider();
-    const result = await polly.synthesize({
-      text,
-      voice: voice || 'Joanna',
-      language: language || 'en-US',
-      rate,
-      includeSpeechMarks,
-    });
-
-    return json({
-      audio: result.audio instanceof Buffer ? result.audio.toString('base64') : result.audio,
-      contentType: result.contentType,
-      speechMarks: result.speechMarks,
-      metadata: result.metadata,
-    });
-  } catch (err) {
-    console.error('[TTS API] Error:', err);
-    throw error(500, { message: err instanceof Error ? err.message : 'Synthesis failed' });
-  }
-};
-```
-
-### Voices Endpoint
-
-Copy the example to: **`src/routes/api/tts/voices/+server.ts`**
-
-```typescript
-import { json, error } from '@sveltejs/kit';
-import type { RequestHandler } from './$types';
-import { PollyServerProvider } from '@pie-players/tts-server-polly';
-
-// Use same singleton as synthesize route
-let pollyProvider: PollyServerProvider | null = null;
-
-async function getPollyProvider(): Promise<PollyServerProvider> {
-  if (!pollyProvider) {
-    pollyProvider = new PollyServerProvider();
-    await pollyProvider.initialize({
-      region: process.env.AWS_REGION || 'us-east-1',
-      credentials: {
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      },
-      engine: 'neural',
-    });
-  }
-  return pollyProvider;
-}
-
-export const GET: RequestHandler = async ({ url }) => {
-  try {
-    const language = url.searchParams.get('language') || undefined;
-    const gender = url.searchParams.get('gender') as 'male' | 'female' | 'neutral' | undefined;
-
-    const polly = await getPollyProvider();
-    const voices = await polly.getVoices({ language, gender });
-
-    return json({ voices });
-  } catch (err) {
-    console.error('[TTS API] Error:', err);
-    throw error(500, { message: err instanceof Error ? err.message : 'Failed to get voices' });
-  }
-};
-```
-
-## Step 4: Use in Client Code
-
-### Basic Usage
-
-```typescript
-import { ServerTTSProvider } from '@pie-players/tts-client-server';
-import { TTSService } from '@pie-players/pie-assessment-toolkit';
-
-// Initialize TTS service with server provider
-const provider = new ServerTTSProvider();
-const ttsService = new TTSService();
-
-await ttsService.initialize(provider, {
-  apiEndpoint: '/api/tts',
-  provider: 'polly',
-  voice: 'Joanna',
-  language: 'en-US',
-  rate: 1.0,
-});
-
-// Speak with word highlighting
-await ttsService.speak('Hello world, this is a test.', {
-  contentElement: document.getElementById('content'),
-});
-```
-
-### With Svelte Component
-
-```svelte
-<script lang="ts">
-  import { ServerTTSProvider } from '@pie-players/tts-client-server';
-  import { TTSService } from '@pie-players/pie-assessment-toolkit';
-  import { onMount } from 'svelte';
-
-  let ttsService: TTSService;
-  let contentElement: HTMLElement;
-
-  onMount(async () => {
-    const provider = new ServerTTSProvider();
-    ttsService = new TTSService();
-
-    await ttsService.initialize(provider, {
-      apiEndpoint: '/api/tts',
-      provider: 'polly',
-      voice: 'Joanna',
-    });
-  });
-
-  async function handleSpeak() {
-    await ttsService.speak('Hello world', {
-      contentElement,
-    });
-  }
-</script>
-
-<div bind:this={contentElement}>
-  <p>Hello world, this is a test of text to speech.</p>
-</div>
-
-<button on:click={handleSpeak}>Speak</button>
-```
-
-## Step 5: Add Redis Caching (Optional)
-
-### Install Redis
-
-```bash
-bun add ioredis
-```
-
-### Update API Route with Caching
-
-```typescript
-import { json, error } from '@sveltejs/kit';
-import type { RequestHandler } from './$types';
-import { PollyServerProvider } from '@pie-players/tts-server-polly';
-import { generateHashedCacheKey } from '@pie-players/tts-server-core';
-import Redis from 'ioredis';
-
-// Singleton instances
-let pollyProvider: PollyServerProvider | null = null;
-let redis: Redis | null = null;
-
-async function getRedis(): Promise<Redis> {
-  if (!redis && process.env.REDIS_URL) {
-    redis = new Redis(process.env.REDIS_URL);
-  }
-  return redis!;
-}
-
-async function getPollyProvider(): Promise<PollyServerProvider> {
-  if (!pollyProvider) {
-    pollyProvider = new PollyServerProvider();
-    await pollyProvider.initialize({
-      region: process.env.AWS_REGION || 'us-east-1',
-      credentials: {
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      },
-      engine: 'neural',
-    });
-  }
-  return pollyProvider;
-}
-
-export const POST: RequestHandler = async ({ request }) => {
-  try {
-    const body = await request.json();
-    const { text, voice = 'Joanna', language = 'en-US', rate = 1.0, includeSpeechMarks = true } = body;
-
-    if (!text || typeof text !== 'string') {
-      throw error(400, { message: 'Text is required' });
-    }
-
-    if (text.length > 3000) {
-      throw error(400, { message: 'Text too long (max 3000 characters)' });
-    }
-
-    // Generate cache key
-    const cacheKey = await generateHashedCacheKey({
-      providerId: 'aws-polly',
-      text,
-      voice,
-      language,
-      rate,
-      format: 'mp3',
-    });
-
-    // Check Redis cache
-    if (process.env.REDIS_URL) {
-      try {
-        const redisClient = await getRedis();
-        const cached = await redisClient.get(cacheKey);
-
-        if (cached) {
-          console.log('[TTS API] Cache hit:', cacheKey);
-          const result = JSON.parse(cached);
-          result.metadata.cached = true;
-          return json(result);
-        }
-      } catch (cacheError) {
-        console.warn('[TTS API] Cache read error:', cacheError);
-        // Continue without cache
-      }
-    }
-
-    // Synthesize with Polly
-    const polly = await getPollyProvider();
-    const result = await polly.synthesize({
-      text,
-      voice,
-      language,
-      rate,
-      includeSpeechMarks,
-    });
-
-    const response = {
-      audio: result.audio instanceof Buffer ? result.audio.toString('base64') : result.audio,
-      contentType: result.contentType,
-      speechMarks: result.speechMarks,
-      metadata: result.metadata,
-    };
-
-    // Cache result
-    if (process.env.REDIS_URL) {
-      try {
-        const redisClient = await getRedis();
-        await redisClient.setex(cacheKey, 24 * 60 * 60, JSON.stringify(response));
-        console.log('[TTS API] Cached result:', cacheKey);
-      } catch (cacheError) {
-        console.warn('[TTS API] Cache write error:', cacheError);
-        // Non-fatal, continue
-      }
-    }
-
-    return json(response);
-  } catch (err) {
-    console.error('[TTS API] Error:', err);
-    throw error(500, { message: err instanceof Error ? err.message : 'Synthesis failed' });
-  }
-};
-```
-
-## Step 6: Test the Integration
-
-### Test API Endpoints
-
-```bash
-# Test synthesize endpoint
-curl -X POST http://localhost:5173/api/tts/synthesize \
-  -H "Content-Type: application/json" \
-  -d '{"text": "Hello world", "voice": "Joanna"}'
-
-# Test voices endpoint
-curl http://localhost:5173/api/tts/voices
-```
-
-### Test in Browser
-
-```typescript
-// In browser console
-const response = await fetch('/api/tts/synthesize', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    text: 'Hello world, this is a test.',
-    voice: 'Joanna',
-  }),
-});
-
-const data = await response.json();
-console.log('Speech marks:', data.speechMarks);
-console.log('Metadata:', data.metadata);
-```
-
-## Redis Caching Benefits
-
-With Redis caching enabled:
-
-- **First request:** Full Polly API call (~300-500ms)
-- **Cached requests:** Redis retrieval (~10-20ms)
-- **Cost savings:** 80-90% reduction in Polly API calls
-- **TTL:** 24 hours (configurable)
-
-### Cache Key Format
-
-```
-tts:aws-polly:Joanna:en-US:1.00:mp3:<sha256-hash-of-text>
-```
-
-## Security Considerations
-
-### Credentials
-
-- ✅ AWS credentials stay on server (never exposed to browser)
-- ✅ Use IAM roles in production (no hardcoded credentials)
-- ✅ Use environment variables for configuration
-
-### Authentication (Optional)
-
-Add authentication middleware to protect API:
-
-```typescript
-// src/hooks.server.ts
-import type { Handle } from '@sveltejs/kit';
-
-export const handle: Handle = async ({ event, resolve }) => {
-  // Check if request is to TTS API
-  if (event.url.pathname.startsWith('/api/tts')) {
-    // Verify JWT token or API key
-    const authHeader = event.request.headers.get('Authorization');
-    if (!authHeader || !isValidToken(authHeader)) {
-      return new Response(JSON.stringify({ error: 'Unauthorized' }), {
-        status: 401,
-        headers: { 'Content-Type': 'application/json' },
-      });
-    }
-  }
-
-  return resolve(event);
-};
-```
-
-### Rate Limiting
-
-Add rate limiting to prevent abuse:
-
-```typescript
-import { rateLimit } from '$lib/rate-limiter';
-
-export const POST: RequestHandler = async ({ request, getClientAddress }) => {
-  // Check rate limit
-  const clientIP = getClientAddress();
-  const allowed = await rateLimit.check(clientIP, {
-    maxRequests: 60, // 60 requests
-    windowMs: 60000, // per minute
-  });
-
-  if (!allowed) {
-    throw error(429, { message: 'Rate limit exceeded' });
-  }
-
-  // ... rest of handler
-};
-```
-
-## Cost Optimization
-
-### AWS Polly Pricing
-
-- **Neural voices:** $16 per 1M characters
-- **Standard voices:** $4 per 1M characters
-
-### Example Costs
-
-**Scenario:** 1000 students taking an assessment
-
-- Average assessment: 5 passages × 500 words × 5 chars = 12,500 chars per student
-- Total: 12.5M characters
-- Cost without caching: $200 (neural) or $50 (standard)
-- Cost with 80% cache hit rate: $40 (neural) or $10 (standard)
-
-### Optimization Tips
-
-1. **Use Redis caching** - 24-hour TTL captures repeated content
-2. **Standard voices for development** - Switch to neural for production
-3. **Monitor usage** - Track API calls and cache hit rates
-4. **Pre-generate common content** - Cache frequently used passages
-
-## Troubleshooting
-
-### Error: "AWS credentials not found"
-
-Check environment variables are set:
-```bash
-echo $AWS_REGION
-echo $AWS_ACCESS_KEY_ID
-```
-
-### Error: "Text too long"
-
-AWS Polly limit is 3000 characters. Split longer text:
-
-```typescript
-function splitText(text: string, maxLength = 2500): string[] {
-  const sentences = text.split(/(?<=[.!?])\s+/);
-  const chunks: string[] = [];
-  let currentChunk = '';
-
-  for (const sentence of sentences) {
-    if (currentChunk.length + sentence.length > maxLength) {
-      chunks.push(currentChunk.trim());
-      currentChunk = sentence;
-    } else {
-      currentChunk += ' ' + sentence;
-    }
-  }
-
-  if (currentChunk.trim()) {
-    chunks.push(currentChunk.trim());
-  }
-
-  return chunks;
-}
-```
-
-### Error: "Speech marks empty"
-
-Check that:
-1. Speech marks are requested in API call
-2. Provider supports speech marks
-3. Text is not empty
-
-### Redis connection errors
-
-If Redis is unavailable, the API will work without caching. Check Redis:
-
-```bash
-redis-cli ping
-# Should return: PONG
-```
-
-## Production Deployment
-
-### Environment Setup
-
-```bash
-# Production environment variables
-export NODE_ENV=production
-export AWS_REGION=us-east-1
-export AWS_ACCESS_KEY_ID=xxx
-export AWS_SECRET_ACCESS_KEY=yyy
-export REDIS_URL=redis://your-redis-host:6379
-```
-
-### Docker Deployment
-
-```dockerfile
-FROM node:20-alpine
-WORKDIR /app
-COPY . .
-RUN npm ci --production
-RUN npm run build
-EXPOSE 3000
-CMD ["node", "build"]
-```
-
-### Health Check
-
-Add a health endpoint:
-
-```typescript
-// src/routes/api/health/+server.ts
-import { json } from '@sveltejs/kit';
-import type { RequestHandler } from './$types';
-
-export const GET: RequestHandler = async () => {
-  const health = {
-    status: 'ok',
-    timestamp: new Date().toISOString(),
-    services: {
-      polly: await checkPolly(),
-      redis: await checkRedis(),
-    },
-  };
-
-  return json(health);
-};
-```
-
-## Next Steps
-
-1. **Test in your app** - Create a demo page
-2. **Monitor usage** - Track API calls and costs
-3. **Add more providers** - Google Cloud TTS, ElevenLabs
-4. **Optimize caching** - Fine-tune TTL and eviction
-
-## Complete Example
-
-See the section-player demo for a complete working example:
-- `packages/section-player/demo.html` - Client-side usage
-- API routes would be added to a SvelteKit app
-
-## Support
-
-For issues or questions:
-- Check the [TTS Server API Architecture](../../../docs/tts-server-api-architecture.md)
-- See [TTS Highlighting Implementation Plan](../../../docs/tts-highlighting-implementation-plan.md)

package/examples/sveltekit/synthesize-server.ts

@@ -1,110 +0,0 @@
-/**
- * SvelteKit API route for TTS synthesis
- *
- * Copy this file to your SvelteKit app:
- * src/routes/api/tts/synthesize/+server.ts
- */
-
-import { generateHashedCacheKey } from "@pie-players/tts-server-core";
-import { PollyServerProvider } from "@pie-players/tts-server-polly";
-import { error, json } from "@sveltejs/kit";
-import type { RequestHandler } from "./$types";
-
-// Initialize Polly provider (singleton)
-let pollyProvider: PollyServerProvider | null = null;
-
-async function getPollyProvider(): Promise<PollyServerProvider> {
-	if (!pollyProvider) {
-		pollyProvider = new PollyServerProvider();
-		await pollyProvider.initialize({
-			region: process.env.AWS_REGION || "us-east-1",
-			credentials: {
-				accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-				secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-			},
-			engine: "neural",
-			defaultVoice: "Joanna",
-		});
-	}
-	return pollyProvider;
-}
-
-// Optional: Redis caching
-// import { createClient } from 'redis';
-// const redis = createClient({ url: process.env.REDIS_URL });
-// await redis.connect();
-
-export const POST: RequestHandler = async ({ request }) => {
-	try {
-		const body = await request.json();
-		const {
-			text,
-			provider = "polly",
-			voice,
-			language,
-			rate,
-			includeSpeechMarks = true,
-		} = body;
-
-		// Validate request
-		if (!text || typeof text !== "string") {
-			throw error(400, { message: "Text is required and must be a string" });
-		}
-
-		if (text.length > 3000) {
-			throw error(400, { message: "Text too long (max 3000 characters)" });
-		}
-
-		// Optional: Check Redis cache
-		// const cacheKey = await generateHashedCacheKey({
-		//   providerId: 'aws-polly',
-		//   text,
-		//   voice: voice || 'Joanna',
-		//   language: language || 'en-US',
-		//   rate: rate || 1.0,
-		//   format: 'mp3',
-		// });
-		//
-		// const cached = await redis.get(cacheKey);
-		// if (cached) {
-		//   console.log('[TTS API] Cache hit:', cacheKey);
-		//   return json(JSON.parse(cached));
-		// }
-
-		// Get Polly provider
-		const polly = await getPollyProvider();
-
-		// Synthesize speech
-		const result = await polly.synthesize({
-			text,
-			voice: voice || "Joanna",
-			language: language || "en-US",
-			rate,
-			includeSpeechMarks,
-		});
-
-		// Convert Buffer to base64 for JSON response
-		const response = {
-			audio:
-				result.audio instanceof Buffer
-					? result.audio.toString("base64")
-					: result.audio,
-			contentType: result.contentType,
-			speechMarks: result.speechMarks,
-			metadata: result.metadata,
-		};
-
-		// Optional: Cache result
-		// await redis.setex(cacheKey, 24 * 60 * 60, JSON.stringify(response));
-
-		return json(response);
-	} catch (err) {
-		console.error("[TTS API] Synthesis error:", err);
-
-		if (err instanceof Error) {
-			throw error(500, { message: err.message });
-		}
-
-		throw error(500, { message: "Internal server error" });
-	}
-};

package/examples/sveltekit/voices-server.ts

@@ -1,65 +0,0 @@
-/**
- * SvelteKit API route for listing TTS voices
- *
- * Copy this file to your SvelteKit app:
- * src/routes/api/tts/voices/+server.ts
- */
-
-import { PollyServerProvider } from "@pie-players/tts-server-polly";
-import { error, json } from "@sveltejs/kit";
-import type { RequestHandler } from "./$types";
-
-// Initialize Polly provider (singleton)
-let pollyProvider: PollyServerProvider | null = null;
-
-async function getPollyProvider(): Promise<PollyServerProvider> {
-	if (!pollyProvider) {
-		pollyProvider = new PollyServerProvider();
-		await pollyProvider.initialize({
-			region: process.env.AWS_REGION || "us-east-1",
-			credentials: {
-				accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-				secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-			},
-			engine: "neural",
-			defaultVoice: "Joanna",
-		});
-	}
-	return pollyProvider;
-}
-
-export const GET: RequestHandler = async ({ url }) => {
-	try {
-		const language = url.searchParams.get("language") || undefined;
-		const gender = url.searchParams.get("gender") as
-			| "male"
-			| "female"
-			| "neutral"
-			| undefined;
-		const quality = url.searchParams.get("quality") as
-			| "standard"
-			| "neural"
-			| "premium"
-			| undefined;
-
-		// Get Polly provider
-		const polly = await getPollyProvider();
-
-		// Get voices with filters
-		const voices = await polly.getVoices({
-			language,
-			gender,
-			quality,
-		});
-
-		return json({ voices });
-	} catch (err) {
-		console.error("[TTS API] Get voices error:", err);
-
-		if (err instanceof Error) {
-			throw error(500, { message: err.message });
-		}
-
-		throw error(500, { message: "Internal server error" });
-	}
-};

package/src/PollyServerProvider.ts

@@ -1,426 +0,0 @@
-/**
- * AWS Polly server-side TTS provider
- * @module @pie-players/tts-server-polly
- */
-
-import {
-	DescribeVoicesCommand,
-	type DescribeVoicesCommandInput,
-	Engine,
-	OutputFormat,
-	PollyClient,
-	SpeechMarkType,
-	SynthesizeSpeechCommand,
-	VoiceId,
-} from "@aws-sdk/client-polly";
-
-import {
-	BaseTTSProvider,
-	type GetVoicesOptions,
-	type ServerProviderCapabilities,
-	type SpeechMark,
-	type SynthesizeRequest,
-	type SynthesizeResponse,
-	TTSError,
-	TTSErrorCode,
-	type TTSServerConfig,
-	type Voice,
-} from "@pie-players/tts-server-core";
-
-/**
- * AWS Polly provider configuration.
- *
- * This extends the base TTSServerConfig with Polly-specific settings.
- * All fields marked with @extension are AWS-specific and not portable.
- */
-export interface PollyProviderConfig extends TTSServerConfig {
-	/**
-	 * AWS region (e.g., 'us-east-1', 'us-west-2', 'eu-west-1')
-	 *
-	 * @extension AWS-specific (region concept)
-	 * @required
-	 */
-	region: string;
-
-	/**
-	 * AWS credentials for API authentication
-	 *
-	 * @extension AWS-specific
-	 * @note In production, prefer IAM roles over hardcoded credentials
-	 * @see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials.html
-	 */
-	credentials?: {
-		accessKeyId: string;
-		secretAccessKey: string;
-		sessionToken?: string;
-	};
-
-	/**
-	 * Polly engine type: 'neural' (higher quality) or 'standard' (lower cost)
-	 *
-	 * @extension AWS Polly-specific
-	 * @default 'neural'
-	 * @note Neural: $16/1M chars, Standard: $4/1M chars
-	 */
-	engine?: "neural" | "standard";
-
-	/**
-	 * Default voice ID if not specified in synthesis requests
-	 *
-	 * @standard Voice selection is standard, but voice names are provider-specific
-	 * @default 'Joanna'
-	 * @see https://docs.aws.amazon.com/polly/latest/dg/voicelist.html
-	 */
-	defaultVoice?: string;
-}
-
-/**
- * AWS Polly Server Provider
- *
- * Provides high-quality neural text-to-speech with precise word-level timing
- * through AWS Polly speech marks.
- *
- * Features:
- * - Native speech marks support (millisecond precision)
- * - Neural and standard voices
- * - 25+ languages
- * - Full SSML support
- * - Parallel audio + speech marks requests
- */
-export class PollyServerProvider extends BaseTTSProvider {
-	readonly providerId = "aws-polly";
-	readonly providerName = "AWS Polly";
-	readonly version = "1.0.0";
-
-	private client!: PollyClient;
-	private engine: "neural" | "standard" = "neural";
-	private defaultVoice = "Joanna";
-
-	/**
-	 * Initialize the AWS Polly provider.
-	 *
-	 * This is FAST and lightweight - only validates config and creates the Polly client.
-	 * Does NOT fetch voices or make test API calls.
-	 *
-	 * @param config - Polly configuration with region and credentials
-	 * @performance Completes in ~10-50ms
-	 */
-	async initialize(config: PollyProviderConfig): Promise<void> {
-		if (!config.region) {
-			throw new TTSError(
-				TTSErrorCode.INITIALIZATION_ERROR,
-				"AWS region is required",
-				undefined,
-				this.providerId,
-			);
-		}
-
-		this.config = config;
-		this.engine = config.engine || "neural";
-		this.defaultVoice = config.defaultVoice || "Joanna";
-
-		try {
-			// Create Polly client (fast - no API calls)
-			this.client = new PollyClient({
-				region: config.region,
-				credentials: config.credentials,
-			});
-
-			this.initialized = true;
-			// NOTE: We do NOT call getVoices() here - that's an explicit secondary operation
-		} catch (error) {
-			throw new TTSError(
-				TTSErrorCode.INITIALIZATION_ERROR,
-				`Failed to initialize AWS Polly: ${error instanceof Error ? error.message : String(error)}`,
-				{ error },
-				this.providerId,
-			);
-		}
-	}
-
-	/**
-	 * Synthesize speech with AWS Polly
-	 */
-	async synthesize(request: SynthesizeRequest): Promise<SynthesizeResponse> {
-		this.ensureInitialized();
-
-		const capabilities = this.getCapabilities();
-		this.validateRequest(request, capabilities);
-
-		const voice = request.voice || this.defaultVoice;
-		const startTime = Date.now();
-
-		try {
-			// Make parallel requests for audio and speech marks
-			const [audioResponse, speechMarksResponse] = await Promise.all([
-				this.synthesizeAudio(request, voice),
-				request.includeSpeechMarks !== false
-					? this.synthesizeSpeechMarks(request, voice)
-					: Promise.resolve([]),
-			]);
-
-			const duration = (Date.now() - startTime) / 1000;
-
-			return {
-				audio: audioResponse.audio,
-				contentType: audioResponse.contentType,
-				speechMarks: speechMarksResponse,
-				metadata: {
-					providerId: this.providerId,
-					voice,
-					duration,
-					charCount: request.text.length,
-					cached: false,
-					timestamp: new Date().toISOString(),
-				},
-			};
-		} catch (error) {
-			throw new TTSError(
-				TTSErrorCode.PROVIDER_ERROR,
-				`AWS Polly synthesis failed: ${error instanceof Error ? error.message : String(error)}`,
-				{ error, request },
-				this.providerId,
-			);
-		}
-	}
-
-	/**
-	 * Synthesize audio stream
-	 */
-	private async synthesizeAudio(
-		request: SynthesizeRequest,
-		voice: string,
-	): Promise<{ audio: Buffer; contentType: string }> {
-		// Detect if text contains SSML tags
-		const isSsml =
-			request.text.includes("<speak") ||
-			request.text.includes("<emphasis") ||
-			request.text.includes("<break") ||
-			request.text.includes("<prosody") ||
-			request.text.includes("<phoneme") ||
-			request.text.includes("<amazon:") ||
-			request.text.includes("<aws-");
-
-		const textType = isSsml ? "ssml" : "text";
-
-		if (isSsml) {
-			console.log(
-				"[PollyServerProvider] Detected SSML content, using TextType: ssml",
-			);
-		}
-
-		const command = new SynthesizeSpeechCommand({
-			Engine: this.engine === "neural" ? Engine.NEURAL : Engine.STANDARD,
-			OutputFormat: OutputFormat.MP3,
-			Text: request.text,
-			TextType: textType,
-			VoiceId: voice as VoiceId,
-			SampleRate: String(request.sampleRate || 24000),
-		});
-
-		const response = await this.client.send(command);
-
-		if (!response.AudioStream) {
-			throw new Error("No audio stream received from AWS Polly");
-		}
-
-		// Convert stream to buffer
-		const chunks: Uint8Array[] = [];
-		const stream = response.AudioStream;
-
-		if (Symbol.asyncIterator in stream) {
-			for await (const chunk of stream as AsyncIterable<Uint8Array>) {
-				chunks.push(chunk);
-			}
-		} else if (stream instanceof Uint8Array) {
-			chunks.push(stream);
-		}
-
-		const audioBuffer = Buffer.concat(chunks);
-
-		return {
-			audio: audioBuffer,
-			contentType: response.ContentType || "audio/mpeg",
-		};
-	}
-
-	/**
-	 * Synthesize speech marks
-	 */
-	private async synthesizeSpeechMarks(
-		request: SynthesizeRequest,
-		voice: string,
-	): Promise<SpeechMark[]> {
-		// Detect if text contains SSML tags (same logic as audio synthesis)
-		const isSsml =
-			request.text.includes("<speak") ||
-			request.text.includes("<emphasis") ||
-			request.text.includes("<break") ||
-			request.text.includes("<prosody") ||
-			request.text.includes("<phoneme") ||
-			request.text.includes("<amazon:") ||
-			request.text.includes("<aws-");
-
-		const textType = isSsml ? "ssml" : "text";
-
-		const command = new SynthesizeSpeechCommand({
-			Engine: this.engine === "neural" ? Engine.NEURAL : Engine.STANDARD,
-			OutputFormat: OutputFormat.JSON,
-			Text: request.text,
-			TextType: textType,
-			VoiceId: voice as VoiceId,
-			SpeechMarkTypes: [SpeechMarkType.WORD],
-		});
-
-		const response = await this.client.send(command);
-
-		if (!response.AudioStream) {
-			return [];
-		}
-
-		// Convert stream to text
-		const chunks: Uint8Array[] = [];
-		const stream = response.AudioStream;
-
-		if (Symbol.asyncIterator in stream) {
-			for await (const chunk of stream as AsyncIterable<Uint8Array>) {
-				chunks.push(chunk);
-			}
-		} else if (stream instanceof Uint8Array) {
-			chunks.push(stream);
-		}
-
-		const marksText = Buffer.concat(chunks).toString("utf-8");
-
-		// Parse NDJSON (newline-delimited JSON)
-		// Each line is a separate JSON object
-		const speechMarks = marksText
-			.trim()
-			.split("\n")
-			.filter((line) => line.trim())
-			.map((line) => {
-				const mark = JSON.parse(line);
-				return {
-					time: mark.time,
-					type: "word" as const,
-					start: mark.start,
-					end: mark.end,
-					value: mark.value,
-				};
-			});
-
-		return speechMarks;
-	}
-
-	/**
-	 * Get available voices from AWS Polly
-	 */
-	async getVoices(options?: GetVoicesOptions): Promise<Voice[]> {
-		this.ensureInitialized();
-
-		try {
-			const input: DescribeVoicesCommandInput = {
-				Engine: this.engine === "neural" ? Engine.NEURAL : Engine.STANDARD,
-			};
-
-			if (options?.language) {
-				input.LanguageCode = options.language as any;
-			}
-
-			const command = new DescribeVoicesCommand(input);
-			const response = await this.client.send(command);
-
-			if (!response.Voices) {
-				return [];
-			}
-
-			return response.Voices.map((voice) => ({
-				id: voice.Id!,
-				name: voice.Name!,
-				language: voice.LanguageName!,
-				languageCode: voice.LanguageCode!,
-				gender: voice.Gender?.toLowerCase() as
-					| "male"
-					| "female"
-					| "neutral"
-					| undefined,
-				quality: (this.engine === "neural" ? "neural" : "standard") as
-					| "neural"
-					| "standard"
-					| "premium",
-				supportedFeatures: {
-					ssml: true,
-					emotions: false,
-					styles: false,
-				},
-				providerMetadata: {
-					supportedEngines: voice.SupportedEngines,
-					additionalLanguageCodes: voice.AdditionalLanguageCodes,
-				},
-			})).filter((voice) => {
-				// Apply filters
-				if (options?.gender && voice.gender !== options.gender) {
-					return false;
-				}
-				if (options?.quality && voice.quality !== options.quality) {
-					return false;
-				}
-				return true;
-			});
-		} catch (error) {
-			throw new TTSError(
-				TTSErrorCode.PROVIDER_ERROR,
-				`Failed to get voices: ${error instanceof Error ? error.message : String(error)}`,
-				{ error },
-				this.providerId,
-			);
-		}
-	}
-
-	/**
-	 * Get AWS Polly capabilities.
-	 *
-	 * Clearly documents what features are W3C-standard vs AWS-specific.
-	 */
-	getCapabilities(): ServerProviderCapabilities {
-		return {
-			// W3C Standard features
-			standard: {
-				supportsSSML: true, // ✅ Full SSML 1.1 + AWS extensions
-				supportsPitch: true, // ✅ Via SSML <prosody pitch> (not direct API param)
-				supportsRate: true, // ✅ Via SSML <prosody rate> (not direct API param)
-				supportsVolume: false, // ❌ Not supported by Polly API (handle client-side)
-				supportsMultipleVoices: true, // ✅ 60+ voices across 25+ languages
-				maxTextLength: 3000, // AWS Polly limit per request
-			},
-
-			// Provider-specific extensions
-			extensions: {
-				supportsSpeechMarks: true, // ✅ Native WORD speech marks (millisecond precision)
-				supportedFormats: ["mp3"], // Currently MP3 only (could add ogg, pcm)
-				supportsSampleRate: true, // ✅ Configurable sample rate
-
-				// AWS Polly-specific features
-				providerSpecific: {
-					engines: ["neural", "standard"], // Engine selection
-					supportedSpeechMarkTypes: ["word"], // Currently only WORD (could add sentence, ssml, viseme)
-					supportsLexicons: false, // Not yet implemented
-					awsSSMLExtensions: true, // <aws-break>, <aws-emphasis>, <aws-w>, etc.
-					neuralVoicesCount: 30, // ~30 neural voices available
-					standardVoicesCount: 30, // ~30 standard voices available
-					languagesCount: 25, // 25+ languages supported
-				},
-			},
-		};
-	}
-
-	/**
-	 * Clean up AWS Polly client
-	 */
-	async destroy(): Promise<void> {
-		if (this.client) {
-			this.client.destroy();
-		}
-		await super.destroy();
-	}
-}

package/src/index.ts

@@ -1,7 +0,0 @@
-/**
- * AWS Polly server-side TTS provider
- * @module @pie-players/tts-server-polly
- */
-
-export type { PollyProviderConfig } from "./PollyServerProvider.js";
-export { PollyServerProvider } from "./PollyServerProvider.js";

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-	"extends": "../tts-server-core/tsconfig.json",
-	"compilerOptions": {
-		"outDir": "./dist",
-		"rootDir": "./src"
-	},
-	"include": ["src/**/*"],
-	"exclude": ["node_modules", "dist", "**/*.test.ts"]
-}