@mastra/voice-aws-nova-sonic 0.2.0 → 0.2.1

package/dist/docs/references/{docs-voice-speech-to-speech.md → guides-voice-speech-to-speech.md}

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Speech-to-Speech capabilities in Mastra
 
 ## Introduction
@@ -8,7 +10,7 @@ Speech-to-Speech (STS) in Mastra provides a standardized interface for real-time
 
 - **`apiKey`**: Your OpenAI API key. Falls back to the `OPENAI_API_KEY` environment variable.
 - **`model`**: The model ID to use for real-time voice interactions (e.g., `gpt-5.1-realtime`).
-- **`speaker`**: The default voice ID for speech synthesis. This allows you to specify which voice to use for the speech output.
+- **`speaker`**: The default voice ID for speech synthesis. You can specify which voice to use for the speech output.
 
 ```typescript
 const voice = new OpenAIRealtimeVoice({
@@ -32,7 +34,7 @@ const agent = new Agent({
   id: 'agent',
   name: 'OpenAI Realtime Agent',
   instructions: `You are a helpful assistant with real-time voice capabilities.`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   voice: new OpenAIRealtimeVoice(),
 })
 
@@ -52,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/guides/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.6-sol',
+  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.6-sol',
+  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)
 
@@ -66,7 +148,7 @@ const agent = new Agent({
   name: 'Gemini Live Agent',
   instructions: 'You are a helpful assistant with real-time voice capabilities.',
   // Model used for text generation; voice provider handles realtime audio
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   voice: new GeminiLiveVoice({
     apiKey: process.env.GOOGLE_API_KEY,
     model: 'gemini-2.0-flash-exp',
@@ -113,7 +195,7 @@ const agent = new Agent({
   name: 'Nova Sonic Agent',
   instructions: 'You are a helpful assistant with real-time voice capabilities.',
   // Model used for text generation; voice provider handles realtime audio
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   voice: new NovaSonicVoice({
     region: 'us-east-1',
     speaker: 'matthew',
@@ -157,7 +239,7 @@ const agent = new Agent({
   name: 'Inworld Realtime Agent',
   instructions: 'You are a helpful assistant with real-time voice capabilities.',
   // Model used for text generation; voice provider handles realtime audio
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   voice: new InworldRealtimeVoice({
     apiKey: process.env.INWORLD_API_KEY,
     model: 'inworld/models/gemma-4-26b-a4b-it',
@@ -190,8 +272,8 @@ await agent.voice.send(micStream)
 
 Note:
 
-- Requires `INWORLD_API_KEY`. Inworld API keys ship pre-Basic-encoded — paste them verbatim.
+- Requires `INWORLD_API_KEY`. Inworld API keys are pre-Basic-encoded: paste them verbatim.
 - The WebSocket URL appends a client-generated `?key=...&protocol=realtime`. The model is configured via the initial `session.update`, not in the URL.
 - Inworld's wire protocol is the OpenAI Realtime GA spec, so event names match `@mastra/voice-openai-realtime`.
-- Typed Inworld realtime knobs (MCP tool routing, semantic VAD eagerness, playback speed, transcription model, output modalities, …) are exposed through the `session` constructor field; an untyped `providerData` escape hatch is also deep-merged for forward compatibility with new Inworld features.
+- Typed Inworld realtime knobs (MCP tool routing, semantic VAD eagerness, playback speed, transcription model, output modalities, …) are exposed through the `session` constructor field. An untyped `providerData` escape hatch is also deep-merged for forward compatibility with new Inworld features.
 - Events: `speaker` (PCM audio stream), `speaking` (audio Buffer per delta), `writing` (text), `conversation.item.added`, `conversation.item.done`, `function_call.arguments`, `tool-call-start`, `tool-call-result`, and `error`.

package/dist/docs/references/{reference-voice-aws-nova-sonic.md → integrations-voice-aws-nova-sonic.md}

@@ -1,4 +1,6 @@
-# AWS Nova Sonic voice
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# AWS Nova Sonic
 
 The `NovaSonicVoice` class provides real-time speech-to-speech capabilities backed by [AWS Bedrock Nova 2 Sonic](https://docs.aws.amazon.com/nova/latest/userguide/speech.html). It opens a bidirectional stream to the model and emits events for assistant audio, transcribed text, tool calls, turn boundaries, and interruptions.
 
@@ -216,7 +218,7 @@ Registers and removes event listeners. See [Voice events](https://mastra.ai/refe
 
 ## Available voices
 
-Nova 2 Sonic ships voices in ten locales. Tiffany and Matthew are polyglot and can speak any supported language.
+Nova 2 Sonic provides voices in ten locales. Tiffany and Matthew are polyglot and can speak any supported language.
 
 | Voice ID   | Name     | Language   | Locale | Gender    | Polyglot |
 | ---------- | -------- | ---------- | ------ | --------- | -------- |