Hermes Agent core 수정 없이 Supertonic2 TTS 붙이기

Hermes에서 TTS 엔진을 조금 바꿔보고 싶어서 작은 프록시 서버를 만들었습니다.

저장소는 여기입니다.
https://github.com/sanguneo/supertonic-openai-tts-proxy

GitHub - sanguneo/supertonic-openai-tts-proxy: OpenAI-compatible local TTS proxy for supertonic

OpenAI-compatible local TTS proxy for supertonic. Contribute to sanguneo/supertonic-openai-tts-proxy development by creating an account on GitHub.

github.com

이 프로젝트는 supertone-inc/supertonic을 실제 음성 합성 엔진으로 사용합니다.
다만 Supertonic을 Hermes에 직접 붙인 건 아니고, 중간에 작은 프록시를 하나 둔 방식입니다.
Hermes 입장에서는 OpenAI TTS API를 호출하는 것처럼 보이지만,
실제로는 로컬에서 실행 중인 Supertonic 프록시로 요청이 갑니다.

왜 프록시로 만들었나

처음에는 Hermes 내부 TTS 코드를 직접 수정하는 방법도 생각했습니다.

그런데 그렇게 하면 나중에 Hermes를 업데이트할 때 귀찮아질 수 있습니다.
수정한 부분이 충돌날 수도 있고, 계속 신경 써야 할 부분이 생깁니다.

그래서 Hermes core는 그대로 두고, OpenAI 호환 API처럼 동작하는 프록시를 만드는 쪽으로 잡았습니다.

Hermes는 이미 tts.provider: openai 설정을 지원하고, base_url도 바꿀 수 있습니다.
그러면 Hermes 설정만 바꿔서 로컬 프록시를 바라보게 만들 수 있습니다.

Hermes / client
      │
      │ OpenAI-compatible request
      ▼
/v1/audio/speech
      │
      │ proxy adapter
      ▼
Supertonic
      │
      │ synthesized audio
      ▼
mp3 / ogg / wav

대충 이런 구조입니다.

Hermes는 그대로 두고,
중간에서 Supertonic을 OpenAI TTS API처럼 보이게 감싸는 방식입니다.

지원하는 기능

현재 넣어둔 기능은 이 정도입니다.

OpenAI 호환 POST /v1/audio/speech
GET /v1/models
GET /health
Supertonic 기반 로컬 TTS 합성
mp3, ogg, wav 출력
긴 문장 분할 처리
Supertonic quality steps 설정
브라우저 테스트용 playground
WSL user systemd 서비스 스크립트
Hermes 설정/복원 스크립트

처음에는 그냥 연결만 해보려고 했는데, 실제로 계속 쓰려면 서비스 등록이나 설정 복원도 필요해서 같이 정리했습니다.

요청 예시

요청은 OpenAI TTS와 비슷한 형태로 보냅니다.

{
  "model": "supertonic-2",
  "voice": "F1",
  "input": "안녕하세요. Supertonic TTS 테스트입니다.",
  "response_format": "mp3",
  "speed": 1.3,
  "total_steps": 3
}

여기서 total_steps는 Supertonic의 품질 설정에 해당합니다.

현재 기본값은 3으로 잡아두었습니다.
빠른 응답을 우선한 설정입니다.

Low     = 3
Normal  = 6
High    = 10

품질을 더 올리고 싶으면 total_steps 값을 올리면 됩니다.
대신 합성 시간은 조금 더 걸릴 수 있습니다.

ogg 출력

출력 포맷은 mp3, ogg, wav를 지원합니다.

일반 오디오 파일로 쓰려면 mp3가 편하고,
원본 확인이나 디버깅에는 wav가 편합니다.

ogg는 Telegram voice message 때문에 넣었습니다.

Telegram 음성 메시지는 보통 Ogg 컨테이너 + Opus 코덱 조합을 사용합니다.

그래서 아래처럼 요청하면:

{
  "response_format": "opus"
}

audio/ogg 형태로 반환합니다.

이렇게 만들어두면 단순 파일 첨부가 아니라, Telegram에서 음성 메시지처럼 다루기 좋습니다.

Hermes 설정

Hermes 설정은 대략 이렇게 바꾸면 됩니다.

tts:
  provider: openai
  openai:
    base_url: http://127.0.0.1:8789/v1
    model: supertonic-2
    voice: F1
    speed: 1.3
    max_text_length: 2000

그리고 .env에는 dummy key를 넣습니다.

VOICE_TOOLS_OPENAI_KEY=dummy

실제 OpenAI API key가 필요한 것은 아닙니다.
로컬 프록시를 쓰는 것이기 때문에 값 자체는 dummy여도 됩니다.

다만 Hermes의 OpenAI TTS provider 경로를 타려면 환경 변수가 필요해서 넣어둔 값입니다.

gateway를 쓰고 있다면 설정 변경 후 재시작합니다.

hermes gateway restart

설정 백업과 복원

Hermes 설정을 바꾸는 작업이라 백업 스크립트도 같이 넣었습니다.

설정 적용은 아래 스크립트로 합니다.

./scripts/setup-hermes-config.sh

이 스크립트는 적용 전에 기존 설정을 백업합니다.

~/.hermes/config.yaml.bak.<timestamp>
~/.hermes/.env.bak.<timestamp>

복원은 아래처럼 할 수 있습니다.

./scripts/restore-hermes-config.sh --list
./scripts/restore-hermes-config.sh --latest
./scripts/restore-hermes-config.sh 20260424_105304

복원할 때도 현재 설정을 바로 덮어쓰지 않고, 먼저 한 번 더 백업합니다.

~/.hermes/config.yaml.pre-restore.<timestamp>
~/.hermes/.env.pre-restore.<timestamp>

설정 파일은 한 번 꼬이면 귀찮아서, 되돌릴 수 있게 만들어두는 편이 마음이 편합니다.

테스트용 playground

프록시 서버 안에 간단한 playground도 넣었습니다.

서버를 실행한 뒤 아래 주소로 들어가면 됩니다.

http://127.0.0.1:8789/

여기서 텍스트, voice, 출력 포맷, 속도, quality steps를 바꿔가며 테스트할 수 있습니다.

별도 프론트엔드 프로젝트를 만든 건 아니고, FastAPI에서 정적 HTML 하나를 서빙하는 정도입니다.

간단히 확인하기에는 이 정도면 충분했습니다.

실행 방법

설치는 uv 기준입니다.

uv sync

개발 서버 실행은 이렇게 합니다.

./scripts/run-dev.sh

기본 주소는 아래입니다.

http://127.0.0.1:8789

상태 확인은 /health로 할 수 있습니다.

curl http://127.0.0.1:8789/health

테스트는 이렇게 실행합니다.

uv run pytest -q

현재 기준 테스트는 통과하는 상태입니다.

13 passed

마무리

이번 작업은 Hermes에 Supertonic을 직접 박아 넣는 방식이 아니라, 중간에 OpenAI 호환 프록시를 두는 방식으로 정리했습니다.

Hermes core를 건드리지 않아도 되고,
문제가 생기면 설정만 되돌리면 됩니다.

그리고 OpenAI TTS API와 비슷한 모양으로 맞춰두면 Hermes 외의 다른 클라이언트에서도 가져다 쓰기 쉽습니다.

로컬 TTS를 Hermes에 붙여보고 싶거나,
Supertonic을 OpenAI 호환 TTS endpoint처럼 써보고 싶은 분들은 참고해보셔도 좋겠습니다.

저작자표시 비영리 변경금지 (새창열림)

왜 프록시로 만들었나

지원하는 기능

요청 예시

ogg 출력

Hermes 설정

설정 백업과 복원

테스트용 playground

실행 방법

마무리

티스토리툴바