@mastra/voice-google 0.12.0 → 0.12.1

package/dist/docs/{voice/02-reference.md → references/reference-voice-google.md}

@@ -1,79 +1,114 @@
-# Voice API Reference
-
-> API reference for voice - 1 entries
-
-
----
-
-## Reference: Google
-
-> Documentation for the Google Voice implementation, providing text-to-speech and speech-to-text capabilities with support for both API key and Vertex AI authentication.
+# 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
+## Usage example
 
 ```typescript
-import { GoogleVoice } from "@mastra/voice-google";
+import { GoogleVoice } from '@mastra/voice-google'
 
 // Initialize with default configuration (uses GOOGLE_API_KEY environment variable)
-const voice = new GoogleVoice();
+const voice = new GoogleVoice()
 
 // Text-to-Speech
-const audioStream = await voice.speak("Hello, world!", {
-  languageCode: "en-US",
+const audioStream = await voice.speak('Hello, world!', {
+  languageCode: 'en-US',
   audioConfig: {
-    audioEncoding: "LINEAR16",
+    audioEncoding: 'LINEAR16',
   },
-});
+})
 
 // Speech-to-Text
 const transcript = await voice.listen(audioStream, {
   config: {
-    encoding: "LINEAR16",
-    languageCode: "en-US",
+    encoding: 'LINEAR16',
+    languageCode: 'en-US',
   },
-});
+})
 
 // Get available voices for a specific language
-const voices = await voice.getSpeakers({ languageCode: "en-US" });
+const voices = await voice.getSpeakers({ languageCode: 'en-US' })
 ```
 
-## Constructor Parameters
+## 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 }`)
 
-### GoogleModelConfig
+**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()
+### `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 from the speaker ID or 'en-US'
+
+**options.audioConfig** (`ISynthesizeSpeechRequest['audioConfig']`): Audio configuration options from Google Cloud Text-to-Speech API
+
 Returns: `Promise<NodeJS.ReadableStream>`
 
-### listen()
+### `listen()`
 
 Converts speech to text using Google Cloud Speech-to-Text service.
 
+**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
+
+**options** (`object`): Recognition options
+
+**options.stream** (`boolean`): Whether to use streaming recognition
+
+**options.config** (`IRecognitionConfig`): Recognition configuration from Google Cloud Speech-to-Text API
+
 Returns: `Promise<string>`
 
-### getSpeakers()
+### `getSpeakers()`
 
 Returns an array of available voice options, where each node contains:
 
-### isUsingVertexAI()
+**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()
+### `getProject()`
 
 Gets the configured Google Cloud project ID.
 
 Returns: `string | undefined` - The project ID or `undefined` if not set
 
-### getLocation()
+### `getLocation()`
 
 Gets the configured Google Cloud location/region.
 
@@ -85,18 +120,18 @@ The Google Voice provider supports two authentication methods:
 
 ### Standard Mode (API Key)
 
-Uses a Google Cloud API key for authentication. Suitable for development and simple use cases.
+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();
+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",
-});
+  speechModel: { apiKey: 'your-api-key' },
+  listeningModel: { apiKey: 'your-api-key' },
+  speaker: 'en-US-Casual-K',
+})
 ```
 
 ### Vertex AI Mode (Service Account)
@@ -104,6 +139,7 @@ const voice = new GoogleVoice({
 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
@@ -117,68 +153,80 @@ Uses Google Cloud project-based authentication with service accounts. Recommende
 // 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'
-});
+  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",
+  project: 'your-gcp-project',
   speechModel: {
-    keyFilename: "/path/to/service-account.json",
+    keyFilename: '/path/to/service-account.json',
   },
   listeningModel: {
-    keyFilename: "/path/to/service-account.json",
+    keyFilename: '/path/to/service-account.json',
   },
-});
+})
 
 // Using in-memory credentials
 const voice = new GoogleVoice({
   vertexAI: true,
-  project: "your-gcp-project",
+  project: 'your-gcp-project',
   speechModel: {
     credentials: {
-      client_email: "service-account@project.iam.gserviceaccount.com",
-      private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
+      client_email: 'service-account@project.iam.gserviceaccount.com',
+      private_key: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
     },
   },
-});
+})
 ```
 
-**Required Permissions:**
+#### Required Permissions
 
-**IAM Roles:**
+#### 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:**
+#### 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
+## 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.

package/dist/index.cjs

@@ -3,7 +3,267 @@
 var stream = require('stream');
 var speech = require('@google-cloud/speech');
 var textToSpeech = require('@google-cloud/text-to-speech');
-var voice = require('@mastra/core/voice');
+
+// src/index.ts
+
+// ../../packages/_internal-core/dist/chunk-HDURQPU2.js
+var RegisteredLogger = {
+  LLM: "LLM"};
+var LogLevel = {
+  DEBUG: "debug",
+  INFO: "info",
+  WARN: "warn",
+  ERROR: "error"};
+var MastraLogger = class {
+  name;
+  level;
+  transports;
+  constructor(options = {}) {
+    this.name = options.name || "Mastra";
+    this.level = options.level || LogLevel.ERROR;
+    this.transports = new Map(Object.entries(options.transports || {}));
+  }
+  getTransports() {
+    return this.transports;
+  }
+  trackException(_error, _metadata) {
+  }
+  async listLogs(transportId, params) {
+    if (!transportId || !this.transports.has(transportId)) {
+      return { logs: [], total: 0, page: params?.page ?? 1, perPage: params?.perPage ?? 100, hasMore: false };
+    }
+    return this.transports.get(transportId).listLogs?.(params) ?? {
+      logs: [],
+      total: 0,
+      page: params?.page ?? 1,
+      perPage: params?.perPage ?? 100,
+      hasMore: false
+    };
+  }
+  async listLogsByRunId({
+    transportId,
+    runId,
+    fromDate,
+    toDate,
+    logLevel,
+    filters,
+    page,
+    perPage
+  }) {
+    if (!transportId || !this.transports.has(transportId) || !runId) {
+      return { logs: [], total: 0, page: page ?? 1, perPage: perPage ?? 100, hasMore: false };
+    }
+    return this.transports.get(transportId).listLogsByRunId?.({ runId, fromDate, toDate, logLevel, filters, page, perPage }) ?? {
+      logs: [],
+      total: 0,
+      page: page ?? 1,
+      perPage: perPage ?? 100,
+      hasMore: false
+    };
+  }
+};
+var ConsoleLogger = class _ConsoleLogger extends MastraLogger {
+  component;
+  filter;
+  constructor(options = {}) {
+    super(options);
+    this.component = options.component;
+    this.filter = options.filter;
+  }
+  child(componentOrBindings) {
+    const component = typeof componentOrBindings === "string" ? componentOrBindings : componentOrBindings?.component ?? this.component;
+    return new _ConsoleLogger({
+      name: this.name,
+      level: this.level,
+      component,
+      filter: this.filter
+    });
+  }
+  shouldLog(level, message, args) {
+    if (!this.filter) return true;
+    try {
+      return this.filter({ component: this.component, level, message, args });
+    } catch (e) {
+      console.error(`[Logger] Filter error for component=${this.component} level=${level}:`, e);
+      return true;
+    }
+  }
+  prefix() {
+    return this.component ? `[${this.component}] ` : "";
+  }
+  debug(message, ...args) {
+    if (this.level === LogLevel.DEBUG && this.shouldLog(LogLevel.DEBUG, message, args)) {
+      console.info(`${this.prefix()}${message}`, ...args);
+    }
+  }
+  info(message, ...args) {
+    if ((this.level === LogLevel.INFO || this.level === LogLevel.DEBUG) && this.shouldLog(LogLevel.INFO, message, args)) {
+      console.info(`${this.prefix()}${message}`, ...args);
+    }
+  }
+  warn(message, ...args) {
+    if ((this.level === LogLevel.WARN || this.level === LogLevel.INFO || this.level === LogLevel.DEBUG) && this.shouldLog(LogLevel.WARN, message, args)) {
+      console.info(`${this.prefix()}${message}`, ...args);
+    }
+  }
+  error(message, ...args) {
+    if ((this.level === LogLevel.ERROR || this.level === LogLevel.WARN || this.level === LogLevel.INFO || this.level === LogLevel.DEBUG) && this.shouldLog(LogLevel.ERROR, message, args)) {
+      console.error(`${this.prefix()}${message}`, ...args);
+    }
+  }
+  async listLogs(_transportId, _params) {
+    return { logs: [], total: 0, page: _params?.page ?? 1, perPage: _params?.perPage ?? 100, hasMore: false };
+  }
+  async listLogsByRunId(_args) {
+    return { logs: [], total: 0, page: _args.page ?? 1, perPage: _args.perPage ?? 100, hasMore: false };
+  }
+};
+
+// ../../packages/_internal-core/dist/base/index.js
+var MastraBase = class {
+  component = RegisteredLogger.LLM;
+  logger;
+  name;
+  #rawConfig;
+  constructor({
+    component,
+    name,
+    rawConfig
+  }) {
+    this.component = component || RegisteredLogger.LLM;
+    this.name = name;
+    this.#rawConfig = rawConfig;
+    this.logger = new ConsoleLogger({ name: `${this.component} - ${this.name}` });
+  }
+  /**
+   * Returns the raw storage configuration this primitive was created from,
+   * or undefined if it was created from code.
+   */
+  toRawConfig() {
+    return this.#rawConfig;
+  }
+  /**
+   * Sets the raw storage configuration for this primitive.
+   * @internal
+   */
+  __setRawConfig(rawConfig) {
+    this.#rawConfig = rawConfig;
+  }
+  /**
+   * Set the logger for the agent
+   * @param logger
+   */
+  __setLogger(logger) {
+    this.logger = "child" in logger && typeof logger.child === "function" ? logger.child({ component: this.component }) : logger;
+  }
+};
+
+// ../../packages/_internals/voice/dist/chunk-NWNKSBZV.js
+var MastraVoice = class extends MastraBase {
+  listeningModel;
+  speechModel;
+  speaker;
+  realtimeConfig;
+  constructor({ listeningModel, speechModel, speaker, realtimeConfig, name } = {}) {
+    super({
+      component: "VOICE",
+      name
+    });
+    this.listeningModel = listeningModel;
+    this.speechModel = speechModel;
+    this.speaker = speaker;
+    this.realtimeConfig = realtimeConfig;
+  }
+  /**
+   * Custom serialization for tracing/observability spans.
+   * Excludes `apiKey` from listeningModel / speechModel / realtimeConfig
+   * and any provider-specific state held by subclasses. Subclasses that
+   * need to expose additional non-sensitive fields can override.
+   */
+  serializeForSpan() {
+    return {
+      component: "VOICE",
+      name: this.name,
+      speaker: this.speaker,
+      listeningModel: this.listeningModel ? { name: this.listeningModel.name } : void 0,
+      speechModel: this.speechModel ? { name: this.speechModel.name } : void 0,
+      realtimeModel: this.realtimeConfig?.model
+    };
+  }
+  updateConfig(_options) {
+    this.logger.debug("updateConfig not implemented by this voice provider");
+  }
+  /**
+   * Initializes a WebSocket or WebRTC connection for real-time communication
+   * @returns Promise that resolves when the connection is established
+   */
+  async connect(_options) {
+    this.logger.debug("connect not implemented by this voice provider");
+  }
+  /**
+   * Relay audio data to the voice provider for real-time processing
+   * @param audioData Audio data to relay
+   */
+  async send(_audioData) {
+    this.logger.debug("relay not implemented by this voice provider");
+  }
+  /**
+   * Trigger voice providers to respond
+   */
+  async answer(_options) {
+    this.logger.debug("answer not implemented by this voice provider");
+  }
+  /**
+   * Equip the voice provider with instructions
+   * @param instructions Instructions to add
+   */
+  addInstructions(_instructions) {
+  }
+  /**
+   * Equip the voice provider with tools
+   * @param tools Array of tools to add
+   */
+  addTools(_tools) {
+  }
+  /**
+   * Disconnect from the WebSocket or WebRTC connection
+   */
+  close() {
+    this.logger.debug("close not implemented by this voice provider");
+  }
+  /**
+   * Register an event listener
+   * @param event Event name (e.g., 'speaking', 'writing', 'error')
+   * @param callback Callback function that receives event data
+   */
+  on(_event, _callback) {
+    this.logger.debug("on not implemented by this voice provider");
+  }
+  /**
+   * Remove an event listener
+   * @param event Event name (e.g., 'speaking', 'writing', 'error')
+   * @param callback Callback function to remove
+   */
+  off(_event, _callback) {
+    this.logger.debug("off not implemented by this voice provider");
+  }
+  /**
+   * Get available speakers/voices
+   * @returns Array of available voice IDs and their metadata
+   */
+  getSpeakers() {
+    this.logger.debug("getSpeakers not implemented by this voice provider");
+    return Promise.resolve([]);
+  }
+  /**
+   * Get available speakers/voices
+   * @returns Array of available voice IDs and their metadata
+   */
+  getListener() {
+    this.logger.debug("getListener not implemented by this voice provider");
+    return Promise.resolve({ enabled: false });
+  }
+};
 
 // src/index.ts
 var resolveAuthConfig = (modelConfig, fallback, vertexConfig) => {
@@ -45,7 +305,7 @@ var buildAuthOptions = (config, vertexConfig) => {
   return options;
 };
 var DEFAULT_VOICE = "en-US-Casual-K";
-var GoogleVoice = class extends voice.MastraVoice {
+var GoogleVoice = class extends MastraVoice {
   ttsClient;
   speechClient;
   vertexAI;