Голос и TTS

Синтез речи (Text-to-Speech)

Преобразуйте текст в речь с помощью десяти провайдеров:

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

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

# В ~/.hermes/config.yaml
tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "neutts" | "kittentts" | "piper"
  speed: 1.0                    # Глобальный множитель скорости (настройки провайдера переопределяют это)
  edge:
    voice: "en-US-AriaNeural"   # 322 голоса, 74 языка
    speed: 1.0                  # Преобразуется в процентное изменение скорости (+/-%)
  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"  # Переопределение для TTS-эндпоинтов, совместимых с OpenAI
    speed: 1.0                  # 0.25 — 4.0
  minimax:
    model: "speech-2.8-hd"     # speech-2.8-hd (по умолчанию), speech-2.8-turbo
    voice_id: "English_Graceful_Lady"  # См. https://platform.minimax.io/faq/system-voice-id
    speed: 1                    # 0.5 — 2.0
    vol: 1                      # 0 — 10
    pitch: 0                    # -12 — 12
  mistral:
    model: "voxtral-mini-tts-2603"
    voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8"  # Paul — нейтральный (по умолчанию)
  gemini:
    model: "gemini-2.5-flash-preview-tts"  # или gemini-2.5-pro-preview-tts
    voice: "Kore"               # 30 предустановленных голосов: Zephyr, Puck, Kore, Enceladus, Gacrux и др.
  xai:
    voice_id: "eve"             # или пользовательский ID голоса — см. документацию ниже
    language: "en"              # Код ISO 639-1
    sample_rate: 24000          # 22050 / 24000 (по умолчанию) / 44100 / 48000
    bit_rate: 128000            # Битрейт MP3; применяется только при codec=mp3
    # base_url: "https://api.x.ai/v1"   # Переопределение через переменную окружения XAI_BASE_URL
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu
  kittentts:
    model: KittenML/kitten-tts-nano-0.8-int8   # 25MB int8; также: kitten-tts-micro-0.8 (41MB), kitten-tts-mini-0.8 (80MB)
    voice: Jasper                               # Jasper, Bella, Luna, Bruno, Rosie, Hugo, Kiki, Leo
    speed: 1.0                                  # 0.5 — 2.0
    clean_text: true                            # Раскрывать числа, валюты, единицы измерения
  piper:
    voice: en_US-lessac-medium                  # имя голоса (автоскачивание) ИЛИ абсолютный путь к .onnx
    # voices_dir: ''                            # по умолчанию: ~/.hermes/cache/piper-voices/
    # use_cuda: false                           # требует onnxruntime-gpu
    # length_scale: 1.0                         # 2.0 = в два раза медленнее
    # noise_scale: 0.667
    # noise_w_scale: 0.8
    # volume: 1.0                               # 0.5 = в два раза тише
    # normalize_audio: true

Управление скоростью: Глобальное значение tts.speed применяется ко всем провайдерам по умолчанию. Каждый провайдер может переопределить его собственной настройкой speed (например, tts.openai.speed: 1.5). Скорость, заданная для конкретного провайдера, имеет приоритет над глобальным значением. По умолчанию — 1.0 (нормальная скорость).

Ограничения длины ввода

У каждого провайдера есть документированный лимит количества символов на один запрос. Hermes обрезает текст перед вызовом провайдера, чтобы запросы никогда не завершались ошибкой превышения длины:

ElevenLabs выбирает лимит на основе настроенного model_id:

Переопределение для каждого провайдера с помощью max_text_length: в соответствующем разделе провайдера вашей TTS-конфигурации:

tts:
  openai:
    max_text_length: 8192   # увеличить или уменьшить лимит провайдера

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

Голосовые сообщения Telegram и ffmpeg

Голосовые сообщения Telegram требуют аудиоформат Opus/OGG:

• OpenAI, ElevenLabs и Mistral создают Opus нативно — дополнительная настройка не требуется

• Edge TTS (по умолчанию) выводит MP3 и требует ffmpeg для конвертации:

• MiniMax TTS выводит MP3 и требует ffmpeg для конвертации в голосовые сообщения Telegram

• Google Gemini TTS выводит сырой PCM и использует ffmpeg для прямой кодировки в Opus для голосовых сообщений Telegram

• xAI TTS выводит MP3 и требует ffmpeg для конвертации в голосовые сообщения Telegram

• NeuTTS выводит WAV и также требует ffmpeg для конвертации в голосовые сообщения Telegram

• KittenTTS выводит WAV и также требует ffmpeg для конвертации в голосовые сообщения Telegram

• Piper выводит WAV и также требует ffmpeg для конвертации в голосовые сообщения Telegram

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Fedora
sudo dnf install ffmpeg

Без ffmpeg аудио от Edge TTS, MiniMax TTS, NeuTTS, KittenTTS и Piper отправляется как обычные аудиофайлы (воспроизводимые, но отображаемые как прямоугольный плеер вместо голосового сообщения).

Пользовательские голоса xAI (клонирование голоса)

xAI поддерживает клонирование вашего голоса и его использование в TTS. Создайте пользовательский голос в xAI Console, затем укажите полученный voice_id в вашей конфигурации:

tts:
  provider: xai
  xai:
    voice_id: "nlbqfwie"   # ваш пользовательский ID голоса

См. документацию xAI Custom Voices для получения информации о записи, поддерживаемых форматах и ограничениях.

Piper (локально, 44 языка)

Piper — это быстрый локальный нейросетевой TTS-движок от Open Home Foundation (поддерживающие Home Assistant). Он работает полностью на CPU, поддерживает 44 языка с предварительно обученными голосами и не требует API-ключа.

Установка через hermes tools → Voice & TTS → Piper — Hermes выполнит pip install piper-tts за вас. Или установите вручную: pip install piper-tts.

Переключение на Piper:

tts:
  provider: piper
  piper:
    voice: en_US-lessac-medium

При первом TTS-вызове для голоса, которого ещё нет в локальном кеше, Hermes выполняет python -m piper.download_voices <name> и загружает модель (~20–90 МБ в зависимости от уровня качества) в ~/.hermes/cache/piper-voices/. Последующие вызовы используют кешированную модель.

Выбор голоса. Полный каталог голосов охватывает английский, испанский, французский, немецкий, итальянский, нидерландский, португальский, русский, польский, турецкий, китайский, арабский, хинди и другие — каждый с уровнями качества x_low / low / medium / high. Примеры голосов на rhasspy.github.io/piper-samples.

Использование предварительно загруженного голоса. Установите tts.piper.voice как абсолютный путь, оканчивающийся на .onnx:

tts:
  piper:
    voice: /path/to/my-custom-voice.onnx

Продвинутые настройки (tts.piper.length_scale / noise_scale / noise_w_scale / volume / normalize_audio, use_cuda) соответствуют 1:1 настройкам SynthesisConfig Piper. Они игнорируются в старых версиях piper-tts.

Пользовательские командные провайдеры

Если нужный вам TTS-движок не поддерживается нативно (VoxCPM, MLX-Kokoro, XTTS CLI, скрипт клонирования голоса или любой другой, имеющий CLI-интерфейс), вы можете подключить его как командный провайдер без написания Python-кода. Hermes записывает входной текст во временный UTF-8-файл, запускает вашу shell-команду и читает аудиофайл, созданный этой командой.

Объявите один или несколько провайдеров в разделе tts.providers.<имя> и переключайтесь между ними с помощью tts.provider: <имя> — так же, как вы переключаетесь между встроенными провайдерами edge и openai.

tts:
  provider: voxcpm                 # выберите любое имя из tts.providers
  providers:
    voxcpm:
      type: command
      command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}"
      output_format: mp3
      timeout: 180
      voice_compatible: true       # попытаться доставить как голосовое сообщение Telegram

    mlx-kokoro:
      type: command
      command: "python -m mlx_kokoro --in {input_path} --out {output_path} --voice {voice}"
      voice: af_sky
      output_format: wav

    piper-custom:                  # нативный Piper также поддерживает пользовательские .onnx через tts.piper.voice
      type: command
      command: "piper -m /path/to/custom.onnx -f {output_path} < {input_path}"
      output_format: wav

Пример: Doubao (китайский seed-tts-2.0)

Для высококачественного китайского TTS через двунаправленный потоковый API ByteDance seed-tts-2.0 установите пакет PyPI doubao-speech и подключите его как командный провайдер:

pip install doubao-speech
export VOLCENGINE_APP_ID="your-app-id"
export VOLCENGINE_ACCESS_TOKEN="your-access-token"

tts:
  provider: doubao
  providers:
    doubao:
      type: command
      command: "doubao-speech say --text-file {input_path} --out {output_path}"
      output_format: mp3
      max_text_length: 1024
      timeout: 30

Учётные данные берутся из вашего shell-окружения (VOLCENGINE_APP_ID / VOLCENGINE_ACCESS_TOKEN) или ~/.doubao-speech/config.yaml. Выберите голос, добавив --voice zh-female-warm (или любой другой псевдоним из doubao-speech list-voices) в команду. doubao-speech также включает потоковую ASR — см. раздел STT ниже для интеграции с Hermes. Исходный код и полная документация: github.com/Hypnus-Yuan/doubao-speech.

Плейсхолдеры

Шаблон вашей команды может ссылаться на следующие плейсхолдеры. Hermes подставляет их во время выполнения и экранирует кавычками (обычные / одинарные / двойные) для безопасности shell, так что пути с пробелами и другие чувствительные символы обрабатываются корректно.

Используйте {{ и }} для литеральных фигурных скобок.

Опциональные ключи

Примечания по поведению

• Встроенные имена всегда побеждают. Запись tts.providers.openai никогда не переопределяет нативный провайдер OpenAI, поэтому никакая пользовательская конфигурация не может незаметно заменить встроенного провайдера.

• Доставка по умолчанию — документ. Командные провайдеры доставляют аудио как обычные вложения на всех платформах. Включите доставку в виде голосового сообщения для каждого провайдера с помощью voice_compatible: true.

• Ошибки команд отображаются агенту. Ненулевой код возврата, пустой вывод или тайм-аут — всё возвращает ошибку с stderr/stdout команды, чтобы вы могли отладить провайдера прямо из диалога.

• type: command используется по умолчанию, когда задан command:. Явное указание type: command — хорошая практика, но не обязательна; запись с непустым command автоматически считается командным провайдером.

• {input_path} / {text_path} взаимозаменяемы. Используйте тот, который лучше читается в вашей команде.

Безопасность

Командные провайдеры выполняют любую shell-команду, которую вы настроили, с правами вашего пользователя. Hermes экранирует значения плейсхолдеров и соблюдает заданный тайм-аут, но сам шаблон команды считается доверенным локальным вводом — относитесь к нему так же, как к shell-скрипту на вашем PATH.

Транскрипция голосовых сообщений (STT)

Голосовые сообщения, отправленные в Telegram, Discord, WhatsApp, Slack или Signal, автоматически транскрибируются и вставляются в виде текста в диалог. Агент видит транскрипцию как обычный текст.

info Нулевая конфигурация Локальная транскрипция работает из коробки, если установлен faster-whisper. Если он недоступен, Hermes также может использовать локальную CLI-утилиту whisper из стандартных путей установки (например, /opt/homebrew/bin) или пользовательскую команду через HERMES_LOCAL_STT_COMMAND.

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

# В ~/.hermes/config.yaml
stt:
  provider: "local"           # "local" | "groq" | "openai" | "mistral" | "xai"
  local:
    model: "base"             # tiny, base, small, medium, large-v3
  openai:
    model: "whisper-1"        # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe
  mistral:
    model: "voxtral-mini-latest"  # voxtral-mini-latest, voxtral-mini-2602
  xai:
    model: "grok-stt"         # xAI Grok STT

Детали провайдеров

Локальный (faster-whisper) — Запускает Whisper локально через faster-whisper. По умолчанию использует CPU, GPU — при наличии. Размеры моделей:

Groq API — Требуется GROQ_API_KEY. Хорошее облачное решение, если вам нужен бесплатный хостинг для STT.

OpenAI API — Сначала использует VOICE_TOOLS_OPENAI_KEY, затем OPENAI_API_KEY как запасной вариант. Поддерживает whisper-1, gpt-4o-mini-transcribe и gpt-4o-transcribe.

Mistral API (Voxtral Transcribe) — Требуется MISTRAL_API_KEY. Использует модели Voxtral Transcribe от Mistral. Поддерживает 13 языков, диаризацию говорящих и временные метки на уровне слов. Установка: pip install hermes-agent[mistral].

xAI Grok STT — Требуется XAI_API_KEY. Отправляет запросы на https://api.x.ai/v1/stt в формате multipart/form-data. Хороший выбор, если вы уже используете xAI для чата или TTS и хотите один API-ключ для всего. Порядок автоопределения ставит его после Groq — явно укажите stt.provider: xai, чтобы принудительно его использовать.

Пользовательская локальная CLI-утилита — Установите HERMES_LOCAL_STT_COMMAND, если хотите, чтобы Hermes вызывал локальную команду транскрипции напрямую. Шаблон команды поддерживает плейсхолдеры {input_path}, {output_dir}, {language} и {model}. Ваша команда должна записать транскрипцию в файл .txt где-нибудь в {output_dir}.

Пример: Doubao / Volcengine ASR

Если вы используете doubao-speech для TTS Doubao (см. выше), тот же пакет обрабатывает и распознавание речи через интерфейс локальной команды STT:

pip install doubao-speech
export VOLCENGINE_APP_ID="your-app-id"
export VOLCENGINE_ACCESS_TOKEN="your-access-token"
export HERMES_LOCAL_STT_COMMAND='doubao-speech transcribe {input_path} --out {output_dir}/transcript.txt'

stt:
  provider: local_command

Hermes записывает входящее голосовое сообщение в {input_path}, выполняет команду и читает файл .txt, созданный в {output_dir}. Язык определяется автоматически эндпоинтом Volcengine bigmodel.

Поведение при откате (Fallback)

Если настроенный провайдер недоступен, Hermes автоматически переключается на запасного:

• Локальный faster-whisper недоступен → Пробует локальную CLI-утилиту whisper или HERMES_LOCAL_STT_COMMAND перед облачными провайдерами

• Ключ Groq не задан → Откат к локальной транскрипции, затем OpenAI

• Ключ OpenAI не задан → Откат к локальной транскрипции, затем Groq

• Ключ/SDK Mistral не задан → Пропускается при автоопределении; переходит к следующему доступному провайдеру

• Ничего не доступно → Голосовые сообщения передаются с соответствующим уведомлением пользователю