Communitygithub.com

delorenj/skills

Generiere Sprache mit dem selbst gehosteten voxxy (vox) TTS-Dienst unter https://vox.delo.sh. Verwende dies, wenn der Nutzer bittet, zu sprechen, zu sagen, zu erzählen, Sprache zu synthetisieren, eine Stimme zu klonen, zu erstellen, hinzuzufügen oder zu registrieren, TTS zu pipen oder Stimmqualitäten durch Beschreibung zu steuern (z.B. „eine junge Frau mit fröhlicher Stimme“). Behandelt HTTP-API-Nutzung, Stimmprofilverwaltung, beschreibungsbasiertes Stimmen-Design, Klonen, MCP-Registrierung und Integrationsmuster für neue Plattformen.

Was ist skills?

Diese Fertigkeit bietet eine umfassende Schnittstelle zu einem selbst gehosteten Text-to-Speech (TTS)-Dienst mit mehreren Engines, der Stimmklonen, beschreibungsbasiertes Stimmen-Design und flexible Synthese-Workflows unterstützt. Sie ist ideal für Entwickler und KI-Agenten, die Sprachausgabe in Plattformen wie Telegram, Discord, Home Assistant, Browser oder Node-RED integrieren möchten. Die Fertigkeit bietet zwei Haupt-MCP-Tools: `speak` für Inline-WAV-Bytes und `speak_url` für OGG/Opus-Audio-URLs – standardmäßig wird `speak_url` empfohlen, da es den Token-Verbrauch reduziert und mit den meisten Zustellkanälen funktioniert. Sie verwaltet auch Stimmprofile über eine PostgreSQL-Datenbank, unterstützt das Upgrade von Engines über einen dreistufigen Container-Workflow und bietet Fallback-Mechanismen: Wenn GPU-Engines ausfallen, kann der Dienst auf ElevenLBS (falls konfiguriert) zurückgreifen. Die Referenzdauer für den Stimmklon ist auf 10 Sekunden begrenzt, und die Synthesegeschwindigkeit beträgt etwa 21 Zeichen pro Sekunde auf einer RTX 3090.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/delorenj/skills/tree/HEAD/vox-tts

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

vox-tts

Ein selbst gehosteter TTS-Dienst unter https://vox.delo.sh, der VoxCPM2 mit einem PostgreSQL-gestützten Stimmprofil-Speicher und Unterstützung für mehrere Engines kapselt. Bereitgestellt unter ~/code/voxxy (Kern: compose.yml, GPU-Engines: compose.engines.yml – beide Engine-Container müssen laufen, sonst verschlechtern sich Klone stillschweigend, siehe unten).

Kurzübersicht

AktionWie
One-off-Synthese (Inline-WAV-Bytes)POST /synthesize { text, voice?, cfg?, steps? } → audio/wav
Synthese zur Auslieferung an Telegram / Browser / HA / DiscordPOST /synthesize-url → {audio_url, engine, duration_s, bytes}
MCP-Tool: Inline-Bytes (Base64-WAV)speak(text, voice?)
MCP-Tool: Liefer-URL (OGG/Opus, Telegram-bereit)speak_url(text, voice?)
MCP-Tool: Stimmen auflistenlist_voices_tool()
Stimmen auflisten (HTTP)GET /voices
Stimme hinzufügenPOST /voices (Multipart: name, display_name, audio)
Interaktives Stimmklonen (Nutzer sagt „Klon meine Stimme als…“)Siehe Interaktiver Stimmklon-Workflow unten
Upgrade einer Engine (VoxCPM / VibeVoice)Siehe Engine-Upgrade-Workflow unten
Sprache über einen Hermes-AgentenNativ via tts.provider: vox (Fleet-Basis); die Fleet lädt NICHT das vox MCP
Sprache von einer Shell / einem beliebigen Agenten mit Terminalvoxxy speak "text" (siehe voxxy speak --help)
Registrierung bei einem MCP-Client ohne nativen vox-PfadMCP-Server unter https://vox.delo.sh/mcp/ (nachgestellter Schrägstrich erforderlich)
Node-REDnode-red-contrib-vox unter ~/docker/stacks/utils/vox/node-red-contrib-vox/
Health + Engine-StatusGET /healthz

Der nachgestellte Schrägstrich bei /mcp/ ist zwingend erforderlich. Ohne ihn führt FastAPI eine 307-Weiterleitung durch und HTTPX verwirft den POST-Body.

speak vs speak_url: Die richtige Wahl treffen

Wenn das Audio...VerwendeGrund
An Telegram / Discord / Slack gesendet wirdspeak_urlKanal-APIs akzeptieren eine URL; ihre Server rufen sie ab. Null Byte-Bloat auf der Agenten-Leitung.
In ein Browser <audio>-Tag eingebunden wirdspeak_urlBrowser streamen URLs; kein Base64-Roundtrip.
An Home Assistant media_player.play_media übergeben wirdspeak_urlHA benötigt eine URL für media_content_id.
Vom Agenten inline verarbeitet wird (Splice, Analyse, Schleife)speakBytes sind bereits lokal; ein URL-Abruf würde einen zusätzlichen Hop bedeuten.
In einer Shell-Skript in eine lokale Datei geschrieben wirdBeidesspeak_url + curl -o ist einfacher als Base64 + base64 -d.

Standardmäßig speak_url verwenden. Es kostet den Agenten keine Tokens (die Antwort ist ein kleines JSON) und funktioniert auf allen Lieferoberflächen außer der rohen Inline-Byte-Verarbeitung.

Engine-Fallback

GET /healthz meldet, welche Engines registriert und ob jede verfügbar ist:

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

Der Orchestrator probiert sie der Reihe nach. Jede speak_url / speak-Antwort enthält engine: "voxcpm" oder engine: "elevenlabs", damit du erkennen kannst, wann der Fallback aktiviert wurde. ElevenLabs deaktiviert sich automatisch, wenn ELEVENLABS_API_KEY nicht gesetzt ist.

Die pro-stimme ElevenLabs-Zuordnung befindet sich in der Spalte voices.elevenlabs_voice_id. Bei NULL wird auf den globalen Standard zurückgegriffen (ELEVENLABS_DEFAULT_VOICE, standardmäßig Adam).

Geklonte Stimmen sind engine-gebunden. Eine über POST /voices geklonte Stimme speichert ihre Referenz in vibevoice_ref_path und wird zuerst von der vibevoice-Engine bedient (pro-Anfrage preferred-Routing in app/engines.py; alles andere folgt der VOX_ENGINES-Reihenfolge, voxcpm zuerst). Wenn vibevoice ausfällt, erhält voxcpm trotzdem das Referenz-Clip — app/voices.py:46-48 fällt auf wav_path für jede Engine ohne spezifische Überschreibung zurück — der Klon verschlechtert sich also, er wird nicht gelöscht. Das Symptom ist ein erkennbarer, aber abweichender Vortrag, kein Fremder. Behebung: docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice, dann bestätige "name":"vibevoice","ready":true in /healthz.

Derjenige, der die Stimme durch eine andere ersetzt, ist der ElevenLabs-Fallback: Wenn beide GPU-Engines ausfallen und ELEVENLABS_API_KEY gesetzt ist, antwortet vox mit 200 in einer fremden Stimme, protokolliert vox: voice clone BYPASSED, und liefert sie trotzdem aus. Überprüfe das engine-Feld bei jeder Klon-Synthese — vibevoice oder voxcpm ist der Klon, elevenlabs ist nicht deine Stimme.

Das Referenz-Budget beträgt 10 Sekunden, nicht 30. Zwei verschiedene Obergrenzen stapeln sich, und nur die zweite ist wichtig. POST /voices kürzt den Import auf VOX_REF_AUDIO_MAX_SECONDS = 30s (compose.yml:16, angewendet in app/main.py:578-584, wobei die ersten 30s behalten werden). Aber der vibevoice-Container setzt dieselbe Variable auf 10 (compose.engines.yml:69), und engines/vibevoice/engine/synth.py:183,208 lädt die Referenz mit duration=10.0 neu. Sein /healthz sagt es direkt: "max_ref_seconds": 10.0. Sekunden 10–30 eines Referenz-Clips werden also gespeichert, gesichert und vom Modell nie gesehen. Schreibe Klon-Passagen für 8–10 saubere Sekunden und platziere den besten, neutralsten Sprachvortrag zuerst – alles danach ist tote Last.

Detaillierte Verfahren

Lies Sprach- und Integrations-Workflows für die entsprechende Implementierung oder Diagnose. Stimmklonen und externe Zustellung erfordern, dass der Benutzer diese Aktionen anfordert.

Standardwerte Spickzettel

ParameterStandardHinweise
cfg2.0Classifier-free guidance; höher = treuer, weniger Variation
steps10Diffusionsschritte; 4-6 für Geschwindigkeit, 15-20 für maximale Qualität
normalizefalseTextnormalisierung (Zahlen → Wörter usw.)
denoisefalseTotes Feld. Deklariert in app/main.py:98, nirgends gelesen; POST /voices hat überhaupt keinen Denoise-Parameter. Bereinige das Audio stattdessen vor dem Hochladen.
Cache-TTL (Audio-URLs)3600sVOX_AUDIO_TTL_SECONDS-Umgebungsvariable; 1h ist reichlich für Telegram
Fallback-Stimme (ElevenLabs)Adam (pNInz6obpgDQGcFmaJgB)ELEVENLABS_DEFAULT_VOICE-Umgebungsvariable

Die Synthese läuft mit etwa 21 Zeichen pro Sekunde auf einer RTX 3090 mit VOX_OPTIMIZE=1 — gemessen, nicht geschätzt: Eine 60-Zeichen-Zeile dauert ~2s, eine 1.665-Zeichen-Zeile ~35s. Plane nach Länge, nicht nach der 2s-Schlagzeile. Der erste Aufruf nach einem Container-Neustart fügt ~15s hinzu (JIT-Kompilierung). OGG/Opus-Transcodierung fügt <100ms via ffmpeg hinzu.

Dies ist für jeden Aufrufer mit einem Timeout wichtig. Das Hermes vox TTS-Plugin hardcodiert einen 60s httpx-Timeout (plugins/tts/vox/__init__.py:29,316) und ignoriert tts.vox.timeout, sodass ein einzelner Chunk von mehr als etwa 2.500 Zeichen sofort fehlschlägt. Begrenze es mit tts.vox.max_text_length (gelesen in tools/tts_tool.py:436-441), das anstatt eines Fehlschlags chunked.

Engine-Upgrade-Workflow

Die Drei-Container-Topologie entkoppelt die Kernorchestrierung (voxxy-core, Container vox, nur CPU) von GPU-gebundenen Sidecar-Engines (voxxy-engine-voxcpm, voxxy-engine-vibevoice). Jeder Engine-Container verwaltet sein eigenes pyproject.toml, uv.lock und Dockerfile unter engines/<name>/.

Schritt-für-Schritt-Upgrade-Verfahren

1. Version Discovery & Laufzeit-Audit

  • Upstream-Releases: Überprüfe PyPI und GitHub-Releases:
    curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version'
    
  • Laufende Container-Version: Überprüfe die installierte Paketversion via importlib.metadata:
    docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
      "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
    
    (Verwende niemals voxcpm.__version__; das Modul definiert es nicht und wirft AttributeError).
  • Modellgewichte auf Hugging Face: Prüfe, ob sich der Snapshot der Modellgewichte aktualisiert hat:
    cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main
    curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
    
    Paketaktualisierungen (Inferenzcode, Streaming-VAE-Decoder, Geräteverwaltung) sind von den Revisionen der Modellgewichte zu unterscheiden.

2. Abhängigkeits-Updates & Lockfile aktualisieren

  • Erhöhe den Version-Pin in engines/<name>/pyproject.toml (z.B. voxcpm==2.0.3).
  • Sperre Abhängigkeiten mit uv neu:
    cd engines/voxcpm && uv lock
    
  • Überprüfe den Diff (git diff engines/voxcpm/uv.lock), um sicherzustellen, dass PyTorch und torchaudio auf dem expliziten pytorch-cu124-Index bleiben und nicht zu PyPI CPU-Rädern abwandern.

3. Erstelle das Engine-Container-Image neu

Erstelle das Engine-Image über compose neu:

docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# Oder über mise-Alias:
mise run build:voxcpm

Das Dockerfile richtet Python 3.12 über uv ein und führt uv sync --frozen --no-install-project in /opt/venv aus.

4. Erstelle den Engine-Container mit Compose-Profil neu

Engine-Container sind mit Compose-Profilen in compose.engines.yml definiert (profiles: ["voxcpm"] / profiles: ["vibevoice"]). Du musst --profile übergeben, sonst ignoriert Compose den Dienst:

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

Überprüfe, ob der Container die neue Version übernommen hat:

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

5. Verifikation & Smoke-Tests

  • Container-Start: Überprüfe die Logs auf erfolgreiches Laden des Modells:
    docker logs --tail 30 voxxy-engine-voxcpm
    # Suche nach: "Loaded VoxCPM2Model" und "Application startup complete."
    
  • Engine-Healthz:
    docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz
    # Erwartet: {"engine":"voxcpm","ready":true,"model_loaded":true,...}
    
  • Direkter Synthese-Test: Sende eine rohe Synthese-Payload direkt vom vox-Kerncontainer über das Docker-Netzwerk:
    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)}'
    
  • Verifikation des Stimmklons: Teste mit einer Referenz-Audio-Datei (/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")))
    '
    
  • Vertrags- und CLI-Tests:
    bash scripts/verify-engine-contract.sh
    (cd cli && uv run pytest)
    

6. Auslieferung

Comitte sowohl pyproject.toml als auch uv.lock im Engine-Verzeichnis:

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

Lessons Learned & Engine-Fallen

  1. voxcpm Paketversionsabfrage: voxcpm gibt KEIN __version__ aus. Der Aufruf von python -c "import voxcpm; print(voxcpm.__version__)" wirft AttributeError. Überprüfe immer die installierten Metadaten mit importlib.metadata.version('voxcpm').
  2. Compose-Profile-Anforderung: In compose.engines.yml hat jede Engine ein Profil (profiles: ["voxcpm"]). Wenn du docker compose up voxxy-engine-voxcpm ohne --profile voxcpm ausführst, überspringt Docker Compose den Dienst stillschweigend.
  3. Standby-Engines sind direkt testbar: Lokale Engines auf einer einzelnen GPU-Karte schließen sich gegenseitig aus (VoxCPM ~5 GB VRAM, VibeVoice ~7,5 GB VRAM). Selbst wenn eine Engine im standby-Modus ist (in voxxy daemon status / .voxxy.state.json), läuft ihr Container weiter und bleibt auf dem internen Docker-Netzwerk gesund (http://voxxy-engine-<name>:8000). Du kannst sie direkt über curl vom vox-Container aus testen, ohne die aktive Engine umschalten zu müssen.
  4. Pytest-Testsuite-Speicherort: Das Ausführen von pytest vom Repository-Stammverzeichnis schlägt fehl, da plugins/tts/vox/ ein Hermes-Plugin ist, das einen agent.tts_provider erwartet. Führe Tests stattdessen immer im Engine-Verzeichnis aus: cd engines/voxcpm && uv run pytest.
  5. Kein automatischer Container-Neustart nach dem Build: Der Build-Schritt (docker compose build) aktualisiert das Image, ersetzt aber NICHT den laufenden Container. Verwende up -d --no-build, um den neuen Container aus dem zwischengespeicherten Image zu erstellen, und vermeide das Flag --build, das einen weiteren Build durchführen würde.

Interaktiver Stimmklon-Workflow

Wenn der Benutzer eine Stimmklon-Aktion anfordert (z.B. „Klon meine Stimme als Rick“), muss der Agent die folgenden Schritte ausführen:

  1. Eine Datei oder Aufnahme vom Benutzer anfordern (mindestens 8, maximal 30 Sekunden, aber das Modell sieht nur die ersten 10).
  2. Die Audiodatei hochladen via POST /voices mit den Feldern name (z.B. „rick“) und display_name (z.B. „Rick“). Das Audio wird verarbeitet und in der Datenbank gespeichert.
  3. Bestätigen, dass die Stimme registriert wurde (GET /voices).
  4. Die neue Stimme testen mit speak_url("Hallo, ich bin Rick.", voice="rick").
  5. Dem Benutzer die URL zur Verfügung stellen oder das Audio über den entsprechenden Kanal abspielen.

Fehlerbehebung

  • Synthese schlägt fehl oder hängt: Überprüfe /healthz auf Engine-Verfügbarkeit. Wenn eine Engine nicht bereit ist, starte ihren Container neu.
  • Geklonte Stimme klingt falsch: Überprüfe, ob die vibevoice-Engine läuft. Falls nicht, wird der Klon mit reduzierter Qualität von voxcpm bedient.
  • Stimme ist nicht die geklonte: Überprüfe das engine-Feld in der Antwort. Wenn es elevenlabs ist, ist der Klon umgangen worden.
  • Timeout-Fehler: Kürze den Text mit tts.vox.max_text_length oder verwende speak_url mit kleineren Blöcken.
  • Stimmklon-Referenz zu lang: Stelle sicher, dass das Audio nicht länger als 10 Sekunden ist (das Modell ignoriert alles darüber hinaus).

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.

Verwandte Skills