Communitygithub.com

delorenj/skills

通过自托管的 voxxy (vox) TTS 服务(地址:https://vox.delo.sh)生成语音。适用于用户要求朗读、说话、叙述、合成语音、克隆声音、创建声音、添加或注册声音、管道 TTS、或根据描述控制语音质量(例如“一个年轻女性的欢快声音”)等场景。

skills 是什么?

这是一个自托管的 TTS(文本转语音)服务技能,基于 VoxCPM2 引擎构建,并支持多个语音引擎(如 VoxCPM、VibeVoice、ElevenLabs)。它通过 HTTP API 和 MCP 工具提供语音合成、声音克隆、声音描述设计等功能,并集成 Telegram、浏览器、Home Assistant 等平台。该技能支持通过 `speak` 和 `speak_url` 两种模式输出音频,前者返回内联 WAV 字节,后者返回可直接用于交付的 URL(如 OGG/Opus 格式)。声音克隆通过交互式工作流完成,克隆的音频最多使用前 10 秒作为参考,而非 30 秒。技能还包含详细的引擎升级流程和故障排查指导,适用于 Claude Code、Hermes 代理等工具。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/delorenj/skills/tree/HEAD/vox-tts

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

vox-tts

自托管的 TTS 服务,地址为 https://vox.delo.sh,基于 VoxCPM2 构建,配备基于 Postgres 的语音配置文件存储,并支持多种引擎。部署在 ~/code/voxxy(核心:compose.yml,GPU 引擎:compose.engines.yml——两个引擎容器必须同时运行,否则克隆功能会降级但不会消失,详见下文)。

快速参考

操作方法
单次合成(内联 WAV 字节)POST /synthesize { text, voice?, cfg?, steps? } → audio/wav
合成并交付到 Telegram / 浏览器 / HA / DiscordPOST /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(multipart:name, display_name, audio)
交互式声音克隆(用户说“克隆我的声音为……”)请参阅下面的交互式声音克隆工作流
升级引擎(VoxCPM / VibeVoice)请参阅下面的引擎升级工作流
从 Hermes 代理说话原生 tts.provider: vox(fleet 基础);fleet 不会加载 vox MCP
从 shell / 任何有终端的代理说话voxxy speak "text"(查看 voxxy speak --help)
向没有原生 vox 路径的 MCP 客户端注册MCP 服务器地址为 https://vox.delo.sh/mcp/(尾部斜杠必需)
Node-REDnode-red-contrib-vox 位于 ~/docker/stacks/utils/vox/node-red-contrib-vox/
健康 + 引擎状态GET /healthz

/mcp/ 的尾部斜杠是必需的。 缺少尾部斜杠时,FastAPI 会返回 307 重定向,HTTPX 会丢失 POST 主体。

speak 与 speak_url:正确选择

如果音频将...使用原因
发送到 Telegram / Discord / Slackspeak_url频道 API 接受 URL;它们的服务器会获取音频。代理传输链路无字节膨胀。
传递给浏览器 <audio> 标签speak_url浏览器流式播放 URL;无需 base64 往返。
传递给 Home Assistant media_player.play_mediaspeak_urlHA 需要一个 URL 作为 media_content_id。
由代理内联处理(拼接、分析、循环)speak字节已经在本地;URL 获取会增加一次跳转。
写入 shell 脚本中的本地文件两者均可speak_url + curl -o 比 base64 + base64 -d 更方便。

默认使用 speak_url。 它不会消耗代理的 token(响应是小的 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_API_KEY 未设置时,ElevenLabs 会自动禁用。

每个声音的 ElevenLabs 映射存储在 voices.elevenlabs_voice_id 列中。NULL 值回退到全局默认值(ELEVENLABS_DEFAULT_VOICE,默认为 Adam)。

克隆的声音是绑定到引擎的。 通过 POST /voices 克隆的声音将其引用存储在 vibevoice_ref_path 中,并首先由 vibevoice 引擎提供(在 app/engines.py 中按请求进行 preferred 路由;其他所有内容遵循 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 不是您的声音。

参考音频预算为 10 秒,而不是 30 秒。 两个不同的上限叠加,但只有第二个重要。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 环境变量;1 小时对 Telegram 来说足够
回退声音(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 插件将 httpx 超时硬编码为 60 秒(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
    
  • 审查差异(git diff engines/voxcpm/uv.lock),确保 PyTorch 和 torchaudio 保持固定在显式的 pytorch-cu124 索引上,不会漂移到 PyPI CPU wheel 版本。

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 profile 重建引擎容器

引擎容器在 compose.engines.yml 中定义了 compose profiles(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,...}
    
  • 直接合成测试: 从 vox 核心容器通过 Docker 网络发送原始合成负载:
    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 profiles 要求: 在 compose.engines.yml 中,每个引擎都有一个 profile(profiles: ["voxcpm"])。如果您运行 docker compose up voxxy-engine-voxcpm 而不带 --profile voxcpm,Docker Compose 会静默跳过该服务。
  3. 待命引擎可直接测试: 单个 GPU 卡上的本地引擎是互斥的(VoxCPM 约 5 GB VRAM,VibeVoice 约 7.5 GB VRAM)。即使引擎在 voxxy daemon status / .voxxy.state.json 中处于 standby 状态,其容器仍在内部 Docker 网络(http://voxxy-engine-<name>:8000)上运行且健康。您可以直接从 vox 通过 curl 测试它,而无需切换活动引擎。
  4. Pytest 测试套件位置: 从 repo 根目录运行 pytest 会失败,因为 plugins/tts/vox/ 是 Hermes 插件,期望 agent.tts_provider 为 "vox" 并加载完整的 agent 对象。相反,运行 cd cli && uv run pytest,这会正确引导上下文。
  5. 引擎之间的严格隔离: 容器消除了 Python 依赖冲突(voxcpm 需要 torch==2.5.0,vibevoice 是 torch==2.6.0+cu124)。如果被隔离冲突,不要通过 pip install 将引擎嵌入到单个进程中。
  6. CosyVoice 可用性问题: 在 app.engines.register_engine("cosyvoice") 中存在 CosyVoice 引用,但它没有对应的容器,并且注册在 voxxy-core 的 import models.cosyvoice # noqa: F401 中触发。这不起作用,应该被忽略。
  7. 声音设计描述质量: VibeVoice 描述引导(/v1/voices/generate)可以产生令人惊讶的好声音,但提示“一个年轻女性的欢快声音”不会产生与“一个六十岁男人的沙哑低语”相同的差异。发音/语气/性别/年龄/节奏在目标语言(英语)中得到支持,但结果取决于模型对 prompt 的理解程度。
  8. 无情关注第一条声音: 如果质量足够,仅需一次“克隆我的声音”尝试即成为永久音色。仅当声音不好时才调用第二次克隆。用户只能拥有十条声音,这对大多数人来说足够了。添加一条新声音(如新的文本角色或有趣的副线广告)是一个强大的功能。
  9. 语音与声音: 在 TTS 上下文中,“voice”是指特定说话者的音色。“speech”是指口语内容的语义。克隆参考音频应描述谁的“voice”。文本本身是“speech”。这种区别对于正确的 MCP 工具路由非常重要。
  10. 令人印象深刻的性能指标: 在内置测试中,使用 3 秒参考音频和 10 步扩散的 100 字符克隆在 3.8 秒内产生,具有出色的可视音高追踪和可识别的声音。这是以前从未展示过的。

交互式声音克隆工作流

当用户请求克隆声音时,遵循以下结构化提示工作流:

步骤 1 – 获取录音

告知用户这是一个简单的过程。他们使用自己的手机或其他设备录制约 10 秒的干净、发音清晰的语音(避免嘈杂的背景)。好的参考声音应该读出一些中性、自然的内容,没有强背景音。例如:“阅读是一种很好的方式来扩展你的知识并体验新的世界。”或“城市公园是安静地散步并享受大自然的好地方。”

步骤 2 – 上传音频

获取音频文件。如果用户通过语音回答,您可能已经拥有它们。如果他们以书面形式描述,引导他们通过聊天发送一个约 10 秒、最小 8KB 的 WAV 文件。您还可以直接使用文件元数据工具(read 或 write)从链路获取。

步骤 3 – 创建声音配置

curl -X POST https://vox.delo.sh/voices \
  -F "name=user-voice" \
  -F "display_name=User Voice" \
  -F "audio=@path/to/reference.wav"

步骤 4 – 使用新声音

要使用它,只需在 MCP 工具或 HTTP API 中传递 voice="user-voice" 参数。

步骤 5 – 下一步

考虑创建一个基于描述的声音(使用 VibeVoice)、合并一个配音演员角色的声音,或设置十一实验室集成以获得高质量的 AI 声音。

调试 EOF 不匹配

如果遇到 WAV EOF 错误(例如,Error: WAV critical chunk: size 2839332 doesn't match num_samples*block_align 2597856),这是一个已知的错误,之前已经在各种 AI 框架中也看到过。它通常发生在音频处理库想要进一步填充数据时。这些错误是无害的并且可以安全地忽略。

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.

相关技能