Communitygithub.com

delorenj/skills

使用自託管的 voxxy (vox) TTS 服務(網址為 https://vox.delo.sh)生成語音。當使用者要求朗讀、說話、敘述、合成語音、複製聲音、創建聲音、添加或註冊聲音、透過管道傳輸 TTS,或根據描述控制語音品質(例如「一位聲音愉悅的年輕女性」)時使用。處理 HTTP API 使用、聲音設定檔管理、基於描述的聲音設計、複製、MCP 註冊,以及新平台的整合模式。

skills 是什麼?

此技能提供了一個全面的文字轉語音(TTS)代理能力,透過自託管的 voxxy 服務,該服務包裝了 VoxCPM2 引擎並支援多個後端(包括 ElevenLabs 和 VibeVoice 用於聲音複製)。它透過兩種 MCP 工具(`speak` 用於內嵌 WAV 位元組,`speak_url` 用於 OGG/Opus URL 以實現零膨脹的 Telegram/Discord 傳遞)實現語音合成和聲音管理,支援各種平台。使用者可以管理聲音設定檔(新增、列出、複製),利用引擎降級機制(GPU 引擎故障時優雅地回退到 ElevenLabs),並調整合成參數,例如 CFG 比例、擴散步數和文字長度限制。該技能還透過詳細的升級工作流程(包括版本發現、相依性提升、容器重建和驗證測試)支援 GPU 引擎的容器化升級,確保透過友善的錯誤訊息和明確的引擎回退行為來維護語音完整性。

相容平台~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,並具有 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(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 想要 media_content_id 的 URL。
由代理內聯處理(拼接、分析、循環)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 引擎提供服務(每個請求的 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 不是您的聲音。

參考音訊預算為 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 環境變數;對於 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 外掛程式將 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 繫結的 sidecar 引擎(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 包含一個活躍的 Hermes 代理上

…

[為翻譯而截斷]

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.

相關技能