AWS Nova Sonic voice

NovaSonicVoice 类由 AWS Bedrock Nova 2 Sonic 提供支持，可实现实时语音到语音交互。它会打开通向模型的双向 stream，并为助理音频、转录文本、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()

身份验证
身份验证的直接链接

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

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

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'

双向 stream 使用的 Bedrock 模型 ID。

credentials?:

AwsCredentialIdentity

静态 AWS 凭据。省略时使用默认 AWS 凭据 Provider 链。

speaker?:

string | NovaSonicVoiceConfigDetails

= 'matthew'

助理的默认语音。传入 'matthew' 等语音 ID 字符串，或包含语言代码和性别的对象。

languageCode?:

NovaSonicLanguageCode

Session 使用的语言代码。多语言语音支持列出的所有语言。

instructions?:

string

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

tools?:

NovaSonicToolConfig[]

向模型公开的 Tool。当语音实例附加到 Agent 时，会自动添加该 Agent 的 Tool。

sessionConfig?:

NovaSonicSessionConfig

推理、轮次检测和 Tool 选择配置。请参阅下方的 Session 配置。

debug?:

boolean

= false

为 stream 事件启用详细日志记录。敏感字段会被遮蔽。

Session 配置
Session 配置的直接链接

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

inferenceConfiguration?:

object

采样和解码参数。

object

maxTokens?:

number

每个轮次生成的最大 token 数。

temperature?:

number

采样温度。

topP?:

number

核采样概率。

topK?:

number

Top-k 采样。

stopSequences?:

string[]

用于结束生成的序列。

turnDetectionConfiguration?:

object

轮次检测的 endpointing 灵敏度。

object

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

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

options?:

{ requestContext?: RequestContext }

可选请求上下文，会传播到 Session 期间发起的 Tool 调用。

返回：Promise<void>

`speak()`
speak的直接链接

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

input:

string | NodeJS.ReadableStream

要合成的文本或文本 stream。

options?:

NovaSonicVoiceOptions

每次调用的覆盖项，例如说话者或语言代码。

返回：Promise<void>

`send()`
send的直接链接

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

audioData:

NodeJS.ReadableStream | Int16Array

要转发给模型的 16 位 PCM 音频。

返回：Promise<void>

`listen()`
listen的直接链接

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

audioData:

NodeJS.ReadableStream

要转录的音频 stream。

返回：Promise<void>

`endAudioInput()`
endaudioinput的直接链接

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

返回：Promise<void>

`addInstructions()`
addinstructions的直接链接

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

instructions?:

string

要应用于 Session 的系统提示词。

返回：void

`addTools()`
addtools的直接链接

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

tools?:

ToolsInput

向模型公开的 Tool。

返回：void

`getSpeakers()`
getspeakers的直接链接

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

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

`getListener()`
getlistener的直接链接

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

返回：Promise<{ enabled: boolean }>

`close()`
close的直接链接

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

返回：void

`on()` / `off()`
on--off的直接链接

注册和移除事件 listener。有关共享事件 API，请参阅语音事件。

事件
事件的直接链接

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 中可用。其他区域会在构造期间抛出配置错误。

用法示例用法示例的直接链接

身份验证身份验证的直接链接

配置配置的直接链接

构造函数选项构造函数选项的直接链接

region?:

model?:

credentials?:

speaker?:

languageCode?:

instructions?:

tools?:

sessionConfig?:

debug?:

Session 配置Session 配置的直接链接

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:

可用语音可用语音的直接链接

注意事项注意事项的直接链接

用法示例
用法示例的直接链接

身份验证
身份验证的直接链接

配置
配置的直接链接

构造函数选项
构造函数选项的直接链接

Session 配置
Session 配置的直接链接

方法
方法的直接链接

`connect()`
connect的直接链接

`speak()`
speak的直接链接

`send()`
send的直接链接

`listen()`
listen的直接链接

`endAudioInput()`
endaudioinput的直接链接

`addInstructions()`
addinstructions的直接链接

`addTools()`
addtools的直接链接

`getSpeakers()`
getspeakers的直接链接

`getListener()`
getlistener的直接链接

`close()`
close的直接链接

`on()` / `off()`
on--off的直接链接

事件
事件的直接链接

可用语音
可用语音的直接链接

注意事项
注意事项的直接链接