음성 및 TTS

anchor alias

음성 및 TTS

Hermes Agent는 모든 메시징 플랫폼에서 텍스트 음성 변환 출력과 음성 메시지 전사를 모두 지원합니다.

Nous Subscribers

유료 Nous Portal 구독이 있는 경우, OpenAI TTS를 별도의 OpenAI API 키 없이 **도구 게이트웨이**를 통해 사용할 수 있습니다. 활성화하려면 hermes model 또는 hermes tools을 실행하세요.

텍스트 음성 변환

10개의 제공업체로 텍스트를 음성으로 변환

제공업체	품질	비용	API 키
Edge TTS (기본)	좋다	무료	필요 없음
엘레븐랩스	훌륭한	유료	`ELEVENLABS_API_KEY`
오픈AI TTS	좋다	유료	`VOICE_TOOLS_OPENAI_KEY`
미니맥스 TTS	훌륭한	유료	`MINIMAX_API_KEY`
미스트랄 (Voxtral TTS)	훌륭한	유료	`MISTRAL_API_KEY`
구글 제미니 TTS	훌륭한	무료 등급	`GEMINI_API_KEY`
xAI TTS	훌륭한	유료	`XAI_API_KEY`
NeuTTS	좋다	무료 (지역)	필요 없음
키튼TTS	좋다	무료 (지역)	필요 없음
파이퍼	좋아요	무료 (지역)	필요 없음

플랫폼 배송

플랫폼	배송	형식
텔레그램	음성 버블(인라인 재생)	오푸스 `.ogg`
디스코드	음성 버블(Opus/OGG), 파일 첨부로 대체됨	오푸스/MP3
왓츠앱	오디오 파일 첨부	MP3
CLI	`~/.hermes/audio_cache/`에 저장됨	MP3

구성

# In ~/.hermes/config.yaml
tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "neutts" | "kittentts" | "piper"
  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)
  gemini:
    model: "gemini-2.5-flash-preview-tts"  # or gemini-2.5-pro-preview-tts
    voice: "Kore"               # 30 prebuilt voices: Zephyr, Puck, Kore, Enceladus, Gacrux, etc.
  xai:
    voice_id: "eve"             # or a custom voice ID — see docs below
    language: "en"              # ISO 639-1 code
    sample_rate: 24000          # 22050 / 24000 (default) / 44100 / 48000
    bit_rate: 128000            # MP3 bitrate; only applies when codec=mp3
    # base_url: "https://api.x.ai/v1"   # Override via XAI_BASE_URL env var
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu
  kittentts:
    model: KittenML/kitten-tts-nano-0.8-int8   #  int8; also: kitten-tts-micro-0.8 (), kitten-tts-mini-0.8 ()
    voice: Jasper                               # Jasper, Bella, Luna, Bruno, Rosie, Hugo, Kiki, Leo
    speed: 1.0                                  # 0.5 - 2.0
    clean_text: true                            # Expand numbers, currencies, units
  piper:
    voice: en_US-lessac-medium                  # voice name (auto-downloaded) OR absolute path to.onnx
    # voices_dir: ''                            # default: ~/.hermes/cache/piper-voices/
    # use_cuda: false                           # requires onnxruntime-gpu
    # length_scale: 1.0                         # 2.0 = twice as slow
    # noise_scale: 0.667
    # noise_w_scale: 0.8
    # volume: 1.0                               # 0.5 = half as loud
    # normalize_audio: true

속도 제어: 전역 tts.speed 값은 기본적으로 모든 제공자에게 적용됩니다. 각 제공자는 자체 speed 설정(예: tts.openai.speed: 1.5)으로 이를 override할 수 있습니다. 제공자별 속도가 전역 값을 우선합니다. 기본값은 1.0(보통 속도)입니다.

입력 길이 제한

각 제공자는 요청당 입력 문자 수 제한이 문서화되어 있습니다. Hermes는 제공자를 호출하기 전에 텍스트를 잘라서 요청이 길이 오류로 실패하지 않도록 합니다:

제공자	기본 글자 수 제한
엣지 TTS	5000
오픈AI	4096
xAI	15000
미니맥스	10000
미스트랄	4000
구글 제미니	5000
일레븐랩스	모델 인식(아래 참조)
뉴TTS	2000
키튼TTS	2000

ElevenLabs가 구성된 model_id에서 캡을 선택합니다:

`model_id`	대문자 (문자)
`eleven_flash_v2_5`	40000
`eleven_flash_v2`	30000
`eleven_multilingual_v2` (기본), `eleven_multilingual_v1`, `eleven_english_sts_v2`, `eleven_english_sts_v1`	10000
`eleven_v3`, `eleven_ttv_v3`	5000
알 수 없는 모델	제공자 기본값(10000)으로 돌아갑니다

프로바이더별 재정의 TTS 구성의 프로바이더 섹션에서 max_text_length: 사용:

tts:
  openai:
    max_text_length: 8192   # raise or lower the provider cap

양의 정수만 허용됩니다. 0, 음수, 숫자가 아닌 값 또는 불리언 값은 제공자 기본값으로 넘어가므로, 잘못된 구성으로 인해 잘림이 실수로 비활성화되지 않습니다.

텔레그램 음성 메시지 말풍선 & ffmpeg

텔레그램 음성 버블에는 Opus/OGG 오디오 형식이 필요합니다:

OpenAI, ElevenLabs, 그리고 Mistral은 Opus를 기본적으로 생성합니다 — 추가 설정 불필요
Edge TTS(기본) 는 MP3를 출력하며 변환을 위해ffmpeg가 필요합니다:
MiniMax TTS는 MP3를 출력하며, Telegram 음성 메시지로 변환하려면 ffmpeg가 필요합니다
Google Gemini TTS는 원시 PCM을 출력하며 ffmpeg를 사용하여 텔레그램 음성 메시지를 위해 직접 Opus로 인코딩합니다
xAI TTS는 MP3를 출력하며, Telegram 음성 메시지로 변환하려면 ffmpeg가 필요합니다
NeuTTS는 WAV를 출력하며 Telegram 음성 메시지로 변환하기 위해 ffmpeg도 필요합니다
KittenTTS는 WAV를 출력하며, Telegram 음성 메시지로 변환하려면 ffmpeg도 필요합니다
Piper는 WAV를 출력하며, Telegram 음성 버블로 변환하기 위해 ffmpeg도 필요합니다

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Fedora
sudo dnf install ffmpeg

ffmpeg 없이 Edge TTS, MiniMax TTS, NeuTTS, KittenTTS, Piper 오디오는 일반 오디오 파일로 전송됩니다(재생 가능하지만, 음성 말풍선 대신 사각형 플레이어로 표시됩니다).

팁

ffmpeg를 설치하지 않고 음성 버블을 원하면 OpenAI, ElevenLabs 또는 Mistral 제공자로 전환하세요.

xAI 맞춤 음성 (음성 복제)

xAI는 사용자의 음성을 복제하고 이를 TTS와 함께 사용하는 것을 지원합니다. xAI 콘솔에서 맞춤 음성을 생성한 다음, 생성된 voice_id를 설정에 입력하세요:

tts:
  provider: xai
  xai:
    voice_id: "nlbqfwie"   # your custom voice ID

녹음, 지원되는 형식 및 제한 사항에 대한 자세한 내용은 xAI 맞춤 음성 문서를 참조하세요.

파이퍼 (로컬, 44개 언어)

파이퍼(Piper)는 오픈 홈 재단(Open Home Foundation, 홈 어시스턴트 유지관리자)이 만든 빠르고 로컬에서 작동하는 신경망 TTS 엔진입니다. 완전히 CPU에서 작동하며, 사전 학습된 음성으로 44개 언어를 지원하고 API 키가 필요 없습니다.

hermes tools 통해 설치 → 음성 & TTS → Piper — Hermes가 pip install piper-tts를 대신 실행합니다. 또는 수동으로 설치: pip install piper-tts.

파이퍼로 전환:

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

로컬에 캐시되지 않은 음성에 대한 첫 번째 TTS 호출 시, Hermes는 python -m piper.download_voices <name>를 실행하고 모델을 (~/.hermes/cache/piper-voices/에) 다운로드합니다(품질 등급에 따라 약 20-). 이후 호출은 캐시된 모델을 재사용합니다.

음성 선택하기. 전체 음성 카탈로그에는 영어, 스페인어, 프랑스어, 독일어, 이탈리아어, 네덜란드어, 포르투갈어, 러시아어, 폴란드어, 터키어, 중국어, 아랍어, 힌디어 등 다양한 언어가 포함되어 있으며, 각각 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)는 Piper의 SynthesisConfig에 1:1로 대응됩니다. 이전 piper-tts 버전에서는 무시됩니다.

사용자 정의 명령 제공자

원하는 TTS 엔진이 기본적으로 지원되지 않는 경우(VoxCPM, MLX-Kokoro, XTTS CLI, 음성 클로닝 스크립트, CLI를 제공하는 다른 모든 것), Python 코드를 작성하지 않고도 그것을 **명령형 제공자(command-type provider)**로 연결할 수 있습니다. Hermes는 입력 텍스트를 임시 UTF-8 파일에 쓰고, 셸 명령을 실행하며, 명령이 생성한 오디오 파일을 읽습니다.

하나 이상의 제공자를 tts.providers.<name> 아래에 선언하고 tts.provider: <name>을 사용하여 전환하세요 — edge 및 openai와 같은 내장 항목 간 전환하는 것과 동일한 방식입니다.

tts:
  provider: voxcpm                 # pick any name under 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       # try to deliver as a Telegram voice bubble

    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:                  # native Piper also supports custom.onnx via 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)

ByteDance의 seed-tts-2.0 양방향 스트리밍 API를 통해 고품질 중국어 TTS를 사용하려면, doubao-speech PyPI 패키지를 설치하고 명령 제공자로 연결하세요:

pip install doubao-speech
export VOLCENGINE_APP_ID="your-app-id"
export VOLCENGINE_ACCESS_TOKEN="your-access-token"
````yaml
tts:
  provider: doubao
  providers:
    doubao:
      type: command
      command: "doubao-speech say --text-file &#123;input_path&#125; --out &#123;output_path&#125;"
      output_format: mp3
      max_text_length: 1024
      timeout: 30

자격 증명은 셸 환경(VOLCENGINE_APP_ID / VOLCENGINE_ACCESS_TOKEN) 또는 ~/.doubao-speech/config.yaml에서 가져옵니다. 명령에 --voice zh-female-warm(또는 doubao-speech list-voices의 다른 별칭)을 추가하여 음성을 선택하세요. doubao-speech는 스트리밍 ASR도 포함합니다 — Hermes 통합에 대해서는 아래 STT 섹션을 참조하세요. 소스 및 전체 문서: github.com/Hypnus-Yuan/doubao-speech.

자리 표시자

귀하의 명령 템플릿은 이러한 플레이스홀더를 참조할 수 있습니다. Hermes는 렌더링 시 각 값을 대체하고 주변 컨텍스트(베어 / 단일 인용 / 이중 인용)에 맞게 셸 인용을 수행하므로, 공백이 있는 경로 및 기타 셸에 민감한 문자가 안전하게 처리됩니다.

플레이스홀더	의미
`{input_path}`	헤르메스가 쓴 임시 UTF-8 텍스트 파일의 경로
`{text_path}`	`{input_path}`의 별칭
`{output_path}`	명령이 오디오를 기록해야 하는 경로
`{format}`	`mp3` / `wav` / `ogg` / `flac`
`{voice}`	`tts.providers.<name>.voice`, 설정되지 않았을 때 비어 있음
`{model}`	`tts.providers.<name>.model`
`{speed}`	해결된 속도 배율 (제공자 또는 전역)

리터럴 중괄호에는 {{와 }}를 사용하세요.

선택적 키

키	기본값	의미
`timeout`	`120`	초; 만료 시 프로세스 트리가 종료됩니다 (Unix `killpg`, Windows `taskkill /T`).
`output_format`	`mp3`	`mp3` / `wav` / `ogg` / `flac` 중 하나. Hermes가 경로를 선택하면 출력 확장자로 자동 추론됩니다.
`voice_compatible`	`false`	`true` 시, Hermes는 MP3/WAV 출력을 ffmpeg를 통해 Opus/OGG로 변환하여 Telegram이 음성 버블을 표시하도록 합니다.
`max_text_length`	`5000`	명령을 실행하기 전에 입력이 이 길이로 잘립니다.
`voice` / `model`	비어 있음	명령어에 자리 표시자 값으로만 전달됨.

행동 기록

내장 이름은 항상 우선합니다. tts.providers.openai 항목은 네이티브 OpenAI 제공자를 가리지 않으므로 어떤 사용자 설정도 내장을 조용히 대체할 수 없습니다.
기본 전달 방식은 문서입니다. 명령 제공자는 모든 플랫폼에서 일반 오디오 첨부 파일로 전달합니다. voice_compatible: true을 사용하여 제공자별 음성 버블 전달을 선택할 수 있습니다.
명령 실패가 에이전트에게 나타납니다. 0이 아닌 종료, 빈 출력 또는 시간 초과는 모두 명령의 stderr/stdout가 포함된 오류를 반환하여 대화에서 제공자를 디버그할 수 있도록 합니다.
type: command는 command:이 설정될 때 기본값입니다. type: command를 명시적으로 작성하는 것은 좋은 습관이지만 필수는 아닙니다; 비어 있지 않은 command 문자열이 있는 항목은 명령 제공자로 취급됩니다.
{input_path} / {text_path}는 서로 교환 가능합니다. 명령어에서 읽기 좋은 쪽을 사용하세요.

보안

명령형 공급자는 사용자의 권한으로 구성한 셸 명령을 실행합니다. Hermes는 자리 표시자 값을 인용하고 구성된 타임아웃을 적용하지만, 명령 템플릿 자체는 신뢰할 수 있는 로컬 입력이므로 PATH에 있는 셸 스크립트를 다루듯이 처리해야 합니다.

음성 메시지 전사 (STT)

텔레그램, 디스코드, 왓츠앱, 슬랙 또는 시그널에서 전송된 음성 메시지는 자동으로 전사되어 대화에 텍스트로 삽입됩니다. 에이전트는 전사본을 일반 텍스트로 확인합니다.

제공자	품질	비용	API 키
로컬 속삭임 (기본)	좋아요	무료	필요 없음
Groq Whisper API	좋은–최고	무료 등급	`GROQ_API_KEY`
OpenAI Whisper API	좋은–최고	유료	`VOICE_TOOLS_OPENAI_KEY` 또는 `OPENAI_API_KEY`

Zero Config

로컬 전사는 faster-whisper가 설치되어 있으면 즉시 작동합니다. 사용할 수 없는 경우, Hermes는 일반 설치 위치(예: /opt/homebrew/bin)에서 로컬 whisper CLI를 사용하거나 HERMES_LOCAL_STT_COMMAND을 통해 사용자 지정 명령을 사용할 수도 있습니다.

구성

# In ~/.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) — 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]로 설치.

xAI Grok STT — XAI_API_KEY가 필요합니다. https://api.x.ai/v1/stt로 multipart/form-data 형식으로 게시합니다. 이미 챗 또는 TTS용으로 xAI를 사용 중이고 모든 기능을 하나의 API 키로 사용하고 싶다면 좋은 선택입니다. 자동 감지 순서는 Groq 다음으로 배치되며, 강제로 사용하려면 stt.provider: xai를 명시적으로 설정해야 합니다.

사용자 지정 로컬 CLI 대체 — Hermes가 로컬 전사 명령을 직접 호출하도록 하려면 HERMES_LOCAL_STT_COMMAND를 설정하세요. 명령 템플릿은 {input_path}, {output_dir}, {language}, 및 {model} 자리 표시자를 지원합니다. 명령은 {output_dir} 아래 어딘가에 .txt 전사를 작성해야 합니다.

예시: Doubao / Volcengine ASR

Doubao TTS에 doubao-speech를 사용하면(위의 예시 참조), 동일한 패키지가 로컬 명령 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 &#123;input_path&#125; --out &#123;output_dir&#125;/transcript.txt'
````yaml
stt:
  provider: local_command

Hermes는 들어오는 음성 메시지를 {input_path}에 기록하고, 명령을 실행하며, {output_dir} 아래에 생성된 .txt 파일을 읽습니다. 언어는 Volcengine 빅모델 엔드포인트에서 자동 감지됩니다.

대체 동작

구성된 제공자를 사용할 수 없는 경우, Hermes는 자동으로 대체합니다:

로컬 faster-whisper 사용 불가 → 클라우드 제공자 전에 로컬 whisper CLI 또는 HERMES_LOCAL_STT_COMMAND 시도
Groq 키가 설정되지 않음 → 로컬 전사로 대체한 후, OpenAI 사용
OpenAI 키가 설정되지 않음 → 로컬 전사로 대체한 후 Groq 사용
Mistral 키/SDK가 설정되지 않음 → 자동 감지에서 건너뜀; 다음 사용 가능한 제공자로 넘어감
사용 가능한 항목 없음 → 음성 메시지는 사용자에게 정확한 알림과 함께 전달됩니다

anchor alias​

anchor alias​

anchor alias​

음성 및 TTS

텍스트 음성 변환​

플랫폼 배송​

구성​

입력 길이 제한​

텔레그램 음성 메시지 말풍선 & ffmpeg​

xAI 맞춤 음성 (음성 복제)​

파이퍼 (로컬, 44개 언어)​

사용자 정의 명령 제공자​

예시: Doubao (중국어 seed-tts-2.0)​

자리 표시자​

선택적 키​

행동 기록​

보안​

음성 메시지 전사 (STT)​

구성​

제공자 정보​

예시: Doubao / Volcengine ASR​

대체 동작​

anchor alias

anchor alias

anchor alias

텍스트 음성 변환

플랫폼 배송

구성

입력 길이 제한

텔레그램 음성 메시지 말풍선 & ffmpeg

xAI 맞춤 음성 (음성 복제)

파이퍼 (로컬, 44개 언어)

사용자 정의 명령 제공자

예시: Doubao (중국어 seed-tts-2.0)

자리 표시자

선택적 키

행동 기록

보안

음성 메시지 전사 (STT)

구성

제공자 정보

예시: Doubao / Volcengine ASR

대체 동작