> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://docs.aws.amazon.com/nova/latest/userguide/speech.html). 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

```typescript
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 :

```typescript
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'`): Région AWS qui héberge le modèle Nova Sonic. (Default: `'us-east-1'`)

**model** (`string`): Identifiant du modèle Bedrock pour le stream bidirectionnel. (Default: `'amazon.nova-2-sonic-v1:0'`)

**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`): 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. (Default: `'matthew'`)

**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`): Active une journalisation détaillée des événements du stream. Les champs sensibles sont masqués. (Default: `false`)

### 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.

**inferenceConfiguration.maxTokens** (`number`): Nombre maximal de tokens générés par tour.

**inferenceConfiguration.temperature** (`number`): Température d'échantillonnage.

**inferenceConfiguration.topP** (`number`): Probabilité d'échantillonnage nucleus.

**inferenceConfiguration.topK** (`number`): Échantillonnage top-k.

**inferenceConfiguration.stopSequences** (`string[]`): Séquences qui mettent fin à la génération.

**turnDetectionConfiguration** (`object`): Sensibilité de détection de fin pour les tours de parole.

**turnDetectionConfiguration.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](https://mastra.zisheng.pro/fr/reference/voice/voice.events) 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.