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

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

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

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

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

1. Установленный Hermes Agent — pip install hermes-agent (см. Установка)

2. Настроенный провайдер LLM — выполните hermes model или укажите учётные данные провайдера в ~/.hermes/.env

3. Работающая базовая настройка — выполните hermes, чтобы убедиться, что агент отвечает на текст перед включением голоса

Обзор

Требования

Пакеты 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]"

Опциональный локальный провайдер TTS: установите neutts отдельно с помощью python -m pip install -U neutts[all]. При первом использовании модель загрузится автоматически.

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

# 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

Ключи 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

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

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

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

Запустите 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 последовательные записи не обнаружат отсутствие речи.

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

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

1. Подтверждение речи — ожидает аудио выше порога RMS (200) в течение как минимум 0,3 с, допуская кратковременные провалы между слогами

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

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

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

Потоковый TTS

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

1. Буферизует текстовые дельты в полные предложения (минимум 20 символов)

2. Удаляет markdown-разметку и блоки <think>

3. Генерирует и воспроизводит аудио для каждого предложения в реальном времени

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

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

Голосовой ответ шлюза (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:

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

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

DISCORD_REQUIRE_MENTION=false

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

Команды

Эти команды работают как в Telegram, так и в Discord (ЛС и текстовые каналы):

/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

Режимы

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

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

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

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

Настройка

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

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

Перейдите в Discord Developer Portal → ваше приложение → Installation → Default Install Settings → Guild Install:

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

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

Повторно пригласите бота с обновлённым URL разрешений:

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

Замените YOUR_APP_ID на ID вашего приложения из Developer Portal.

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

В Developer Portal → ваше приложение → Bot → Privileged Gateway Intents, включите все три:

Message Content Intent обязателен. Server Members Intent требуется только если ваш список DISCORD_ALLOWED_USERS использует имена пользователей — если вы используете числовые ID, его можно оставить ВЫКЛЮЧЕННЫМ. Сопоставление SSRC голосового канала → user_id берётся из SPEAKING опкода Discord на голосовом вебсокете и не требует Server Members Intent.

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

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

Когда бот заходит в голосовой канал, он:

1. Слушает аудиопоток каждого пользователя независимо

2. Обнаруживает тишину — 1,5 с тишины после как минимум 0,5 с речи запускает обработку

3. Транскрибирует аудио через Whisper STT (локальный, Groq или OpenAI)

4. Обрабатывает через полный пайплайн агента (сессия, инструменты, память)

5. Произносит ответ обратно в голосовой канал через TTS

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

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

• Транскрипты отображаются в текстовом канале: [Voice] @user: что вы сказали

• Ответы агента отправляются как текст в канал И озвучиваются в голосовом канале

• Текстовый канал — тот, в котором была введена команда /voice join

Защита от эха

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

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

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

# ~/.hermes/.env
DISCORD_ALLOWED_USERS=284102345871466496

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

config.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

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

Сравнение провайдеров TTS

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

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

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

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

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

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

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

1. Пишете @ и выбираете пользователя-бота (с #дискриминатором), а не роль с тем же именем

2. Или используйте ЛС — упоминание не требуется

3. Или установите DISCORD_REQUIRE_MENTION=false в ~/.hermes/.env

Бот заходит в голосовой канал, но не слышит меня

• Проверьте, что ваш Discord ID указан в DISCORD_ALLOWED_USERS

• Убедитесь, что вы не в режиме «заглушен» в Discord

• Боту нужно событие SPEAKING от Discord, прежде чем он сможет сопоставить ваше аудио — начните говорить в течение нескольких секунд после подключения

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

• Проверьте доступность STT: установите faster-whisper (ключ не нужен) или задайте GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY

• Проверьте, что модель LLM настроена и доступна

• Просмотрите логи шлюза: tail -f ~/.hermes/logs/gateway.log

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

• Возможно, провайдер TTS не работает — проверьте ключ API и квоту

• Edge TTS (бесплатно, без ключа) используется как запасной вариант по умолчанию

• Проверьте логи на наличие ошибок TTS

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

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

• Используйте более тихое окружение

• Настройте silence_threshold в конфиге (выше = менее чувствительно)

• Попробуйте другую модель STT