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・ECS・EKS の IAM ロール、その他の標準ソースをこの順序で確認します。

静的な認証情報を使用するには、コンストラクターに渡します。

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'

アシスタントのデフォルト Voice。'matthew' などの Voice ID 文字列、または言語コードと性別を含むオブジェクトを渡します。

languageCode?:

NovaSonicLanguageCode

セッションで使用する言語コード。多言語 Voice は一覧にあるすべての言語をサポートします。

instructions?:

string

セッション開始時に送信するシステムプロンプト。connect() の前に addInstructions() を呼び出すことと同等です。

tools?:

NovaSonicToolConfig[]

モデルに公開する Tool。Voice インスタンスを Agent に関連付けると、Agent の Tool が自動的に追加されます。

sessionConfig?:

NovaSonicSessionConfig

推論、ターン検出、Tool 選択の設定。以下の「セッション設定」を参照してください。

debug?:

boolean

= false

ストリームイベントの詳細ログを有効にします。機密フィールドはマスクされます。

セッション設定
セッション設定への直接リンク

sessionConfig は推論パラメーターとターン交代の動作を制御します。すべてのフィールドは省略可能です。

inferenceConfiguration?:

object

サンプリングおよびデコードのパラメーター。

object

maxTokens?:

number

ターンごとに生成する最大トークン数。

temperature?:

number

サンプリング温度。

topP?:

number

Nucleus sampling の確率。

topK?:

number

Top-k sampling。

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 への双方向ストリームを開き、最初のセッション、プロンプト、システムイベントを送信します。speak、listen、send より前に呼び出してください。

options?:

{ requestContext?: RequestContext }

セッション中の Tool 呼び出しに伝播する省略可能なリクエストコンテキスト。

戻り値：Promise<void>

`speak()`
speakへの直接リンク

テキストプロンプトの音声を合成し、音声の生成に合わせて speaking イベントを送出します。

input:

string | NodeJS.ReadableStream

合成するテキストまたはテキストストリーム。

options?:

NovaSonicVoiceOptions

Speaker や言語コードなど、呼び出しごとの上書き設定。

戻り値： Promise<void>

`send()`
sendへの直接リンク

マイク音声（または任意の PCM ソース）をモデルへストリーミングします。ライブの継続的な会話に使用します。

audioData:

NodeJS.ReadableStream | Int16Array

モデルに転送する16ビット PCM 音声。

戻り値： Promise<void>

`listen()`
listenへの直接リンク

send() に処理を委譲する便利なラッパーです。有限の音声ストリームを1回だけ文字起こしする場合に使用します。

audioData:

NodeJS.ReadableStream

文字起こしする音声ストリーム。

戻り値： Promise<void>

`endAudioInput()`
endaudioinputへの直接リンク

現在の音声ターンの終了を通知し、モデルが応答を確定できるようにします。ユーザーが発話を終え、Provider にサーバー側のターン検出が設定されていない場合に呼び出してください。

戻り値： Promise<void>

`addInstructions()`
addinstructionsへの直接リンク

アクティブなセッションのシステムプロンプトを更新します。

instructions?:

string

セッションに適用するシステムプロンプト。

戻り値：void

`addTools()`
addtoolsへの直接リンク

Voice インスタンスに Tool を登録します。NovaSonicVoice を Agent に関連付けると、Agent の Tool が自動的に追加されます。

tools?:

ToolsInput

モデルに公開する Tool。

戻り値： void

`getSpeakers()`
getspeakersへの直接リンク

Nova 2 Sonic がサポートする Voice の一覧を返します。

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

`getListener()`
getlistenerへの直接リンク

Voice インスタンスが現在開いているストリームを保持しているかどうかを返します。

戻り値：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

ターンのトークン使用量。コールバックは { inputTokens: number, outputTokens: number, totalTokens: number } を受け取ります。

error:

event

ストリームまたは Provider のエラー。コールバックは { message: string, code?: string, details?: unknown } を受け取ります。

generationStage は暫定的な文字起こし（'SPECULATIVE'）と確定済みの文字起こし（'FINAL'）を区別します。永続ストレージには 'FINAL' のテキスト、ライブキャプションには 'SPECULATIVE' のテキストを使用してください。

使用可能な Voice
使用可能な Voiceへの直接リンク

Nova 2 Sonic は10のロケールで Voice を提供します。Tiffany と Matthew は多言語 Voice で、サポートされるすべての言語を話せます。

Voice 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 で利用できます。その他のリージョンでは、構築時に設定エラーがスローされます。

使用例使用例への直接リンク

認証認証への直接リンク

設定設定への直接リンク

コンストラクターオプションコンストラクターオプションへの直接リンク

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:

使用可能な Voice使用可能な Voiceへの直接リンク

注意事項注意事項への直接リンク

使用例
使用例への直接リンク

認証
認証への直接リンク

設定
設定への直接リンク

コンストラクターオプション
コンストラクターオプションへの直接リンク

セッション設定
セッション設定への直接リンク

メソッド
メソッドへの直接リンク

`connect()`
connectへの直接リンク

`speak()`
speakへの直接リンク

`send()`
sendへの直接リンク

`listen()`
listenへの直接リンク

`endAudioInput()`
endaudioinputへの直接リンク

`addInstructions()`
addinstructionsへの直接リンク

`addTools()`
addtoolsへの直接リンク

`getSpeakers()`
getspeakersへの直接リンク

`getListener()`
getlistenerへの直接リンク

`close()`
closeへの直接リンク

`on()` / `off()`
on--offへの直接リンク

イベント
イベントへの直接リンク

使用可能な Voice
使用可能な Voiceへの直接リンク

注意事項
注意事項への直接リンク