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

# AWS Nova Sonic 語音

`NovaSonicVoice` 類別由 [AWS Bedrock Nova 2 Sonic](https://docs.aws.amazon.com/nova/latest/userguide/speech.html) 支援，提供實時語音對語音功能。它會開啟連接模型的雙向串流，並針對助理音訊、轉錄文字、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()
```

## 身份驗證

如未傳入 `credentials` 選項，`NovaSonicVoice` 會使用 AWS SDK 憑證解析鏈。Mastra 會呼叫 `@aws-sdk/credential-provider-node` 的 `defaultProvider()`，依次檢查環境變數、共用憑證檔案、EC2 的 IAM role、ECS、EKS 及其他標準來源。

如要使用靜態憑證，請將它們傳入建構函式：

```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`): 雙向串流所使用的 Bedrock 模型 ID。 (Default: `'amazon.nova-2-sonic-v1:0'`)

**credentials** (`AwsCredentialIdentity`): 靜態 AWS 憑證。省略時會使用預設 AWS 憑證 Provider 鏈。

**speaker** (`string | NovaSonicVoiceConfigDetails`): 助理的預設語音。傳入 'matthew' 等語音 ID 字串，或包含語言代碼及性別的物件。 (Default: `'matthew'`)

**languageCode** (`NovaSonicLanguageCode`): 工作階段使用的語言代碼。多語言語音支援列出的所有語言。

**instructions** (`string`): 工作階段開始時傳送的 system prompt。等同於在 connect() 前呼叫 addInstructions()。

**tools** (`NovaSonicToolConfig[]`): 提供給模型的 Tools。當語音實例連接至 Agent 時，系統會自動加入該 Agent 的 Tools。

**sessionConfig** (`NovaSonicSessionConfig`): 推理、對話輪次偵測及 Tool 選擇設定。請參閱下方的工作階段設定。

**debug** (`boolean`): 啟用串流事件的詳細記錄。敏感欄位會被遮蔽。 (Default: `false`)

### 工作階段設定

`sessionConfig` 控制推理參數及對話輪次交替行為。所有欄位均為選填。

**inferenceConfiguration** (`object`): 取樣及解碼參數。

**inferenceConfiguration.maxTokens** (`number`): 每個對話輪次可產生的 token 上限。

**inferenceConfiguration.temperature** (`number`): 取樣溫度。

**inferenceConfiguration.topP** (`number`): 核取樣機率。

**inferenceConfiguration.topK** (`number`): Top-k 取樣。

**inferenceConfiguration.stopSequences** (`string[]`): 結束產生內容的序列。

**turnDetectionConfiguration** (`object`): 對話輪次偵測的端點判定靈敏度。

**turnDetectionConfiguration.endpointingSensitivity** (`'HIGH' | 'MEDIUM' | 'LOW'`): 模型將對話輪次視為完成前的停頓時間。HIGH 最快結束輪次（停頓約 1.5 秒）、MEDIUM 較為均衡（約 1.75 秒），LOW 等候時間最長（約 2 秒）。

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

**enableKnowledgeGrounding** (`boolean`): 啟用以 Bedrock 知識庫為基礎的檢索增強內容依據。

**knowledgeBaseConfig** (`{ knowledgeBaseId?: string; dataSourceId?: string }`): 啟用知識依據功能時使用的知識庫。

## 方法

### `connect()`

開啟連接 AWS Bedrock 的雙向串流，並傳送初始工作階段、prompt 及 system 事件。請在 `speak`、`listen` 或 `send` 前呼叫此方法。

**options** (`{ requestContext?: RequestContext }`): 選填的請求 context，會傳遞至工作階段期間發出的 Tool 呼叫。

傳回值：`Promise<void>`

### `speak()`

為文字 prompt 合成語音，並在產生音訊時發出 `speaking` 事件。

**input** (`string | NodeJS.ReadableStream`): 要合成的文字或文字串流。

**options** (`NovaSonicVoiceOptions`): 每次呼叫的覆寫設定，例如語音或語言代碼。

傳回值：`Promise<void>`

### `send()`

將咪高峰音訊（或任何 PCM 來源）串流至模型。此方法適用於實時連續對話。

**audioData** (`NodeJS.ReadableStream | Int16Array`): 要轉送至模型的 16 位元 PCM 音訊。

傳回值：`Promise<void>`

### `listen()`

委派至 `send()` 的便利 wrapper。如要對有限長度的音訊串流進行單次轉錄，請使用此方法。

**audioData** (`NodeJS.ReadableStream`): 要轉錄的音訊串流。

傳回值：`Promise<void>`

### `endAudioInput()`

表示目前的音訊對話輪次已結束，讓模型完成其回應。如用戶停止說話，而 Provider 未設定伺服器端對話輪次偵測，請呼叫此方法。

傳回值：`Promise<void>`

### `addInstructions()`

更新使用中工作階段的 system prompt。

**instructions** (`string`): 要套用至工作階段的 system prompt。

傳回值：`void`

### `addTools()`

向語音實例註冊 Tools。當 `NovaSonicVoice` 連接至 Agent 時，系統會自動加入該 Agent 的 Tools。

**tools** (`ToolsInput`): 向模型提供的 Tools。

傳回值：`void`

### `getSpeakers()`

傳回 Nova 2 Sonic 支援的語音清單。

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

### `getListener()`

傳回語音實例目前是否持有開啟的串流。

傳回值：`Promise<{ enabled: boolean }>`

### `close()`

關閉雙向串流並銷毀底層 Bedrock 用戶端。對話結束時請呼叫此方法。

傳回值：`void`

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

註冊及移除事件監聽器。共用事件 API 請參閱 [Voice 事件](https://mastra.zisheng.pro/zh-HK/reference/voice/voice.events)。

## 事件

`NovaSonicVoice` 會發出以下事件：

**speaking** (`event`): 助理音訊區塊。回呼會收到 { audioData: Int16Array, sampleRate?: number }。

**writing** (`event`): 來自用戶或助理的轉錄文字。回呼會收到 { text: string, role: 'assistant' | 'user', generationStage?: 'SPECULATIVE' | 'FINAL' }。

**toolCall** (`event`): 模型要求呼叫 Tool。回呼會收到 { name: string, args: Record\<string, any>, id: string }。

**interrupt** (`event`): 用戶或模型中斷目前的對話輪次。回呼會收到 { type: 'user' | 'model', timestamp: number }。

**turnComplete** (`event`): 模型已完成其對話輪次。回呼會收到 { timestamp: number }。

**session** (`event`): 工作階段狀態轉換。回呼會收到 { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'error' }。

**usage** (`event`): 該對話輪次的 token 使用量。回呼會收到 { inputTokens: number, outputTokens: number, totalTokens: number }。

**error** (`event`): 串流或 Provider 錯誤。回呼會收到 { message: string, code?: string, details?: unknown }。

`generationStage` 用於區分暫定轉錄內容（`'SPECULATIVE'`）與最終轉錄內容（`'FINAL'`）。請使用 `'FINAL'` 文字作持久儲存，並使用 `'SPECULATIVE'` 文字顯示即時字幕。

## 可用語音

Nova 2 Sonic 提供十個地區設定的語音。Tiffany 和 Matthew 是多語言語音，可說任何受支援的語言。

| 語音 ID      | 名稱       | 語言   | 地區設定  | 性別 | 多語言 |
| ---------- | -------- | ---- | ----- | -- | --- |
| `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 形式串流。助理音訊會在 `speaking` 事件中以 `Int16Array` 形式發出。
- 語音實例必須先呼叫 `connect()`，才能呼叫任何其他串流方法。
- `close()` 會銷毀底層 `BedrockRuntimeClient`，以釋放 HTTP/2 工作階段。
- Nova 2 Sonic 可在 `us-east-1`、`us-west-2` 及 `ap-northeast-1` 使用。使用其他區域會在建構期間拋出設定錯誤。