Communitygithub.com

delorenj/skills

셀프 호스팅 voxxy (vox) TTS 서비스(https://vox.delo.sh)를 사용하여 음성을 생성합니다. 사용자가 말하기, 읽기, 내레이션, 음성 합성, 음성 복제, 음성 생성, 음성 추가 또는 등록, TTS 파이프, 설명 기반 음성 품질 제어 등을 요청할 때 사용합니다.

skills란 무엇인가요?

이 스킬은 셀프 호스팅 TTS 서비스인 voxxy (vox)를 통해 음성 합성, 음성 복제, 음성 프로필 관리를 수행하는 에이전트 스킬입니다. HTTP API와 MCP 도구를 모두 제공하여 에이전트가 텍스트를 음성으로 변환하거나, 사용자 음성을 복제하거나, 기존 음성 프로필을 관리할 수 있습니다. Hermes 에이전트, 터미널, Node-RED, Home Assistant, Telegram, Discord 등 다양한 플랫폼과 통합되며, VoxCPM2와 ElevenLabs 엔진을 지원합니다. 음성 품질은 설명 기반으로 제어할 수 있으며(예: "쾌활한 목소리의 젊은 여성"), 음성 복제 시 참조 오디오 길이는 10초로 제한됩니다. GPU 엔진 컨테이너가 다운되면 ElevenLabs로 폴백되며, 이 경우 원래 음성과 다른 음성으로 합성될 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/delorenj/skills/tree/HEAD/vox-tts

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

vox-tts

https://vox.delo.sh 에서 셀프 호스팅되는 TTS 서비스입니다. VoxCPM2를 기반으로 하며, PostgreSQL 기반 음성 프로필 저장소와 여러 엔진을 지원합니다. ~/code/voxxy에 배포되어 있습니다 (핵심: compose.yml, GPU 엔진: compose.engines.yml — 두 엔진 컨테이너가 모두 실행 중이어야 합니다. 그렇지 않으면 복제 음성이 저하됩니다. 아래 참조).

빠른 참조

동작방법
일회성 합성 (인라인 WAV 바이트)POST /synthesize { text, voice?, cfg?, steps? } → audio/wav
Telegram / 브라우저 / HA / Discord 전달을 위한 합성POST /synthesize-url → {audio_url, engine, duration_s, bytes}
MCP 도구: 인라인 바이트 (base64 WAV)speak(text, voice?)
MCP 도구: 전달 URL (OGG/Opus, Telegram 준비 완료)speak_url(text, voice?)
MCP 도구: 음성 목록 조회list_voices_tool()
음성 목록 조회 (HTTP)GET /voices
음성 추가POST /voices (멀티파트: name, display_name, audio)
대화형 음성 복제 (사용자가 "내 목소리를 ~로 복제해줘"라고 말하는 경우)아래 대화형 음성 복제 워크플로우 참조
엔진 업그레이드 (VoxCPM / VibeVoice)아래 엔진 업그레이드 워크플로우 참조
Hermes 에이전트에서 말하기기본 tts.provider: vox (fleet base); fleet은 vox MCP를 로드하지 않음
셸 / 터미널이 있는 모든 에이전트에서 말하기voxxy speak "텍스트" (voxxy speak --help 참조)
기본 vox 경로가 없는 MCP 클라이언트에 등록https://vox.delo.sh/mcp/ 의 MCP 서버 (후행 슬래시 필수)
Node-RED~/docker/stacks/utils/vox/node-red-contrib-vox/ 의 node-red-contrib-vox
상태 + 엔진 상태 확인GET /healthz

/mcp/ 의 후행 슬래시는 필수입니다. 없으면 FastAPI가 307 리디렉션을 반환하고 HTTPX가 POST 본문을 삭제합니다.

speak vs speak_url: 올바른 것 선택

오디오가 다음으로 전송될 경우...사용이유
Telegram / Discord / Slackspeak_url채널 API가 URL을 허용합니다. 서버에서 가져옵니다. 에이전트 와이어에 바이트 블로트가 없습니다.
브라우저 <audio> 태그에 파이프speak_url브라우저가 URL을 스트리밍합니다. base64 왕복이 없습니다.
Home Assistant media_player.play_media에 전달speak_urlHA는 media_content_id 에 URL을 필요로 합니다.
에이전트에서 인라인으로 처리 (연결, 분석, 반복)speak바이트가 이미 로컬에 있습니다. URL 가져오기는 홉을 추가합니다.
셸 스크립트에서 로컬 파일로 작성둘 다 가능speak_url + curl -o 가 base64 + base64 -d 보다 쉽습니다.

기본값은 speak_url 입니다. 에이전트의 토큰 비용이 없으며 (응답이 작은 JSON임), 원시 인라인 바이트 처리를 제외한 모든 전달 표면에서 작동합니다.

엔진 폴백

GET /healthz 는 등록된 엔진과 각 엔진의 사용 가능 여부를 보고합니다:

{
  "status": "ok",
  "model_loaded": true,
  "engines": [
    { "name": "voxcpm", "available": true },
    { "name": "elevenlabs", "available": true }
  ]
}

오케스트레이터는 순서대로 시도합니다. 모든 speak_url / speak 응답은 engine: "voxcpm" 또는 engine: "elevenlabs" 를 포함하므로 폴백이 발생했는지 감지할 수 있습니다. ElevenLabs는 ELEVENLABS_API_KEY 가 설정되지 않으면 자동으로 비활성화됩니다.

음성별 ElevenLabs 매핑은 voices.elevenlabs_voice_id 열에 있습니다. NULL은 전역 기본값 (ELEVENLABS_DEFAULT_VOICE, 기본적으로 Adam)으로 폴백됩니다.

복제된 음성은 엔진에 바인딩됩니다. POST /voices 를 통해 복제된 음성은 참조를 vibevoice_ref_path 에 저장하고 vibevoice 엔진이 먼저 제공합니다 (요청당 preferred 라우팅은 app/engines.py 에서 처리, 나머지는 VOX_ENGINES 순서를 따르며 voxcpm이 먼저임). vibevoice가 다운되면 voxcpm이 여전히 참조 클립을 받습니다 — app/voices.py:46-48 은 특정 재정의가 없는 모든 엔진에 대해 wav_path 로 폴백합니다 — 따라서 복제는 저하되지만 지워지지는 않습니다. 증상은 낯선 사람이 아닌 인식 가능하지만 잘못된 읽기입니다. 해결 방법: docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice 를 실행한 다음 /healthz 에서 "name":"vibevoice","ready":true 를 확인합니다.

음성을 완전히 대체하는 것은 ElevenLabs 폴백입니다: 두 GPU 엔진이 모두 다운되고 ELEVENLABS_API_KEY 가 설정된 경우, vox는 낯선 사람의 목소리로 200 을 응답하고 vox: voice clone BYPASSED 를 기록한 다음 어쨌든 전달합니다. 모든 복제 합성에서 engine 필드를 확인하십시오 — vibevoice 또는 voxcpm 은 복제된 음성이고, elevenlabs 는 당신의 음성이 아닙니다.

참조 예산은 30초가 아니라 10초입니다. 두 개의 다른 상한이 누적되며, 두 번째 상한만 중요합니다. POST /voices 는 수집을 VOX_REF_AUDIO_MAX_SECONDS = 30초로 자릅니다 (compose.yml:16, app/main.py:578-584 에서 적용, 처음 30초 유지). 그러나 vibevoice 컨테이너는 동일한 변수를 10으로 설정하고 (compose.engines.yml:69), engines/vibevoice/engine/synth.py:183,208 은 duration=10.0 으로 참조를 다시 로드합니다. /healthz 에서 직접 확인할 수 있습니다: "max_ref_seconds": 10.0. 따라서 모든 참조 클립의 10-30초는 저장되고 백업되지만 모델에서 사용되지 않습니다. 8-10초의 깨끗한 복제 구절을 작성하고 가장 좋고 중립적인 음성을 먼저 넣으십시오. 이후의 모든 것은 무게입니다.

상세 절차

관련 구현 또는 진단을 보려면 음성 및 통합 워크플로우를 읽으십시오. 음성 복제 및 외부 전달은 사용자가 해당 작업을 요청해야 합니다.

기본값 치트 시트

매개변수기본값참고 사항
cfg2.0분류기 없는 안내; 높을수록 더 충실하고 변형이 적음
steps10확산 단계; 속도를 위해 4-6, 최대 품질을 위해 15-20
normalizefalse텍스트 정규화 (숫자 → 단어 등)
denoisefalse죽은 필드. app/main.py:98 에 선언되었지만 어디에서도 읽지 않음; POST /voices 에는 denoise 매개변수가 전혀 없습니다. 대신 업로드 전에 오디오를 정리하십시오.
캐시 TTL (오디오 URL)3600sVOX_AUDIO_TTL_SECONDS 환경 변수; Telegram에는 1시간이 충분함
폴백 음성 (ElevenLabs)Adam (pNInz6obpgDQGcFmaJgB)ELEVENLABS_DEFAULT_VOICE 환경 변수

합성은 RTX 3090에서 VOX_OPTIMIZE=1 로 초당 약 21자 속도로 실행됩니다 — 측정된 값이며 추정치가 아닙니다: 60자 라인은 약 2초, 1,665자 라인은 약 35초가 걸립니다. 2초 헤드라인이 아닌 길이로 예산을 세우십시오. 컨테이너 재시작 후 첫 번째 호출은 약 15초가 추가됩니다 (JIT 컴파일). OGG/Opus 트랜스코딩은 ffmpeg를 통해 100ms 미만이 추가됩니다.

이것은 시간 초과가 있는 모든 호출자에게 중요합니다. Hermes vox TTS 플러그인은 60초 httpx 시간 초과를 하드코딩하고 (plugins/tts/vox/__init__.py:29,316) tts.vox.timeout 을 무시하므로, 약 2,500자를 초과하는 단일 청크는 실패합니다. tts.vox.max_text_length 로 제한하십시오 (tools/tts_tool.py:436-441 에서 읽음). 이는 실패하는 대신 청크로 분할합니다.

엔진 업그레이드 워크플로우

세 컨테이너 토폴로지는 핵심 오케스트레이션 (voxxy-core, 컨테이너 vox, CPU 전용)을 GPU 바운드 사이드카 엔진 (voxxy-engine-voxcpm, voxxy-engine-vibevoice)에서 분리합니다. 각 엔진 컨테이너는 engines/<name>/ 아래에 자체 pyproject.toml, uv.lock, Dockerfile 을 유지 관리합니다.

단계별 업그레이드 절차

1. 버전 검색 및 런타임 감사

  • 업스트림 릴리스: PyPI 및 GitHub 릴리스 확인:
    curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version'
    
  • 실행 중인 컨테이너 버전: importlib.metadata 를 통해 설치된 패키지 버전 확인:
    docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
      "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
    
    (절대 voxcpm.__version__ 을 사용하지 마십시오. 모듈이 이를 정의하지 않으며 AttributeError 가 발생합니다).
  • Hugging Face의 모델 가중치: 모델 가중치 스냅샷이 업데이트되었는지 확인:
    cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main
    curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
    
    패키지 업데이트 (추론 코드, 스트리밍 VAE 디코더, 장치 처리)는 모델 가중치 개정판과 별개입니다.

2. 종속성 범프 및 잠금 파일 업데이트

  • engines/<name>/pyproject.toml 에서 버전 핀 범프 (예: voxcpm==2.0.3).
  • uv로 종속성 재잠금:
    cd engines/voxcpm && uv lock
    
  • diff 검토 (git diff engines/voxcpm/uv.lock)하여 PyTorch 및 torchaudio가 명시적 pytorch-cu124 인덱스에 고정되어 있고 PyPI CPU 휠로 표류하지 않는지 확인.

3. 엔진 컨테이너 이미지 재빌드

compose를 통해 엔진 이미지 재빌드:

docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# 또는 mise 별칭 사용:
mise run build:voxcpm

Dockerfile은 uv를 통해 Python 3.12를 프로비저닝하고 uv sync --frozen --no-install-project 를 /opt/venv 에 실행합니다.

4. compose 프로필로 엔진 컨테이너 재생성

엔진 컨테이너는 compose.engines.yml 에 compose 프로필로 정의됩니다 (profiles: ["voxcpm"] / profiles: ["vibevoice"]). --profile 을 전달해야 합니다. 그렇지 않으면 compose가 서비스를 무시합니다:

docker compose -f compose.yml -f compose.engines.yml --profile voxcpm up -d --no-build voxxy-engine-voxcpm

컨테이너가 새 버전을 선택했는지 확인:

docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
  "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"

5. 확인 및 스모크 테스트

  • 컨테이너 시작: 성공적인 모델 로드에 대한 로그 검사:
    docker logs --tail 30 voxxy-engine-voxcpm
    # 확인: "Loaded VoxCPM2Model" 및 "Application startup complete."
    
  • 엔진 healthz:
    docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz
    # 예상: {"engine":"voxcpm","ready":true,"model_loaded":true,...}
    
  • 직접 합성 테스트: Docker 네트워크를 통해 vox 코어 컨테이너에서 직접 원시 합성 페이로드 전송:
    docker exec vox curl -s -X POST http://voxxy-engine-voxcpm:8000/v1/synthesize \
      -H 'content-type: application/json' \
      -d '{"text":"Testing synthesis."}' | jq -r '{engine, sample_rate, duration_s, bytes, has_wav: (.wav_b64 != null)}'
    
  • 음성 복제 확인: 참조 오디오 샘플로 테스트 (/data/voices/rick.wav):
    docker exec vox python3 -c '
    import base64, urllib.request, json
    with open("/data/voices/rick.wav", "rb") as f:
        b64 = base64.b64encode(f.read()).decode("ascii")
    data = json.dumps({"text": "Test clone.", "reference_audio_b64": b64}).encode("utf-8")
    req = urllib.request.Request("http://voxxy-engine-voxcpm:8000/v1/synthesize", data=data, headers={"Content-Type": "application/json"})
    print(json.loads(urllib.request.urlopen(req).read().decode("utf-8")))
    '
    
  • 계약 및 CLI 테스트:
    bash scripts/verify-engine-contract.sh
    (cd cli && uv run pytest)
    

6. 전달

엔진 디렉토리에 pyproject.toml 과 uv.lock 을 모두 커밋:

git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): upgrade voxcpm to <version>"
git push origin main

얻은 교훈 및 엔진 주의사항

  1. voxcpm 패키지 버전 검사: voxcpm 은 __version__ 을 노출하지 않습니다. python -c "import voxcpm; print(voxcpm.__version__)" 을 호출하면 AttributeError 가 발생합니다. 항상 importlib.metadata.version('voxcpm') 으로 설치된 메타데이터를 검사하십시오.
  2. Compose 프로필 요구 사항: compose.engines.yml 에서 각 엔진에는 프로필이 있습니다 (profiles: ["voxcpm"]). --profile voxcpm 없이 docker compose up voxxy-engine-voxcpm 을 실행하면 Docker Compose가 서비스를 자동으로 건너뜁니다.
  3. 대기 엔진은 직접 테스트 가능: 단일 GPU 카드의 로컬 엔진은 상호 배타적입니다 (VoxCPM ~5GB VRAM, VibeVoice ~7.5GB VRAM). 엔진이 voxxy daemon status / .voxxy.state.json 에서 standby 모드에 있더라도 해당 컨테이너는 내부 Docker 네트워크 (http://voxxy-engine-<name>:8000)에서 실행 중이고 정상 상태를 유지합니다. 활성 엔진을 전환하지 않고 vox 에서 curl을 통해 직접 테스트할 수 있습니다.
  4. Pytest 테스트 스위트 위치: 저장소 루트에서 pytest 를 실행하면 실패합니다. plugins/tts/vox/ 는 Hermes 플러그인으로, agent.tts_provider ...

[번역을 위해 잘림]

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

delorenj/skills

Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a static poster frame and an optional local demo script.

delorenj/skills

ASCII video: convert video/audio to colored ASCII MP4/GIF.

delorenj/skills

Plan, build and quality-check a premium short commercial for a real business (roofing, property, ecommerce, B2B software) using AI-generated footage, code-built motion (HTML/GSAP), selective Three.js and an independent-critic "Gauntlet" loop. Use when asked to make a launch-style / SaaS-style video, business ad, explainer, sample reel or pitch video, or to review and improve one. Encodes motion principles distilled from 28 professional launch films, a quality bar, audio rules and a business-offer playbook.

delorenj/skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

delorenj/skills

Generate professional voiceovers using ElevenLabs AI. Use when the user needs to create voiceovers for videos, audio narration, or text-to-speech content. Supports multiple voices with character presets (narrator, salesperson, expert) for natural delivery. Includes single scene regeneration for fine-tuning.

delorenj/skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

delorenj/skills

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

delorenj/skills

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

delorenj/skills

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

delorenj/skills

Manim CE animations: 3Blue1Brown math/algo videos.

delorenj/skills

Join a Google Meet or Zoom call as a video meeting agent via PikaStreaming. Trigger: user drops a Google Meet or Zoom link, or asks to join a meeting.

delorenj/skills

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

delorenj/skills

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

delorenj/skills

YouTube transcripts to summaries, threads, blogs.

관련 스킬