voice-dialog

AI Agent에 음성 대화 기능을 추가하는 MCP 서버로, 명령줄 도구로도 사용할 수 있습니다. Agent가 작업을 마치면 말로 알려줄 수 있고, 질문을 하거나 답변을 들을 수도 있습니다. 인식은 로컬 whisper에서 실행되고, 합성은 시스템 내장 TTS를 사용하며, 전 과정에서 인터넷에 연결하지 않고 오디오를 전송하지 않습니다.

할 수 있는 것

你（没看屏幕）："搞定了吗？"
Agent（出声）："代码写完了，测试全过。要提交吗？"      ← ask_by_voice
你："先不提交，我看看再说"                             ← listen 收到，本地转写
Agent（出声）："好，先留着。"                          ← speak

Related MCP server: Pipecat MCP Server

빠른 시작

git clone https://github.com/VictorHuang0843/voice-dialog.git
cd voice-dialog

# 没装 uv？先来这个（Windows 用 install.ps1）：
#   curl -LsSf https://astral.sh/uv/install.sh | sh

uv run voice-dialog init

init은 7단계 완전 자동 가이드입니다: uv 설치 → 의존성 설치(uv가 Python까지 설치해 줍니다) → whisper 모델 다운로드(464MB, 중국 네트워크는 자동으로 hf-mirror 사용) → 마이크 권한 실측 → TTS 출력 실측 → MCP 등록 명령 출력. 실패한 단계의 수정 명령을 안내하고, 수정 후 다시 실행하면 됩니다.

한 번 시도해 보세요:

uv run voice-dialog speak "语音系统就绪" --lang zh
uv run voice-dialog ask "请说话" --wait-start 60
# 你会听到：高亮上扬"叮↑"= 开始说话 → 停 3 秒 → 低沉"咚…咚↓"= 录音结束

Agent 연동

모든 MCP 클라이언트(Claude Code, Codex, Cursor, LoopX……):

{
  "mcpServers": {
    "voice-dialog": {
      "command": "uv",
      "args": ["--project", "/你的路径/voice-dialog", "run", "voice-dialog", "serve"]
    }
  }
}

Claude Code 한 줄 등록:

claude mcp add voice-dialog -s user -- uv --project /你的路径/voice-dialog run voice-dialog serve

MCP를 지원하지 않는 도구: CLI를 직접 호출, uv run voice-dialog speak/listen/ask "...".

Claude Code Skill(선택 사항, Agent에게 언제 말하고 언제 들을지 가르침): skills/voice-dialog/를 ~/.claude/skills/에 복사하세요.

지원 플랫폼

언어 자동 감지(whisper는 ~100개 언어 지원), VD_LANG=zh로 고정 가능; 모델 크기는 VD_MODEL=small로 조정 가능.

자주 묻는 질문

개인정보 보호

음성은 로컬에서 인식(faster-whisper)되고, 텍스트는 시스템 TTS로 재생되며, 클라우드 API를 호출하지 않고 오디오를 업로드하지 않습니다.

License

MIT

모델 설명

기본 다운로드? whisper small(int8 양자화, 약 464MB), 중영문 인식 효과와 속도의 균형점. 첫 listen/init 시 자동 다운로드되고, 이후 로컬에 캐시되며(macOS/Linux: ~/.cache/huggingface/hub/, Windows: %USERPROFILE%\.cache\huggingface\hub\), 다시 다운로드하지 않습니다.

다운로드 소스 선택? 코드에 다운로드 로직이 하드코딩되어 있지 않습니다. WhisperModel("small", ...) 생성 시 faster-whisper 라이브러리가 HuggingFace에서 자동으로 다운로드합니다. 기본은 공식 소스 huggingface.co를 사용하고, 공식 소스에 연결할 수 없으면 코드가 자동으로 국내 미러 hf-mirror.com으로 전환해 재시도합니다(HF_ENDPOINT 환경 변수 설정으로 구현). 국내 사용자는 미리 수동으로 고정할 수도 있습니다:

export HF_ENDPOINT=https://hf-mirror.com   # 加进 ~/.zshrc 一劳永逸

더 큰 모델로 교체? 환경 변수 VD_MODEL로 제어하며, 다시 실행하면 적용됩니다:

VD_MODEL=base uv run voice-dialog listen   # 单次用 base

zip으로 설치(git clone 불필요)

zip 다운로드(또는 친구가 직접 보내줌) → 원하는 위치에 압축 해제(예: ~/tools/) → 터미널을 열고 디렉터리로 이동, 이후는 AI에게 맡기세요:

Claude Code(또는 명령을 실행할 수 있는 모든 AI 프로그래밍 도구)에서 아래 내용을 그대로 보내세요:

帮我安装这个目录里的 voice-dialog 项目：
1. cd 到这个目录跑 uv run voice-dialog init（没装 uv 就先装：curl -LsSf https://astral.sh/uv/install.sh | sh）
2. init 全绿后，把打印出来的 claude mcp add 命令执行掉
3. 最后跑 uv run voice-dialog doctor 给我看结果

모든 것을 설치하고 Claude Code에 등록하며, 세션을 재시작하면 사용할 수 있습니다.

수동으로도 가능합니다. 명령 두 개면 됩니다:

cd 解压后的目录
uv run voice-dialog init        # 结束时打印注册命令，复制执行

Mac에서 터미널이 익숙하지 않다면: 압축 해제 후 폴더에서 마우스 오른쪽 클릭 → 서비스 → 폴더 위치에 새 터미널 창 열기를 선택하면 디렉터리로 이동합니다.