Halaman ini diterjemahkan dari dokumentasi bahasa Inggris. Perintah, pengenal, dan contoh tidak diubah. Runtime 7.24.4 · SDK 2.6.7. Sumber bahasa Inggris

Notifikasi audio

Status: Saat ini Cakupan: suara TUI AX Code dan peringatan yang diucapkan Terakhir ditinjau: 2026-09-12 Pemilik: pengelola runtime AX Code

TUI dapat memutar suara sistem — atau mengucapkan frasa templat yang singkat — setiap kali AX Code membutuhkan perhatian Anda:

Permintaan izin — sebuah alat menunggu persetujuan Anda.
Pertanyaan agen — agen mengajukan pertanyaan kepada Anda.
Giliran selesai — eksekusi telah selesai (mati secara bawaan).
Kesalahan sesi — giliran gagal.

Audio mengikuti pemicu yang sama dengan notifikasi terminal (notifikasi desktop OSC 9, atau bel terminal jika OSC 9 tidak didukung) dan dikendalikan oleh sakelar notifications.enabled yang sama. Fitur ini mati secara bawaan; mengaktifkannya tidak mengubah hal lain pada notifikasi.

Konfigurasi

Atur notifications.sound di tui.json:

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

Bidang	Nilai	Bawaan	Arti
`enabled`	boolean	`true`	Gerbang utama untuk notifikasi terminal dan audio.
`sound`	`"off"`, `"chime"`, `"speak"`	`"off"`	`chime` memutar suara sistem; `speak` menyintesis suara ucapan.
`voice`	string	`""`	Nama suara platform (`say -v '?'` di macOS); kosong = bawaan.
`rate`	integer	`0`	Kecepatan bicara jika didukung (kata/menit macOS, 1–500); 0 = bawaan.
`events.permission`	boolean	`true`	Peringatan pada permintaan izin.
`events.question`	boolean	`true`	Peringatan pada pertanyaan agen.
`events.complete`	boolean	`false`	Peringatan saat giliran selesai.
`events.error`	boolean	`true`	Peringatan pada kesalahan sesi.

Nilai yang tidak valid dibuang per bidang: nilai sound yang buruk kembali ke "off" tanpa memengaruhi pengaturan Anda yang lain.

Dukungan platform

Platform	Denting	Ucapan	Persyaratan
macOS	`afplay` (suara sistem)	`say`	Sudah bawaan.
Windows	`System.Media.SoundPlayer`	`System.Speech`	Sudah bawaan (PowerShell).
Linux	`paplay`, cadangan `canberra-gtk-play`	`spd-say`, cadangan `espeak-ng`	Pasang PulseAudio/`libcanberra` dan/atau `speech-dispatcher`/`espeak-ng`.

Ketersediaan diperiksa saat runtime. Jika tidak ada backend yang dapat dipakai, langkah audio dilewati diam-diam dan notifikasi terminal tetap menjadi cadangan. Pemutaran diserialkan (satu suara pada satu waktu, pengulangan digabung), setiap peristiwa memberi peringatan paling banyak sekali, dan antarmuka tidak pernah menunggu pemutaran. Eksekusi tanpa antarmuka (ax-code run) tidak pernah memutar audio.

Yang diucapkan

Ucapan hanya memakai empat templat tetap: Approval required: <tool>, Question: <first question>, Session idle: <session title>, dan AX Code error. Teks dipotong dan karakter kendali dihapus. Argumen alat, jalur berkas dari muatan, keluaran model, dan pesan kesalahan tidak pernah diucapkan — aman untuk ruang bersama dalam batas itu.

Suara khusus lewat hooks

Untuk kendali penuh (berkas suara Anda sendiri, teks berbeda, peristiwa tambahan), sambungkan pemutar apa pun melalui hooks siklus hidup — ini juga berfungsi saat notifikasi audio dimatikan. Setelah ikut serta dengan AX_CODE_TRUST_PROJECT_CONFIG=1, buat .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'" }
  ]
}

Gunakan pemutar platform Anda (afplay di macOS, paplay di Linux, PowerShell [System.Media] di Windows). Perintah hook adalah cuplikan shell — buat agar berjalan tanpa menunggu supaya tidak menunda jalur siklus hidup.

Membangun pemberi tahu eksternal

Alat eksternal (bilah status, dorongan seluler, aplikasi desktop) dapat berlangganan aliran peristiwa server dan bereaksi terhadap permission.asked, question.asked, session.status, dan session.error — lihat Kompatibilitas HTTP dan OpenAPI.