이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

오디오 알림

상태: 현재 범위: AX Code TUI 소리와 음성 알림 최종 검토: 2026-09-12 담당: AX Code 런타임 유지관리자

TUI는 AX Code가 사용자의 주의가 필요할 때마다 시스템 소리를 내거나, 짧은 템플릿 문장을 읽어 줍니다.

권한 요청 — 도구가 승인을 기다립니다.
에이전트 질문 — 에이전트가 질문을 했습니다.
턴 완료 — 실행이 끝났습니다(기본값은 꺼짐).
세션 오류 — 턴이 실패했습니다.

오디오는 터미널 알림과 같은 트리거를 탑니다. OSC 9 데스크톱 알림이거나, OSC 9를 지원하지 않으면 터미널 벨입니다. 같은 notifications.enabled 스위치로 제어합니다. 기본값은 꺼짐이며, 켜도 알림의 다른 동작은 바뀌지 않습니다.

구성

notifications.sound을 tui.json에서 설정합니다.

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

필드	값	기본값	의미
`enabled`	불리언	`true`	터미널 알림과 오디오의 주 스위치입니다.
`sound`	`"off"`, `"chime"`, `"speak"`	`"off"`	`chime`은 시스템 소리를 재생하고, `speak`은 음성을 합성합니다.
`voice`	문자열	`""`	플랫폼 음성 이름(macOS에서는 `say -v '?'`). 비어 있으면 기본값입니다.
`rate`	정수	`0`	지원되는 경우의 말하기 속도(macOS는 분당 단어 수, 1–500). 0은 기본값입니다.
`events.permission`	불리언	`true`	권한 요청 때 알립니다.
`events.question`	불리언	`true`	에이전트 질문 때 알립니다.
`events.complete`	불리언	`false`	턴이 끝날 때 알립니다.
`events.error`	불리언	`true`	세션 오류 때 알립니다.

잘못된 값은 필드마다 버려집니다. sound 값이 잘못되면 다른 설정은 그대로 두고 "off"로 되돌립니다.

플랫폼 지원

플랫폼	차임	음성	요구 사항
macOS	`afplay` (시스템 소리)	`say`	기본 제공.
Windows	`System.Media.SoundPlayer`	`System.Speech`	기본 제공(PowerShell).
Linux	`paplay`, 폴백 `canberra-gtk-play`	`spd-say`, 폴백 `espeak-ng`	PulseAudio/`libcanberra` 및/또는 `speech-dispatcher`/`espeak-ng`을 설치합니다.

사용 가능 여부는 런타임에 확인합니다. 쓸 수 있는 백엔드가 없으면 오디오 단계는 조용히 건너뛰고, 터미널 알림이 폴백으로 남습니다. 재생은 직렬화됩니다. 한 번에 소리 하나이며, 반복은 하나로 합칩니다. 각 이벤트는 최대 한 번만 알리고, 인터페이스는 재생을 기다리지 않습니다. 헤드리스 실행(ax-code run)은 오디오를 재생하지 않습니다.

읽어 주는 내용

음성은 네 가지 고정 템플릿만 사용합니다. Approval required: <tool>, Question: <first question>, Session idle: <session title>, AX Code error입니다. 텍스트는 잘라 내고 제어 문자를 제거합니다. 도구 인자, 페이로드의 파일 경로, 모델 출력, 오류 메시지는 읽지 않습니다. 이 한계 안에서는 공유 공간에서도 안전합니다.

훅으로 사용자 지정 소리

완전히 제어하려면(자신의 소리 파일, 다른 텍스트, 추가 이벤트) 수명 주기 훅으로 원하는 재생기를 연결합니다. 오디오 알림을 꺼 둔 상태에서도 동작합니다. AX_CODE_TRUST_PROJECT_CONFIG=1로 선택한 뒤 .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'" }
  ]
}

플랫폼의 재생기를 사용합니다(macOS는 afplay, Linux는 paplay, Windows는 PowerShell [System.Media]). 훅 명령은 셸 조각입니다. 수명 주기 경로를 지연시키지 않도록, 끝내기를 기다리지 않는 방식으로 유지합니다.

외부 알림기 만들기

외부 도구(상태 표시줄, 모바일 푸시, 데스크톱 앱)는 서버의 이벤트 스트림을 구독하고 permission.asked, question.asked, session.status, session.error에 반응할 수 있습니다. HTTP 및 OpenAPI 호환성을 보십시오.