AWS Nova Sonic Voice

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 角色、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,
  },
})

此 Voice 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

工作階段開始時傳送的系統提示。等同於在 connect() 前呼叫 addInstructions()。

tools?:

NovaSonicToolConfig[]

向模型公開的 Tools。Voice 執行個體附加至 Agent 時，系統會自動加入 Agent 的 Tools。

sessionConfig?:

NovaSonicSessionConfig

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

debug?:

boolean

= false

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

工作階段設定

sessionConfig 控制推論參數與對話輪替行為。所有欄位皆為選填。

inferenceConfiguration?:

object

取樣與解碼參數。

object

maxTokens?:

number

每個對話輪次產生的權杖數上限。

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()

開啟與 AWS Bedrock 之間的雙向資料流，並傳送初始工作階段、提示與系統事件。請先呼叫此方法，再呼叫 speak、listen 或 send。

options?:

{ requestContext?: RequestContext }

選用的請求內容，會傳播至工作階段期間進行的 Tool 呼叫。

回傳：Promise<void>

speak()

合成文字提示的語音，並在產生音訊時發出 speaking 事件。

input:

string | NodeJS.ReadableStream

要合成的文字或文字資料流。

options?:

NovaSonicVoiceOptions

單次呼叫的覆寫設定，例如語音或語言程式碼。

回傳：Promise<void>

send()

將麥克風音訊（或任何 PCM 來源）串流傳送至模型。適用於即時且持續的對話。

audioData:

NodeJS.ReadableStream | Int16Array

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

回傳：Promise<void>

listen()

委派給 send() 的便利包裝函式。當您要對有限的音訊資料流執行單次轉錄時使用。

audioData:

NodeJS.ReadableStream

要轉錄的音訊資料流。

回傳：Promise<void>

endAudioInput()

指示目前音訊輪次結束，讓模型完成回應。當使用者停止說話，且 Provider 未設定伺服器端對話輪次偵測時，請呼叫此方法。

回傳：Promise<void>

addInstructions()

更新作用中工作階段的系統提示。

instructions?:

string

要套用至工作階段的系統提示。

回傳：void

addTools()

在 Voice 執行個體註冊 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()

回傳 Voice 執行個體目前是否維持開啟的資料流。

回傳：Promise<{ enabled: boolean }>

close()

關閉雙向資料流並終止底層 Bedrock 使用者端。對話結束時請呼叫此方法。

回傳：void

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

對話輪次的權杖用量。回呼會收到 { 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 發出。
• Voice 執行個體必須先呼叫 connect()，才能呼叫其他串流方法。
• close() 會終止底層 BedrockRuntimeClient，以釋放 HTTP/2 工作階段。
• Nova 2 Sonic 可在 us-east-1、us-west-2 與 ap-northeast-1 使用。其他區域會在建構期間擲回設定錯誤。