음성 모드

Hermes 에이전트는 CLI와 메시징 플랫폼 전반에서 완전한 음성 상호작용을 지원합니다. 마이크를 사용해 에이전트와 대화하고, 음성 응답을 들으며, Discord 음성 채널에서 실시간 음성 대화를 나눌 수 있습니다.

권장 구성 및 실제 사용 패턴이 포함된 실용적인 설정 안내를 원하면 Hermes에서 음성 모드 사용하기를 참조하세요.

필수 조건

음성 기능을 사용하기 전에 다음을 확인하세요:

Hermes 에이전트 설치됨 — pip install hermes-agent (설치 참조)
LLM 제공자가 구성됨 — hermes model를 실행하거나 ~/.hermes/.env에서 선호하는 제공자 자격 증명을 설정하세요
작동하는 기본 설정 — 음성을 활성화하기 전에 에이전트가 텍스트에 반응하는지 확인하려면 hermes를 실행하세요

팁

~/.hermes/ 디렉토리와 기본 config.yaml 는 hermes를 처음 실행할 때 자동으로 생성됩니다. API 키를 위해서는 ~/.hermes/.env만 수동으로 생성하면 됩니다.

개요

기능	플랫폼	설명
인터랙티브 보이스	CLI	Ctrl+B를 눌러 녹음하면, 에이전트가 침묵을 자동으로 감지하고 응답합니다
자동 음성 응답	텔레그램, 디스코드	에이전트가 텍스트 응답과 함께 음성 오디오를 전송합니다
음성 채널	디스코드	봇이 VC에 참여하고, 사용자가 말하는 것을 듣고, 답변을 말한다

요구 사항

파이썬 패키지

# 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]"

추가	패키지	필요한
`voice`	`sounddevice`, `numpy`	CLI 음성 모드
`messaging`	`discord.py[voice]`, `python-telegram-bot`, `aiohttp`	디스코드 및 텔레그램 봇
`tts-premium`	`elevenlabs`	ElevenLabs TTS 제공자

선택적 로컬 TTS 제공자: neutts를 python -m pip install -U neutts[all]와 별도로 설치하세요. 첫 사용 시 모델을 자동으로 다운로드합니다.

정보

discord.py[voice] 는 PyNaCl(음성 암호화를 위해)과 opus 바인딩을 자동으로 설치합니다. 이는 Discord 음성 채널 지원을 위해 필요합니다.

시스템 종속성

# 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

의존	목적	필요함
포트오디오	마이크 입력 및 오디오 재생	CLI 음성 모드
ffmpeg	오디오 형식 변환 (MP3 → Opus, PCM → WAV)	모든 플랫폼
오푸스	디스코드 음성 코덱	디스코드 음성 채널
espeak-ng	음소화 백엔드	로컬 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

팁

faster-whisper가 설치되어 있으면, 음성 모드는 STT를 위해 API 키 없이 작동합니다. 모델(base의 경우 약 )은 처음 사용할 때 자동으로 다운로드됩니다.

CLI 음성 모드

음성 모드는 클래식 CLI (hermes chat)와 TUI (hermes --tui) 모두에서 사용할 수 있습니다. 동작은 두 환경에서 동일하며, 동일한 슬래시 명령, 동일한 VAD 무음 감지, 동일한 스트리밍 TTS, 동일한 환각 필터가 적용됩니다. 추가로 TUI는 ~/.hermes/logs/에 크래시 포렌식 로그를 전달하므로, 특이한 오디오 백엔드에서 푸시투토크 실패가 발생해도 로그가 사라지지 않고 전체 스택 트레이스와 함께 보고될 수 있습니다.

빠른 시작

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

작동 원리

CLI를 hermes으로 시작하고 /voice on으로 음성 모드를 활성화하세요
Ctrl+B를 누르세요 — 비프음(880Hz)이 울리고 녹음이 시작됩니다
말하기 — 실시간 오디오 레벨 바가 입력을 표시합니다: ● [▁▂▃▅▇▇▅▂] ❯
말하기를 멈추세요 — 3초간 침묵 후 녹음이 자동으로 중지됩니다
두 번의 삑 소리 (660Hz) 녹음이 종료되었음을 확인
오디오는 Whisper를 통해 전사되어 에이전트로 전송됩니다
TTS가 활성화되면 에이전트의 답변이 음성으로 재생됩니다
녹음이 자동으로 다시 시작됩니다 — 아무 키도 누르지 않고 다시 말하세요

이 루프는 녹음 중에 Ctrl+B를 누를 때까지(연속 모드를 종료) 또는 3번 연속 녹음에서 음성이 감지되지 않을 때까지 계속됩니다.

팁

레코드 키는 ~/.hermes/config.yaml에서 voice.record_key를 통해 구성할 수 있습니다(기본값: ctrl+b).

침묵 감지

두 단계 알고리즘이 당신이 말을 마쳤을 때를 감지합니다:

음성 확인 — RMS 임계값(200) 이상인 오디오가 최소 0.3초 동안 지속될 때까지 대기하며, 음절 사이의 짧은 하강은 허용
종료 감지 — 음성이 확인되면, 3.0초 동안 지속적인 무음 후에 트리거됩니다

15초 동안 음성이 전혀 감지되지 않으면 녹음이 자동으로 중지됩니다.

silence_threshold와 silence_duration는 config.yaml에서 모두 구성할 수 있습니다. 또한 voice.beep_enabled: false을 사용하여 녹음 시작/중지 비프음을 비활성화할 수도 있습니다.

스트리밍 TTS

TTS가 활성화되면, 에이전트는 텍스트를 생성하면서 문장 단위로 응답을 말합니다 — 전체 응답을 기다릴 필요가 없습니다:

텍스트 델타를 완전한 문장(최소 20자)으로 버퍼링합니다
마크다운 서식을 제거하고 <think> 블록을 제거합니다
문장별로 실시간 음성을 생성하고 재생합니다

환각 필터

Whisper는 때때로 침묵이나 배경 소음에서 유령 텍스트를 생성합니다(예: "시청해 주셔서 감사합니다", "구독" 등). 에이전트는 여러 언어에서 알려진 26개의 환각 문구 집합과 반복되는 변형을 포착하는 정규식 패턴을 사용하여 이를 걸러냅니다.

게이트웨이 음성 응답 (텔레그램 및 디스코드)

메시징 봇을 아직 설정하지 않았다면, 플랫폼별 가이드를 참조하세요:

메시징 플랫폼에 연결하기 위해 게이트웨이를 시작하세요:

hermes gateway        # Start the gateway (connects to configured platforms)
hermes gateway setup  # Interactive setup wizard for first-time configuration

디스코드: 채널 vs DM

봇은 디스코드에서 두 가지 상호작용 모드를 지원합니다:

모드	말하는 방법	언급 필요	설정
다이렉트 메시지 (DM)	봇의 프로필 열기 → "메시지"	No	즉시 작동
서버 채널	봇이 있는 텍스트 채널에 입력하세요	예 (`@botname`)	봇은 서버에 초대되어야 합니다

DM(개인용 권장): 봇과 DM을 열고 입력하기만 하면 됩니다 — @멘션은 필요하지 않습니다. 음성 답장과 모든 명령어는 채널에서 사용하는 것과 동일하게 작동합니다.

서버 채널: 봇은 @멘션될 때만 응답합니다(예: @hermesbyt4 hello). 멘션 팝업에서 같은 이름의 역할이 아닌 봇 사용자를 선택했는지 확인하세요.

팁

서버 채널에서 멘션 요구 사항을 비활성화하려면 ~/.hermes/.env에 다음을 추가하십시오:

DISCORD_REQUIRE_MENTION=false

또는 특정 채널을 자유 응답으로 설정합니다 (언급할 필요 없음):

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

명령어

이것들은 텔레그램과 디스코드(개인 메시지 및 텍스트 채널) 모두에서 작동합니다:

/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

모드

모드	명령	행동
`off`	`/voice off`	텍스트 전용(기본)
`voice_only`	`/voice on`	음성 메시지를 보낼 때만 대답합니다
`all`	`/voice tts`	모든 메시지에 대답합니다

음성 모드 설정은 게이트웨이 재시작 시에도 유지됩니다.

플랫폼 배송

플랫폼	형식	노트
텔레그램	음성 말풍선 (Opus/OGG)	채팅에서 바로 재생됩니다. 필요하면 ffmpeg가 MP3를 Opus로 변환합니다.
디스코드	원어 음성 버블 (Opus/OGG)	사용자 음성 메시지처럼 인라인으로 재생됩니다. 음성 버블 API가 실패하면 파일 첨부로 대체됩니다

디스코드 음성 채널

가장 몰입감 있는 음성 기능: 봇이 디스코드 음성 채널에 참여하여 사용자의 말을 듣고, 그들의 발화를 텍스트로 변환한 후 에이전트를 통해 처리하고, 응답을 음성 채널에서 다시 말합니다.

설정

1. 디스코드 봇 권한

이미 텍스트용 Discord 봇이 설정되어 있다면 (Discord 설정 가이드 참조), 음성 권한을 추가해야 합니다.

Discord 개발자 포털 → 당신의 애플리케이션 → 설치 → 기본 설치 설정 → 길드 설치로 이동:

이 권한을 기존 텍스트 권한에 추가하십시오:

허가	목적	필수
연결	음성 채널 참여	예
말하다	음성 채널에서 TTS 오디오 재생	예
음성 활동 사용	사용자가 말하고 있을 때 감지	추천

업데이트된 권한 정수:

레벨	정수	포함된 내용
텍스트만	`274878286912`	채널 보기, 메시지 보내기, 기록 읽기, 임베드, 첨부파일, 스레드, 반응
텍스트 + 음성	`274881432640`	위의 모든 것 + 연결, 말하기

업데이트된 권한 URL로 봇을 다시 초대하세요:

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274881432640
``YOUR_APP_ID`를 개발자 포털에서 받은 애플리케이션 ID로 교체하세요.

:::warning
이미 들어있는 서버에 봇을 다시 초대하면 제거하지 않고도 권한이 업데이트됩니다. 데이터나 설정은 손실되지 않습니다.

:::
#### 2. 특권 게이트웨이 인텐트 \{#2-privileged-gateway-intents}

[개발자 포털](https://discord.com/developers/applications) → 내 애플리케이션 → **봇** → **권한 있는 게이트웨이 인텐트**, 세 가지 모두 활성화:

| 의도 | 목적 |
|--------|---------|
| **프레즌스 인텐트** | 사용자의 온라인/오프라인 상태 감지 |
| **서버 구성원의 의도** | `DISCORD_ALLOWED_USERS`의 사용자 이름을 숫자 ID로 변환하기 (조건부) |
| **메시지 내용 의도** | 채널에서 문자 메시지 내용을 읽기 |

**메시지 내용 인텐트(Message Content Intent)**가 필요합니다. **서버 멤버 인텐트(Server Members Intent)**는 `DISCORD_ALLOWED_USERS` 목록이 사용자 이름을 사용할 경우에만 필요합니다 — 숫자 사용자 ID를 사용하는 경우에는 끌 수 있습니다. 음성 채널 SSRC → user_id 매핑은 Discord 음성 웹소켓의 SPEAKING opcode에서 가져오며, 서버 멤버 인텐트가 **필요하지 않습니다**.

#### 3. 오푸스 코덱 \{#3-opus-codec}

게이트웨이를 실행하는 컴퓨터에 Opus 코덱 라이브러리가 설치되어 있어야 합니다:

```bash
# macOS (Homebrew)
brew install opus

# Ubuntu/Debian
sudo apt install libopus0

봇은 다음에서 코덱을 자동으로 로드합니다:

macOS: /opt/homebrew/lib/libopus.dylib
리눅스: 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

봇은 몇 초 안에 디스코드에서 온라인 상태가 되어야 합니다.

명령어

봇이 있는 디스코드 텍스트 채널에서 이것들을 사용하세요:

/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

정보

/voice join를 실행하기 전에 음성 채널에 있어야 합니다. 봇은 사용자가 있는 동일한 음성 채널에 참여합니다.

작동 원리

봇이 음성 채널에 참여하면, 그것은:

각 사용자의 오디오 스트림을 독립적으로 듣습니다
침묵 감지 — 최소 0.5초의 음성 후 1.5초 동안 침묵이 있으면 처리 시작
Whisper STT(로컬, Groq, 또는 OpenAI)를 통해 오디오를 전사합니다
세션, 도구, 메모리를 포함한 전체 에이전트 파이프라인을 통한 프로세스
TTS를 통해 음성 채널에서 답장을 말합니다

텍스트 채널 통합

봇이 음성 채널에 있을 때:

성적표는 텍스트 채널 [Voice] @user: what you said 에 나타납니다
에이전트 응답은 채널에 텍스트로 전송되며 VC에서 음성으로도 전달됩니다
텍스트 채널은 /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 제공업체 비교

제공자	모델	속도	품질	비용	API 키
현지	`base`	빠름(CPU/GPU에 따라 다름)	좋아요	무료	No
현지	`small`	중간	더 나은	무료	No
현지	`large-v3`	느린	최고	무료	No
그로크	`whisper-large-v3-turbo`	매우 빠름 (~0.5초)	좋아요	무료 등급	예
그로크	`whisper-large-v3`	빠름 (~1초)	더 나은	무료 등급	예
오픈AI	`whisper-1`	빠름 (~1초)	좋아요	유료	예
오픈AI	`gpt-4o-transcribe`	중간 (~2초)	최고	유료	예

공급자 우선순위(자동 폴백): 로컬 > 그록 > 오픈AI

TTS 제공업체 비교

제공자	품질	비용	지연	키 필요
엣지 TTS	좋아요	무료	~1s	No
엘레븐랩스	훌륭한	유료	~2s	예
OpenAI TTS	좋아요	유료	~1.5s	예
NeuTTS	좋아요	무료	CPU/GPU에 따라 다릅니다	No

NeuTTS는 위의 tts.neutts 설정 블록을 사용합니다.

문제 해결

"오디오 장치를 찾을 수 없습니다" (CLI)

PortAudio가 설치되지 않았습니다:

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

봇이 디스코드 서버 채널에서 응답하지 않습니다

봇은 기본적으로 서버 채널에서 @멘션이 필요합니다. 다음을 확인하세요:

@를 입력하고 동일한 이름의 역할이 아니라 봇 사용자(#식별자 포함)를 선택하세요
또는 대신 DM을 사용하세요 — 언급할 필요 없음
또는 ~/.hermes/.env에 DISCORD_REQUIRE_MENTION=false을 설정하세요

봇이 VC에 들어오지만 내 말을 듣지 못해요

당신의 Discord 사용자 ID가 DISCORD_ALLOWED_USERS에 있는지 확인하세요
Discord에서 음소거되지 않았는지 확인하세요
봇이 오디오를 매핑하기 전에 Discord에서 SPEAKING 이벤트가 필요합니다 — 참가 후 몇 초 내에 말하기 시작하세요

봇이 제 말을 듣지만 반응하지 않습니다

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 모델을 시도해 보세요

필수 조건​

개요​

요구 사항​

파이썬 패키지​

시스템 종속성​

API 키​

CLI 음성 모드​

빠른 시작​

작동 원리​

침묵 감지​

스트리밍 TTS​

환각 필터​

게이트웨이 음성 응답 (텔레그램 및 디스코드)​

디스코드: 채널 vs DM​

명령어​

모드​

플랫폼 배송​

디스코드 음성 채널​

설정​

1. 디스코드 봇 권한​

4. 환경 변수​

게이트웨이를 시작하세요​

명령어​

작동 원리​

텍스트 채널 통합​

에코 방지​

접근 제어​

구성 참조​

config.yaml​

환경 변수​

STT 제공업체 비교​

TTS 제공업체 비교​

문제 해결​

"오디오 장치를 찾을 수 없습니다" (CLI)​

봇이 디스코드 서버 채널에서 응답하지 않습니다​

봇이 VC에 들어오지만 내 말을 듣지 못해요​

봇이 제 말을 듣지만 반응하지 않습니다​

봇은 텍스트에서는 응답하지만 음성 채널에서는 응답하지 않습니다​

Whisper가 쓰레기 텍스트를 반환합니다​

필수 조건

개요

요구 사항

파이썬 패키지

시스템 종속성

API 키

CLI 음성 모드

빠른 시작

작동 원리

침묵 감지

스트리밍 TTS

환각 필터

게이트웨이 음성 응답 (텔레그램 및 디스코드)

디스코드: 채널 vs DM

명령어

모드

플랫폼 배송

디스코드 음성 채널

설정

1. 디스코드 봇 권한

4. 환경 변수

게이트웨이를 시작하세요

명령어

작동 원리

텍스트 채널 통합

에코 방지

접근 제어

구성 참조

config.yaml

환경 변수

STT 제공업체 비교

TTS 제공업체 비교

문제 해결

"오디오 장치를 찾을 수 없습니다" (CLI)

봇이 디스코드 서버 채널에서 응답하지 않습니다

봇이 VC에 들어오지만 내 말을 듣지 못해요

봇이 제 말을 듣지만 반응하지 않습니다

봇은 텍스트에서는 응답하지만 음성 채널에서는 응답하지 않습니다

Whisper가 쓰레기 텍스트를 반환합니다