Voix AWS Nova Sonic

La classe NovaSonicVoice fournit des fonctionnalités de conversation vocale en temps réel reposant sur AWS Bedrock Nova 2 Sonic. Elle ouvre un stream bidirectionnel vers le modèle et émet des événements pour l'audio de l'assistant, le texte transcrit, les appels de Tool, les limites des tours de parole et les interruptions.

Exemple d'utilisation

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

Authentification

NovaSonicVoice utilise la chaîne de résolution des identifiants du SDK AWS lorsque l'option credentials n'est pas transmise. Mastra appelle defaultProvider() depuis @aws-sdk/credential-provider-node, qui vérifie, dans l'ordre, les variables d'environnement, les fichiers d'identifiants partagés, les rôles IAM pour EC2, ECS et EKS, ainsi que les autres sources standard.

Pour utiliser des identifiants statiques, transmettez-les au constructeur :

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,
  },
})

Le Provider Voice ne journalise jamais les valeurs des identifiants.

Configuration

Options du constructeur

region?:

'us-east-1' | 'us-west-2' | 'ap-northeast-1'

= 'us-east-1'

Région AWS qui héberge le modèle Nova Sonic.

model?:

string

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

Identifiant du modèle Bedrock pour le stream bidirectionnel.

credentials?:

AwsCredentialIdentity

Identifiants AWS statiques. Lorsqu'ils sont omis, la chaîne de Providers d'identifiants AWS par défaut est utilisée.

speaker?:

string | NovaSonicVoiceConfigDetails

= 'matthew'

Voix par défaut de l'assistant. Transmettez une chaîne d'identifiant de voix telle que 'matthew', ou un objet comprenant un code de langue et un genre.

languageCode?:

NovaSonicLanguageCode

Code de langue utilisé pour la session. Les voix polyglottes prennent en charge toutes les langues répertoriées.

instructions?:

string

Prompt système envoyé au début de la session. Équivaut à appeler addInstructions() avant connect().

tools?:

NovaSonicToolConfig[]

Tools exposés au modèle. Lorsque l'instance Voice est associée à un Agent, les Tools de l'Agent sont ajoutés automatiquement.

sessionConfig?:

NovaSonicSessionConfig

Configuration de l’inférence, de la détection des tours de parole et du choix des Tools. Consultez la section Configuration de session ci-dessous.

debug?:

boolean

= false

Active une journalisation détaillée des événements du stream. Les champs sensibles sont masqués.

Configuration de session

sessionConfig contrôle les paramètres d'inférence et le comportement des tours de parole. Tous les champs sont facultatifs.

inferenceConfiguration?:

object

Paramètres d'échantillonnage et de décodage.

object

maxTokens?:

number

Nombre maximal de tokens générés par tour.

temperature?:

number

Température d'échantillonnage.

topP?:

number

Probabilité d'échantillonnage nucleus.

topK?:

number

Échantillonnage top-k.

stopSequences?:

string[]

Séquences qui mettent fin à la génération.

turnDetectionConfiguration?:

object

Sensibilité de détection de fin pour les tours de parole.

object

endpointingSensitivity?:

'HIGH' | 'MEDIUM' | 'LOW'

Durée de la pause avant que le modèle considère un tour comme terminé. HIGH termine les tours le plus rapidement (environ 1,5 s de pause), MEDIUM offre un équilibre (environ 1,75 s) et LOW attend le plus longtemps (environ 2 s).

toolChoice?:

'auto' | 'any' | { tool: { name: string } }

Manière dont le modèle décide s'il doit appeler un Tool.

enableKnowledgeGrounding?:

boolean

Active l'ancrage augmenté par la récupération dans une base de connaissances Bedrock.

knowledgeBaseConfig?:

{ knowledgeBaseId?: string; dataSourceId?: string }

Base de connaissances utilisée lorsque l'ancrage par les connaissances est activé.

Méthodes

connect()

Ouvre le stream bidirectionnel vers AWS Bedrock et envoie les événements initiaux de session, de prompt et de système. Appelez cette méthode avant speak, listen ou send.

options?:

{ requestContext?: RequestContext }

Contexte de requête facultatif propagé aux appels de Tool effectués pendant la session.

Renvoie : Promise<void>

speak()

Synthétise la parole à partir d'un prompt textuel et émet des événements speaking au fil de la production audio.

input:

string | NodeJS.ReadableStream

Texte ou stream de texte à synthétiser.

options?:

NovaSonicVoiceOptions

Remplacements propres à cet appel, tels que la voix ou le code de langue.

Renvoie : Promise<void>

send()

Diffuse l'audio du microphone (ou de toute source PCM) vers le modèle. Utilisez cette méthode pour une conversation continue en direct.

audioData:

NodeJS.ReadableStream | Int16Array

Audio PCM 16 bits à transmettre au modèle.

Renvoie : Promise<void>

listen()

Wrapper pratique qui délègue à send(). Utilisez-le pour effectuer une seule passe de transcription sur un stream audio fini.

audioData:

NodeJS.ReadableStream

Stream audio à transcrire.

Renvoie : Promise<void>

endAudioInput()

Signale la fin du tour audio actuel afin que le modèle puisse finaliser sa réponse. Appelez cette méthode lorsque l'utilisateur cesse de parler et que le Provider n'est pas configuré pour détecter les tours côté serveur.

Renvoie : Promise<void>

addInstructions()

Met à jour le prompt système de la session active.

instructions?:

string

Prompt système à appliquer à la session.

Renvoie : void

addTools()

Enregistre des Tools auprès de l'instance Voice. Lorsque NovaSonicVoice est associé à un Agent, les Tools de cet Agent sont ajoutés automatiquement.

tools?:

ToolsInput

Tools exposés au modèle.

Renvoie : void

getSpeakers()

Renvoie la liste des voix prises en charge par Nova 2 Sonic.

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

getListener()

Indique si l'instance Voice détient actuellement un stream ouvert.

Renvoie : Promise<{ enabled: boolean }>

close()

Ferme le stream bidirectionnel et détruit le client Bedrock sous-jacent. Appelez cette méthode à la fin de la conversation.

Renvoie : void

on() / off()

Enregistre et supprime des écouteurs d'événements. Consultez les événements Voice pour découvrir l'API d'événements partagée.

Événements

NovaSonicVoice émet les événements suivants :

speaking:

event

Fragment audio de l'assistant. Le callback reçoit { audioData: Int16Array, sampleRate?: number }.

writing:

event

Texte transcrit de l'utilisateur ou de l'assistant. Le callback reçoit { text: string, role: 'assistant' | 'user', generationStage?: 'SPECULATIVE' | 'FINAL' }.

toolCall:

event

Le modèle a demandé un appel de Tool. Le callback reçoit { name: string, args: Record<string, any>, id: string }.

interrupt:

event

L'utilisateur ou le modèle a interrompu le tour en cours. Le callback reçoit { type: 'user' | 'model', timestamp: number }.

turnComplete:

event

Le modèle a terminé son tour. Le callback reçoit { timestamp: number }.

session:

event

Transition de l'état de la session. Le callback reçoit { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'error' }.

usage:

event

Utilisation des tokens pour le tour. Le callback reçoit { inputTokens: number, outputTokens: number, totalTokens: number }.

error:

event

Erreur du stream ou du Provider. Le callback reçoit { message: string, code?: string, details?: unknown }.

generationStage distingue les transcriptions provisoires ('SPECULATIVE') des transcriptions finalisées ('FINAL'). Utilisez le texte 'FINAL' pour le stockage persistant et le texte 'SPECULATIVE' pour les sous-titres en direct.

Voix disponibles

Nova 2 Sonic propose des voix pour dix paramètres régionaux. Tiffany et Matthew sont polyglottes et peuvent parler toutes les langues prises en charge.

Identifiant de voix	Nom	Langue	Paramètres régionaux	Genre	Polyglotte
tiffany	Tiffany	anglais	en-US	feminine	yes
matthew	Matthew	anglais	en-US	masculine	yes
amy	Amy	anglais	en-GB	feminine	no
olivia	Olivia	anglais	en-AU	feminine	no
kiara	Kiara	anglais	en-IN	feminine	no
arjun	Arjun	anglais	en-IN	masculine	no
ambre	Ambre	français	fr-FR	feminine	no
florian	Florian	français	fr-FR	masculine	no
beatrice	Beatrice	italien	it-IT	feminine	no
lorenzo	Lorenzo	italien	it-IT	masculine	no
tina	Tina	allemand	de-DE	feminine	no
lennart	Lennart	allemand	de-DE	masculine	no
lupe	Lupe	espagnol	es-US	feminine	no
carlos	Carlos	espagnol	es-US	masculine	no
carolina	Carolina	portugais	pt-BR	feminine	no
leo	Leo	portugais	pt-BR	masculine	no
kiara	Kiara	hindi	hi-IN	feminine	no
arjun	Arjun	hindi	hi-IN	masculine	no

Remarques

• L'audio est diffusé en PCM 16 bits. L'audio de l'assistant est émis sous la forme d'un Int16Array lors de l'événement speaking.
• L'instance Voice doit appeler connect() avant toute autre méthode de streaming.
• close() détruit le BedrockRuntimeClient sous-jacent afin de libérer la session HTTP/2.
• Nova 2 Sonic est disponible dans les régions us-east-1, us-west-2 et ap-northeast-1. Les autres régions provoquent une erreur de configuration lors de la construction.