@mastra/voice-google 0.14.0 → 0.14.1

package/dist/docs/references/reference-voice-google.md

@@ -1,274 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Google
-
-The Google Voice implementation in Mastra provides both text-to-speech (TTS) and speech-to-text (STT) capabilities using Google Cloud services. It supports multiple voices, languages, advanced audio configuration options, and both standard API key authentication and Vertex AI mode for enterprise deployments.
-
-## Usage example
-
-```typescript
-import { GoogleVoice } from '@mastra/voice-google'
-
-// Initialize with default configuration (uses GOOGLE_API_KEY environment variable)
-const voice = new GoogleVoice()
-
-// Text-to-Speech (plain text)
-const audioStream = await voice.speak('Hello, world!', {
-  languageCode: 'en-US',
-  audioConfig: {
-    audioEncoding: 'LINEAR16',
-  },
-})
-
-// Text-to-Speech with SSML
-const ssmlStream = await voice.speak('ignored', {
-  input: {
-    ssml: '<speak>Take <say-as interpret-as="unit">5 mg</say-as> daily.</speak>',
-  },
-})
-
-// Text-to-Speech with Gemini-TTS model
-const geminiStream = await voice.speak('Hello from Gemini TTS!', {
-  voice: { name: 'Kore', modelName: 'gemini-2.5-flash-preview-tts' },
-  input: { prompt: 'Warm, calm tone.' },
-})
-
-// Speech-to-Text
-const transcript = await voice.listen(audioStream, {
-  config: {
-    encoding: 'LINEAR16',
-    languageCode: 'en-US',
-  },
-})
-
-// Get available voices for a specific language
-const voices = await voice.getSpeakers({ languageCode: 'en-US' })
-```
-
-## Constructor parameters
-
-**speechModel** (`GoogleModelConfig`): Configuration for text-to-speech functionality (Default: `{ apiKey: process.env.GOOGLE_API_KEY }`)
-
-**speechModel.apiKey** (`string`): Google Cloud API key. Falls back to GOOGLE\_API\_KEY environment variable. Not used when vertexAI is true.
-
-**speechModel.keyFilename** (`string`): Path to service account JSON key file. Falls back to GOOGLE\_APPLICATION\_CREDENTIALS environment variable.
-
-**speechModel.credentials** (`object`): In-memory service account credentials object with client\_email and private\_key properties.
-
-**listeningModel** (`GoogleModelConfig`): Configuration for speech-to-text functionality (Default: `{ apiKey: process.env.GOOGLE_API_KEY }`)
-
-**listeningModel.apiKey** (`string`): Google Cloud API key. Falls back to GOOGLE\_API\_KEY environment variable. Not used when vertexAI is true.
-
-**listeningModel.keyFilename** (`string`): Path to service account JSON key file. Falls back to GOOGLE\_APPLICATION\_CREDENTIALS environment variable.
-
-**listeningModel.credentials** (`object`): In-memory service account credentials object with client\_email and private\_key properties.
-
-**speaker** (`string`): Default voice ID to use for text-to-speech (Default: `'en-US-Casual-K'`)
-
-**vertexAI** (`boolean`): Enable Vertex AI mode for enterprise deployments. Uses project-based authentication instead of API keys. Requires 'project' to be set. (Default: `false`)
-
-**project** (`string`): Google Cloud project ID (required when vertexAI is true). Falls back to GOOGLE\_CLOUD\_PROJECT environment variable.
-
-**location** (`string`): Google Cloud region for Vertex AI. Falls back to GOOGLE\_CLOUD\_LOCATION environment variable. (Default: `'us-central1'`)
-
-## Methods
-
-### `speak()`
-
-Converts text to speech using Google Cloud Text-to-Speech service.
-
-**input** (`string | NodeJS.ReadableStream`): Text to convert to speech. If a stream is provided, it will be converted to text first.
-
-**options** (`object`): Speech synthesis options
-
-**options.speaker** (`string`): Voice ID to use for this request.
-
-**options.languageCode** (`string`): Language code for the voice (e.g., 'en-US'). Defaults to the language code derived from the speaker ID, or 'en-US'.
-
-**options.input** (`ISynthesizeSpeechRequest['input']`): Rich input object passed through to the Google Cloud TTS API. Supports ssml, markup, prompt (Gemini-TTS style steering), customPronunciations, and multiSpeakerMarkup. When provided without text, ssml, markup, or multiSpeakerMarkup, the positional input argument is used as the text field automatically.
-
-**options.voice** (`ISynthesizeSpeechRequest['voice']`): Voice configuration merged on top of defaults (name and languageCode). Supports modelName (e.g., 'gemini-2.5-flash-preview-tts') and multiSpeakerVoiceConfig.
-
-**options.audioConfig** (`ISynthesizeSpeechRequest['audioConfig']`): Audio configuration options from Google Cloud Text-to-Speech API.
-
-Returns: `Promise<NodeJS.ReadableStream>`
-
-### `listen()`
-
-Converts speech to text using Google Cloud Speech-to-Text service. Supports both v1 (default) and v2 APIs. The v2 API adds support for AAC-in-MP4 audio (iOS Safari) via auto-decoding.
-
-#### v1 (default)
-
-**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
-
-**options** (`GoogleListenOptionsV1`): v1 recognition options
-
-**options.config** (`IRecognitionConfig`): v1 recognition configuration from Google Cloud Speech-to-Text API
-
-#### v2
-
-Pass `v2: true` to use the Cloud Speech-to-Text v2 API, which supports additional audio formats like AAC-in-MP4 (iOS Safari).
-
-```typescript
-const transcript = await voice.listen(iosSafariAacStream, {
-  v2: true,
-  config: {
-    autoDecodingConfig: {},
-  },
-})
-```
-
-**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
-
-**options** (`GoogleListenOptionsV2`): v2 recognition options
-
-**options.v2** (`true`): Enables the v2 API path
-
-**options.config** (`v2.IRecognitionConfig`): v2 recognition configuration. Defaults to auto-decoding with languageCodes: \['en-US'] and model: 'long'. Set autoDecodingConfig: {} to auto-detect the audio format, or use explicitDecodingConfig to specify an encoding like MP4\_AAC, M4A\_AAC, or MOV\_AAC.
-
-**options.recognizer** (`string`): v2 recognizer resource path. Defaults to projects/{project}/locations/global/recognizers/\_ where {project} is resolved from the constructor project option, GOOGLE\_CLOUD\_PROJECT, or the client's default project.
-
-Returns: `Promise<string>`
-
-### `getSpeakers()`
-
-Returns an array of available voice options, where each node contains:
-
-**voiceId** (`string`): Unique identifier for the voice
-
-**languageCodes** (`string[]`): List of language codes supported by this voice
-
-### `isUsingVertexAI()`
-
-Checks if Vertex AI mode is enabled.
-
-Returns: `boolean` - `true` if using Vertex AI, `false` otherwise
-
-### `getProject()`
-
-Gets the configured Google Cloud project ID.
-
-Returns: `string | undefined` - The project ID or `undefined` if not set
-
-### `getLocation()`
-
-Gets the configured Google Cloud location/region.
-
-Returns: `string` - The location (default: `'us-central1'`)
-
-## Authentication
-
-The Google Voice provider supports two authentication methods:
-
-### Standard Mode (API Key)
-
-Uses a Google Cloud API key for authentication. Suitable for development and basic use cases.
-
-```typescript
-// Using environment variable (GOOGLE_API_KEY)
-const voice = new GoogleVoice()
-
-// Using explicit API key
-const voice = new GoogleVoice({
-  speechModel: { apiKey: 'your-api-key' },
-  listeningModel: { apiKey: 'your-api-key' },
-  speaker: 'en-US-Casual-K',
-})
-```
-
-### Vertex AI Mode (Service Account)
-
-Uses Google Cloud project-based authentication with service accounts. Recommended for production and enterprise deployments.
-
-**Benefits:**
-
-- Better security (no API keys in code)
-- IAM-based access control
-- Project-level billing and quotas
-- Audit logging
-- Enterprise features
-
-**Configuration Options:**
-
-```typescript
-// Using Application Default Credentials (ADC)
-// Set GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT env vars
-const voice = new GoogleVoice({
-  vertexAI: true,
-  project: 'your-gcp-project',
-  location: 'us-central1', // Optional, defaults to 'us-central1'
-})
-
-// Using service account key file
-const voice = new GoogleVoice({
-  vertexAI: true,
-  project: 'your-gcp-project',
-  speechModel: {
-    keyFilename: '/path/to/service-account.json',
-  },
-  listeningModel: {
-    keyFilename: '/path/to/service-account.json',
-  },
-})
-
-// Using in-memory credentials
-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-----',
-    },
-  },
-})
-```
-
-#### Required Permissions
-
-#### 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
-
-## Important notes
-
-1. **Authentication**: Either a Google Cloud API key (standard mode) or service account credentials (Vertex AI mode) is required.
-
-2. **Environment Variables**:
-
-   - `GOOGLE_API_KEY` - API key for standard mode
-   - `GOOGLE_CLOUD_PROJECT` - Project ID for Vertex AI mode
-   - `GOOGLE_CLOUD_LOCATION` - Location for Vertex AI mode (defaults to 'us-central1')
-   - `GOOGLE_APPLICATION_CREDENTIALS` - Path to service account key file
-
-3. The default voice is set to `'en-US-Casual-K'`.
-
-4. Both text-to-speech and speech-to-text services use LINEAR16 as the default audio encoding.
-
-5. The `speak()` method supports advanced audio configuration through the Google Cloud Text-to-Speech API.
-
-6. The `listen()` method supports various recognition configurations through the Google Cloud Speech-to-Text API.
-
-7. Available voices can be filtered by language code using the `getSpeakers()` method.
-
-8. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.