语音与文本转语音（TTS）

Hermes Agent 支持跨消息平台的文本转语音输出，以及语音消息转录能力。

文本转语音（TTS）

目前支持六种语音合成提供商：

提供商	质量	成本	API 密钥
Edge TTS（默认）	良好	免费	无需
ElevenLabs	优秀	付费	ELEVENLABS_API_KEY
OpenAI TTS	良好	付费	VOICE_TOOLS_OPENAI_KEY
MiniMax TTS	优秀	付费	MINIMAX_API_KEY
Mistral（Voxtral TTS）	优秀	付费	MISTRAL_API_KEY
NeuTTS	良好	免费	无需

平台交付方式

平台	交付形式	格式
Telegram	语音气泡（内联播放）	Opus .ogg
Discord	语音气泡（Opus/OGG），降级为文件附件	Opus/MP3
WhatsApp	音频文件附件	MP3
CLI	保存至 ~/.hermes/audio_cache/	MP3

配置说明

# In ~/.hermes/config.yaml
tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "neutts"
  speed: 1.0                    # Global speed multiplier (provider-specific settings override this)
  edge:
    voice: "en-US-AriaNeural"   # 322 voices, 74 languages
    speed: 1.0                  # Converted to rate percentage (+/-%)
  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"  # Override for OpenAI-compatible TTS endpoints
    speed: 1.0                  # 0.25 - 4.0
  minimax:
    model: "speech-2.8-hd"     # speech-2.8-hd (default), speech-2.8-turbo
    voice_id: "English_Graceful_Lady"  # See 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 - Neutral (default)
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

语速控制：全局设置 tts.speed 默认适用于所有提供商。每个提供商也可以通过自己的 speed 配置单独覆盖（例如 tts.openai.speed: 1.5）。提供商级设置优先于全局值，默认值为 1.0（正常语速）。

Telegram 语音气泡与 ffmpeg

Telegram 语音气泡要求音频格式为 Opus/OGG：

• OpenAI、ElevenLabs 和 Mistral 原生输出 Opus —— 无需额外配置
• Edge TTS（默认）输出 MP3，需通过 ffmpeg 转换
• MiniMax TTS 输出 MP3，需通过 ffmpeg 转换以适配 Telegram 语音气泡
• NeuTTS 输出 WAV，同样需要 ffmpeg 转换以适配 Telegram 语音气泡

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Fedora
sudo dnf install ffmpeg

若未安装 ffmpeg，Edge TTS、MiniMax TTS 和 NeuTTS 的音频将作为普通音频文件发送（可播放，但显示为矩形播放器而非语音气泡）。

tip

如果你希望在不安装 ffmpeg 的情况下直接获得语音气泡，可以切换到 OpenAI、ElevenLabs 或 Mistral。

语音消息转录（STT）

Telegram、Discord、WhatsApp、Slack 或 Signal 上收到的语音消息会自动转录，并将文字内容注入对话中。代理将该转录文本视为普通文本处理。

提供商	质量	成本	API 密钥
本地 Whisper（默认）	良好	免费	无需
Groq Whisper API	良好–最佳	免费额度	GROQ_API_KEY
OpenAI Whisper API	良好–最佳	付费	VOICE_TOOLS_OPENAI_KEY 或 OPENAI_API_KEY

一键配置

如果已经安装 faster-whisper，本地转录基本可以直接开箱即用。即使它不可用，Hermes 也会尝试从常见路径（如 /opt/homebrew/bin）调用本地 whisper CLI，或者使用你通过 HERMES_LOCAL_STT_COMMAND 指定的自定义命令。

配置说明

# In ~/.hermes/config.yaml
stt:
  provider: "local"           # "local" | "groq" | "openai" | "mistral"
  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

提供商详情

本地（faster-whisper） —— 通过 faster-whisper 在本地运行 Whisper。默认使用 CPU，若有 GPU 则自动启用。模型大小如下：

模型	大小	速度	质量
tiny	~75 MB	最快	基础
base	~150 MB	快	良好（默认）
small	~500 MB	中等	更佳
medium	~1.5 GB	较慢	优秀
large-v3	~3 GB	最慢	最佳

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。使用 Mistral 的 Voxtral Transcribe 模型。支持 13 种语言、说话人分离和词级别时间戳。可通过 pip install hermes-agent[mistral] 安装。

自定义本地 CLI 回退 —— 若希望 Hermes 直接调用本地转录命令，请设置 HERMES_LOCAL_STT_COMMAND。命令模板支持以下占位符：{input_path}、{output_dir}、{language} 和 {model}。

回退行为

如果当前配置的提供商不可用，Hermes 会按以下顺序自动回退：

• 本地 faster-whisper 不可用 → 优先尝试本地 whisper CLI 或 HERMES_LOCAL_STT_COMMAND，再尝试云端提供商
• Groq 密钥未设置 → 回退至本地转录，再尝试 OpenAI
• OpenAI 密钥未设置 → 回退至本地转录，再尝试 Groq
• Mistral 密钥/SDK 未设置 → 在自动检测阶段跳过，继续尝试下一个可用提供商
• 全部不可用 → 语音消息直接通过，并向用户发送准确提示