voice-dialog

MCP-сервер, добавляющий голосовой диалог AI-агенту, который также можно использовать как инструмент командной строки. Когда агент закончил работу, он может сообщить вам голосом, а также спросить вас и выслушать ответ. Распознавание выполняется локально на 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 秒 → 低沉"咚…咚↓"= 录音结束

Подключение вашего агента

Любой 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 (опционально, обучает агента, когда говорить/слушать): скопируйте 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/ → откройте терминал и перейдите в каталог, дальше доверьтесь ИИ:

В Claude Code (или любом ИИ-инструменте программирования, умеющем выполнять команды) отправьте ему следующий текст как есть:

帮我安装这个目录里的 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: после распаковки щёлкните правой кнопкой по папке → Службы → Новый терминал в папке, и вы окажетесь в нужном каталоге.