Claude Code용 로컬 음성 인터페이스 Raz

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Raz는 오디오를 클라우드로 보내지 않고 Apple Silicon에서 Claude Code와 음성으로 대화하도록 만든 로컬 인터페이스입니다. mlx-whisper가 push-to-talk 음성을 텍스트로 바꾸고, kokoro-mlx와 localhost의 FastAPI 서버가 Claude의 산문 응답을 음성으로 변환하며 코드 블록과 표는 건너뜁니다. MCP 도구 10개로 음성 설정과 듣기 상태를 Claude가 제어하고, Whisper는 5분 유휴 뒤 언로드되어 약 4GB의 메모리를 반환합니다. 54개 음성과 10개 언어를 지원하며 Apple Silicon Mac, Python 3.12, Claude Code, uv 환경에서 약 5분 만에 설치할 수 있습니다.

실용적 조언

Apple Silicon Mac에서 Claude Code를 음성으로 사용하려면 저장소를 복제한 뒤 `uv sync`를 실행하고 MCP 서버와 Stop hook을 차례로 등록하면 됩니다. Right Option 키를 push-to-talk 입력 키로 사용하므로 전역 단축키 충돌 여부를 먼저 확인하는 편이 좋습니다. Whisper가 첫 입력 때 로드되므로 최초 음성 인식에는 모델 초기화 시간이 필요합니다.

섹션별 상세

Raz는 클라우드 서비스로 오디오를 보내지 않고 Claude Code와 음성으로 주고받으려는 요구에서 출발한 로컬 인터페이스입니다. 사용자가 Right Option 키를 누른 채 말하고 손을 떼면 mlx-whisper가 음성을 텍스트로 바꿔 Claude Code 입력창에 붙여 넣습니다. 응답 쪽에서는 Stop hook이 실행되며 코드 블록과 표를 건너뛰고 산문만 TTS로 읽어 작업 중 음성 대화를 이어 가도록 구성됩니다.

전체 처리는 Apple Silicon에 맞춘 로컬 구성으로 이루어집니다. kokoro-mlx가 TTS를, mlx-whisper의 large-v3-turbo와 greedy decoding이 STT를 맡고, localhost의 FastAPI 서버가 음성 합성 요청을 처리합니다. 따라서 게시물의 핵심 구현은 음성 입력과 출력을 각각 로컬 모델과 로컬 서버로 분리해 Claude Code의 기존 입력·응답 흐름에 연결한 데 있습니다.

Raz는 음성 기능을 단순한 입출력 장치가 아니라 Claude Code가 제어할 수 있는 도구로 확장합니다. MCP 서버에 등록된 10개 도구를 통해 Claude가 음성, 속도, 동작 모드를 바꾸거나 듣기를 시작하고 중지할 수 있습니다. 게시물은 54개 음성과 10개 언어를 지원한다고 밝혀 다국어 음성 인터페이스로 사용할 수 있는 범위도 구체적으로 제시합니다.

메모리 사용량을 줄이기 위해 Whisper는 첫 사용 시에만 로드되고 5분 동안 유휴 상태이면 자동으로 언로드됩니다. 이 방식으로 약 4GB를 반환하며, 음성 입력을 계속 실행하지 않는 동안 Apple Silicon의 메모리 점유를 낮춥니다. 설치에는 Apple Silicon Mac, Python 3.12, Claude Code, uv가 필요하고 `uv sync`, MCP 서버 등록, 자동 발화 훅 추가 순서로 약 5분이 걸린다고 안내합니다.

용어 해설

음성 합성(TTS): — TTS는 텍스트를 음성으로 변환하는 기술입니다. 이 프로젝트에서는 Claude Code의 답변에서 산문을 추출한 뒤 코드 블록과 표를 제외하고 음성으로 읽어 주는 출력 단계에 사용됩니다.
음성 인식(STT): — STT는 사용자의 음성을 텍스트로 바꾸는 기술입니다. Right Option 키를 누른 동안 녹음한 음성을 mlx-whisper가 전사하고, 변환된 문장을 Claude Code에 붙여 넣는 입력 과정에 쓰입니다.
모델 컨텍스트 프로토콜(MCP): — MCP는 외부 기능을 AI 애플리케이션과 연결하는 인터페이스입니다. Raz는 10개의 MCP 도구를 통해 Claude가 음성 변경, 속도 조절, 듣기 시작과 중지를 직접 제어하도록 구성됩니다.
중지 훅(Stop hook): — Stop hook은 Claude Code의 응답 처리가 끝나는 시점에 외부 동작을 실행하는 연결 지점입니다. Raz는 이 훅에서 완성된 응답을 로컬 TTS 서버로 전달해 자동 음성 출력을 시작합니다.
탐욕적 디코딩(greedy decoding): — greedy decoding은 각 단계에서 가장 높은 확률의 토큰을 선택해 음성을 텍스트로 변환하는 추론 방식입니다. Raz의 STT 구성은 mlx-whisper의 large-v3-turbo 모델에 이 방식을 적용합니다.

언급된 도구

kokoro-mlx추천

Apple Silicon에서 로컬 TTS를 실행하는 라이브러리

mlx-whisper추천

large-v3-turbo와 greedy decoding을 이용해 로컬 STT를 실행하는 라이브러리

FastAPI중립

localhost에서 TTS 요청을 처리하는 서버 구성

MCP추천

Claude Code가 Raz의 음성 제어 기능을 호출하도록 연결하는 서버 인터페이스

pynput중립

전역 push-to-talk 단축키를 처리하는 라이브러리

uv중립

Python 의존성 설치와 프로젝트 동기화에 사용하는 도구

언급된 리소스

GitHubMateob6/claude-voice-interaction