🏠 Главная › user guide › voice mode

Голосовой режим

Hermes Agent поддерживает полное голосовое взаимодействие через интерфейс командной строки и платформы обмена сообщениями. Разговаривайте с агентом с помощью микрофона, слушайте устные ответы и общайтесь в реальном времени в голосовых каналах Discord.

Если вам нужно практическое руководство по настройке с рекомендуемыми конфигурациями и реальными схемами использования, см. Использовать голосовой режим с Hermes.

Предварительные условия

Прежде чем использовать голосовые функции, убедитесь, что у вас есть:

  1. Агент Hermes установлен — pip install hermes-agent (см. Установка)
  2. Настроен поставщик LLM – запустите hermes model или установите предпочитаемые учетные данные поставщика в ~/.hermes/.env
  3. Рабочая базовая настройка — запустите hermes, чтобы убедиться, что агент отвечает на текст, прежде чем включать голосовую связь.:::совет Каталог ~/.hermes/ и файл config.yaml по умолчанию создаются автоматически при первом запуске hermes. Вам нужно только вручную создать ~/.hermes/.env для ключей API.

Обзор

Особенность Платформа Описание
Интерактивный голос интерфейс командной строки Нажмите Ctrl+B для записи, агент автоматически обнаружит тишину и ответит
Автоматический голосовой ответ Телеграмма, Дискорд Агент отправляет голосовой звук вместе с текстовыми ответами
Голосовой канал Раздор Бот присоединяется к ВК, слушает разговоры пользователей, говорит и отвечает

Требования

Пакеты Python

# CLI voice mode (microphone + audio playback)
pip install "hermes-agent[voice]"

# Discord + Telegram messaging (includes discord.py[voice] for VC support)
pip install "hermes-agent[messaging]"

# Premium TTS (ElevenLabs)
pip install "hermes-agent[tts-premium]"

# Local TTS (NeuTTS, optional)
python -m pip install -U neutts[all]

# Everything at once
pip install "hermes-agent[all]"
Экстра Пакеты Требуется для
голос sounddevice, numpy Голосовой режим CLI
обмен сообщениями discord.py[voice], python-telegram-bot, aiohttp Боты Discord и Telegram
ттс-премиум одиннадцатьлабов ElevenLabs TTS-провайдер

Дополнительный локальный поставщик TTS: установите neutts отдельно с помощью python -m pip install -U neutts[all]. При первом использовании модель загружается автоматически.:::информация discord.py[voice] автоматически устанавливает PyNaCl (для шифрования голоса) и привязки opus. Это необходимо для поддержки голосового канала Discord.

Системные зависимости

# macOS
brew install portaudio ffmpeg opus
brew install espeak-ng   # for NeuTTS

# Ubuntu/Debian
sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng   # for NeuTTS
Зависимость Цель Требуется для
ПортАудио Вход для микрофона и воспроизведение звука Голосовой режим CLI
ffmpeg Преобразование аудиоформатов (MP3 → Opus, PCM → WAV) Все платформы
Опус Голосовой кодек Discord Голосовые каналы Discord
говорить-нг Серверная часть Phonemizer Местный провайдер NeuTTS

API-ключи

Добавьте в ~/.hermes/.env:

# Speech-to-Text — local provider needs NO key at all
# pip install faster-whisper          # Free, runs locally, recommended
GROQ_API_KEY=your-key                 # Groq Whisper — fast, free tier (cloud)
VOICE_TOOLS_OPENAI_KEY=your-key       # OpenAI Whisper — paid (cloud)

# Text-to-Speech (optional — Edge TTS and NeuTTS work without any key)
ELEVENLABS_API_KEY=***           # ElevenLabs — premium quality
# VOICE_TOOLS_OPENAI_KEY above also enables OpenAI TTS
```:::совет
Если установлен faster-whisper, голосовой режим работает с **нулевыми ключами API** для STT. Модель (~150 МБ для базовой версии) загружается автоматически при первом использовании.</div>
---

## Голосовой режим CLI

Голосовой режим доступен как в **классическом интерфейсе командной строки** («hermeschat»), так и в **TUI** («hermes --tui»). Поведение в обоих случаях идентично — одни и те же команды слэша, одинаковое обнаружение тишины VAD, один и тот же потоковый TTS, один и тот же фильтр галлюцинаций. TUI дополнительно пересылает журналы анализа сбоев в `~/.hermes/logs/`, поэтому о сбоях режима «нажми и говори» на экзотических аудиосерверах можно сообщать с полной трассировкой стека, а не исчезать молча.

### Быстрый старт

Запустите CLI и включите голосовой режим:
```bash
hermes                # Start the interactive CLI

Затем используйте эти команды внутри CLI:

/voice          Toggle voice mode on/off
/voice on       Enable voice mode
/voice off      Disable voice mode
/voice tts      Toggle TTS output
/voice status   Show current state

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

  1. Запустите CLI с помощью hermes и включите голосовой режим с помощью /voice on.
  2. Нажмите Ctrl+B — раздастся звуковой сигнал (880 Гц), начнется запись.
  3. Говорите — полоса уровня звука в реальном времени показывает ваш ввод: ● [ ▂▃▅▇▇▅▂] ❯
  4. Перестать говорить — после 3 секунд молчания запись автоматически прекращается.
  5. Два звуковых сигнала (660 Гц), подтверждающие окончание записи.
  6. Аудио расшифровывается через Whisper и отправляется агенту.
  7. Если TTS включен, ответ агента произносится вслух.
  8. Запись автоматически возобновляется — говорите еще раз, не нажимая ни одной клавиши.

Этот цикл продолжается до тех пор, пока вы не нажмете Ctrl+B во время записи (выход из непрерывного режима) или пока 3 последовательные записи не обнаружат речи.:::совет Ключ записи настраивается с помощью voice.record_key в ~/.hermes/config.yaml (по умолчанию: ctrl+b).

Обнаружение тишины

Двухэтапный алгоритм определяет, когда вы закончили говорить:

  1. Речевое подтверждение — ожидание звука выше среднеквадратического порога (200) в течение не менее 0,3 с, допуская короткие провалы между слогами.
  2. Обнаружение окончания — после подтверждения речи срабатывает через 3,0 секунды непрерывной тишины.

Если в течение 15 секунд речь вообще не распознается, запись автоматически останавливается.

И «silence_threshold», и «silence_duration» настраиваются в «config.yaml». Вы также можете отключить звуковые сигналы начала/остановки записи с помощью voice.beep_enabled: false.

Потоковое TTS

Когда TTS включен, агент произносит свой ответ предложение за предложением по мере генерации текста — вы не ждете полного ответа:

  1. Буферизирует текстовые различия в полные предложения (минимум 20 символов).
  2. Удаляет форматирование уценки и блоки <think>.
  3. Генерирует и воспроизводит звук для каждого предложения в режиме реального времени.

Фильтр галлюцинаций

Whisper иногда генерирует фантомный текст из тишины или фонового шума («Спасибо за просмотр», «Подписаться» и т. д.). Агент отфильтровывает их, используя набор из 26 известных фраз-галлюцинаций на нескольких языках, а также шаблон регулярного выражения, который улавливает повторяющиеся варианты.

Голосовой ответ на шлюзе (Telegram и Discord)

Если вы еще не настроили своих ботов для обмена сообщениями, см. руководства для конкретной платформы: - Руководство по настройке Telegram - Руководство по настройке Discord

Запустите шлюз для подключения к вашим платформам обмена сообщениями:

hermes gateway        # Start the gateway (connects to configured platforms)
hermes gateway setup  # Interactive setup wizard for first-time configuration

Discord: Каналы против личных сообщений

Бот поддерживает два режима взаимодействия в Discord:

Режим Как говорить Упоминание обязательно Настройка
Прямое сообщение (DM) Открыть профиль бота → «Сообщение» Нет Работает сразу
Канал сервера Введите текстовый канал, где присутствует бот Да (@botname`) Бота необходимо пригласить на сервер

DM (рекомендуется для личного использования): Просто откройте DM с ботом и введите сообщение — @упоминание не требуется. Голосовые ответы и все команды работают так же, как и в каналах.

Каналы сервера: Бот отвечает только тогда, когда вы @упоминаете его (например, @hermesbyt4 hello). Убедитесь, что вы выбрали пользователя-бота во всплывающем окне с упоминанием, а не роль с тем же именем.:::совет Чтобы отключить требование упоминания в каналах сервера, добавьте в ~/.hermes/.env:

DISCORD_REQUIRE_MENTION=false

Или установите определенные каналы как свободные ответы (упоминание не требуется):

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321
```</div>
### Команды

Они работают как в Telegram, так и в Discord (DM и текстовые каналы):

/voice Toggle voice mode on/off /voice on Voice replies only when you send a voice message /voice tts Voice replies for ALL messages /voice off Disable voice replies /voice status Show current setting

### Режимы

| Режим | Команда | Поведение |
|------|---------|----------|
| `выключено` | `/голос выключен` | Только текст (по умолчанию) |
| `voice_only` | `/голос включен` | Говорит ответ только при отправке голосового сообщения |
| `все` | `/voice tts` | Говорит ответ на каждое сообщение |

Настройка голосового режима сохраняется после перезапуска шлюза.

### Доставка платформы

| Платформа | Формат | Заметки |
|----------|--------|-------|
| **Телеграмма** | Голосовой пузырь (Opus/OGG) | Играет онлайн в чате. ffmpeg конвертирует MP3 → Opus при необходимости |
| **Раздор** | Родной голосовой пузырь (Opus/OGG) | Воспроизводится как голосовое сообщение пользователя. Возвращается к вложению файла в случае сбоя API голосового пузыря |

---

## Голосовые каналы Discord

Самая захватывающая голосовая функция: бот подключается к голосовому каналу Discord, слушает речь пользователей, расшифровывает их речь, обрабатывает через агента и произносит ответ обратно в голосовой канал.

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

#### 1. Разрешения бота Discord

Если у вас уже настроен бот Discord для текстовых сообщений (см. [Руководство по настройке Discord](../messaging/discord.md)), вам необходимо добавить голосовые разрешения.

Перейдите на [Портал разработчиков Discord](https://discord.com/developers/applications) → ваше приложение → **Установка** → **Настройки установки по умолчанию** → **Гильдейская установка**:

**Добавьте эти разрешения к существующим текстовым разрешениям:**

| Разрешение | Цель | Требуется |
|-----------|---------|----------|
| **Подключиться** | Присоединяйтесь к голосовым каналам | Да |
| **Говори** | Воспроизведение звука TTS в голосовых каналах | Да |
| **Использовать голосовую активность** | Обнаруживать, когда пользователи говорят | Рекомендуется |

**Обновленное целое число разрешений:**

| Уровень | Целое число | Что включено |
|-------|---------|----------------|
| Только текст | `274878286912` | Просмотр каналов, отправка сообщений, чтение истории, встраивание, вложения, темы, реакции |
| Текст + Голос | `274881432640` | Все выше + Подключайтесь, говорите |

**Повторно пригласите бота**, указав обновленный URL-адрес разрешений:

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274881432640

Замените «YOUR_APP_ID» на свой идентификатор приложения с портала разработчиков.:::предупреждение
Повторное приглашение бота на сервер, на котором он уже находится, обновит его разрешения, не удаляя его. Вы не потеряете ни данные, ни конфигурацию.</div>
#### 2. Намерения привилегированного шлюза

На [Портале разработчика](https://discord.com/developers/applications) → ваше приложение → **Бот** → **Привилегированные шлюзовые намерения** включите все три:

| Намерение | Цель |
|--------|---------|
| **Намерение присутствия** | Определить статус пользователя онлайн/оффлайн |
| **Намерение участников сервера** | Преобразовать имена пользователей в `DISCORD_ALLOWED_USERS` в числовые идентификаторы (условно) |
| **Намерение содержимого сообщения** | Чтение содержимого текстовых сообщений в каналах |

**Обязательное значение содержания сообщения**. **Намерение участников сервера** необходимо только в том случае, если в вашем списке `DISCORD_ALLOWED_USERS` используются имена пользователей — если вы используете числовые идентификаторы пользователей, вы можете оставить его выключенным. Сопоставление голосового канала SSRC → user_id происходит из кода операции SPEAKING Discord на голосовом веб-сокете и **не** требует намерения участников сервера.

#### 3. Кодек Opus

Библиотека кодеков Opus должна быть установлена на машине, на которой работает шлюз:
```bash
# macOS (Homebrew)
brew install opus

# Ubuntu/Debian
sudo apt install libopus0

Бот автоматически загружает кодек из: - macOS: /opt/homebrew/lib/libopus.dylib - Linux: libopus.so.0

4. Переменные среды

# ~/.hermes/.env

# Discord bot (already configured for text)
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=your-user-id

# STT — local provider needs no key (pip install faster-whisper)
# GROQ_API_KEY=your-key            # Alternative: cloud-based, fast, free tier

# TTS — optional. Edge TTS and NeuTTS need no key.
# ELEVENLABS_API_KEY=***      # Premium quality
# VOICE_TOOLS_OPENAI_KEY=***  # OpenAI TTS / Whisper

Запуск шлюза

hermes gateway        # Start with existing configuration

Бот должен подключиться к Discord в течение нескольких секунд.

Команды

Используйте их в текстовом канале Discord, где присутствует бот:

/voice join      Bot joins your current voice channel
/voice channel   Alias for /voice join
/voice leave     Bot disconnects from voice channel
/voice status    Show voice mode and connected channel
```:::информация
Прежде чем запускать `/voice join`, вы должны находиться в голосовом канале. Бот присоединяется к тому же ВК, в котором вы находитесь.</div>
### Как это работает

Когда бот подключается к голосовому каналу, он:

1. **Прослушивает** аудиопоток каждого пользователя независимо.
2. **Обнаруживает тишину** — тишина в течение 1,5 с после не менее 0,5 с речи запускает обработку.
3. **Транскрибирует** звук через Whisper STT (локальный, Groq или OpenAI).
4. **Процессы** через весь конвейер агента (сеанс, инструменты, память).
5. **Проговаривает** ответ в голосовом канале через TTS.

### Интеграция текстового канала

Когда бот находится в голосовом канале:

- В текстовом канале появляются расшифровки: `[Voice] @user: что ты сказал`
- Ответы агентов отправляются в виде текста в канале и озвучиваются в ВК.
- Текстовый канал — это тот, в котором было выполнено `/voice join`.

### Предотвращение эха

Бот автоматически приостанавливает прослушивание звука во время воспроизведения ответов TTS, не позволяя ему слышать и повторно обрабатывать собственный вывод.

### Контроль доступа

Только пользователи, перечисленные в DISCORD_ALLOWED_USERS, могут взаимодействовать посредством голоса. Звук других пользователей молча игнорируется.
```bash
# ~/.hermes/.env
DISCORD_ALLOWED_USERS=284102345871466496

Справочник по конфигурации

конфиг.yaml

# Voice recording (CLI)
voice:
  record_key: "ctrl+b"            # Key to start/stop recording
  max_recording_seconds: 120       # Maximum recording length
  auto_tts: false                  # Auto-enable TTS when voice mode starts
  beep_enabled: true               # Play record start/stop beeps
  silence_threshold: 200           # RMS level (0-32767) below which counts as silence
  silence_duration: 3.0            # Seconds of silence before auto-stop

# Speech-to-Text
stt:
  provider: "local"                  # "local" (free) | "groq" | "openai"
  local:
    model: "base"                    # tiny, base, small, medium, large-v3
  # model: "whisper-1"              # Legacy: used when provider is not set

# Text-to-Speech
tts:
  provider: "edge"                 # "edge" (free) | "elevenlabs" | "openai" | "neutts" | "minimax"
  edge:
    voice: "en-US-AriaNeural"      # 322 voices, 74 languages
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"    # Adam
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"                 # alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  # optional: override for self-hosted or OpenAI-compatible endpoints
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

Переменные среды

# Speech-to-Text providers (local needs no key)
# pip install faster-whisper        # Free local STT — no API key needed
GROQ_API_KEY=...                    # Groq Whisper (fast, free tier)
VOICE_TOOLS_OPENAI_KEY=...         # OpenAI Whisper (paid)

# STT advanced overrides (optional)
STT_GROQ_MODEL=whisper-large-v3-turbo    # Override default Groq STT model
STT_OPENAI_MODEL=whisper-1               # Override default OpenAI STT model
GROQ_BASE_URL=https://api.groq.com/openai/v1     # Custom Groq endpoint
STT_OPENAI_BASE_URL=https://api.openai.com/v1    # Custom OpenAI STT endpoint

# Text-to-Speech providers (Edge TTS and NeuTTS need no key)
ELEVENLABS_API_KEY=***             # ElevenLabs (premium quality)
# VOICE_TOOLS_OPENAI_KEY above also enables OpenAI TTS

# Discord voice channel
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=...

Сравнение поставщиков STT

Провайдер Модель Скорость Качество Стоимость API-ключ
Местный база Быстро (зависит от процессора/графического процессора) Хорошо Бесплатно Нет
Местный маленький Средний Лучше Бесплатно Нет
Местный большой-v3 Медленно Лучшее Бесплатно Нет
Грок шепот-большой-v3-турбо Очень быстро (~0,5 с) Хорошо Уровень бесплатного пользования Да
Грок шепот-большой-v3 Быстро (~1 с) Лучше Уровень бесплатного пользования Да
ОпенАИ шепот-1 Быстро (~1 с) Хорошо Платный Да
ОпенАИ gpt-4o-транскрибировать Средний (~2 с) Лучшее Платный Да

Приоритет провайдера (автоматический резерв): local > groq > openai

Сравнение поставщиков TTS

Провайдер Качество Стоимость Задержка Требуется ключ
Пограничный TTS Хорошо Бесплатно ~1 с Нет
ЭлевенЛабс Отлично Платный ~2 с Да
OpenAI TTS Хорошо Платный ~1,5 с Да
НейТТС Хорошо Бесплатно Зависит от процессора/графического процессора Нет

NeuTTS использует конфигурационный блок tts.neutts, указанный выше.

Устранение неполадок

«Аудиоустройство не найдено» (CLI)

PortAudio не установлен:

brew install portaudio    # macOS
sudo apt install portaudio19-dev  # Ubuntu

Бот не отвечает в каналах сервера Discord

Бот по умолчанию требует @mention в каналах сервера. Убедитесь, что вы:

  1. Введите @ и выберите пользователя-бота (с #дискриминатором), а не роль с тем же именем.
  2. Или вместо этого используйте личные сообщения — упоминание не требуется.
  3. Или установите DISCORD_REQUIRE_MENTION=false в ~/.hermes/.env

Бот заходит в ВК, но меня не слышит

Бот меня слышит, но не отвечает

Бот отвечает текстом, но не в голосовом канале

Whisper возвращает мусорный текст

Фильтр галлюцинаций автоматически улавливает большинство случаев. Если вы все еще получаете фантомные расшифровки: