@pie-players/tts-server-polly 0.3.74 → 1.0.0-beta.0

package/README.md

@@ -1,23 +1,16 @@
 # @pie-players/tts-server-polly
 
-AWS Polly provider for server-side text-to-speech with native speech marks support.
-
-For the cross-package TTS architecture and browser/server flow, see
-[TTS Architecture](../../docs/accessibility/tts-architecture.md). This README
-focuses on AWS Polly-specific provider configuration and behavior.
-
-## Overview
-
-This package provides a server-side TTS provider that uses AWS Polly to generate high-quality neural speech with millisecond-precise word timing through speech marks.
-
-## Features
-
-- ✅ **Native Speech Marks** - Millisecond-accurate word timing from AWS Polly
-- ✅ **Neural Voices** - High-quality neural TTS (default) or standard voices
-- ✅ **25+ Languages** - Wide language support
-- ✅ **Full SSML** - Supports Speech Synthesis Markup Language
-- ✅ **Parallel Requests** - Audio and speech marks fetched simultaneously
-- ✅ **60+ Voices** - Multiple voices per language
+`PollyServerProvider`, the AWS Polly provider for server-side text-to-speech
+(TTS), built on `@pie-players/tts-server-core`. It returns audio together with
+Polly's speech marks, the word timings that drive read-aloud highlighting in the
+browser. This README covers the provider's configuration and behavior for
+developers writing a host's TTS routes. The
+[integration guide](./examples/INTEGRATION-GUIDE.md) builds those routes in
+SvelteKit; the [AWS Polly setup guide](../../docs/accessibility/aws-polly-setup-guide.md)
+covers credentials and the IAM policy; [TTS Architecture](../../docs/accessibility/tts-architecture.md)
+covers the browser and server flow across packages.
+
+The package runs on Node.js 20 or later.
 
 ## Installation
 
@@ -32,37 +25,48 @@ npm install @pie-players/tts-server-polly
 ```typescript
 import { PollyServerProvider } from '@pie-players/tts-server-polly';
 
+const { AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN } = process.env;
+
 const provider = new PollyServerProvider();
 
 await provider.initialize({
   region: 'us-east-1',
-  credentials: {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-  },
+  // Explicit keys only when both are set; otherwise the AWS SDK default
+  // credential chain resolves them (IAM role, SSO, shared profile).
+  credentials:
+    AWS_ACCESS_KEY_ID && AWS_SECRET_ACCESS_KEY
+      ? {
+          accessKeyId: AWS_ACCESS_KEY_ID,
+          secretAccessKey: AWS_SECRET_ACCESS_KEY,
+          sessionToken: AWS_SESSION_TOKEN || undefined,
+        }
+      : undefined,
   engine: 'neural', // or 'standard'
   defaultVoice: 'Joanna',
 });
 ```
 
+`initialize` validates the config and creates the Polly client without calling
+AWS. A missing `region` throws a `TTSError` with `INITIALIZATION_ERROR`.
+
 ### Synthesize Speech
 
 ```typescript
 const result = await provider.synthesize({
   text: 'Hello world, this is a test of AWS Polly text to speech.',
-  voice: 'Joanna', // Optional, uses defaultVoice if not specified
+  voice: 'Joanna', // optional; see Voice Selection
   includeSpeechMarks: true,
 });
 
 console.log('Audio:', result.audio); // Buffer
-console.log('Speech marks:', result.speechMarks); // Array of word timings
-console.log('Duration:', result.metadata.duration, 'seconds');
+console.log('Speech marks:', result.speechMarks); // word timings
+console.log('Synthesis time:', result.metadata.duration, 'seconds');
 ```
 
 ### List Available Voices
 
 ```typescript
-// Get all neural voices
+// Voices for the configured engine
 const voices = await provider.getVoices();
 
 // Filter by language
@@ -72,6 +76,11 @@ const spanishVoices = await provider.getVoices({ language: 'es-ES' });
 const femaleVoices = await provider.getVoices({ gender: 'female' });
 ```
 
+`getVoices` asks Polly for the configured engine's voices, in the requested
+language when one is given, and filters by gender and quality locally. Each
+voice's `providerMetadata` carries Polly's `supportedEngines` and
+`additionalLanguageCodes`.
+
 ### Speech Marks Example
 
 ```typescript
@@ -87,6 +96,10 @@ const result = await provider.synthesize({
 // ]
 ```
 
+`time` is milliseconds into the audio. `start` and `end` are UTF-16 indexes into
+the request text, end exclusive; the provider re-anchors Polly's UTF-8 byte
+offsets to them.
+
 ## Configuration
 
 ### PollyProviderConfig
@@ -94,55 +107,74 @@ const result = await provider.synthesize({
 ```typescript
 interface PollyProviderConfig {
   region: string;                    // AWS region (required)
-  credentials?: {                    // AWS credentials (optional if using IAM)
+  credentials?: {                    // omitted: AWS SDK default credential chain
     accessKeyId: string;
     secretAccessKey: string;
     sessionToken?: string;
   };
-  engine?: 'neural' | 'standard';   // Voice engine (default: 'neural')
-  defaultVoice?: string;             // Default voice ID (default: 'Joanna')
+  engine?: 'neural' | 'standard';   // fixed per instance (default: 'neural')
+  defaultVoice?: string;             // default: 'Joanna'
+  enableLogging?: boolean;           // log SSML detection (default: false)
 }
 ```
 
-### Environment Variables
-
-```bash
-AWS_REGION=us-east-1
-AWS_ACCESS_KEY_ID=your_key_id
-AWS_SECRET_ACCESS_KEY=your_secret_key
-```
+The provider reads no environment variables; the host passes region and
+credentials in. The [setup guide](../../docs/accessibility/aws-polly-setup-guide.md)
+lists the variables the demo routes read and the IAM role setup for production.
+
+## Synthesis Behavior
+
+- **Requests.** Each synthesis sends two SynthesizeSpeech requests in parallel,
+  one for the audio and one for the speech marks. `includeSpeechMarks: false`
+  skips the second.
+- **Speech-mark types.** `providerOptions.speechMarkTypes` selects among `word`,
+  `sentence` and `ssml`. Without it, or when it names none of them, Polly returns
+  word marks.
+- **Engine.** The engine is set at `initialize`, and a request cannot change it.
+  A host that offers both engines runs one instance per engine.
+- **Output.** `format: 'ogg'` returns Ogg Vorbis, `'pcm'` returns PCM, and
+  anything else MP3; `'wav'` fails validation. `sampleRate` defaults to 24000 Hz
+  for MP3 and Ogg Vorbis and to 16000 Hz for PCM, which Polly takes only at 8000
+  or 16000. `contentType` is the one Polly reports, `audio/mpeg` when it reports
+  none.
+- **SSML and prosody.** Text containing SSML tags, Polly's `<amazon:…>` and
+  `<aws-…>` extensions included, goes to Polly unchanged. Plain text with a
+  `rate` or `pitch` other than 1 is escaped and wrapped in `<speak><prosody>`,
+  so the two apply to plain text only. A `rate` above 2 speaks at 2, Polly's
+  200% ceiling. The neural engine drops `pitch`.
+
+### Voice Selection
+
+A request's `voice` wins. Without one, the provider picks a voice for the
+request's `language` from the engine's voice listing and falls back to
+`defaultVoice`; the core README's [voice resolution](../tts-server-core/README.md#voice-resolution)
+section has the matching rules.
 
 ## Capabilities
 
 | Feature | Support |
 |---------|---------|
-| Speech Marks | ✅ Native |
-| SSML | ✅ Full |
-| Pitch Control | ⚠️ SSML only |
-| Rate Control | ✅ SSML |
-| Volume Control | ❌ Client-side |
-| Max Text Length | 3000 chars |
-| Audio Format | MP3 |
+| Speech Marks | Word, sentence and SSML marks |
+| SSML | Polly's supported subset |
+| Pitch Control | Standard engine only; plain text |
+| Rate Control | Plain text, through `<prosody>`; up to 2× |
+| Volume Control | Not supported |
+| Max Text Length | 3000 characters |
+| Audio Formats | MP3, Ogg Vorbis, PCM |
+| Sample Rate | Per request (default 24000 Hz, 16000 Hz for PCM) |
 
 ## Cost
 
-- **Standard voices:** $4 per 1M characters
-- **Neural voices:** $16 per 1M characters
-- **Speech marks:** Included (no extra charge)
-
-## Supported Voices
+Polly bills each SynthesizeSpeech request by characters; a synthesis with speech
+marks makes two (audio and marks). Current rates:
+<https://aws.amazon.com/polly/pricing/>
 
-Popular voices include:
+## Voices
 
-- **English (US):** Joanna, Matthew, Ivy, Kendra, Joey
-- **English (UK):** Amy, Brian, Emma
-- **Spanish:** Lucia, Conchita, Enrique
-- **French:** Celine, Mathieu
-- **German:** Marlene, Hans
-- **Italian:** Carla, Giorgio
-- **Portuguese:** Vitoria, Ricardo
-
-Use `getVoices()` for complete list.
+Polly's [voice list](https://docs.aws.amazon.com/polly/latest/dg/available-voices.html)
+names each voice and the engines it supports; `getVoices()` returns the voices
+available to the configured engine. A voice the engine does not support fails
+with `INVALID_REQUEST`.
 
 ## Error Handling
 
@@ -160,25 +192,26 @@ try {
 }
 ```
 
+AWS failures from `synthesize` and `getVoices` arrive as a `TTSError`:
+
+| AWS failure | `TTSErrorCode` |
+|-------------|----------------|
+| `TextLengthExceededException` | `TEXT_TOO_LONG` |
+| Invalid SSML, sample rate, language, engine, speech-mark, lexicon or S3/SNS input; `ValidationException` | `INVALID_REQUEST` |
+| `ThrottlingException`, `ServiceQuotaExceededException`, HTTP 429 | `RATE_LIMIT_EXCEEDED` |
+| HTTP 401 or 403 | `AUTHENTICATION_ERROR` |
+| Anything else | `PROVIDER_ERROR` |
+
+Request validation runs before any AWS call and rejects with a `TTSError`:
+`TEXT_TOO_LONG` for text over 3000 characters, `INVALID_REQUEST` for empty text,
+an unsupported format, or a rate or pitch out of range. A call before
+`initialize` throws a `TTSError` with `INITIALIZATION_ERROR`.
+
 ## AWS IAM Permissions
 
-Required IAM permissions:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "polly:SynthesizeSpeech",
-        "polly:DescribeVoices"
-      ],
-      "Resource": "*"
-    }
-  ]
-}
-```
+The provider needs `polly:SynthesizeSpeech` and `polly:DescribeVoices`. The
+[AWS Polly Setup Guide](../../docs/accessibility/aws-polly-setup-guide.md) has the
+policy and the credential setup.
 
 ## License
 

package/dist/PollyServerProvider.d.ts

@@ -2,6 +2,7 @@
  * AWS Polly server-side TTS provider
  * @module @pie-players/tts-server-polly
  */
+import { PollyClient } from "@aws-sdk/client-polly";
 import { BaseTTSProvider, type GetVoicesOptions, type ServerProviderCapabilities, type SynthesizeRequest, type SynthesizeResponse, type TTSServerConfig, type Voice } from "@pie-players/tts-server-core";
 /**
  * AWS Polly provider configuration.
@@ -34,7 +35,7 @@ export interface PollyProviderConfig extends TTSServerConfig {
      *
      * @extension AWS Polly-specific
      * @default 'neural'
-     * @note Neural: $16/1M chars, Standard: $4/1M chars
+     * @see https://aws.amazon.com/polly/pricing/
      */
     engine?: "neural" | "standard";
     /**
@@ -45,7 +46,25 @@ export interface PollyProviderConfig extends TTSServerConfig {
      * @see https://docs.aws.amazon.com/polly/latest/dg/voicelist.html
      */
     defaultVoice?: string;
+    /**
+     * Enable detailed logging for debugging
+     *
+     * @default false
+     */
+    enableLogging?: boolean;
 }
+/**
+ * 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
+ * - Full SSML support
+ * - Parallel audio + speech marks requests
+ */
 export declare class PollyServerProvider extends BaseTTSProvider {
     readonly providerId = "aws-polly";
     readonly providerName = "AWS Polly";
@@ -53,7 +72,9 @@ export declare class PollyServerProvider extends BaseTTSProvider {
     private client;
     private engine;
     private defaultVoice;
+    private enableLogging;
     private resolveOutputFormat;
+    private resolveEngine;
     private resolveSpeechMarkTypes;
     /**
      * Initialize the AWS Polly provider.
@@ -65,10 +86,17 @@ export declare class PollyServerProvider extends BaseTTSProvider {
      * @performance Completes in ~10-50ms
      */
     initialize(config: PollyProviderConfig): Promise<void>;
+    /** The AWS client every request goes through; a test subclass supplies a fake. */
+    protected createClient(config: PollyProviderConfig): PollyClient;
     /**
      * Synthesize speech with AWS Polly
      */
     synthesize(request: SynthesizeRequest): Promise<SynthesizeResponse>;
+    /**
+     * Neural voices take `<prosody>` rate and volume but not pitch. Polly's
+     * rate runs 20–200%, so a faster request speaks at 200%.
+     */
+    protected buildProsodyAttrs(request: SynthesizeRequest): string;
     /**
      * Synthesize audio stream
      */

package/dist/PollyServerProvider.js

@@ -3,25 +3,14 @@
  * @module @pie-players/tts-server-polly
  */
 import { DescribeVoicesCommand, Engine, PollyClient, SynthesizeSpeechCommand, } from "@aws-sdk/client-polly";
-import { BaseTTSProvider, TTSError, TTSErrorCode, } from "@pie-players/tts-server-core";
-/**
- * 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
- */
+import { anchorSpeechMarks, BaseTTSProvider, TTSError, TTSErrorCode, } from "@pie-players/tts-server-core";
 /**
  * Polly's own SSML vocabulary, on top of the standard elements the base provider
  * knows. `<amazon:effect>` and the `<aws-*>` family are Polly-only.
  */
 const POLLY_SSML_TAGS = ["<amazon:", "<aws-"];
+/** Polly's `<prosody rate>` runs 20–200%. */
+const POLLY_MAX_RATE = 2;
 /**
  * AWS SDK exception names (`error.name`) that mean the request itself was
  * invalid or unsupported, as opposed to a transient/provider-side failure.
@@ -45,6 +34,37 @@ const POLLY_RATE_LIMIT_EXCEPTIONS = new Set([
     "ThrottlingException",
     "ServiceQuotaExceededException",
 ]);
+/** Polly takes 8000 and 16000 Hz for pcm, and also 22050 and 24000 for mp3 and ogg_vorbis. */
+const DEFAULT_SAMPLE_RATE_HERTZ = {
+    mp3: 24000,
+    ogg_vorbis: 24000,
+    pcm: 16000,
+};
+/** Collects a Polly response body (`AudioStream`) into one buffer. */
+async function readResponseBody(stream) {
+    const chunks = [];
+    if (Symbol.asyncIterator in stream) {
+        for await (const chunk of stream) {
+            chunks.push(chunk);
+        }
+    }
+    else if (stream instanceof Uint8Array) {
+        chunks.push(stream);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * 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
+ * - Full SSML support
+ * - Parallel audio + speech marks requests
+ */
 export class PollyServerProvider extends BaseTTSProvider {
     providerId = "aws-polly";
     providerName = "AWS Polly";
@@ -52,6 +72,7 @@ export class PollyServerProvider extends BaseTTSProvider {
     client;
     engine = "neural";
     defaultVoice = "Joanna";
+    enableLogging = false;
     resolveOutputFormat(request) {
         switch (request.format) {
             case "ogg":
@@ -65,26 +86,15 @@ export class PollyServerProvider extends BaseTTSProvider {
                 return "mp3";
         }
     }
+    resolveEngine() {
+        return this.engine === "neural" ? Engine.NEURAL : Engine.STANDARD;
+    }
     resolveSpeechMarkTypes(request) {
-        const providerOptions = (request.providerOptions || {});
-        const configured = providerOptions.speechMarkTypes;
-        if (!Array.isArray(configured) || configured.length === 0) {
-            return ["word"];
-        }
-        const resolved = configured
-            .map((entry) => {
-            if (entry === "word")
-                return "word";
-            if (entry === "sentence")
-                return "sentence";
-            if (entry === "ssml")
-                return "ssml";
-            return null;
-        })
-            .filter((entry) => entry !== null);
-        if (resolved.length === 0)
+        const configured = request.providerOptions?.speechMarkTypes;
+        if (!Array.isArray(configured))
             return ["word"];
-        return resolved;
+        const resolved = configured.filter((entry) => entry === "word" || entry === "sentence" || entry === "ssml");
+        return resolved.length > 0 ? resolved : ["word"];
     }
     /**
      * Initialize the AWS Polly provider.
@@ -102,19 +112,22 @@ export class PollyServerProvider extends BaseTTSProvider {
         this.config = config;
         this.engine = config.engine || "neural";
         this.defaultVoice = config.defaultVoice || "Joanna";
+        this.enableLogging = config.enableLogging || false;
         try {
-            // Create Polly client (fast - no API calls)
-            this.client = new PollyClient({
-                region: config.region,
-                credentials: config.credentials,
-            });
+            this.client = this.createClient(config);
             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);
         }
     }
+    /** The AWS client every request goes through; a test subclass supplies a fake. */
+    createClient(config) {
+        return new PollyClient({
+            region: config.region,
+            credentials: config.credentials,
+        });
+    }
     /**
      * Synthesize speech with AWS Polly
      */
@@ -122,10 +135,9 @@ export class PollyServerProvider extends BaseTTSProvider {
         this.ensureInitialized();
         const capabilities = this.getCapabilities();
         this.validateRequest(request, capabilities);
-        const voice = request.voice || this.defaultVoice;
+        const voice = await this.resolveRequestVoice(request, 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
@@ -151,41 +163,43 @@ export class PollyServerProvider extends BaseTTSProvider {
             throw this.mapPollyErrorToTTSError(error, { request });
         }
     }
+    /**
+     * Neural voices take `<prosody>` rate and volume but not pitch. Polly's
+     * rate runs 20–200%, so a faster request speaks at 200%.
+     */
+    buildProsodyAttrs(request) {
+        return super.buildProsodyAttrs({
+            ...request,
+            rate: request.rate === undefined
+                ? undefined
+                : Math.min(request.rate, POLLY_MAX_RATE),
+            pitch: this.engine === "neural" ? undefined : request.pitch,
+        });
+    }
     /**
      * Synthesize audio stream
      */
     async synthesizeAudio(request, voice) {
-        if (this.detectSSML(request.text, POLLY_SSML_TAGS)) {
+        if (this.enableLogging && this.detectSSML(request.text, POLLY_SSML_TAGS)) {
             console.log("[PollyServerProvider] Detected SSML content, using TextType: ssml");
         }
         const { text, isSsml } = this.applyProsody(request.text, request, POLLY_SSML_TAGS);
         const textType = isSsml ? "ssml" : "text";
+        const outputFormat = this.resolveOutputFormat(request);
         const command = new SynthesizeSpeechCommand({
-            Engine: this.engine === "neural" ? Engine.NEURAL : Engine.STANDARD,
-            OutputFormat: this.resolveOutputFormat(request),
+            Engine: this.resolveEngine(),
+            OutputFormat: outputFormat,
             Text: text,
             TextType: textType,
             VoiceId: voice,
-            SampleRate: String(request.sampleRate || 24000),
+            SampleRate: String(request.sampleRate || DEFAULT_SAMPLE_RATE_HERTZ[outputFormat]),
         });
         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 = [];
-        const stream = response.AudioStream;
-        if (Symbol.asyncIterator in stream) {
-            for await (const chunk of stream) {
-                chunks.push(chunk);
-            }
-        }
-        else if (stream instanceof Uint8Array) {
-            chunks.push(stream);
-        }
-        const audioBuffer = Buffer.concat(chunks);
         return {
-            audio: audioBuffer,
+            audio: await readResponseBody(response.AudioStream),
             contentType: response.ContentType || "audio/mpeg",
         };
     }
@@ -196,7 +210,7 @@ export class PollyServerProvider extends BaseTTSProvider {
         const { text, isSsml } = this.applyProsody(request.text, request, POLLY_SSML_TAGS);
         const textType = isSsml ? "ssml" : "text";
         const command = new SynthesizeSpeechCommand({
-            Engine: this.engine === "neural" ? Engine.NEURAL : Engine.STANDARD,
+            Engine: this.resolveEngine(),
             OutputFormat: "json",
             Text: text,
             TextType: textType,
@@ -207,21 +221,9 @@ export class PollyServerProvider extends BaseTTSProvider {
         if (!response.AudioStream) {
             return [];
         }
-        // Convert stream to text
-        const chunks = [];
-        const stream = response.AudioStream;
-        if (Symbol.asyncIterator in stream) {
-            for await (const chunk of stream) {
-                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
+        const marksText = (await readResponseBody(response.AudioStream)).toString("utf-8");
+        // Polly returns speech marks as NDJSON: one JSON object per line.
+        const reported = marksText
             .trim()
             .split("\n")
             .filter((line) => line.trim())
@@ -240,7 +242,9 @@ export class PollyServerProvider extends BaseTTSProvider {
                 value: mark.value,
             };
         });
-        return speechMarks;
+        // Polly's offsets count UTF-8 bytes of the text it was sent, prosody
+        // envelope included.
+        return anchorSpeechMarks(reported, request.text);
     }
     /**
      * Get available voices from AWS Polly
@@ -249,7 +253,7 @@ export class PollyServerProvider extends BaseTTSProvider {
         this.ensureInitialized();
         try {
             const input = {
-                Engine: this.engine === "neural" ? Engine.NEURAL : Engine.STANDARD,
+                Engine: this.resolveEngine(),
             };
             if (options?.language) {
                 input.LanguageCode = options.language;
@@ -276,7 +280,6 @@ export class PollyServerProvider extends BaseTTSProvider {
                     additionalLanguageCodes: voice.AdditionalLanguageCodes,
                 },
             })).filter((voice) => {
-                // Apply filters
                 if (options?.gender && voice.gender !== options.gender) {
                     return false;
                 }
@@ -299,27 +302,24 @@ export class PollyServerProvider extends BaseTTSProvider {
         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
+                supportsSSML: true, // Polly's supported SSML subset
+                supportsPitch: this.engine === "standard", // Via SSML <prosody pitch>; neural voices lack it
+                supportsRate: true, // Via SSML <prosody rate> (not direct API param)
+                supportsVolume: false, // Not supported by Polly API (handle client-side)
+                supportsMultipleVoices: true, // see describeVoices for the roster
                 maxTextLength: 3000, // AWS Polly limit per request
             },
             // Provider-specific extensions
             extensions: {
-                supportsSpeechMarks: true, // ✅ Native WORD speech marks (millisecond precision)
+                supportsSpeechMarks: true, // Native WORD speech marks (millisecond precision)
                 supportedFormats: ["mp3", "ogg", "pcm"],
-                supportsSampleRate: true, // ✅ Configurable sample rate
+                supportsSampleRate: true, // Configurable sample rate
                 // AWS Polly-specific features
                 providerSpecific: {
                     engines: ["neural", "standard"], // Engine selection
                     supportedSpeechMarkTypes: ["word", "sentence", "ssml"],
                     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
+                    awsSSMLExtensions: true, // <amazon:effect>, <amazon:domain>, <amazon:auto-breaths>
                 },
             },
         };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/tts-server-polly",
-	"version": "0.3.74",
+	"version": "1.0.0-beta.0",
 	"description": "AWS Polly provider for server-side TTS with speech marks support",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -17,8 +17,7 @@
 	"scripts": {
 		"build": "tsc",
 		"dev": "tsc --watch",
-		"test": "vitest run --passWithNoTests",
-		"test:coverage": "vitest --coverage"
+		"test": "vitest run"
 	},
 	"keywords": [
 		"tts",
@@ -38,8 +37,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@aws-sdk/client-polly": "^3.1137.0",
-		"@pie-players/tts-server-core": "0.3.74"
+		"@aws-sdk/client-polly": "^3.1147.0",
+		"@pie-players/tts-server-core": "1.0.0-beta.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",