> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# AWS Nova Sonic voice

`NovaSonicVoice` 类由 [AWS Bedrock Nova 2 Sonic](https://docs.aws.amazon.com/nova/latest/userguide/speech.html) 提供支持，可实现实时语音到语音交互。它会打开通向模型的双向 stream，并为助理音频、转录文本、Tool 调用、轮次边界和中断发出事件。

## 用法示例

```typescript
import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

// Initialize using the default AWS credential provider chain
const voice = new NovaSonicVoice({
  region: 'us-east-1',
  speaker: 'matthew',
})

// Or pass explicit credentials
const voiceWithCredentials = new NovaSonicVoice({
  region: 'us-east-1',
  speaker: 'tiffany',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
})

// Establish the bidirectional stream
await voice.connect()

// Listen for assistant audio (Int16Array PCM)
voice.on('speaking', ({ audioData }) => {
  if (audioData) playAudio(audioData)
})

// Listen for transcribed text from the user and assistant
voice.on('writing', ({ text, role, generationStage }) => {
  console.log(`${role} (${generationStage ?? 'FINAL'}): ${text}`)
})

// Stream microphone audio in real time
const microphoneStream = getMicrophoneStream()
await voice.send(microphoneStream)

// Disconnect when done
voice.close()
```

## 身份验证

`NovaSonicVoice` 在未传入 `credentials` 选项时使用 AWS SDK 凭据解析链。Mastra 会调用 `defaultProvider()`（来自 `@aws-sdk/credential-provider-node`），依次检查环境变量、共享凭据文件、EC2、ECS、EKS 的 IAM role 以及其他标准来源。

要使用静态凭据，请将其传入构造函数：

```typescript
new NovaSonicVoice({
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    sessionToken: process.env.AWS_SESSION_TOKEN,
  },
})
```

语音 Provider 绝不会记录凭据值。

## 配置

### 构造函数选项

**region** (`'us-east-1' | 'us-west-2' | 'ap-northeast-1'`): 托管 Nova Sonic 模型的 AWS 区域。 (Default: `'us-east-1'`)

**model** (`string`): 双向 stream 使用的 Bedrock 模型 ID。 (Default: `'amazon.nova-2-sonic-v1:0'`)

**credentials** (`AwsCredentialIdentity`): 静态 AWS 凭据。省略时使用默认 AWS 凭据 Provider 链。

**speaker** (`string | NovaSonicVoiceConfigDetails`): 助理的默认语音。传入 'matthew' 等语音 ID 字符串，或包含语言代码和性别的对象。 (Default: `'matthew'`)

**languageCode** (`NovaSonicLanguageCode`): Session 使用的语言代码。多语言语音支持列出的所有语言。

**instructions** (`string`): Session 开始时发送的系统提示词。等同于在 connect() 前调用 addInstructions()。

**tools** (`NovaSonicToolConfig[]`): 向模型公开的 Tool。当语音实例附加到 Agent 时，会自动添加该 Agent 的 Tool。

**sessionConfig** (`NovaSonicSessionConfig`): 推理、轮次检测和 Tool 选择配置。请参阅下方的 Session 配置。

**debug** (`boolean`): 为 stream 事件启用详细日志记录。敏感字段会被遮蔽。 (Default: `false`)

### Session 配置

`sessionConfig` 控制推理参数和轮次交互行为。所有字段均为可选。

**inferenceConfiguration** (`object`): 采样和解码参数。

**inferenceConfiguration.maxTokens** (`number`): 每个轮次生成的最大 token 数。

**inferenceConfiguration.temperature** (`number`): 采样温度。

**inferenceConfiguration.topP** (`number`): 核采样概率。

**inferenceConfiguration.topK** (`number`): Top-k 采样。

**inferenceConfiguration.stopSequences** (`string[]`): 用于结束生成的序列。

**turnDetectionConfiguration** (`object`): 轮次检测的 endpointing 灵敏度。

**turnDetectionConfiguration.endpointingSensitivity** (`'HIGH' | 'MEDIUM' | 'LOW'`): 模型将轮次视为完成前的暂停时长。HIGH 最快结束轮次（暂停约 1.5 秒），MEDIUM 较为均衡（约 1.75 秒），LOW 等待时间最长（约 2 秒）。

**toolChoice** (`'auto' | 'any' | { tool: { name: string } }`): 模型决定是否调用 Tool 的方式。

**enableKnowledgeGrounding** (`boolean`): 针对 Bedrock knowledge base 启用检索增强 grounding。

**knowledgeBaseConfig** (`{ knowledgeBaseId?: string; dataSourceId?: string }`): 启用 knowledge grounding 时使用的 knowledge base。

## 方法

### `connect()`

打开通向 AWS Bedrock 的双向 stream，并发送初始 Session、提示词和系统事件。请在 `speak`、`listen` 或 `send` 前调用此方法。

**options** (`{ requestContext?: RequestContext }`): 可选请求上下文，会传播到 Session 期间发起的 Tool 调用。

返回：`Promise<void>`

### `speak()`

为文本提示词合成语音，并在生成音频时发出 `speaking` 事件。

**input** (`string | NodeJS.ReadableStream`): 要合成的文本或文本 stream。

**options** (`NovaSonicVoiceOptions`): 每次调用的覆盖项，例如说话者或语言代码。

返回：`Promise<void>`

### `send()`

将麦克风音频（或任意 PCM 来源）流式传输到模型。此方法适用于实时连续对话。

**audioData** (`NodeJS.ReadableStream | Int16Array`): 要转发给模型的 16 位 PCM 音频。

返回：`Promise<void>`

### `listen()`

委托给 `send()` 的便捷封装。需要对有限音频 stream 执行一次转录时可使用此方法。

**audioData** (`NodeJS.ReadableStream`): 要转录的音频 stream。

返回：`Promise<void>`

### `endAudioInput()`

发出当前音频轮次结束的信号，以便模型完成响应。当用户停止说话且 Provider 未配置服务端轮次检测时，请调用此方法。

返回：`Promise<void>`

### `addInstructions()`

更新活动 Session 的系统提示词。

**instructions** (`string`): 要应用于 Session 的系统提示词。

返回：`void`

### `addTools()`

向语音实例注册 Tool。当 `NovaSonicVoice` 附加到 Agent 时，会自动添加该 Agent 的 Tool。

**tools** (`ToolsInput`): 向模型公开的 Tool。

返回：`void`

### `getSpeakers()`

返回 Nova 2 Sonic 支持的语音列表。

返回：`Promise<Array<{ voiceId: string; name: string; language: string; locale: string; gender: 'masculine' | 'feminine'; polyglot: boolean }>>`

### `getListener()`

返回语音实例当前是否持有打开的 stream。

返回：`Promise<{ enabled: boolean }>`

### `close()`

关闭双向 stream 并销毁底层 Bedrock client。请在对话结束时调用此方法。

返回：`void`

### `on()` / `off()`

注册和移除事件 listener。有关共享事件 API，请参阅[语音事件](https://mastra.zisheng.pro/reference/voice/voice.events)。

## 事件

`NovaSonicVoice` 会发出以下事件：

**speaking** (`event`): 助理音频 chunk。callback 接收 { audioData: Int16Array, sampleRate?: number }。

**writing** (`event`): 来自用户或助理的转录文本。callback 接收 { text: string, role: 'assistant' | 'user', generationStage?: 'SPECULATIVE' | 'FINAL' }。

**toolCall** (`event`): 模型请求了 Tool 调用。callback 接收 { name: string, args: Record\<string, any>, id: string }。

**interrupt** (`event`): 用户或模型中断了当前轮次。callback 接收 { type: 'user' | 'model', timestamp: number }。

**turnComplete** (`event`): 模型完成了其轮次。callback 接收 { timestamp: number }。

**session** (`event`): Session 状态转换。callback 接收 { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'error' }。

**usage** (`event`): 该轮次的 token 用量。callback 接收 { inputTokens: number, outputTokens: number, totalTokens: number }。

**error** (`event`): Stream 或 Provider 错误。callback 接收 { message: string, code?: string, details?: unknown }。

`generationStage` 用于区分临时转录（`'SPECULATIVE'`）和最终转录（`'FINAL'`）。持久化存储请使用 `'FINAL'` 文本，实时字幕请使用 `'SPECULATIVE'` 文本。

## 可用语音

Nova 2 Sonic 提供十种 locale 的语音。Tiffany 和 Matthew 是多语言语音，可以使用任何受支持的语言说话。

| 语音 ID      | 名称       | 语言   | Locale | 性别 | 多语言 |
| ---------- | -------- | ---- | ------ | -- | --- |
| `tiffany`  | Tiffany  | 英语   | en-US  | 女性 | 是   |
| `matthew`  | Matthew  | 英语   | en-US  | 男性 | 是   |
| `amy`      | Amy      | 英语   | en-GB  | 女性 | 否   |
| `olivia`   | Olivia   | 英语   | en-AU  | 女性 | 否   |
| `kiara`    | Kiara    | 英语   | en-IN  | 女性 | 否   |
| `arjun`    | Arjun    | 英语   | en-IN  | 男性 | 否   |
| `ambre`    | Ambre    | 法语   | fr-FR  | 女性 | 否   |
| `florian`  | Florian  | 法语   | fr-FR  | 男性 | 否   |
| `beatrice` | Beatrice | 意大利语 | it-IT  | 女性 | 否   |
| `lorenzo`  | Lorenzo  | 意大利语 | it-IT  | 男性 | 否   |
| `tina`     | Tina     | 德语   | de-DE  | 女性 | 否   |
| `lennart`  | Lennart  | 德语   | de-DE  | 男性 | 否   |
| `lupe`     | Lupe     | 西班牙语 | es-US  | 女性 | 否   |
| `carlos`   | Carlos   | 西班牙语 | es-US  | 男性 | 否   |
| `carolina` | Carolina | 葡萄牙语 | pt-BR  | 女性 | 否   |
| `leo`      | Leo      | 葡萄牙语 | pt-BR  | 男性 | 否   |
| `kiara`    | Kiara    | 印地语  | hi-IN  | 女性 | 否   |
| `arjun`    | Arjun    | 印地语  | hi-IN  | 男性 | 否   |

## 注意事项

- 音频以 16 位 PCM 的形式流式传输。助理音频以 `Int16Array` 的形式在 `speaking` 事件上发出。
- 语音实例必须先调用 `connect()`，然后才能调用其他流式方法。
- `close()` 会销毁底层 `BedrockRuntimeClient`，以释放 HTTP/2 Session。
- Nova 2 Sonic 在 `us-east-1`、`us-west-2` 和 `ap-northeast-1` 中可用。其他区域会在构造期间抛出配置错误。