🏠 Главная › User Guide › voice mode

sidebar_position: 10 title: "Voice Mode" description: "Real-time voice conversations with Hermes Agent — CLI, Telegram, Discord (DMs, text channels, and voice channels)" lang: ru

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

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]"
Экстра Пакеты Требуется для
voice sounddevice, numpy Голосовой режим CLI
messaging discord.py[voice], python-telegram-bot, aiohttp Боты Discord и Telegram
tts-premium elevenlabs 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 МБ для base) загружается автоматически при первом использовании.

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

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

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

Запустите CLI и включите голосовой режим:

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

Команды

Они работают как в 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

Режимы

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

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

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

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

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

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

Настройка

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

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

Перейдите на Портал разработчиков Discord → ваше приложение → Установка → Настройки установки по умолчанию → Гильдейская установка:

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

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

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

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

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

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

Замените YOUR_APP_ID на свой идентификатор приложения с портала разработчиков.

:::предупреждение Повторное приглашение бота на сервер, на котором он уже находится, обновит его разрешения, не удаляя его. Вы не потеряете ни данные, ни конфигурацию.

2. Намерения привилегированного шлюза

На Портале разработчика → ваше приложение → Бот → Привилегированные шлюзовые намерения включите все три:

Намерение Цель
Намерение присутствия Определить статус пользователя онлайн/оффлайн
Намерение участников сервера Сопоставить голосовые идентификаторы SSRC с идентификаторами пользователей Discord
Намерение содержимого сообщения Чтение содержимого текстовых сообщений в каналах

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

3. Кодек Opus

Библиотека кодеков Opus должна быть установлена на машине, на которой работает шлюз:

# 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, вы должны находиться в голосовом канале. Бот присоединяется к тому же ВК, в котором вы находитесь.

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

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

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

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

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

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

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

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

Только пользователи, перечисленные в DISCORD_ALLOWED_USERS, могут взаимодействовать посредством голоса. Звук других пользователей молча игнорируется.

# ~/.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-ключ
Местный base Быстро (зависит от процессора/графического процессора) Хорошо Бесплатно Нет
Местный small Средний Лучше Бесплатно Нет
Местный large-v3 Медленно Лучшее Бесплатно Нет
Грок whisper-large-v3-turbo Очень быстро (~0,5 с) Хорошо Уровень бесплатного пользования Да
Грок whisper-large-v3 Быстро (~1 с) Лучше Уровень бесплатного пользования Да
ОпенАИ whisper-1 Быстро (~1 с) Хорошо Платный Да
ОпенАИ gpt-4o-transcribe Средний (~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 возвращает мусорный текст

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