Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Notificações de áudio

Status: Atual Escopo: som e alertas falados da TUI do AX Code Última revisão: 2026-09-12 Responsável: mantenedores do runtime do AX Code

A TUI pode tocar um som do sistema — ou falar uma frase curta montada a partir de um modelo — sempre que o AX Code precisar da sua atenção:

Solicitação de permissão — uma ferramenta aguarda a sua aprovação.
Pergunta do agente — o agente fez uma pergunta a você.
Turno concluído — a execução terminou (desligado por padrão).
Erro de sessão — o turno falhou.

O áudio usa os mesmos gatilhos da notificação do terminal (notificação de área de trabalho OSC 9, ou o sino do terminal onde o OSC 9 não tem suporte) e obedece ao mesmo interruptor notifications.enabled. Ele fica desligado por padrão; ligá-lo não muda mais nada nas notificações.

Configuração

Defina notifications.sound em tui.json:

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

Campo	Valores	Padrão	Significado
`enabled`	booleano	`true`	Interruptor geral das notificações do terminal e do áudio.
`sound`	`"off"`, `"chime"`, `"speak"`	`"off"`	`chime` toca um som do sistema; `speak` sintetiza a voz.
`voice`	string	`""`	Nome da voz da plataforma (`say -v '?'` no macOS); vazio = padrão.
`rate`	inteiro	`0`	Ritmo da fala onde houver suporte (palavras por minuto no macOS, 1–500); 0 = padrão.
`events.permission`	booleano	`true`	Alerta em solicitações de permissão.
`events.question`	booleano	`true`	Alerta em perguntas do agente.
`events.complete`	booleano	`false`	Alerta quando um turno termina.
`events.error`	booleano	`true`	Alerta em erros de sessão.

Valores inválidos são descartados campo a campo: um valor ruim de sound volta para "off" sem afetar as outras configurações.

Suporte por plataforma

Plataforma	Toque	Fala	Requisito
macOS	`afplay` (som do sistema)	`say`	Integrado.
Windows	`System.Media.SoundPlayer`	`System.Speech`	Integrado (PowerShell).
Linux	`paplay`, alternativa `canberra-gtk-play`	`spd-say`, alternativa `espeak-ng`	Instale PulseAudio/`libcanberra` e/ou `speech-dispatcher`/`espeak-ng`.

A disponibilidade é sondada em tempo de execução. Sem um backend utilizável, a etapa de áudio é ignorada em silêncio e a notificação do terminal permanece como reserva. A reprodução é serializada (um som por vez; repetições se juntam), cada evento alerta no máximo uma vez, e a interface nunca espera o fim da reprodução. Execuções headless (ax-code run) nunca tocam áudio.

O que é falado

A fala usa apenas quatro frases modelo fixas: Approval required: <tool>, Question: <first question>, Session idle: <session title> e AX Code error. O texto é truncado e os caracteres de controle são removidos. Argumentos de ferramenta, caminhos de arquivo vindos das cargas, saída do modelo e mensagens de erro nunca são falados — seguro para ambientes compartilhados dentro desses limites.

Sons personalizados por hooks

Para controle total (o seu próprio arquivo de som, outro texto, eventos extras), ligue qualquer reprodutor pelos hooks de ciclo de vida — isso também funciona com as notificações de áudio desligadas. Depois de optar com AX_CODE_TRUST_PROJECT_CONFIG=1, crie .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'" }
  ]
}

Use o reprodutor da plataforma (afplay no macOS, paplay no Linux, PowerShell [System.Media] no Windows). Comandos de hook são trechos de shell — deixe-os disparar sem esperar o retorno, para que não atrasem o caminho do ciclo de vida.

Montar um notificador externo

Ferramentas externas (barras de status, push no celular, um aplicativo de área de trabalho) podem assinar o fluxo de eventos do servidor e reagir a permission.asked, question.asked, session.status e session.error — veja Compatibilidade de HTTP e OpenAPI.