@pie-players/tts-server-google 0.3.75 → 1.0.0-beta.1

package/README.md

@@ -1,24 +1,16 @@
 # @pie-players/tts-server-google
 
-Google Cloud Text-to-Speech provider for server-side text-to-speech with 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 Google Cloud provider configuration and behavior.
-
-## Overview
-
-This package provides a server-side TTS provider that uses Google Cloud Text-to-Speech to generate high-quality neural speech with millisecond-precise word timing through SSML mark injection.
-
-## Features
-
-- ✅ **Speech Marks Support** - Millisecond-accurate word timing via SSML marks + timepoints
-- ✅ **WaveNet Neural Voices** - High-quality neural TTS with Google's WaveNet technology
-- ✅ **50+ Languages** - Extensive language support
-- ✅ **Full SSML** - Supports Speech Synthesis Markup Language 1.1
-- ✅ **Single API Call** - Audio and speech marks in one request (more efficient than AWS Polly)
-- ✅ **200+ Voices** - Multiple voice types per language (Standard, WaveNet, Studio)
-- ✅ **Flexible Authentication** - Service account, API key, or Application Default Credentials
+`GoogleCloudTTSProvider`, the Google Cloud Text-to-Speech provider for
+server-side text-to-speech (TTS), built on `@pie-players/tts-server-core`. It
+returns audio with word timings, which it gets by injecting SSML `<mark>` tags
+and reading Google's timepoints; the timings 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, and
+[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
 
@@ -37,15 +29,23 @@ const provider = new GoogleCloudTTSProvider();
 
 await provider.initialize({
   projectId: 'my-gcp-project',
-  credentials: '/path/to/service-account.json', // Or use other auth methods
-  voiceType: 'wavenet', // 'wavenet', 'standard', or 'studio'
+  credentials: '/path/to/service-account.json', // or another authentication method
+  voiceType: 'wavenet', // 'wavenet', 'standard', or 'studio' (Studio returns no speech marks)
   defaultVoice: 'en-US-Wavenet-A',
 });
 ```
 
+`initialize` validates the config and creates the Google client without calling
+Google. A missing `projectId` throws a `TTSError` with `INITIALIZATION_ERROR`.
+
 ### Authentication Methods
 
-#### 1. Service Account JSON File (Recommended for Production)
+The project needs the Cloud Text-to-Speech API enabled, with billing, as
+Google's [setup page](https://docs.cloud.google.com/text-to-speech/docs/get-started)
+describes. The provider reads no environment variables; `credentials` selects
+the method.
+
+#### Service Account Key File
 
 ```typescript
 await provider.initialize({
@@ -54,7 +54,9 @@ await provider.initialize({
 });
 ```
 
-#### 2. Service Account Object (For Containers/Serverless)
+#### Service Account Key Object
+
+For containers and serverless platforms that hold the key as a secret:
 
 ```typescript
 await provider.initialize({
@@ -66,7 +68,7 @@ await provider.initialize({
 });
 ```
 
-#### 3. API Key (For Simple Applications)
+#### API Key
 
 ```typescript
 await provider.initialize({
@@ -77,10 +79,15 @@ await provider.initialize({
 });
 ```
 
-#### 4. Application Default Credentials (For Local Development)
+#### Application Default Credentials
+
+Omitting `credentials` uses
+[Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials):
+`gcloud auth application-default login` locally, the file named by
+`GOOGLE_APPLICATION_CREDENTIALS`, or the attached service account on Google
+Cloud.
 
 ```typescript
-// Omit credentials to use gcloud auth application-default login
 await provider.initialize({
   projectId: 'my-project',
 });
@@ -91,13 +98,13 @@ await provider.initialize({
 ```typescript
 const result = await provider.synthesize({
   text: 'Hello world, this is a test of Google Cloud Text to Speech.',
-  voice: 'en-US-Wavenet-A', // Optional, uses defaultVoice if not specified
+  voice: 'en-US-Wavenet-A', // 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
@@ -116,6 +123,10 @@ const femaleVoices = await provider.getVoices({ gender: 'female' });
 const neuralVoices = await provider.getVoices({ quality: 'neural' });
 ```
 
+`getVoices` passes `language` to Google and filters by gender and quality
+locally. Quality follows the voice name: `Wavenet` is `neural`, `Studio` is
+`premium`, and every other voice is `standard`.
+
 ### Speech Marks Example
 
 ```typescript
@@ -147,6 +158,9 @@ const result = await provider.synthesize({
 });
 ```
 
+The [TTS authoring guide](../../docs/accessibility/tts-authoring-guide.md#ssml-provider-support)
+covers how much of authored SSML Google voices.
+
 ## Configuration
 
 ### GoogleCloudTTSConfig
@@ -154,84 +168,97 @@ const result = await provider.synthesize({
 ```typescript
 interface GoogleCloudTTSConfig {
   projectId: string;                    // Google Cloud project ID (required)
-  credentials?:                         // Authentication (optional if using ADC)
-    | string                            // Path to service account JSON
-    | {                                 // Service account object
+  credentials?:                         // omitted: Application Default Credentials
+    | string                            // Path to a service account key file
+    | {                                 // Service account key object
         client_email: string;
         private_key: string;
+        project_id?: string;
       }
     | { apiKey: string };               // API key
-  voiceType?: 'wavenet' | 'standard' | 'studio';  // Voice type (default: 'wavenet')
-  defaultVoice?: string;                // Default voice (default: 'en-US-Wavenet-A')
-  audioEncoding?: 'MP3' | 'LINEAR16' | 'OGG_OPUS';  // Audio format (default: 'MP3')
-  enableLogging?: boolean;              // Debug logging (default: false)
+  voiceType?: 'wavenet' | 'standard' | 'studio';  // default: 'wavenet'
+  defaultVoice?: string;                // default: 'en-US-Wavenet-A'
+  audioEncoding?: 'MP3' | 'LINEAR16' | 'OGG_OPUS';  // output encoding (default: 'MP3')
+  enableLogging?: boolean;              // default: false
 }
 ```
 
-### Environment Variables
-
-```bash
-GOOGLE_CLOUD_PROJECT=my-project
-GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
-```
+## Synthesis Behavior
+
+- **Requests.** One SynthesizeSpeech call returns the audio and, with speech
+  marks requested, the timepoints of the injected marks.
+- **Output.** `audioEncoding` fixes the output for the instance: `MP3` returns
+  `audio/mpeg`, `LINEAR16` `audio/wav`, `OGG_OPUS` `audio/ogg`. A request's
+  `format` is only validated against `mp3`, `wav` and `ogg`. `sampleRate`
+  defaults to 24000 Hz. The language code sent to Google comes from the voice
+  name.
+- **Prosody.** Plain text with a `rate` or `pitch` other than 1 is escaped and
+  wrapped in `<prosody>`. Authored SSML goes to Google with its markup
+  unchanged, so `rate` and `pitch` apply to plain text only. A Studio voice
+  drops `pitch`.
+- **Limits.** The provider accepts 5000 characters per request.
+  `ServerTTSProvider` declares 3000, and the toolkit splits longer reads to fit,
+  so requests from the browser stay under the provider's limit.
+
+### Voice Selection
+
+A request's `voice` wins. Without one, the provider picks a voice for the
+request's `language` from Google's voice listing, preferring voices of the
+configured `voiceType`, and falls back to `defaultVoice`; the core README's
+[voice resolution](../tts-server-core/README.md#voice-resolution) section has the
+matching rules.
+
+### Speech Marks
+
+Speech marks are on unless the request sets `includeSpeechMarks: false`, and are
+word marks only.
+
+1. The provider places a `<mark>` before each word: a run of letters, combining
+   marks, digits and apostrophes, so accented words stay whole.
+2. Google returns a timepoint for each mark.
+3. The provider converts the timepoints to speech marks in milliseconds, sorted
+   by time.
+
+Plain-text offsets are UTF-16 indexes into the request text. Authored SSML keeps
+its markup and takes marks in its text nodes, so its offsets index the SSML.
+Entities are never read as words, and an element whose content the engine
+replaces (`<sub>`, `<say-as>`, `<phoneme>`) takes one mark before its opening
+tag, valued with its text.
+
+Studio voices take no `<mark>` tags. A voice whose name contains `Studio`, or
+one Google answers with its Studio `<mark>`-unsupported error, is synthesized as
+audio only and returns `speechMarks: []`, so `ServerTTSProvider` reports no word
+boundaries for it.
 
 ## Capabilities
 
 | Feature | Support |
 |---------|---------|
-| Speech Marks | ✅ Via SSML marks |
-| SSML | ✅ Full 1.1 |
-| Pitch Control | ✅ SSML |
-| Rate Control | ✅ SSML |
-| Volume Control | ❌ Client-side |
-| Max Text Length | 5000 chars |
-| Audio Formats | MP3, WAV, OGG |
+| Speech Marks | Word marks via SSML marks; none for Studio voices |
+| SSML | Google's supported subset |
+| Pitch Control | Plain text; none for Studio voices |
+| Rate Control | Plain text, through `<prosody>` |
+| Volume Control | Not supported |
+| Max Text Length | 5000 characters |
+| Audio Formats | MP3, WAV (LINEAR16), OGG (Opus) |
+| Sample Rate | Per request (default 24000 Hz) |
+
+The [provider comparison](../../docs/accessibility/tts-architecture.md#provider-comparison)
+sets these against Polly and the custom transport.
 
 ## Cost
 
-- **Standard voices:** $4 per 1M characters
-- **WaveNet (neural) voices:** $16 per 1M characters
-- **Studio voices:** $16 per 1M characters
-- **Speech marks (timepoints):** Included (no extra charge)
-
-Pricing is competitive with AWS Polly.
-
-## Supported Voices
-
-Popular voices include:
+Current rates: <https://cloud.google.com/text-to-speech/pricing>
 
-### Standard Voices
-- **English (US):** en-US-Standard-A/B/C/D/E/F/G/H/I/J
-- **English (UK):** en-GB-Standard-A/B/C/D/F
-- **Spanish:** es-ES-Standard-A/B/C/D
-- **French:** fr-FR-Standard-A/B/C/D/E
-- **German:** de-DE-Standard-A/B/C/D/E/F
-- **Italian:** it-IT-Standard-A/B/C/D
-- **Portuguese:** pt-BR-Standard-A/B/C
+## Voices
 
-### WaveNet (Neural) Voices
-- **English (US):** en-US-Wavenet-A/B/C/D/E/F/G/H/I/J
-- **English (UK):** en-GB-Wavenet-A/B/C/D/F
-- **Spanish:** es-ES-Wavenet-B/C/D
-- **French:** fr-FR-Wavenet-A/B/C/D/E
-- **German:** de-DE-Wavenet-A/B/C/D/E/F
-- **Italian:** it-IT-Wavenet-A/B/C/D
-- **Portuguese:** pt-BR-Wavenet-A/B/C
+Google's [voice list](https://docs.cloud.google.com/text-to-speech/docs/list-voices-and-types)
+names the voices per language and type; `getVoices()` returns those the project
+can use. Names follow `{languageCode}-{voiceType}-{variant}`:
 
-### Studio Voices
-- **English (US):** en-US-Studio-O/Q
-- **English (UK):** en-GB-Studio-B/C
-
-Use `getVoices()` for the complete list of 200+ voices.
-
-## Voice Naming Convention
-
-Google Cloud voices follow the pattern: `{languageCode}-{voiceType}-{variant}`
-
-Examples:
-- `en-US-Wavenet-A` - US English, WaveNet (neural), variant A
-- `es-ES-Standard-B` - Spanish (Spain), Standard, variant B
-- `fr-FR-Studio-A` - French, Studio (premium), variant A
+- `en-US-Wavenet-A`: US English, WaveNet (neural), variant A
+- `es-ES-Standard-B`: Spanish (Spain), Standard, variant B
+- `fr-FR-Studio-A`: French, Studio (premium), variant A
 
 ## Error Handling
 
@@ -256,52 +283,20 @@ try {
 }
 ```
 
-## Google Cloud IAM Permissions
-
-Required IAM permissions for the service account:
-
-```json
-{
-  "role": "roles/cloudtexttospeech.user",
-  "permissions": [
-    "texttospeech.operations.get",
-    "texttospeech.voices.list",
-    "texttospeech.voices.synthesize"
-  ]
-}
-```
-
-Or use the predefined role:
-
-```bash
-gcloud projects add-iam-policy-binding PROJECT_ID \
-  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
-  --role="roles/cloudtexttospeech.user"
-```
-
-## Comparison with AWS Polly
-
-| Feature | Google Cloud TTS | AWS Polly |
-|---------|------------------|-----------|
-| **Voices** | 200+ voices | 60+ voices |
-| **Languages** | 50+ languages | 25+ languages |
-| **Speech Marks** | Via SSML marks | Native |
-| **API Calls** | Single call | Two parallel calls |
-| **Max Text** | 5000 chars | 3000 chars |
-| **Neural Cost** | $16/1M chars | $16/1M chars |
-| **Standard Cost** | $4/1M chars | $4/1M chars |
-| **Authentication** | Flexible (4 methods) | AWS credentials |
-| **Region** | Global service | Region-specific |
-
-## How Speech Marks Work
-
-Unlike AWS Polly (which provides native speech marks), Google Cloud TTS requires SSML mark injection:
+`synthesize` maps Google's gRPC status codes:
 
-1. The provider automatically parses your text and injects `<mark>` tags before each word
-2. Google Cloud TTS returns timepoints corresponding to these marks
-3. The provider converts timepoints to the unified speech mark format
+| Google failure | `TTSErrorCode` |
+|----------------|----------------|
+| `PERMISSION_DENIED` (7) | `AUTHENTICATION_ERROR` |
+| `RESOURCE_EXHAUSTED` (8) | `RATE_LIMIT_EXCEEDED` |
+| `INVALID_ARGUMENT` (3) | `INVALID_REQUEST` |
+| Anything else, a response without audio included | `PROVIDER_ERROR` |
 
-This process is transparent to the user - just set `includeSpeechMarks: true`.
+Every `getVoices` failure is a `PROVIDER_ERROR`. Request validation runs before
+any Google call and rejects with a `TTSError`: `TEXT_TOO_LONG` for text over
+5000 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`.
 
 ## Advanced Configuration
 
@@ -319,7 +314,7 @@ await provider.initialize({
 ```typescript
 await provider.initialize({
   projectId: 'my-project',
-  enableLogging: true, // Logs SSML injection and speech marks extraction
+  enableLogging: true, // Logs SSML detection and the marks injected and extracted
 });
 ```
 

package/dist/GoogleCloudTTSProvider.d.ts

@@ -2,6 +2,7 @@
  * Google Cloud Text-to-Speech server-side TTS provider
  * @module @pie-players/tts-server-google
  */
+import { v1beta1 } from "@google-cloud/text-to-speech";
 import { BaseTTSProvider, type GetVoicesOptions, type ServerProviderCapabilities, type SynthesizeRequest, type SynthesizeResponse, type TTSServerConfig, type Voice } from "@pie-players/tts-server-core";
 /**
  * Google Cloud Text-to-Speech provider configuration.
@@ -41,7 +42,7 @@ export interface GoogleCloudTTSConfig extends TTSServerConfig {
      * Voice type: 'wavenet' (neural), 'standard', or 'studio' (premium)
      *
      * @default 'wavenet'
-     * @note WaveNet: $16/1M chars, Standard: $4/1M chars, Studio: $16/1M chars
+     * @see https://cloud.google.com/text-to-speech/pricing
      */
     voiceType?: "wavenet" | "standard" | "studio";
     /**
@@ -74,7 +75,7 @@ export interface GoogleCloudTTSConfig extends TTSServerConfig {
  * Features:
  * - Speech marks support via SSML mark injection (millisecond precision)
  * - WaveNet (neural), Standard, and Studio voice types
- * - 200+ voices across 50+ languages
+ * - Voices across many languages, listed by `getVoices`
  * - Full SSML support
  * - Single API call for audio + speech marks
  */
@@ -99,12 +100,15 @@ export declare class GoogleCloudTTSProvider extends BaseTTSProvider {
      * @performance Completes in ~10-50ms
      */
     initialize(config: GoogleCloudTTSConfig): Promise<void>;
+    /** The Google client every request goes through; a test subclass supplies a fake. */
+    protected createClient(clientConfig: ConstructorParameters<typeof v1beta1.TextToSpeechClient>[0]): v1beta1.TextToSpeechClient;
     /**
      * Synthesize speech with Google Cloud TTS
      */
     synthesize(request: SynthesizeRequest): Promise<SynthesizeResponse>;
     /**
-     * Synthesize audio stream only (no speech marks)
+     * Synthesize audio stream only (no speech marks). A Studio voice takes
+     * `<prosody>` rate but not pitch, so its request drops pitch.
      */
     private synthesizeAudio;
     /**
@@ -116,16 +120,17 @@ export declare class GoogleCloudTTSProvider extends BaseTTSProvider {
      */
     private injectSSMLMarks;
     /**
-     * Extract words from existing SSML (simplified version for v1)
+     * Inject a mark before each word of authored SSML, keeping its markup.
+     * Offsets index the SSML itself. An element whose content the engine
+     * replaces (`<sub>`, `<say-as>`, `<phoneme>`) takes one mark before its
+     * opening tag, valued with its text, since a mark may not sit inside it.
      */
     private extractWordsFromSSML;
+    private markTextNode;
     /**
      * Extract speech marks from Google's timepoints
      */
     private extractSpeechMarksFromTimepoints;
-    /**
-     * Detect if text contains SSML markup
-     */
     /**
      * Get available voices from Google Cloud TTS
      */

package/dist/GoogleCloudTTSProvider.js

@@ -4,6 +4,44 @@
  */
 import { v1beta1, protos } from "@google-cloud/text-to-speech";
 import { BaseTTSProvider, TTSError, TTSErrorCode, } from "@pie-players/tts-server-core";
+const DEFAULT_SAMPLE_RATE_HERTZ = 24000;
+const CONTENT_TYPE_BY_ENCODING = {
+    MP3: "audio/mpeg",
+    LINEAR16: "audio/wav",
+    OGG_OPUS: "audio/ogg",
+};
+// The segment of a Google voice name that identifies its voice type.
+const VOICE_TYPE_NAME_SEGMENT = {
+    wavenet: "Wavenet",
+    standard: "Standard",
+    studio: "Studio",
+};
+// gRPC status codes the Google client reports in `error.code`.
+const GRPC_STATUS = {
+    INVALID_ARGUMENT: 3,
+    PERMISSION_DENIED: 7,
+    RESOURCE_EXHAUSTED: 8,
+};
+// Google voice names start with their locale: "en-US-Wavenet-A" → "en-US".
+const languageCodeOf = (voice) => voice.split("-").slice(0, 2).join("-");
+// Letters, digits and combining marks, so accented words stay whole.
+const WORD_PATTERN = /[\p{L}\p{M}\p{N}'\u2019]+/gu;
+const SSML_TEXT_TOKEN_PATTERN = /&(?:#\d+|#x[\da-f]+|[a-z]+);|[\p{L}\p{M}\p{N}'\u2019]+/giu;
+const SSML_ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+};
+const decodeSSMLText = (text) => text.replace(/&(#\d+|#x[\da-f]+|[a-z]+);/gi, (entity, name) => {
+    if (name[0] !== "#")
+        return SSML_ENTITIES[name.toLowerCase()] ?? entity;
+    const code = name[1] === "x" || name[1] === "X"
+        ? Number.parseInt(name.slice(2), 16)
+        : Number.parseInt(name.slice(1), 10);
+    return Number.isFinite(code) ? String.fromCodePoint(code) : entity;
+});
 /**
  * Google Cloud Text-to-Speech Server Provider
  *
@@ -13,7 +51,7 @@ import { BaseTTSProvider, TTSError, TTSErrorCode, } from "@pie-players/tts-serve
  * Features:
  * - Speech marks support via SSML mark injection (millisecond precision)
  * - WaveNet (neural), Standard, and Studio voice types
- * - 200+ voices across 50+ languages
+ * - Voices across many languages, listed by `getVoices`
  * - Full SSML support
  * - Single API call for audio + speech marks
  */
@@ -58,7 +96,6 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
         this.audioEncoding = config.audioEncoding || "MP3";
         this.enableLogging = config.enableLogging || false;
         try {
-            // Initialize Google Cloud TTS client
             const clientConfig = {
                 projectId: config.projectId,
             };
@@ -78,7 +115,7 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
                 }
             }
             // Else: Use Application Default Credentials (ADC)
-            this.client = new v1beta1.TextToSpeechClient(clientConfig);
+            this.client = this.createClient(clientConfig);
             this.initialized = true;
             if (this.enableLogging) {
                 console.log("[GoogleCloudTTS] Initialized successfully");
@@ -88,6 +125,10 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
             throw new TTSError(TTSErrorCode.INITIALIZATION_ERROR, `Failed to initialize Google Cloud TTS: ${error instanceof Error ? error.message : String(error)}`, { error }, this.providerId);
         }
     }
+    /** The Google client every request goes through; a test subclass supplies a fake. */
+    createClient(clientConfig) {
+        return new v1beta1.TextToSpeechClient(clientConfig);
+    }
     /**
      * Synthesize speech with Google Cloud TTS
      */
@@ -95,173 +136,112 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
         this.ensureInitialized();
         const capabilities = this.getCapabilities();
         this.validateRequest(request, capabilities);
-        const voiceType = { wavenet: "Wavenet", standard: "Standard", studio: "Studio" }[this.voiceType];
+        const voiceType = VOICE_TYPE_NAME_SEGMENT[this.voiceType];
         const voice = await this.resolveRequestVoice(request, this.defaultVoice, (candidate) => candidate.id.includes(voiceType));
         const startTime = Date.now();
+        const respond = (result, speechMarks) => ({
+            audio: result.audio,
+            contentType: result.contentType,
+            speechMarks,
+            metadata: {
+                providerId: this.providerId,
+                voice,
+                duration: (Date.now() - startTime) / 1000,
+                charCount: request.text.length,
+                cached: false,
+                timestamp: new Date().toISOString(),
+            },
+        });
         try {
-            // Check if speech marks are requested
             if (request.includeSpeechMarks !== false && !this.isStudioVoice(voice)) {
-                // Use SSML marks injection for precise word timing
                 const result = await this.synthesizeWithSpeechMarks(request, voice);
-                const duration = (Date.now() - startTime) / 1000;
-                return {
-                    audio: result.audio,
-                    contentType: result.contentType,
-                    speechMarks: result.speechMarks,
-                    metadata: {
-                        providerId: this.providerId,
-                        voice,
-                        duration,
-                        charCount: request.text.length,
-                        cached: false,
-                        timestamp: new Date().toISOString(),
-                    },
-                };
-            }
-            else {
-                // Audio only (no speech marks)
-                const result = await this.synthesizeAudio(request, voice);
-                const duration = (Date.now() - startTime) / 1000;
-                return {
-                    audio: result.audio,
-                    contentType: result.contentType,
-                    speechMarks: [],
-                    metadata: {
-                        providerId: this.providerId,
-                        voice,
-                        duration,
-                        charCount: request.text.length,
-                        cached: false,
-                        timestamp: new Date().toISOString(),
-                    },
-                };
+                return respond(result, result.speechMarks);
             }
+            return respond(await this.synthesizeAudio(request, voice), []);
         }
         catch (error) {
             // Studio voices do not support SSML <mark> tags used for timing extraction.
             // Fall back to audio-only synthesis rather than failing the request.
             if (request.includeSpeechMarks !== false &&
                 this.isStudioMarkUnsupportedError(error)) {
-                const result = await this.synthesizeAudio(request, voice);
-                const duration = (Date.now() - startTime) / 1000;
-                return {
-                    audio: result.audio,
-                    contentType: result.contentType,
-                    speechMarks: [],
-                    metadata: {
-                        providerId: this.providerId,
-                        voice,
-                        duration,
-                        charCount: request.text.length,
-                        cached: false,
-                        timestamp: new Date().toISOString(),
-                    },
-                };
+                try {
+                    return respond(await this.synthesizeAudio(request, voice, true), []);
+                }
+                catch (fallbackError) {
+                    throw this.mapGoogleErrorToTTSError(fallbackError);
+                }
             }
             throw this.mapGoogleErrorToTTSError(error);
         }
     }
     /**
-     * Synthesize audio stream only (no speech marks)
+     * Synthesize audio stream only (no speech marks). A Studio voice takes
+     * `<prosody>` rate but not pitch, so its request drops pitch.
      */
-    async synthesizeAudio(request, voice) {
+    async synthesizeAudio(request, voice, studio = this.isStudioVoice(voice)) {
         if (this.detectSSML(request.text) && this.enableLogging) {
             console.log("[GoogleCloudTTS] Detected SSML content");
         }
-        const { text, isSsml } = this.applyProsody(request.text, request);
-        // Parse voice name to extract language code
-        const languageCode = voice.split("-").slice(0, 2).join("-"); // e.g., "en-US" from "en-US-Wavenet-A"
-        // Map our audio encoding to Google's enum
-        const audioEncodingMap = {
-            MP3: "MP3",
-            LINEAR16: "LINEAR16",
-            OGG_OPUS: "OGG_OPUS",
-        };
+        const { text, isSsml } = this.applyProsody(request.text, studio ? { ...request, pitch: undefined } : request);
         const [response] = await this.client.synthesizeSpeech({
             input: isSsml ? { ssml: text } : { text },
             voice: {
-                languageCode,
+                languageCode: languageCodeOf(voice),
                 name: voice,
             },
             audioConfig: {
-                audioEncoding: audioEncodingMap[this.audioEncoding],
-                sampleRateHertz: request.sampleRate || 24000,
+                audioEncoding: this.audioEncoding,
+                sampleRateHertz: request.sampleRate || DEFAULT_SAMPLE_RATE_HERTZ,
             },
         });
         if (!response.audioContent) {
             throw new Error("No audio content received from Google Cloud TTS");
         }
-        // Convert Uint8Array to Buffer
-        const audioBuffer = Buffer.from(response.audioContent);
-        const contentTypeMap = {
-            MP3: "audio/mpeg",
-            LINEAR16: "audio/wav",
-            OGG_OPUS: "audio/ogg",
-        };
         return {
-            audio: audioBuffer,
-            contentType: contentTypeMap[this.audioEncoding],
+            audio: Buffer.from(response.audioContent),
+            contentType: CONTENT_TYPE_BY_ENCODING[this.audioEncoding],
         };
     }
     /**
      * Synthesize with speech marks using SSML mark injection
      */
     async synthesizeWithSpeechMarks(request, voice) {
-        // Check if the text is already SSML
         const isUserSSML = this.detectSSML(request.text);
-        // If user provided SSML, we need to inject marks within the existing SSML
-        // For simplicity in v1, we'll inject marks for plain text only. Already-SSML
-        // input skips prosody wrapping too: injecting <prosody> into markup the
-        // caller authored themselves would require parsing it.
+        // Authored SSML keeps its markup and takes marks in its text nodes. It
+        // skips prosody wrapping: injecting <prosody> into markup the caller
+        // authored would require parsing it.
         const { ssml, wordMap } = isUserSSML
             ? this.extractWordsFromSSML(request.text)
             : this.injectSSMLMarks(request.text, this.buildProsodyAttrs(request));
         if (this.enableLogging) {
             console.log(`[GoogleCloudTTS] Injected ${wordMap.length} SSML marks`);
         }
-        // Parse voice name to extract language code
-        const languageCode = voice.split("-").slice(0, 2).join("-");
-        // Map our audio encoding to Google's enum
-        const audioEncodingMap = {
-            MP3: "MP3",
-            LINEAR16: "LINEAR16",
-            OGG_OPUS: "OGG_OPUS",
-        };
         // Single API call with timepoint tracking enabled
-        const responseArray = await this.client.synthesizeSpeech({
+        const [response] = await this.client.synthesizeSpeech({
             input: { ssml },
             voice: {
-                languageCode,
+                languageCode: languageCodeOf(voice),
                 name: voice,
             },
             audioConfig: {
-                audioEncoding: audioEncodingMap[this.audioEncoding],
-                sampleRateHertz: request.sampleRate || 24000,
+                audioEncoding: this.audioEncoding,
+                sampleRateHertz: request.sampleRate || DEFAULT_SAMPLE_RATE_HERTZ,
             },
             enableTimePointing: [
                 protos.google.cloud.texttospeech.v1beta1.SynthesizeSpeechRequest
                     .TimepointType.SSML_MARK,
             ],
         });
-        const response = responseArray[0];
         if (!response.audioContent) {
             throw new Error("No audio content received from Google Cloud TTS");
         }
-        // Convert Uint8Array to Buffer
-        const audioBuffer = Buffer.from(response.audioContent);
-        const contentTypeMap = {
-            MP3: "audio/mpeg",
-            LINEAR16: "audio/wav",
-            OGG_OPUS: "audio/ogg",
-        };
-        // Extract speech marks from timepoints
         const speechMarks = this.extractSpeechMarksFromTimepoints(response.timepoints || [], wordMap);
         if (this.enableLogging) {
             console.log(`[GoogleCloudTTS] Extracted ${speechMarks.length} speech marks`);
         }
         return {
-            audio: audioBuffer,
-            contentType: contentTypeMap[this.audioEncoding],
+            audio: Buffer.from(response.audioContent),
+            contentType: CONTENT_TYPE_BY_ENCODING[this.audioEncoding],
             speechMarks,
         };
     }
@@ -270,27 +250,16 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
      */
     injectSSMLMarks(text, prosodyAttrs = "") {
         const words = [];
-        const wordRegex = /\b[\w']+\b/g;
-        let match;
-        let markIndex = 0;
-        while ((match = wordRegex.exec(text)) !== null) {
-            const word = match[0];
-            const start = match.index;
-            const end = start + word.length;
-            const markName = `w${markIndex++}`;
-            words.push({ word, start, end, markName });
-        }
-        // Build SSML with marks
         let ssml = prosodyAttrs ? `<speak><prosody ${prosodyAttrs}>` : "<speak>";
         let lastEnd = 0;
-        for (const { word, start, end, markName } of words) {
-            // Add text before word (including whitespace and punctuation)
-            ssml += this.escapeSSML(text.slice(lastEnd, start));
-            // Add marked word
-            ssml += `<mark name="${markName}"/>${this.escapeSSML(word)}`;
-            lastEnd = end;
+        for (const match of text.matchAll(WORD_PATTERN)) {
+            const word = match[0];
+            const start = match.index;
+            const markName = `w${words.length}`;
+            words.push({ word, start, end: start + word.length, markName });
+            ssml += `${this.escapeSSML(text.slice(lastEnd, start))}<mark name="${markName}"/>${this.escapeSSML(word)}`;
+            lastEnd = start + word.length;
         }
-        // Add remaining text
         ssml +=
             this.escapeSSML(text.slice(lastEnd)) +
                 (prosodyAttrs ? "</prosody>" : "") +
@@ -298,16 +267,63 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
         return { ssml, wordMap: words };
     }
     /**
-     * Extract words from existing SSML (simplified version for v1)
+     * Inject a mark before each word of authored SSML, keeping its markup.
+     * Offsets index the SSML itself. An element whose content the engine
+     * replaces (`<sub>`, `<say-as>`, `<phoneme>`) takes one mark before its
+     * opening tag, valued with its text, since a mark may not sit inside it.
      */
     extractWordsFromSSML(ssmlText) {
-        // For now, just strip SSML tags and inject marks
-        // More sophisticated SSML parsing can be added in future versions
-        const plainText = ssmlText
-            .replace(/<[^>]+>/g, " ") // Remove all tags
-            .replace(/\s+/g, " ") // Normalize whitespace
-            .trim();
-        return this.injectSSMLMarks(plainText);
+        const words = [];
+        const mark = (word, start, end) => {
+            const markName = `w${words.length}`;
+            words.push({ word, start, end, markName });
+            return `<mark name="${markName}"/>`;
+        };
+        let ssml = "";
+        let cursor = 0;
+        for (const tag of ssmlText.matchAll(/<[^>]*>/g)) {
+            if (tag.index < cursor)
+                continue;
+            ssml += this.markTextNode(ssmlText, cursor, tag.index, mark);
+            const opaque = /^<\s*(sub|say-as|phoneme)\b(?![^>]*\/>)[^>]*>$/i.exec(tag[0]);
+            const close = opaque
+                ? new RegExp(`</\\s*${opaque[1]}\\s*>`, "i")
+                : null;
+            const closeMatch = close?.exec(ssmlText.slice(tag.index));
+            if (opaque && closeMatch) {
+                const contentStart = tag.index + tag[0].length;
+                const contentEnd = tag.index + closeMatch.index;
+                const raw = ssmlText.slice(contentStart, contentEnd);
+                const inner = raw.trim();
+                const innerStart = contentStart + raw.indexOf(inner);
+                const elementEnd = contentEnd + closeMatch[0].length;
+                ssml += inner
+                    ? mark(decodeSSMLText(inner), innerStart, innerStart + inner.length)
+                    : "";
+                ssml += ssmlText.slice(tag.index, elementEnd);
+                cursor = elementEnd;
+                continue;
+            }
+            ssml += tag[0];
+            cursor = tag.index + tag[0].length;
+        }
+        ssml += this.markTextNode(ssmlText, cursor, ssmlText.length, mark);
+        return { ssml, wordMap: words };
+    }
+    // Marks each word of an SSML text node, which is already escaped, so
+    // entities stay whole and are never read as words.
+    markTextNode(ssmlText, from, to, mark) {
+        const segment = ssmlText.slice(from, to);
+        let out = "";
+        let lastEnd = 0;
+        for (const match of segment.matchAll(SSML_TEXT_TOKEN_PATTERN)) {
+            if (match[0].startsWith("&"))
+                continue;
+            const start = from + match.index;
+            out += `${segment.slice(lastEnd, match.index)}${mark(match[0], start, start + match[0].length)}${match[0]}`;
+            lastEnd = match.index + match[0].length;
+        }
+        return out + segment.slice(lastEnd);
     }
     /**
      * Extract speech marks from Google's timepoints
@@ -318,7 +334,6 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
         }
         const speechMarks = [];
         for (const timepoint of timepoints) {
-            // Find corresponding word in our map
             const wordInfo = wordMap.find((w) => w.markName === timepoint.markName);
             if (wordInfo &&
                 timepoint.timeSeconds !== undefined &&
@@ -332,12 +347,8 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
                 });
             }
         }
-        // Sort by time
         return speechMarks.sort((a, b) => a.time - b.time);
     }
-    /**
-     * Detect if text contains SSML markup
-     */
     /**
      * Get available voices from Google Cloud TTS
      */
@@ -353,7 +364,6 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
             return response.voices
                 .map((voice) => this.mapGoogleVoiceToVoice(voice))
                 .filter((voice) => {
-                // Apply filters
                 if (options?.gender && voice.gender !== options.gender) {
                     return false;
                 }
@@ -414,10 +424,10 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
             // W3C Standard features
             standard: {
                 supportsSSML: true, // ✅ Full SSML 1.1 support
-                supportsPitch: true, // ✅ Via SSML <prosody pitch>
+                supportsPitch: this.voiceType !== "studio", // Via SSML <prosody pitch>; Studio voices lack it
                 supportsRate: true, // ✅ Via SSML <prosody rate>
                 supportsVolume: false, // ❌ Not supported (handle client-side)
-                supportsMultipleVoices: true, // ✅ 200+ voices across 50+ languages
+                supportsMultipleVoices: true, // ✅ Listed by getVoices
                 maxTextLength: 5000, // Google Cloud TTS limit per request
             },
             // Provider-specific extensions
@@ -428,8 +438,6 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
                 // Google Cloud-specific features
                 providerSpecific: {
                     voiceTypes: ["standard", "wavenet", "studio"],
-                    voicesCount: 200, // ~200+ voices available
-                    languagesCount: 50, // 50+ languages supported
                     supportsAudioProfiles: true, // Audio device profiles
                     supportsEffects: false, // No built-in effects
                     supportsEmotions: false, // No emotion control
@@ -442,21 +450,17 @@ export class GoogleCloudTTSProvider extends BaseTTSProvider {
      * Map Google Cloud errors to TTSError codes
      */
     mapGoogleErrorToTTSError(error) {
-        const message = error.message || String(error);
-        // Check for specific Google Cloud error codes
-        if (error.code === 7) {
-            // PERMISSION_DENIED
+        const err = error;
+        const message = err.message || String(error);
+        if (err.code === GRPC_STATUS.PERMISSION_DENIED) {
             return new TTSError(TTSErrorCode.AUTHENTICATION_ERROR, `Google Cloud authentication failed: ${message}`, { error }, this.providerId);
         }
-        if (error.code === 8) {
-            // RESOURCE_EXHAUSTED
+        if (err.code === GRPC_STATUS.RESOURCE_EXHAUSTED) {
             return new TTSError(TTSErrorCode.RATE_LIMIT_EXCEEDED, `Google Cloud rate limit exceeded: ${message}`, { error }, this.providerId);
         }
-        if (error.code === 3) {
-            // INVALID_ARGUMENT
+        if (err.code === GRPC_STATUS.INVALID_ARGUMENT) {
             return new TTSError(TTSErrorCode.INVALID_REQUEST, `Invalid request to Google Cloud TTS: ${message}`, { error }, this.providerId);
         }
-        // Default to provider error
         return new TTSError(TTSErrorCode.PROVIDER_ERROR, `Google Cloud TTS error: ${message}`, { error }, this.providerId);
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/tts-server-google",
-	"version": "0.3.75",
+	"version": "1.0.0-beta.1",
 	"description": "Google Cloud Text-to-Speech 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",
@@ -40,7 +39,7 @@
 	},
 	"dependencies": {
 		"@google-cloud/text-to-speech": "^7.1.1",
-		"@pie-players/tts-server-core": "0.3.75"
+		"@pie-players/tts-server-core": "1.0.0-beta.1"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",