Communitygithub.com

delorenj/skills

Générer de la parole en utilisant le service TTS auto-hébergé voxxy (vox) à https://vox.delo.sh. À utiliser lorsque l'utilisateur demande de parler, dire, narrer, synthétiser la parole, cloner une voix, créer une voix, ajouter ou enregistrer une voix, pipe TTS, ou contrôler les qualités vocales par description (par exemple « une jeune femme à la voix joyeuse »). Gère l'utilisation de l'API HTTP, la gestion des profils vocaux, la conception vocale par description, le clonage, l'enregistrement MCP et les modèles d'intégration pour les nouvelles plateformes.

Qu'est-ce que skills ?

Cette compétence pour agents IA permet de transformer du texte en parole via le service auto-hébergé voxxy (vox), déployé à l'adresse https://vox.delo.sh. Elle est utile pour intégrer une synthèse vocale de haute qualité directement dans les workflows d'agents comme Claude, Cursor ou Codex, sans dépendre de services cloud externes. La compétence offre deux outils MCP principaux : `speak` pour renvoyer des octets audio bruts (WAV en base64), et `speak_url` pour renvoyer une URL d'audio (OGG/Opus) prête à être utilisée par Telegram, Discord, les navigateurs ou Home Assistant. Elle prend en charge la gestion de profils vocaux (liste, ajout, clonage interactif), la conception de voix par description textuelle, et l'intégration avec plusieurs moteurs de synthèse (VoxCPM2, VibeVoice, ElevenLabs) avec bascule automatique en cas de panne. Le service est accessible via HTTP, MCP, ligne de commande (`voxxy speak`), et possède un nœud Node-RED dédié. La documentation détaillée, incluse dans le fichier SKILL.md, couvre les procédures de clonage vocal, de mise à niveau des moteurs, et les astuces de dépannage pour les environnements conteneurisés.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

vox-tts

Un service TTS auto-hébergé à https://vox.delo.sh encapsulant VoxCPM2 avec un stockage de profils vocaux basé sur Postgres et la prise en charge de plusieurs moteurs. Déployé dans ~/code/voxxy (cœur : compose.yml, moteurs GPU : compose.engines.yml — les deux conteneurs de moteurs doivent être actifs, sinon les clones se dégradent silencieusement, voir ci-dessous).

Référence rapide

ActionComment
Synthèse ponctuelle (octets WAV en ligne)POST /synthesize { text, voice?, cfg?, steps? } → audio/wav
Synthèse pour livraison à Telegram / navigateur / HA / DiscordPOST /synthesize-url → {audio_url, engine, duration_s, bytes}
Outil MCP : octets en ligne (WAV en base64)speak(text, voice?)
Outil MCP : URL de livraison (OGG/Opus, prêt pour Telegram)speak_url(text, voice?)
Outil MCP : lister les voixlist_voices_tool()
Lister les voix (HTTP)GET /voices
Ajouter une voixPOST /voices (multipart : name, display_name, audio)
Clonage vocal interactif (l'utilisateur dit « clone ma voix en tant que... »)Voir Flux de clonage vocal interactif ci-dessous
Mettre à niveau un moteur (VoxCPM / VibeVoice)Voir Flux de mise à niveau du moteur ci-dessous
Parler depuis un agent Hermestts.provider: vox natif (base de la flotte) ; la flotte NE charge PAS le MCP vox
Parler depuis un shell / tout agent avec un terminalvoxxy speak "texte" (voir voxxy speak --help)
S'enregistrer auprès d'un client MCP sans chemin vox natifServeur MCP à https://vox.delo.sh/mcp/ (barre oblique finale requise)
Node-REDnode-red-contrib-vox à ~/docker/stacks/utils/vox/node-red-contrib-vox/
Santé + état du moteurGET /healthz

La barre oblique finale sur /mcp/ est obligatoire. Sans elle, FastAPI redirige avec un code 307 et HTTPX perd le corps de la requête POST.

speak vs speak_url : choisir le bon outil

Si l'audio sera...UtiliserPourquoi
Envoyé à Telegram / Discord / Slackspeak_urlLes API des canaux acceptent une URL ; leurs serveurs la récupèrent. Zéro gonflement d'octets sur le fil de l'agent.
Redirigé vers une balise <audio> du navigateurspeak_urlLes navigateurs diffusent des URL ; pas d'aller-retour en base64.
Transmis à media_player.play_media de Home Assistantspeak_urlHA veut une URL pour media_content_id.
Traité en ligne par l'agent (assemblage, analyse, boucle)speakLes octets sont déjà locaux ; une récupération d'URL ajouterait un saut.
Écrit dans un fichier local dans un script shellles deuxspeak_url + curl -o est plus facile que base64 + base64 -d.

Par défaut, utilisez speak_url. Cela ne coûte rien à l'agent en tokens (la réponse est un petit JSON) et fonctionne sur toutes les surfaces de livraison, sauf le traitement brut d'octets en ligne.

Basculement du moteur

GET /healthz signale quels moteurs sont enregistrés et si chacun est disponible :

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

L'orchestrateur les essaie dans l'ordre. Chaque réponse speak_url / speak inclut engine: "voxcpm" ou engine: "elevenlabs" afin que vous puissiez détecter quand le basculement a eu lieu. ElevenLabs se désactive automatiquement lorsque ELEVENLABS_API_KEY n'est pas défini.

Le mappage par voix d'ElevenLabs se trouve dans la colonne voices.elevenlabs_voice_id. NULL revient à la valeur par défaut globale (ELEVENLABS_DEFAULT_VOICE, Adam par défaut).

Les voix clonées sont liées au moteur. Une voix clonée via POST /voices stocke sa référence dans vibevoice_ref_path et est servie en priorité par le moteur vibevoice (routage preferred par requête dans app/engines.py ; tout le reste suit l'ordre VOX_ENGINES, voxcpm en premier). Si vibevoice est hors service, voxcpm reçoit toujours le clip de référence — app/voices.py:46-48 revient à wav_path pour tout moteur sans remplacement spécifique — donc le clone se dégrade, il n'est pas effacé. Le symptôme est une lecture reconnaissable mais erronée, pas un inconnu. Correctif : docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice, puis confirmez "name":"vibevoice","ready":true dans /healthz.

Celui qui remplace complètement la voix est le basculement ElevenLabs : si les deux moteurs GPU sont hors service et que ELEVENLABS_API_KEY est définie, vox répond 200 avec une voix étrangère, en enregistrant vox: voice clone BYPASSED, et la livre quand même. Vérifiez le champ engine sur chaque synthèse clonée — vibevoice ou voxcpm est le clone, elevenlabs n'est pas votre voix.

Le budget de référence est de 10 secondes, pas 30. Deux limitations différentes s'empilent, et seule la seconde compte. POST /voices limite l'ingestion à VOX_REF_AUDIO_MAX_SECONDS = 30s (compose.yml:16, appliquée à app/main.py:578-584, en gardant les premières 30s). Mais le conteneur vibevoice définit la même variable à 10 (compose.engines.yml:69), et engines/vibevoice/engine/synth.py:183,208 recharge la référence avec duration=10.0. Son /healthz le dit directement : "max_ref_seconds": 10.0. Ainsi, les secondes 10 à 30 de tout clip de référence sont stockées, sauvegardées, mais jamais vues par le modèle. Rédigez les passages de clonage pour 8 à 10 secondes propres et mettez le discours le meilleur et le plus neutre en premier — tout ce qui suit est du poids mort.

Procédures détaillées

Consultez flux de travail vocal et d'intégration pour l'implémentation ou le diagnostic correspondant. Le clonage vocal et la livraison externe nécessitent que l'utilisateur demande ces actions.

Aide-mémoire des valeurs par défaut

ParamètreValeur par défautRemarques
cfg2.0Guidage sans classifieur ; plus élevé = plus fidèle, moins de variation
steps10Étapes de diffusion ; 4-6 pour la vitesse, 15-20 pour une qualité maximale
normalizefalseNormalisation du texte (chiffres → mots, etc.)
denoisefalseChamp mort. Déclaré à app/main.py:98, lu nulle part ; POST /voices n'a aucun paramètre denoise du tout. Nettoyez l'audio avant le téléchargement à la place.
TTL du cache (URL audio)3600sVariable d'env VOX_AUDIO_TTL_SECONDS ; 1h est largement suffisant pour Telegram
Voix de repli (ElevenLabs)Adam (pNInz6obpgDQGcFmaJgB)Variable d'env ELEVENLABS_DEFAULT_VOICE

La synthèse s'exécute à environ 21 caractères par seconde sur un RTX 3090 avec VOX_OPTIMIZE=1 — mesuré, pas estimé : une ligne de 60 caractères prend ~2s, une ligne de 1 665 caractères prend ~35s. Budget par longueur, pas par l'annonce de 2s. Le premier appel après un redémarrage du conteneur ajoute ~15s (compilation JIT). Le transcodage OGG/Opus ajoute <100ms via ffmpeg.

Ceci est important pour tout appelant avec un délai d'attente. Le plugin TTS vox d'Hermes code en dur un délai d'attente httpx de 60s (plugins/tts/vox/__init__.py:29,316) et ignore tts.vox.timeout, donc un seul bloc dépassant environ 2 500 caractères échoue complètement. Limitez-le avec tts.vox.max_text_length (lu à tools/tts_tool.py:436-441), qui divise en blocs au lieu d'échouer.

Flux de mise à niveau du moteur

La topologie à trois conteneurs découple l'orchestration centrale (voxxy-core, conteneur vox, uniquement CPU) des moteurs side-car liés au GPU (voxxy-engine-voxcpm, voxxy-engine-vibevoice). Chaque conteneur de moteur maintient son propre pyproject.toml, uv.lock et Dockerfile sous engines/<name>/.

Procédure de mise à niveau étape par étape

1. Découverte de version et audit d'exécution

  • Versions en amont : Vérifiez PyPI et les publications GitHub :
    curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version'
    
  • Version du conteneur en cours d'exécution : Vérifiez la version du paquet installé via importlib.metadata :
    docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
      "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
    
    (N'utilisez jamais voxcpm.__version__ ; le module ne le définit pas et lève AttributeError).
  • Poids du modèle sur Hugging Face : Vérifiez si l'instantané des poids du modèle a été mis à jour :
    cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main
    curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
    
    Les mises à jour de paquets (code d'inférence, décodeurs VAE de diffusion, gestion des périphériques) sont distinctes des révisions des poids du modèle.

2. Mise à jour des dépendances et mise à jour du fichier de verrouillage

  • Mettez à jour le verrouillage de version dans engines/<name>/pyproject.toml (par exemple voxcpm==2.0.3).
  • Re-verrouillez les dépendances avec uv :
    cd engines/voxcpm && uv lock
    
  • Examinez le diff (git diff engines/voxcpm/uv.lock) pour vous assurer que PyTorch et torchaudio restent épinglés à l'index explicite pytorch-cu124 et ne dérivent pas vers les wheels CPU PyPI.

3. Reconstruire l'image du conteneur du moteur

Reconstruisez l'image du moteur via compose :

docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# Ou via l'alias mise :
mise run build:voxcpm

Le Dockerfile provisionne Python 3.12 via uv et exécute uv sync --frozen --no-install-project dans /opt/venv.

4. Recréer le conteneur du moteur avec le profil compose

Les conteneurs de moteur sont définis avec des profils compose dans compose.engines.yml (profiles: ["voxcpm"] / profiles: ["vibevoice"]). Vous devez passer --profile sinon compose ignorera le service :

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

Vérifiez que le conteneur a bien pris la nouvelle version :

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

5. Vérification et test de validation

  • Démarrage du conteneur : Inspectez les logs pour un chargement réussi du modèle :
    docker logs --tail 30 voxxy-engine-voxcpm
    # Recherchez : "Loaded VoxCPM2Model" et "Application startup complete."
    
  • Healthz du moteur :
    docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz
    # Attend : {"engine":"voxcpm","ready":true,"model_loaded":true,...}
    
  • Test de synthèse directe : Envoyez une charge utile de synthèse brute directement depuis le conteneur central vox via le réseau 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)}'
    
  • Vérification du clonage vocal : Testez avec un échantillon audio de référence (/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")))
    '
    
  • Tests de contrat et CLI :
    bash scripts/verify-engine-contract.sh
    (cd cli && uv run pytest)
    

6. Livraison

Validez à la fois pyproject.toml et uv.lock dans le répertoire du moteur :

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

Leçons apprises et pièges du moteur

  1. Inspection de version du paquet voxcpm : voxcpm n'expose PAS __version__. Appeler python -c "import voxcpm; print(voxcpm.__version__)" lève AttributeError. Inspectez toujours les métadonnées installées avec importlib.metadata.version('voxcpm').
  2. Exigence des profils Compose : Dans compose.engines.yml, chaque moteur a un profil (profiles: ["voxcpm"]). Si vous exécutez docker compose up voxxy-engine-voxcpm sans --profile voxcpm, Docker Compose ignorera silencieusement le service.
  3. Les moteurs en veille sont directement testables : Les moteurs locaux sur une seule carte GPU s'excluent mutuellement (VoxCPM ~5 Go VRAM, VibeVoice ~7,5 Go VRAM). Même si un moteur est en standby dans voxxy daemon status / .voxxy.state.json, son conteneur reste en cours d'exécution et sain sur le réseau Docker interne (http://voxxy-engine-<name>:8000). Vous pouvez le tester directement via curl depuis vox sans changer le moteur actif.
  4. Emplacement de la suite de tests Pytest : Exécuter pytest depuis la racine du dépôt échoue car plugins/tts/vox/ est un plugin Hermes s'attendant à un agent.tts_provider ... [tronqué pour la traduction]

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.

Skills associés