AWS Nova Sonic 語音

NovaSonicVoice 類別由 AWS Bedrock Nova 2 Sonic 支援，提供實時語音對語音功能。它會開啟連接模型的雙向串流，並針對助理音訊、轉錄文字、Tool 呼叫、對話輪次界線及中斷發出事件。

使用範例
使用範例的直接連結

src/mastra/voice.ts
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 及其他標準來源。

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

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'

= 'us-east-1'

託管 Nova Sonic 模型的 AWS 區域。

model?:

string

= 'amazon.nova-2-sonic-v1:0'

雙向串流所使用的 Bedrock 模型 ID。

credentials?:

AwsCredentialIdentity

靜態 AWS 憑證。省略時會使用預設 AWS 憑證 Provider 鏈。

speaker?:

string | NovaSonicVoiceConfigDetails

= 'matthew'

助理的預設語音。傳入 'matthew' 等語音 ID 字串，或包含語言代碼及性別的物件。

languageCode?:

NovaSonicLanguageCode

工作階段使用的語言代碼。多語言語音支援列出的所有語言。

instructions?:

string

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

tools?:

NovaSonicToolConfig[]

提供給模型的 Tools。當語音實例連接至 Agent 時，系統會自動加入該 Agent 的 Tools。

sessionConfig?:

NovaSonicSessionConfig

推理、對話輪次偵測及 Tool 選擇設定。請參閱下方的工作階段設定。

debug?:

boolean

= false

啟用串流事件的詳細記錄。敏感欄位會被遮蔽。

工作階段設定
工作階段設定的直接連結

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

inferenceConfiguration?:

object

取樣及解碼參數。

object

maxTokens?:

number

每個對話輪次可產生的 token 上限。

temperature?:

number

取樣溫度。

topP?:

number

核取樣機率。

topK?:

number

Top-k 取樣。

stopSequences?:

string[]

結束產生內容的序列。

turnDetectionConfiguration?:

object

對話輪次偵測的端點判定靈敏度。

object

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()`
connect 的直接連結

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

options?:

{ requestContext?: RequestContext }

選填的請求 context，會傳遞至工作階段期間發出的 Tool 呼叫。

傳回值：Promise<void>

`speak()`
speak 的直接連結

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

input:

string | NodeJS.ReadableStream

要合成的文字或文字串流。

options?:

NovaSonicVoiceOptions

每次呼叫的覆寫設定，例如語音或語言代碼。

傳回值：Promise<void>

`send()`
send 的直接連結

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

audioData:

NodeJS.ReadableStream | Int16Array

要轉送至模型的 16 位元 PCM 音訊。

傳回值：Promise<void>

`listen()`
listen 的直接連結

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

audioData:

NodeJS.ReadableStream

要轉錄的音訊串流。

傳回值：Promise<void>

`endAudioInput()`
endaudioinput 的直接連結

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

傳回值：Promise<void>

`addInstructions()`
addinstructions 的直接連結

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

instructions?:

string

要套用至工作階段的 system prompt。

傳回值：void

`addTools()`
addtools 的直接連結

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

tools?:

ToolsInput

向模型提供的 Tools。

傳回值：void

`getSpeakers()`
getspeakers 的直接連結

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

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

`getListener()`
getlistener 的直接連結

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

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

`close()`
close 的直接連結

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

傳回值：void

`on()` / `off()`
on--off 的直接連結

註冊及移除事件監聽器。共用事件 API 請參閱 Voice 事件。

事件
事件的直接連結

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 使用。使用其他區域會在建構期間拋出設定錯誤。

使用範例使用範例 的直接連結

身份驗證身份驗證 的直接連結

設定設定 的直接連結

建構函式選項建構函式選項 的直接連結

region?:

model?:

credentials?:

speaker?:

languageCode?:

instructions?:

tools?:

sessionConfig?:

debug?:

工作階段設定工作階段設定 的直接連結

inferenceConfiguration?:

maxTokens?:

temperature?:

topP?:

topK?:

stopSequences?:

turnDetectionConfiguration?:

endpointingSensitivity?:

toolChoice?:

enableKnowledgeGrounding?:

knowledgeBaseConfig?:

方法方法 的直接連結

connect()connect 的直接連結

options?:

speak()speak 的直接連結

input:

options?:

send()send 的直接連結

audioData:

listen()listen 的直接連結

audioData:

endAudioInput()endaudioinput 的直接連結

addInstructions()addinstructions 的直接連結

instructions?:

addTools()addtools 的直接連結

tools?:

getSpeakers()getspeakers 的直接連結

getListener()getlistener 的直接連結

close()close 的直接連結

on() / off()on--off 的直接連結

事件事件 的直接連結

speaking:

writing:

toolCall:

interrupt:

turnComplete:

session:

usage:

error:

可用語音可用語音 的直接連結

注意事項注意事項 的直接連結

使用範例
使用範例的直接連結

身份驗證
身份驗證的直接連結

設定
設定的直接連結

建構函式選項
建構函式選項的直接連結

工作階段設定
工作階段設定的直接連結

方法
方法的直接連結

`connect()`
connect 的直接連結

`speak()`
speak 的直接連結

`send()`
send 的直接連結

`listen()`
listen 的直接連結

`endAudioInput()`
endaudioinput 的直接連結

`addInstructions()`
addinstructions 的直接連結

`addTools()`
addtools 的直接連結

`getSpeakers()`
getspeakers 的直接連結

`getListener()`
getlistener 的直接連結

`close()`
close 的直接連結

`on()` / `off()`
on--off 的直接連結

事件
事件的直接連結

可用語音
可用語音的直接連結

注意事項
注意事項的直接連結