본문으로 건너뛰기

음성 및 TTS

anchor alias​
anchor alias​
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는 제공자를 호출하기 전에 텍스트를 잘라서 요청이 길이 오류로 실패하지 않도록 합니다:

제공자기본 글자 수 제한
엣지 TTS5000
오픈AI4096
xAI15000
미니맥스10000
미스트랄4000
구글 제미니5000
일레븐랩스모델 인식(아래 참조)
뉴TTS2000
키튼TTS2000

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

model_id대문자 (문자)
eleven_flash_v2_540000
eleven_flash_v230000
eleven_multilingual_v2 (기본), eleven_multilingual_v1, eleven_english_sts_v2, eleven_english_sts_v110000
eleven_v3, eleven_ttv_v35000
알 수 없는 모델제공자 기본값(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}Hermes가 쓴 임시 UTF-8 텍스트 파일의 경로
{text_path}{input_path}의 별칭
{output_path}명령이 오디오를 기록해야 하는 경로
{format}mp3 / wav / ogg / flac
{voice}tts.providers.&lt;name&gt;.voice, 설정되지 않았을 때 비어 있음
{model}tts.providers.&lt;name&gt;.model
{speed}해결된 속도 배율 (제공자 또는 전역)

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

선택적 키​

키기본값의미
timeout120초; 만료 시 프로세스 트리가 종료됩니다 (Unix killpg, Windows taskkill /T).
output_formatmp3mp3 / wav / ogg / flac 중 하나. Hermes가 경로를 선택하면 출력 확장자로 자동 추론됩니다.
voice_compatiblefalsetrue 시, Hermes는 MP3/WAV 출력을 ffmpeg를 통해 Opus/OGG로 변환하여 Telegram이 음성 버블을 표시하도록 합니다.
max_text_length5000명령을 실행하기 전에 입력이 이 길이로 잘립니다.
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가 설정되지 않음 → 자동 감지에서 건너뜀; 다음 사용 가능한 제공자로 넘어감
  • 사용 가능한 항목 없음 → 음성 메시지는 사용자에게 정확한 알림과 함께 전달됩니다