talkback — 듣기, 읽기 대신은(는) 무엇을 하나요?

모든 프로젝트 디렉토리에서 텍스트를 소리 내어 읽어주고, 오디오를 저장하며, 제한된 할당량을 조용히 소모하지 않습니다.

기본적으로 요청 시에만 동작합니다. 사용자가 "그거 소리 내어 설명해줘"라고 요청하거나 스크립트를 직접 실행할 때만 읽어줍니다. 누군가 말하기 모드를 켜기 전까지는 스스로 내레이션하지 않으며, 말하기 모드는 한 번에 하나의 세션에만 적용됩니다.

사용 방법

S=~/.claude/skills/talkback/scripts

$S/talkback.py "여기에 변경된 내용과 그 이유가 있습니다."   # ElevenLabs (기본값)
$S/talkback.py --fast "임시 메시지."                      # 로컬, 즉시, 무료
$S/talkback.py --quota                                     # 남은 할당량 확인
$S/talkback.py --voices                                    # 사용 가능한 음성 목록
$S/talkback.py --dry-run "..."                             # 읽을 텍스트만 확인, 합성하지 않음
$S/talkback.py --help                                      # 모든 플래그 보기

$S/talkback-hook.py --on                                   # 말하기 모드 켜기, 이 세션만
$S/talkback-hook.py --off                                  # 말하기 모드 끄기
$S/talkback-hook.py --status                               # 누가 말하고 있는지, 훅이 연결되었는지 확인
$S/talkback-hook.py --outputs                              # 이 호스트의 오디오 출력 장치 목록

텍스트를 파이프로 전달할 수도 있습니다: git log -1 --format=%B | $S/talkback.py.

에이전트가 사용하는 방법

여기에는 두 가지 다른 기능이 있습니다. 일회성 말하기는 talkback.py에 전달할 구성된 산문입니다. 말하기 모드는 talkback-hook.py로 켜고 끄는 지속적인 설정입니다. 텍스트를 직접 구성할 필요 없이, 훅이 응답을 읽습니다.

일회성 말하기

사용자가 설명을 듣고 싶어할 때, 듣기에 적합하게 글을 쓰고 말하세요. 원시 마크다운이나 diff를 도구에 파이프로 전달하지 마세요. 변경된 내용, 이유, 사용자에게 의미하는 바 등 2~5문장의 평범한 말하기 산문을 구성하여 전달하세요. 듣는 사람은 되돌려 읽을 수 없으므로, 결론부터 말하세요.

기본적으로 좋은 음성을 사용하세요. 계획이 여유롭습니다. 텍스트가 임시적이거나 네트워크 지연을 원하지 않을 때는 --fast를 사용하세요. 폴백이 발생한 경우 어떤 백엔드를 사용했는지 알려주세요.

말하기 모드 사용

사용자의 말은 하나의 명령어에 매핑됩니다. 명령어를 실행하기만 하면 됩니다. 변경 사항을 수동으로 내레이션하지 마세요. 훅이 당신이 작성하는 응답을 읽을 것이기 때문입니다.

사용자 말	실행할 명령어
"말하기 모드 켜줘", "계속 말해줘", "이 세션 내레이션 해줘"	`talkback-hook.py --on`
"말하기 그만", "음소거", "조용히 해"	`talkback-hook.py --off`
"핵심만 알려줘", "간략하게"	`talkback-hook.py --on brief`
"중요한 부분만 말해줘"	`talkback-hook.py --on marker`
"내 에어팟 써", "X 기기로 재생해줘"	`talkback-hook.py --outputs`, 그 다음 `--on --output "<이름>"`
"싼 음성 써", "할당량 소모하지 마"	`talkback-hook.py --on --backend say`
"켜져 있어?", "왜 아무 소리도 안 들려?"	`talkback-hook.py --status`
"다른 게 말하고 있어?"	`talkback-hook.py --sessions`
"모든 것을 조용히 해" (모든 세션)	`talkback-hook.py --off --all`

사용자에게 작동한다고 말하기 전에 확인해야 할 세 가지:

--status는 훅이 등록되었는지 보고합니다. 등록되지 않은 경우 --install을 실행하고 다시 시작해야 한다고 알리세요.
--status가 이 세션이 시작된 후에 훅이 등록되었다고 경고하면, 말하기 모드는 켜져 있지만 여기서는 소리가 나지 않습니다. 그렇게 말하세요. 사용자가 침묵 속에서 발견하게 두지 마세요.
말하기 모드는 세션이 지속되지 않습니다. 다시 시작하거나 /clear 후에는 다시 꺼지며 --on이 필요합니다. 이는 의도적인 설계이며 버그가 아닙니다. 사용자가 다시 요청하지 않도록 한 번만 설명하세요.

marker 모드에서는 — 그리고 읽어주기가 응답 자체 대신 듣기에 적합한 요약이 되기를 원할 때마다 — 메시지 끝에 마커를 추가하세요:

<!-- talkback: 인증 계층 리팩토링, 호출 지점 3개, 테스트 통과. -->

백엔드

백엔드	비용	품질	참고
`elevenlabs` (기본값)	할당량 제한	최고	할당량 보호, 자동으로 `say`로 폴백
`say` (`--fast`)	무료, 무제한	보통	macOS 기본, ~즉시, 네트워크 불필요
`omnivoice`	무료, 무제한	좋음	로컬 + 개인 정보 보호; 백엔드가 실행 중이어야 함. 미확인 — 아래 참조

백엔드 체인

elevenlabs → omnivoice → say, 최고 우선. 작업을 처리할 수 없는 단계(키 없음, 할당량 소진, 로컬 서버 다운, 합성 오류)는 다음 단계로 넘기므로, 음성이 없어지는 대신 품질이 저하됩니다. TALKBACK_CHAIN이 순서를 변경합니다.

특정 단계를 명시적으로 요청하면 그 단계부터 시작하여 아래로만 내려갑니다: --fast는 "지금 로컬"을 의미하며, 할당량이 있는 백엔드로 다시 올라가지 않습니다. 모든 폴백은 이유를 stderr에 출력하고 선택된 백엔드는 원장(ledger)에 기록되므로, 품질 저하가 발생해도 조용히 넘어가지 않습니다.

--strict는 모든 폴백을 하드 실패(종료 코드 1)로 전환하여, 조용히 품질이 저하되어서는 안 되는 스크립트에 사용합니다.

할당량

계정은 Creator 등급입니다: 월 130,958자. 2분 분량의 음성 설명은 약 1,500자이므로, 한 달에 약 87번 사용 가능합니다. 따라서 좋은 음성을 특별한 경우가 아닌 기본값으로 사용할 수 있습니다.

메모리가 아닌 사용 시점에 확인하세요. talkback.py --quota는 실시간으로 읽어옵니다. 등급은 이미 한 번 변경되었으며, 문서에 적힌 숫자는 계획이 변경되는 순간 오래된 정보가 됩니다.

합성하기 전에 도구는 실시간 할당량을 읽고 250자의 예비 할당량을 유지하므로, 한 번의 긴 설명으로 잔액이 완전히 소진되지 않습니다. 요청이 맞지 않으면 stderr에 경고하고 say를 대신 사용합니다.

자격 증명은 다음 순서로 확인됩니다: $ELEVENLABS_API_KEY → ~/.elevenlabs/api_key (elevenlabs auth login으로 작성) → ~/broomva/.env.local의 ELEVENLABS_API_KEY. 이 머신에는 두 개의 서로 다른 키가 있으며 동일한 계정으로 확인되므로, 하나를 확인하면 둘 다 확인하는 것과 같습니다.

Creator 등급은 또한 인스턴트 및 프로페셔널 음성 복제(30개 음성 슬롯, 1개 프로페셔널)를 잠금 해제합니다. --voices는 계정에서 현재 사용할 수 있는 음성을 나열합니다.

@elevenlabs/cli 패키지는 런타임에 사용되지 않으며 이 작업을 수행할 수 없습니다. 이 패키지의 전체 기능은 auth · agents · tools · tests · components로, 호스팅된 ConvAI 에이전트 프로젝트를 관리합니다. 합성 명령어가 없습니다. 이 CLI는 auth login에만 유용하며, 키 파일을 작성합니다.

OmniVoice 등급은 미확인

omnivoice 백엔드는 문서화된 형태로 구현되었지만 실제로 테스트되지 않았습니다 — 이 기능이 출시될 때 로컬 백엔드가 다운되어 있었습니다. 정상적으로 저하됩니다(say로 폴백되거나 --strict에서 실패). 설정하려면 omnivoice 스킬을 참조하세요. 저장소는 이미 ~/broomva/external/OmniVoice-Studio에 있습니다.

음성 텍스트 처리

에이전트의 산문은 듣기 위해 작성된 것이 아니므로, 텍스트가 먼저 준비됩니다:

코드 블록 → (코드 생략); URL → (링크)
제목과 글머리 기호는 문장 구분점이 되어 목록이 서로 붙어 읽히지 않습니다.
깊은 경로는 기본 이름으로 단축됩니다(src/lib/engine.py → engine.py); 전체 경로를 듣고 싶다면 --keep-paths를 전달하세요.
마크다운 강조는 범위를 구분하는 경우에만 제거됩니다. backend_chain 내부의 밑줄은 그대로 유지됩니다. 지우면 사용자가 검색할 수 있는 기호를 검색할 수 없는 기호로 바꾸기 때문입니다.

저장된 오디오

모든 발화는 ~/.talkback/audio/ 디렉토리에 타임스탬프와 슬러그가 포함된 파일 이름의 mp3(ffmpeg가 있을 경우 변환)로 저장되며, ~/.talkback/ledger.jsonl에 추가됩니다. 저장하지 않으려면 --no-save, 출력 디렉토리를 변경하려면 --out-dir을 사용하세요.

말하기 모드 — 세션 진행 상황 내레이션

말하기 모드는 에이전트가 매 응답의 끝에 짧은 읽어주기를 말하게 합니다. 세션이 지속되는 동안만 유지됩니다. 기본적으로 꺼져 있으며, 수동으로 켜고, 하나의 세션에만 속합니다.

$S/talkback-hook.py --on                    # 모든 응답, 상세, 이 세션
$S/talkback-hook.py --on brief              # 시작 부분만
$S/talkback-hook.py --on marker             # 마커가 있는 응답만
$S/talkback-hook.py --on --backend elevenlabs   # 좋은 음성, 할당량 사용
$S/talkback-hook.py --on --output "AirPods Pro"  # 이 세션이 사용할 스피커
$S/talkback-hook.py --off                   # 말하기 중지 (이 세션)
$S/talkback-hook.py --off --all             # 모든 세션 강제 중지
$S/talkback-hook.py --status                # 모드, 백엔드, 말하고 있는 다른 세션
$S/talkback-hook.py --sessions              # 현재 말하고 있는 모든 세션

세션 범위인 이유

Stop 훅은 한 번 전역적으로 영구적으로 등록됩니다. 세션 중에 전환할 수 없는 토글은 토글이 아닙니다. 따라서 훅은 모든 세션에서 실행되며, 플래그가 범위를 지정합니다: 말하기 모드는 머신의 속성이 아니라 세션의 속성입니다.

플래그는 ~/.talkback/sessions/<session-id>입니다. 옵트인하지 않은 세션에는 플래그가 없으므로 훅은 소리 없이 종료 코드 0으로 종료됩니다. 이것이 바로 여섯 개의 병렬 에이전트가 여섯 개의 작업 디렉토리에서 조용히 있는 동안 사용자가 보고 있는 하나의 세션만 말하게 하는 이유입니다. 0.3.0 이전 디자인에는 머신 전체에 하나의 플래그가 있었으며, 이것이 결코 켜지지 않은 이유입니다. 활성화하면 상자의 모든 에이전트가 동시에 들리게 되었기 때문입니다.

세션 ID는 CLAUDE_CODE_SESSION_ID 또는 CLAUDE_SESSION_ID에서 읽습니다. --session <id>로 명시적으로 설정할 수 있습니다. 둘 다 없으면 명령어는 pass --session <id>를 출력하고 종료 코드 2로 종료됩니다. 예전에는 작업 디렉토리에서 가장 최근 트랜스크립트로 폴백되었는데, 이는 하나의 디렉토리에 두 개의 세션이 열려 있을 때 --on이 요청한 세션이 아닌 가장 최근에 접근한 세션을 활성화했음을 의미합니다.

훅 측면에서 페이로드의 session_id는 권위적입니다. 존재하는 경우 게이트가 승인하는 유일한 키입니다. 트랜스크립트 파일 이름 stem은 해당 필드가 없을 때만 사용됩니다. 둘 다 한때 함께 허용되었는데, 이는 세션 A와 세션 B의 트랜스크립트를 명명하는 페이로드가 B의 옵트인을 확인하고 A에서 말하게 할 수 있었습니다.

--session <id>로 다른 세션을 대상으로 하는 것은 의도적이며 보안 경계가 아닙니다. 세션 A가 talkback-hook.py --session B --off를 실행하면 B의 동의 없이 B의 말하기 모드를 활성화 또는 비활성화합니다. 플래그를 설정한 세션에 바인딩하는 소유권 검사는 없습니다. 이는 기능이며, 의도적으로 유지됩니다. 상자의 모든 세션은 동일한 OS 사용자로 실행되므로, 모든 세션은 ~/.talkback/sessions/ 아래에 다른 세션의 플래그 파일을 직접 쓸 수 있습니다. CLI 내부의 소유권 검사는 플래그를 통한 정중한 경로만 막을 뿐 직접적인 경로는 막지 못합니다. 동일 주체 경계는 주체를 공유하는 작성자를 막을 수 없습니다. 플래그는 오디오의 범위를 지정하므로 병렬 에이전트는 기본적으로 조용히 유지됩니다. 제어의 범위를 지정하지 않으며, 여기 있는 어떤 것도 그렇게 읽혀서는 안 됩니다.

상세 수준

모드	말하는 내용
`full` (세션 기본값)	전체 응답, 매 응답마다 — 에이전트가 마커를 작성한 경우 마커로 시작
`brief`	`TALKBACK_HOOK_CHARS`(320자) 이상인 응답의 시작 부분(`TALKBACK_HOOK_MIN_CHARS` 80자 초과); 마커가 있으면 마커 우선
`marker`	`<!-- talkback: … -->` 마커가 있는 응답만, 그리고 마커 텍스트만
`off`	절대 말하지 않음 — `--off`가 전역 플래그를 무시할 때 작성

full이 기본값인 이유는 읽어주기의 요점은 자리에서 벗어나 무슨 일이 일어났는지 알면서 돌아오는 것이기 때문입니다. 제한된 발췌는 답변의 미리보기일 뿐 답변 자체가 아닙니다. 여전히 화면을 읽어야 하며, 이것이 바로 말하기 모드가 존재하는 이유입니다. 생략되는 것은 들을 수 없는 것(코드 블록, URL, 깊은 경로 — 음성 텍스트 처리 참조)뿐이며, 단지 긴 것이 생략되지는 않습니다. full에는 길이 하한도 없습니다. "완료, 테스트 통과"는 자리에서 떠나 있을 때 원하는 결과이며, 소음이 아닙니다.

brief와 marker는 자세한 내용보다는 진행 상황의 개요를 원하는 긴 무인 작업 흐름을 위한 것입니다.

TALKBACK_FULL_MAX_CHARS는 full에 상한을 둡니다(기본값 없음). 상한을 두면 full은 전체를 듣기에 충분히 가치 있는 응답에서 brief로 되돌아갑니다.

읽어주기는 전체 백엔드 체인을 사용합니다. ElevenLabs를 먼저 시도하고, 사용할 수 없는 경우에만 다음 단계로 내려갑니다. 따라서 모든 응답의 전체 상세 내용은 실제 할당량을 소비합니다. 1,500자 응답은 월간 Creator 잔액의 약 1%이므로, 긴 세션은 예비 할당량에 도달하게 되며, 그 시점에서도 조용해지지 않고 다음 단계에서 계속 말합니다. --on --backend say는 낮은 수준으로 고정하고, --on brief는 길이를 줄입니다.

하나의 읽어주기가 다음 읽어주기와 겹칠 때

전체 읽어주기가 재생 중일 때 다음 응답이 끝날 수 있습니다. TALKBACK_ON_OVERLAP이 동작을 결정합니다:

값	동작
`interrupt` (기본값)	새로운 읽어주기가 이전 것을 중단합니다 — 가장 최근 상태가 들을 가치가 있는 상태입니다
`queue`	순서대로 재생되므로 긴 상세 읽어주기가 잘리지 않습니다. 지연되지만 모든 것을 들을 수 있습니다

queue는 전체를 다시 듣고자 하는 무인 작업 흐름에 적합한 설정입니다. interrupt는 기계 앞에 있을 때 최신 상태를 듣고자 할 때 적합합니다.

마커

marker 모드에서 단일 응답을 선택하거나, 메시지의 시작 부분 대신 듣기에 적합한 요약을 말하려면 메시지 끝에 다음을 추가하세요:

<!-- talkback: 인증 계층 리팩토링, 호출 지점 3개, 테스트 통과. -->

full 모드에서 마커는 헤드라인이 됩니다. 먼저 말해지고, 그 뒤에 전체 응답이 이어지므로, 읽어주기는 세부 사항을 잃지 않으면서 결론으로 시작합니다. brief 모드에서 마커는 발췌를 대체하며, 마커가 없는 응답은 문장 경계에서 잘린 시작 부분으로 폴백됩니다.

스피커 선택

오디오는 Claude Code를 실행하는 기계에서 출력됩니다. 전화, 태블릿 또는 다른 노트북에서 세션을 제어하더라도 여전히 호스트에서 소리가 나므로, 중요한 것은 호스트의 출력 중 어느 것을 사용할지 선택하는 것입니다. Mac에 페어링된 AirPods, AirPlay 스피커, 디스플레이, 내장 스피커 등이 될 수 있습니다.

$S/talkback-hook.py --outputs             # 이 호스트가 재생할 수 있는 장치
$S/talkback-hook.py --on --output "AirPods Pro"
$S/talkback.py -d "MacBook Pro Speakers" "선택한 장치로 한 번 말하기"

출력은 세션별로 저장됩니다.

talkback — 듣기, 읽기 대신