@mastra/voice-google-gemini-live 0.14.3 → 0.14.4-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/voice-google-gemini-live
 
+## 0.14.4-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`6789ab4`](https://github.com/mastra-ai/mastra/commit/6789ab4191ddcd32a932898b360b191e80cee1a9)]:
+  - @mastra/schema-compat@1.3.4-alpha.0
+
 ## 0.14.3
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-voice-google-gemini-live
 description: Documentation for @mastra/voice-google-gemini-live. Use when working with @mastra/voice-google-gemini-live APIs, configuration, or implementation.
 metadata:
   package: "@mastra/voice-google-gemini-live"
-  version: "0.14.3"
+  version: "0.14.4-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.14.3",
+  "version": "0.14.4-alpha.0",
   "package": "@mastra/voice-google-gemini-live",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-voice-overview.md

@@ -4,9 +4,9 @@
 
 Mastra's Voice system provides a unified interface for voice interactions, enabling text-to-speech (TTS), speech-to-text (STT), and real-time speech-to-speech (STS) capabilities in your applications.
 
-## Adding voice to agents
+## Add voice to agents
 
-To learn how to integrate voice capabilities into your agents, check out the [Adding Voice to Agents](https://mastra.ai/docs/agents/adding-voice) documentation. This section covers how to use both single and multiple voice providers, as well as real-time interactions.
+Pass a voice provider to an agent with the `voice` property. The same property supports text-to-speech (TTS), speech-to-text (STT), and real-time speech-to-speech (STS), depending on the provider you configure.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -1139,7 +1139,7 @@ const voiceAgent = new Agent({
 })
 ```
 
-### Using Multiple Voice Providers
+### Using multiple voice providers
 
 This example demonstrates how to create and use two different voice providers in Mastra: OpenAI for speech-to-text (STT) and PlayAI for text-to-speech (TTS).
 

package/dist/docs/references/docs-voice-speech-to-speech.md

@@ -54,7 +54,87 @@ const micStream = getMicrophoneStream()
 await agent.voice.send(micStream)
 ```
 
-For integrating Speech-to-Speech capabilities with agents, refer to the [Adding Voice to Agents](https://mastra.ai/docs/agents/adding-voice) documentation.
+For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/docs/voice/overview).
+
+## Use tools in realtime sessions
+
+Realtime voice providers can use tools configured on the agent. Add the tools to the `Agent` definition, then connect and send audio through the voice provider:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import { calculate, search } from '../tools'
+
+export const agent = new Agent({
+  id: 'speech-to-speech-agent',
+  name: 'Speech-to-Speech Agent',
+  instructions: 'You are a helpful assistant with speech-to-speech capabilities.',
+  model: 'openai/gpt-5.5',
+  tools: {
+    search,
+    calculate,
+  },
+  voice: new OpenAIRealtimeVoice(),
+})
+```
+
+## Listen for realtime events
+
+Realtime voice providers emit events you can use to update your UI, play assistant audio, log transcriptions, and handle errors:
+
+```typescript
+agent.voice.on('speaking', ({ audio }) => {
+  playAudio(audio)
+})
+
+agent.voice.on('writing', ({ text, role }) => {
+  console.log(`${role}: ${text}`)
+})
+
+agent.voice.on('error', error => {
+  console.error('Voice error:', error)
+})
+```
+
+Event names and payloads vary by provider. Check the provider section below or the provider reference for the full event list.
+
+## Per-session voice instances
+
+A static `voice` instance is shared across every request. This works for one-shot text-to-speech, but real-time and speech-to-speech providers store session state such as the WebSocket connection, tools, instructions, and request context. If one agent handles several live sessions at once, a shared instance can let one session overwrite another session's state.
+
+Provide `voice` as a resolver when each live session needs its own voice instance. Mastra runs the resolver on each `getVoice()` call and returns a fresh instance for that request context:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { RequestContext } from '@mastra/core/request-context'
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+
+export const agent = new Agent({
+  id: 'support-line',
+  name: 'Support Line',
+  instructions: ({ requestContext }) => `Help user ${requestContext.get('user')}.`,
+  model: 'openai/gpt-5.5',
+  voice: ({ requestContext }) =>
+    new OpenAIRealtimeVoice({
+      apiKey: requestContext.get('apiKey'),
+    }),
+})
+
+const requestContext = new RequestContext()
+requestContext.set('user', 'user-123')
+requestContext.set('apiKey', process.env.OPENAI_API_KEY)
+
+const voice = await agent.getVoice({ requestContext })
+await voice.connect()
+```
+
+When you use a resolver:
+
+- Each call to `getVoice()` returns a new instance, so concurrent sessions don't share state.
+- Mastra doesn't add tools or instructions to a resolver instance. Configure them inside the resolver or on the provider.
+- You own the returned instance lifecycle, so call `disconnect()` or `close()` when the session ends.
+
+The `agent.voice` getter has no request context, so it throws when `voice` is a resolver. Use `agent.getVoice({ requestContext })` instead.
 
 ## Google Gemini Live (Realtime)
 

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

@@ -162,7 +162,7 @@ await voice.sendContext([
 await voice.send(micStream)
 ```
 
-**turns** (`IncrementalTurn[]`): Prior conversation turns to seed into the session. Each turn has a \`role\` ("user" or "assistant") and \`content\` string. Both roles are supported on newer models (e.g. \`gemini-2.5-flash-native-audio-preview-12-2025\`). Some older models only accept user-role turns.
+**turns** (`IncrementalTurn[]`): Prior conversation turns to seed into the session. Each turn has a role ("user" or "assistant") and content string. Both roles are supported on newer models (e.g. gemini-2.5-flash-native-audio-preview-12-2025). Some older models only accept user-role turns.
 
 **options** (`object`): Optional configuration.
 
@@ -266,9 +266,9 @@ The GeminiLiveVoice class emits the following events:
 
 **speaking** (`event`): Emitted with audio metadata. Callback receives { audioData?: Int16Array, sampleRate?: number }.
 
-**writing** (`event`): Emitted when transcribed text is available. Callback receives { text: string, role: 'assistant' | 'user' }. On native-audio models the assistant transcript is driven by the server's \`output\_audio\_transcription\` channel rather than \`modelTurn.parts.text\`.
+**writing** (`event`): Emitted when transcribed text is available. Callback receives { text: string, role: 'assistant' | 'user' }. On native-audio models the assistant transcript is driven by the server's output\_audio\_transcription channel rather than modelTurn.parts.text.
 
-**thinking** (`event`): Emitted on native-audio models with the model's chain-of-thought / reasoning text from \`modelTurn.parts.text\`. Callback receives { text: string }. Does not fire on non-native-audio models, where \`modelTurn.parts.text\` is the spoken response and is emitted as \`writing\` instead.
+**thinking** (`event`): Emitted on native-audio models with the model's chain-of-thought / reasoning text from modelTurn.parts.text. Callback receives { text: string }. Does not fire on non-native-audio models, where modelTurn.parts.text is the spoken response and is emitted as writing instead.
 
 **session** (`event`): Emitted on session state changes. Callback receives { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'updated', config?: object }.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/voice-google-gemini-live",
-  "version": "0.14.3",
+  "version": "0.14.4-alpha.0",
   "description": "Mastra Google Gemini Live API integration",
   "type": "module",
   "files": [
@@ -27,23 +27,23 @@
     "@google/genai": "^1.52.0",
     "google-auth-library": "^10.6.2",
     "ws": "^8.21.0",
-    "@mastra/schema-compat": "1.3.3"
+    "@mastra/schema-compat": "1.3.4-alpha.0"
   },
   "devDependencies": {
     "@types/node": "22.19.21",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "4.1.8",
-    "@vitest/ui": "4.1.8",
+    "@vitest/coverage-v8": "4.1.9",
+    "@vitest/ui": "4.1.9",
     "eslint": "^10.4.1",
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "4.1.8",
+    "vitest": "4.1.9",
     "zod": "^4.4.3",
-    "@internal/lint": "0.0.111",
-    "@internal/types-builder": "0.0.86",
-    "@internal/voice": "0.0.11",
-    "@internal/test-utils": "0.0.47"
+    "@internal/lint": "0.0.113",
+    "@internal/test-utils": "0.0.49",
+    "@internal/types-builder": "0.0.88",
+    "@internal/voice": "0.0.13"
   },
   "homepage": "https://mastra.ai",
   "repository": {