Raz — голосовой интерфейс для Claude Code

Общайтесь с Claude Code голосом. Claude отвечает вслух. Всё работает локально на вашем Mac — никаких облачных API, никаких подписок, данные не покидают ваш компьютер.

Raz (от арамейского רָז, «раскрытая тайна») даёт Claude Code голос и слух: kokoro-mlx отвечает за речь, а mlx-whisper — за распознавание. Обе модели оптимизированы для Apple Silicon.

Как это работает

You speak (hold Right Option key) ──► Whisper transcribes ──► text goes to Claude
Claude responds ──► auto-speak reads the response aloud through your speakers

Вот и всё. Когда Raz включён, вы ведёте голосовой диалог с Claude. Кодовые блоки и таблицы молча пропускаются — озвучивается только обычный текст.

Что вам понадобится

Установка

Вся установка занимает около 5 минут. Каждый шаг — просто копирование и вставка.

Шаг 1. Клонирование и установка

git clone https://github.com/Mateob6/claude-voice-interaction.git
cd claude-voice-interaction
uv sync

Эта команда загружает код и устанавливает все зависимости Python (kokoro-mlx, mlx-whisper, FastAPI, pynput и т. д.) в изолированное виртуальное окружение.

Шаг 2. Установка CLI

mkdir -p ~/.local/bin
ln -sf "$(pwd)/scripts/raz" ~/.local/bin/raz
chmod +x scripts/raz scripts/start_server.sh scripts/stop_server.sh

Убедитесь, что ~/.local/bin есть в вашем PATH. Если нет:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Проверьте, что всё работает:

raz help

Шаг 3. Регистрация MCP-сервера

Это позволит Claude Code управлять Raz через 10 встроенных инструментов (speak, смена голоса, запуск/остановка прослушивания и т. д.):

claude mcp add raz -- uv run --directory "$(pwd)" python -m raz.mcp_server

Шаг 4. Настройка автоозвучивания

Этот хук автоматически озвучивает ответы Claude. Добавьте его в настройки Claude Code:

cat ~/.claude/settings.json

Если файл уже существует — добавьте секцию hooks. Если нет — создайте его:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/FULL/PATH/TO/claude-voice-interaction/hooks/stop_hook.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Важно: замените /FULL/PATH/TO/claude-voice-interaction на реальный путь, куда вы клонировали репозиторий. Его можно узнать командой pwd, находясь в каталоге проекта.

Шаг 5. Первый запуск

raz start

Эта команда запускает два процесса:

• TTS-сервер (текст-в-речь) — загружает модель kokoro-mlx (~10 секунд при первом запуске)

• STT-демон (речь-в-текст) — следит за нажатием правой клавиши Option

Вы должны увидеть:

=== Starting Raz ===
Starting Raz TTS server (background) on port 8787...
Raz ready!
Starting STT daemon (lang=es)...
Loading Whisper model. ready!
PID: 12345

Проверьте:

raz say "Hello, I can speak now"

Если вы слышите голос — всё работает. Остановить Raz можно так:

raz stop

Использование Raz

Начало голосового сеанса

raz start    # start voice + mic
raz stop     # stop everything
raz status   # check what's running

Разговор с Claude (push-to-talk)

1. Удерживайте клавишу Right Option (⌥) на клавиатуре

2. Произнесите сообщение

3. Отпустите клавишу

4. Распознанный текст будет вставлен в Claude Code

Вы услышите звук Tink, когда запись начнётся, и Pop, когда она закончится.

В первый раз: macOS запросит разрешение на специальные возможности для вашего терминального приложения. Предоставьте его — pynput нужен он для глобального отслеживания горячей клавиши.

При первом нажатии: модель Whisper загружается при первом использовании (~3 секунды). После этого транскрибация происходит почти мгновенно. Модель автоматически выгружается после 5 минут бездействия, чтобы освободить память.

Смена голоса

raz voice af_heart    # switch to English female (best quality)
raz voice em_alex     # switch to Spanish male (default)
raz voice bm_fable    # switch to British storyteller
raz voices            # see all 54 voices

Настройка скорости

raz speed 1.5    # faster
raz speed 0.8    # slower
raz speed 1.0    # normal

Одноразовая транскрибация

Записать звук и скопировать транскрипцию в буфер обмена (без запущенного демона):

raz listen         # Spanish (default)
raz listen en      # English
# Press Ctrl+C when done speaking

Горячая клавиша (необязательно)

Включать и выключать Raz из любой приложения можно через глобальную горячую клавишу:

raz shortcut install

Затем назначьте сочетание:

1. System Settings → Keyboard → Keyboard Shortcuts → Services → General

2. Найдите пункт «Activar Raz» (озвучка в списке Services)

3. Нажмите «Add Shortcut» и введите нужную комбинацию (например, ⌃⌘R)

Теперь эта комбинация будет переключать Raz из любого места, с уведомлением macOS.

Голоса

54 голоса — в 10 языках. Яркие представители:

Полный список: raz voices

Конфигурация

Режимы автоозвучивания

raz mode smart    # recommended
raz mode auto     # hear everything
raz mode off      # silent, use speak() when needed

Определение языка

Raz автоматически определяет, на испанском или английском написан текст, и переключает голоса. Если вы задали em_alex (испанский мужской), а Claude отвечает на английском, Raz переключится на am_adam (английский мужской) и затем вернётся обратно.

Язык распознавания (STT)

Демон push-to-talk по умолчанию слушает испанскую речь. Запустить его с другим языком:

raz stt start en    # English
raz stt start es    # Spanish (default)

Архитектура

Claude Code
  ├── MCP tools (10) ──► localhost:8787 (TTS: kokoro-mlx)
  │                  ──► raz.stt.daemon  (STT: control)
  ├── Stop hook ──► localhost:8787/auto-speak
  ├── STT daemon (pynput + mlx-whisper) ──► clipboard ──► paste
  └── CLI (raz) ──► unified lifecycle

STT-демон загружает Whisper лениво (при первом нажатии) и автоматически выгружает модель через 5 минут бездействия, освобождая ~4 ГБ памяти.

Решение проблем

«Правая клавиша Option не работает»

Вашему терминальному приложению нужно разрешение специальных возможностей (Accessibility). Откройте «Системные настройки → Приватность и безопасность → Специальные возможности» и добавьте ваш терминал (iTerm2, Terminal.app и т. д.).

«raz start зависает на «Loading Whisper model»»

При первом запуске загружается модель Whisper (~800 МБ). Проверьте подключение к интернету. После первого запуска модель уже находится в кэше.

«Порт 8787 уже занят»

Выполняется другой экземпляр Raz. Остановите его:

raz stop
# If that doesn't work:
pkill -f "raz.tts_server"

«No daemon doesn't stop»

pkill -f "run_daemon"

«Нет звука»

Проверьте, правильно ли настроен вывод звука на Mac (Системные настройки → Звук). Raz играет через выход по умолчанию.

Справочник по CLI

raz start           # Start Raz (voice + mic)
raz stop            # Stop Raz
raz on / raz off    # Enable/disable Raz
raz status          # Show Raz status

raz say "text"      # Speak text
raz listen [lang]   # Record → transcribe → clipboard
raz voice NAME      # Change voice
raz voices          # List all 54 voices
raz mode MODE       # smart | auto | off
raz speed N         # 0.5–2.0

raz stt start|stop  # Mic only
raz tts start|stop  # Voice only
raz shortcut install|remove  # Keyboard shortcut

Инструменты MCP

При подключении как MCP-сервер Claude Code получает следующие 10 инструментов:

Лицензия

MIT