@mastra/voice-google 0.12.0-beta.0 → 0.12.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @mastra/voice-google
 
+## 0.12.0-beta.2
+
+### Patch Changes
+
+- Add embedded documentation support for Mastra packages ([#11472](https://github.com/mastra-ai/mastra/pull/11472))
+
+  Mastra packages now include embedded documentation in the published npm package under `dist/docs/`. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from `node_modules`.
+
+  Each package includes:
+  - **SKILL.md** - Entry point explaining the package's purpose and capabilities
+  - **SOURCE_MAP.json** - Machine-readable index mapping exports to types and implementation files
+  - **Topic folders** - Conceptual documentation organized by feature area
+
+  Documentation is driven by the `packages` frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
+
+- Updated dependencies [[`d2d3e22`](https://github.com/mastra-ai/mastra/commit/d2d3e22a419ee243f8812a84e3453dd44365ecb0), [`bc72b52`](https://github.com/mastra-ai/mastra/commit/bc72b529ee4478fe89ecd85a8be47ce0127b82a0), [`05b8bee`](https://github.com/mastra-ai/mastra/commit/05b8bee9e50e6c2a4a2bf210eca25ee212ca24fa), [`c042bd0`](https://github.com/mastra-ai/mastra/commit/c042bd0b743e0e86199d0cb83344ca7690e34a9c), [`940a2b2`](https://github.com/mastra-ai/mastra/commit/940a2b27480626ed7e74f55806dcd2181c1dd0c2), [`e0941c3`](https://github.com/mastra-ai/mastra/commit/e0941c3d7fc75695d5d258e7008fd5d6e650800c), [`0c0580a`](https://github.com/mastra-ai/mastra/commit/0c0580a42f697cd2a7d5973f25bfe7da9055038a), [`28f5f89`](https://github.com/mastra-ai/mastra/commit/28f5f89705f2409921e3c45178796c0e0d0bbb64), [`e601b27`](https://github.com/mastra-ai/mastra/commit/e601b272c70f3a5ecca610373aa6223012704892), [`3d3366f`](https://github.com/mastra-ai/mastra/commit/3d3366f31683e7137d126a3a57174a222c5801fb), [`5a4953f`](https://github.com/mastra-ai/mastra/commit/5a4953f7d25bb15ca31ed16038092a39cb3f98b3), [`eb9e522`](https://github.com/mastra-ai/mastra/commit/eb9e522ce3070a405e5b949b7bf5609ca51d7fe2), [`20e6f19`](https://github.com/mastra-ai/mastra/commit/20e6f1971d51d3ff6dd7accad8aaaae826d540ed), [`4f0b3c6`](https://github.com/mastra-ai/mastra/commit/4f0b3c66f196c06448487f680ccbb614d281e2f7), [`74c4f22`](https://github.com/mastra-ai/mastra/commit/74c4f22ed4c71e72598eacc346ba95cdbc00294f), [`81b6a8f`](https://github.com/mastra-ai/mastra/commit/81b6a8ff79f49a7549d15d66624ac1a0b8f5f971), [`e4d366a`](https://github.com/mastra-ai/mastra/commit/e4d366aeb500371dd4210d6aa8361a4c21d87034), [`a4f010b`](https://github.com/mastra-ai/mastra/commit/a4f010b22e4355a5fdee70a1fe0f6e4a692cc29e), [`73b0bb3`](https://github.com/mastra-ai/mastra/commit/73b0bb394dba7c9482eb467a97ab283dbc0ef4db), [`5627a8c`](https://github.com/mastra-ai/mastra/commit/5627a8c6dc11fe3711b3fa7a6ffd6eb34100a306), [`3ff45d1`](https://github.com/mastra-ai/mastra/commit/3ff45d10e0c80c5335a957ab563da72feb623520), [`251df45`](https://github.com/mastra-ai/mastra/commit/251df4531407dfa46d805feb40ff3fb49769f455), [`f894d14`](https://github.com/mastra-ai/mastra/commit/f894d148946629af7b1f452d65a9cf864cec3765), [`c2b9547`](https://github.com/mastra-ai/mastra/commit/c2b9547bf435f56339f23625a743b2147ab1c7a6), [`580b592`](https://github.com/mastra-ai/mastra/commit/580b5927afc82fe460dfdf9a38a902511b6b7e7f), [`58e3931`](https://github.com/mastra-ai/mastra/commit/58e3931af9baa5921688566210f00fb0c10479fa), [`08bb631`](https://github.com/mastra-ai/mastra/commit/08bb631ae2b14684b2678e3549d0b399a6f0561e), [`4fba91b`](https://github.com/mastra-ai/mastra/commit/4fba91bec7c95911dc28e369437596b152b04cd0), [`12b0cc4`](https://github.com/mastra-ai/mastra/commit/12b0cc4077d886b1a552637dedb70a7ade93528c)]:
+  - @mastra/core@1.0.0-beta.20
+
+## 0.12.0-beta.1
+
+### Minor Changes
+
+- Add Vertex AI support to GoogleVoice provider ([#10661](https://github.com/mastra-ai/mastra/pull/10661))
+  - Add `vertexAI`, `project`, and `location` configuration options
+  - Support Vertex AI authentication via project ID and service accounts
+  - Add helper methods: `isUsingVertexAI()`, `getProject()`, `getLocation()`
+  - Support `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` environment variables
+  - Update README with Vertex AI usage examples
+
+  This makes `@mastra/voice-google` consistent with `@mastra/voice-google-gemini-live` and enables enterprise deployments using Google Cloud project-based authentication instead of API keys.
+
+### Patch Changes
+
+- Updated dependencies [[`ac0d2f4`](https://github.com/mastra-ai/mastra/commit/ac0d2f4ff8831f72c1c66c2be809706d17f65789), [`1a0d3fc`](https://github.com/mastra-ai/mastra/commit/1a0d3fc811482c9c376cdf79ee615c23bae9b2d6), [`85a628b`](https://github.com/mastra-ai/mastra/commit/85a628b1224a8f64cd82ea7f033774bf22df7a7e), [`c237233`](https://github.com/mastra-ai/mastra/commit/c23723399ccedf7f5744b3f40997b79246bfbe64), [`15f9e21`](https://github.com/mastra-ai/mastra/commit/15f9e216177201ea6e3f6d0bfb063fcc0953444f), [`ff94dea`](https://github.com/mastra-ai/mastra/commit/ff94dea935f4e34545c63bcb6c29804732698809), [`5b2ff46`](https://github.com/mastra-ai/mastra/commit/5b2ff4651df70c146523a7fca773f8eb0a2272f8), [`db41688`](https://github.com/mastra-ai/mastra/commit/db4168806d007417e2e60b4f68656dca4e5f40c9), [`5ca599d`](https://github.com/mastra-ai/mastra/commit/5ca599d0bb59a1595f19f58473fcd67cc71cef58), [`bff1145`](https://github.com/mastra-ai/mastra/commit/bff114556b3cbadad9b2768488708f8ad0e91475), [`5c8ca24`](https://github.com/mastra-ai/mastra/commit/5c8ca247094e0cc2cdbd7137822fb47241f86e77), [`e191844`](https://github.com/mastra-ai/mastra/commit/e1918444ca3f80e82feef1dad506cd4ec6e2875f), [`22553f1`](https://github.com/mastra-ai/mastra/commit/22553f11c63ee5e966a9c034a349822249584691), [`7237163`](https://github.com/mastra-ai/mastra/commit/72371635dbf96a87df4b073cc48fc655afbdce3d), [`2500740`](https://github.com/mastra-ai/mastra/commit/2500740ea23da067d6e50ec71c625ab3ce275e64), [`873ecbb`](https://github.com/mastra-ai/mastra/commit/873ecbb517586aa17d2f1e99283755b3ebb2863f), [`4f9bbe5`](https://github.com/mastra-ai/mastra/commit/4f9bbe5968f42c86f4930b8193de3c3c17e5bd36), [`02e51fe`](https://github.com/mastra-ai/mastra/commit/02e51feddb3d4155cfbcc42624fd0d0970d032c0), [`8f3fa3a`](https://github.com/mastra-ai/mastra/commit/8f3fa3a652bb77da092f913ec51ae46e3a7e27dc), [`cd29ad2`](https://github.com/mastra-ai/mastra/commit/cd29ad23a255534e8191f249593849ed29160886), [`bdf4d8c`](https://github.com/mastra-ai/mastra/commit/bdf4d8cdc656d8a2c21d81834bfa3bfa70f56c16), [`854e3da`](https://github.com/mastra-ai/mastra/commit/854e3dad5daac17a91a20986399d3a51f54bf68b), [`ce18d38`](https://github.com/mastra-ai/mastra/commit/ce18d38678c65870350d123955014a8432075fd9), [`cccf9c8`](https://github.com/mastra-ai/mastra/commit/cccf9c8b2d2dfc1a5e63919395b83d78c89682a0), [`61a5705`](https://github.com/mastra-ai/mastra/commit/61a570551278b6743e64243b3ce7d73de915ca8a), [`db70a48`](https://github.com/mastra-ai/mastra/commit/db70a48aeeeeb8e5f92007e8ede52c364ce15287), [`f0fdc14`](https://github.com/mastra-ai/mastra/commit/f0fdc14ee233d619266b3d2bbdeea7d25cfc6d13), [`db18bc9`](https://github.com/mastra-ai/mastra/commit/db18bc9c3825e2c1a0ad9a183cc9935f6691bfa1), [`9b37b56`](https://github.com/mastra-ai/mastra/commit/9b37b565e1f2a76c24f728945cc740c2b09be9da), [`41a23c3`](https://github.com/mastra-ai/mastra/commit/41a23c32f9877d71810f37e24930515df2ff7a0f), [`5d171ad`](https://github.com/mastra-ai/mastra/commit/5d171ad9ef340387276b77c2bb3e83e83332d729), [`f03ae60`](https://github.com/mastra-ai/mastra/commit/f03ae60500fe350c9d828621006cdafe1975fdd8), [`d1e74a0`](https://github.com/mastra-ai/mastra/commit/d1e74a0a293866dece31022047f5dbab65a304d0), [`39e7869`](https://github.com/mastra-ai/mastra/commit/39e7869bc7d0ee391077ce291474d8a84eedccff), [`5761926`](https://github.com/mastra-ai/mastra/commit/57619260c4a2cdd598763abbacd90de594c6bc76), [`c900fdd`](https://github.com/mastra-ai/mastra/commit/c900fdd504c41348efdffb205cfe80d48c38fa33), [`604a79f`](https://github.com/mastra-ai/mastra/commit/604a79fecf276e26a54a3fe01bb94e65315d2e0e), [`887f0b4`](https://github.com/mastra-ai/mastra/commit/887f0b4746cdbd7cb7d6b17ac9f82aeb58037ea5), [`2562143`](https://github.com/mastra-ai/mastra/commit/256214336b4faa78646c9c1776612393790d8784), [`ef11a61`](https://github.com/mastra-ai/mastra/commit/ef11a61920fa0ed08a5b7ceedd192875af119749)]:
+  - @mastra/core@1.0.0-beta.6
+
 ## 0.12.0-beta.0
 
 ### Minor Changes

package/README.md

@@ -12,16 +12,50 @@ npm install @mastra/voice-google
 
 ## Configuration
 
-You can authenticate in one of the following ways:
+The module supports multiple authentication methods:
+
+### Option 1: API Key (Development)
+
+Use an API key from [Google Cloud Console](https://console.cloud.google.com/apis/credentials):
 
 ```bash
 GOOGLE_API_KEY=your_api_key
-# or provide a service account key picked up by ADC
+```
+
+### Option 2: Service Account (Recommended)
+
+Use a service account key file:
+
+```bash
 GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
 ```
 
+### Option 3: Vertex AI (Recommended for Production)
+
+Use OAuth authentication with Google Cloud Platform for enterprise deployments:
+
+```bash
+# Set project ID
+GOOGLE_CLOUD_PROJECT=your_project_id
+
+# Optional: Set location (defaults to us-central1)
+GOOGLE_CLOUD_LOCATION=us-central1
+
+# Authenticate via gcloud CLI
+gcloud auth application-default login
+```
+
+Or use a service account:
+
+```bash
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+GOOGLE_CLOUD_PROJECT=your_project_id
+```
+
 ## Usage
 
+### Standard Usage
+
 ```typescript
 import { GoogleVoice } from '@mastra/voice-google';
 
@@ -50,6 +84,129 @@ const audioStream = await voice.speak('Hello from Mastra!', {
 const text = await voice.listen(audioStream);
 ```
 
+### Vertex AI Mode
+
+For enterprise deployments, use Vertex AI mode which provides better integration with Google Cloud infrastructure:
+
+```typescript
+import { GoogleVoice } from '@mastra/voice-google';
+
+// Initialize with Vertex AI
+const voice = new GoogleVoice({
+  vertexAI: true,
+  project: 'your-gcp-project',
+  location: 'us-central1', // Optional, defaults to 'us-central1'
+  speaker: 'en-US-Studio-O',
+});
+
+// Works the same as standard mode
+const audioStream = await voice.speak('Hello from Vertex AI!');
+const text = await voice.listen(audioStream);
+
+// Check if using Vertex AI
+console.log(voice.isUsingVertexAI()); // true
+console.log(voice.getProject()); // 'your-gcp-project'
+console.log(voice.getLocation()); // 'us-central1'
+```
+
+### Vertex AI with Service Account
+
+```typescript
+import { GoogleVoice } from '@mastra/voice-google';
+
+const voice = new GoogleVoice({
+  vertexAI: true,
+  project: 'your-gcp-project',
+  location: 'us-central1',
+  speechModel: {
+    keyFilename: '/path/to/service-account.json',
+  },
+  listeningModel: {
+    keyFilename: '/path/to/service-account.json',
+  },
+});
+```
+
+### Vertex AI with In-Memory Credentials
+
+```typescript
+import { GoogleVoice } from '@mastra/voice-google';
+
+const voice = new GoogleVoice({
+  vertexAI: true,
+  project: 'your-gcp-project',
+  speechModel: {
+    credentials: {
+      client_email: 'service-account@project.iam.gserviceaccount.com',
+      private_key: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
+    },
+  },
+});
+```
+
+## API Reference
+
+### Constructor Options
+
+| Option           | Type                | Description                                      |
+| ---------------- | ------------------- | ------------------------------------------------ |
+| `speechModel`    | `GoogleModelConfig` | Configuration for TTS                            |
+| `listeningModel` | `GoogleModelConfig` | Configuration for STT                            |
+| `speaker`        | `string`            | Default voice ID (default: `'en-US-Casual-K'`)   |
+| `vertexAI`       | `boolean`           | Enable Vertex AI mode (default: `false`)         |
+| `project`        | `string`            | Google Cloud project ID (required for Vertex AI) |
+| `location`       | `string`            | Google Cloud region (default: `'us-central1'`)   |
+
+### GoogleModelConfig
+
+| Option        | Type     | Description                           |
+| ------------- | -------- | ------------------------------------- |
+| `apiKey`      | `string` | Google Cloud API key                  |
+| `keyFilename` | `string` | Path to service account JSON key file |
+| `credentials` | `object` | In-memory service account credentials |
+
+### Methods
+
+#### `speak(input, options?)`
+
+Converts text to speech.
+
+- `input`: `string | NodeJS.ReadableStream` - Text to convert
+- `options.speaker`: Override default voice
+- `options.languageCode`: Language code (e.g., `'en-US'`)
+- `options.audioConfig`: Audio encoding options
+
+Returns: `Promise<NodeJS.ReadableStream>` - Audio stream
+
+#### `listen(audioStream, options?)`
+
+Converts speech to text.
+
+- `audioStream`: `NodeJS.ReadableStream` - Audio to transcribe
+- `options.config`: Recognition configuration
+
+Returns: `Promise<string>` - Transcribed text
+
+#### `getSpeakers(options?)`
+
+Lists available voices.
+
+- `options.languageCode`: Filter by language (default: `'en-US'`)
+
+Returns: `Promise<Array<{ voiceId: string, languageCodes: string[] }>>`
+
+#### `isUsingVertexAI()`
+
+Returns `true` if Vertex AI mode is enabled.
+
+#### `getProject()`
+
+Returns the configured Google Cloud project ID.
+
+#### `getLocation()`
+
+Returns the configured Google Cloud location/region.
+
 ## Features
 
 - Neural Text-to-Speech synthesis
@@ -58,6 +215,35 @@ const text = await voice.listen(audioStream);
 - Streaming support for both speech and transcription
 - High-quality audio processing
 - Natural-sounding voice synthesis
+- **Vertex AI support for enterprise deployments**
+
+## Required Permissions for Vertex AI
+
+When using Vertex AI, ensure your service account or user has the appropriate IAM roles and OAuth scopes:
+
+### IAM Roles
+
+**For Text-to-Speech:**
+
+- `roles/texttospeech.admin` - Text-to-Speech Admin (full access)
+- `roles/texttospeech.editor` - Text-to-Speech Editor (create and manage)
+- `roles/texttospeech.viewer` - Text-to-Speech Viewer (read-only)
+
+**For Speech-to-Text:**
+
+- `roles/speech.client` - Speech-to-Text Client
+
+### OAuth Scopes
+
+**For synchronous Text-to-Speech synthesis:**
+
+- `https://www.googleapis.com/auth/cloud-platform` - Full access to Google Cloud Platform services
+
+**For long-audio Text-to-Speech operations:**
+
+- `locations.longAudioSynthesize` - Create long-audio synthesis operations
+- `operations.get` - Get operation status
+- `operations.list` - List operations
 
 ## Voice Options
 

package/dist/docs/README.md

@@ -0,0 +1,32 @@
+# @mastra/voice-google Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── agents/ (1 files)
+├── voice/ (2 files)
+```
+
+## Version
+
+Package: @mastra/voice-google
+Version: 0.12.0-beta.2

package/dist/docs/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mastra-voice-google-docs
+description: Documentation for @mastra/voice-google. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/voice-google Documentation
+
+> **Version**: 0.12.0-beta.2
+> **Package**: @mastra/voice-google
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Agents](agents/) - 1 file(s)
+- [Voice](voice/) - 2 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.12.0-beta.2",
+  "package": "@mastra/voice-google",
+  "exports": {},
+  "modules": {}
+}