Skip to main content
Glama

voice-dialog

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

할 수 있는 것

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

도구

용도

speak

단방향 안내 방송(작업 완료, 마일스톤)

listen

녹음+인식(구술 지시)

ask_by_voice

원자적 질문: 한 번 말하기→한 번 듣기, 자동으로 계속 듣지 않음(무한 루프 방지)

init

원클릭 초기화(아래 참조)

doctor

환경 점검(확인만, 설치 안 함)

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/에 복사하세요.

지원 플랫폼

macOS

Windows

Linux

음성 인식

실측 통과

사용 가능

사용 가능

음성 합성

시스템 TTS

SAPI

espeak-ng 설치 필요

알림음

사용 가능

사용 가능

ffmpeg 필요

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

자주 묻는 질문

증상

해결 방법

init에서 uv 미설치 오류

위의 curl 설치 명령 실행 후 터미널 재시작

마이크 프로브 실패

macOS: 시스템 설정→개인정보 보호 및 보안→마이크→터미널 체크; Windows: 설정→개인정보→마이크

모델 다운로드 실패/매우 느림

export HF_ENDPOINT=https://hf-mirror.com 후 다시 실행

TTS 소리 없음

시스템 출력 장치가 가상 사운드 카드(BlackHole 등)에 점유되었는지 확인

코드 수정이 반영 안 됨

MCP 서버는 상주 프로세스: pkill -f "voice-dialog serve"

개인정보 보호

음성은 로컬에서 인식(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

크기

특징

tiny

~75MB

가장 빠름, 정확도 보통

base

~142MB

빠름, 일상에 충분

small(기본)

~464MB

균형, 추천

medium

~1.5GB

더 정확, M 칩에서 초 단위 전사가 10초 단위로

large-v3

~3GB

가장 정확하고 느림, 짧은 대화에는 비추천

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers