Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Notifications audio

Statut : actuel Portée : sons du TUI AX Code et alertes parlées Dernière revue : 2026-09-12 Responsable : mainteneurs du runtime AX Code

Le TUI peut jouer un son système — ou prononcer une courte phrase à partir d’un modèle — chaque fois qu’AX Code a besoin de votre attention :

Demande de permission — un outil attend votre approbation.
Question de l’agent — l’agent vous a posé une question.
Tour terminé — l’exécution est finie (désactivé par défaut).
Erreur de session — le tour a échoué.

L’audio suit les mêmes déclencheurs que la notification de terminal (notification de bureau OSC 9, ou la sonnerie du terminal lorsque OSC 9 n’est pas pris en charge) et il est soumis au même interrupteur notifications.enabled. Il est désactivé par défaut ; l’activer ne change rien d’autre aux notifications.

Configuration

Définissez notifications.sound dans tui.json :

{
  "notifications": {
    "enabled": true,
    "sound": "chime",
    "events": {
      "permission": true,
      "question": true,
      "complete": false,
      "error": true
    }
  }
}

Champ	Valeurs	Défaut	Signification
`enabled`	booléen	`true`	Barrière principale des notifications de terminal et de l’audio.
`sound`	`"off"`, `"chime"`, `"speak"`	`"off"`	`chime` joue un son système ; `speak` synthétise la voix.
`voice`	chaîne	`""`	Nom de voix de la plateforme (`say -v '?'` sur macOS) ; vide = défaut.
`rate`	entier	`0`	Débit de parole là où il est pris en charge (mots/min sur macOS, 1–500) ; 0 = défaut.
`events.permission`	booléen	`true`	Alerte sur les demandes de permission.
`events.question`	booléen	`true`	Alerte sur les questions de l’agent.
`events.complete`	booléen	`false`	Alerte lorsqu’un tour se termine.
`events.error`	booléen	`true`	Alerte sur les erreurs de session.

Les valeurs invalides sont écartées champ par champ : une mauvaise valeur de sound revient à "off" sans toucher vos autres réglages.

Prise en charge des plateformes

Plateforme	Carillon	Parole	Exigence
macOS	`afplay` (son système)	`say`	Intégré.
Windows	`System.Media.SoundPlayer`	`System.Speech`	Intégré (PowerShell).
Linux	`paplay`, repli `canberra-gtk-play`	`spd-say`, repli `espeak-ng`	Installez PulseAudio/`libcanberra` et/ou `speech-dispatcher`/`espeak-ng`.

La disponibilité est sondée au runtime. Sans backend utilisable, l’étape audio est ignorée en silence et la notification de terminal reste le repli. La lecture est sérialisée (un son à la fois, les répétitions se regroupent), chaque événement alerte au plus une fois, et l’interface n’attend jamais la lecture. Les exécutions sans interface (ax-code run) ne jouent jamais d’audio.

Ce qui est prononcé

La parole n’utilise que quatre modèles fixes : Approval required: <tool>, Question: <first question>, Session idle: <session title> et AX Code error. Le texte est tronqué et débarrassé des caractères de contrôle. Les arguments d’outils, les chemins de fichiers issus des charges, la sortie du modèle et les messages d’erreur ne sont jamais prononcés — sûr pour les espaces partagés, dans ces limites.

Sons personnalisés via les crochets

Pour un contrôle complet (votre propre fichier son, un texte différent, des événements en plus), branchez n’importe quel lecteur via les Hooks du cycle de vie — cela fonctionne aussi lorsque les notifications audio sont désactivées. Après activation avec AX_CODE_TRUST_PROJECT_CONFIG=1, créez .ax-code/hooks.json :

{
  "hooks": [
    { "event": "Stop", "command": "afplay /System/Library/Sounds/Glass.aiff" },
    { "event": "PreToolUse", "matcher": "bash|edit|write", "command": "say 'AX Code needs approval'" }
  ]
}

Utilisez le lecteur de votre plateforme (afplay sur macOS, paplay sur Linux, PowerShell [System.Media] sur Windows). Les commandes de crochet sont des extraits de shell — gardez-les en envoi sans attente afin qu’elles ne puissent pas retarder le chemin du cycle de vie.

Construire un notificateur externe

Des outils externes (barres d’état, poussée mobile, une application de bureau) peuvent s’abonner au flux d’événements du serveur et réagir à permission.asked, question.asked, session.status et session.error — voir Compatibilité HTTP et OpenAPI.