Communitygithub.com

delorenj/skills

Genera voz mediante el servicio TTS autogestionado voxxy (vox) en https://vox.delo.sh. Úsalo cuando el usuario pida hablar, decir, narrar, sintetizar voz, clonar una voz, crear una voz, añadir o registrar una voz, pipear TTS o controlar cualidades de la voz por descripción (p. ej., 'una mujer joven con voz alegre'). Maneja el uso de la API HTTP, la gestión de perfiles de voz, el diseño de voz basado en descripciones, la clonación, el registro MCP y los patrones de integración para nuevas plataformas.

¿Qué es skills?

La habilidad **delorenj/skills** proporciona capacidades completas de síntesis de voz a través del servicio TTS autogestionado `voxxy (vox)` alojado en `https://vox.delo.sh`. Está diseñada para agentes de IA y desarrolladores que necesitan generación de voz de alta calidad, clonación de voz y gestión de perfiles de voz. La habilidad expone múltiples modos de síntesis: `speak` devuelve bytes WAV en línea (base64) adecuados para el procesamiento interno del agente, mientras que `speak_url` devuelve una URL de audio OGG/Opus optimizada para la entrega a plataformas como Telegram, Discord, Slack, navegadores web y Home Assistant. Por defecto, se recomienda `speak_url` porque minimiza la sobrecarga de bytes en el cable del agente. Ofrece soporte para múltiples motores TTS (VoxCPM, VibeVoice y ElevenLabs como respaldo), con cambio automático entre ellos basado en disponibilidad. Las voces clonadas se almacenan en una base de datos PostgreSQL y el sistema gestiona el enrutamiento preferente de motores. La habilidad también incluye procedimientos detallados para la actualización de motores, clonación interactiva de voz y registro con clientes MCP que no tienen una ruta nativa a vox.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

vox-tts

Un servicio TTS autogestionado en https://vox.delo.sh que envuelve VoxCPM2 con un almacén de perfiles de voz respaldado por PostgreSQL y soporte para múltiples motores. Desplegado en ~/code/voxxy (núcleo: compose.yml, motores GPU: compose.engines.yml — ambos contenedores de motores deben estar activos o los clones se degradan silenciosamente, ver más abajo).

Referencia rápida

AcciónCómo
Síntesis única (bytes WAV en línea)POST /synthesize { text, voice?, cfg?, steps? } → audio/wav
Síntesis para entrega a Telegram / navegador / HA / DiscordPOST /synthesize-url → {audio_url, engine, duration_s, bytes}
Herramienta MCP: bytes en línea (WAV base64)speak(text, voice?)
Herramienta MCP: URL de entrega (OGG/Opus, listo para Telegram)speak_url(text, voice?)
Herramienta MCP: listar voceslist_voices_tool()
Listar voces (HTTP)GET /voices
Añadir una vozPOST /voices (multipart: name, display_name, audio)
Clonación interactiva de voz (el usuario dice "clona mi voz como…")Ver Flujo de trabajo de clonación interactiva de voz más abajo
Actualizar un motor (VoxCPM / VibeVoice)Ver Flujo de trabajo de actualización de motor más abajo
Hablar desde un agente Hermestts.provider: vox nativo (base de la flota); la flota NO carga el MCP de vox
Hablar desde un shell / cualquier agente con terminalvoxxy speak "texto" (ver voxxy speak --help)
Registrar con un cliente MCP que no tiene ruta nativa a voxServidor MCP en https://vox.delo.sh/mcp/ (la barra inclinada final es obligatoria)
Node-REDnode-red-contrib-vox en ~/docker/stacks/utils/vox/node-red-contrib-vox/
Estado de salud + motoresGET /healthz

La barra inclinada final en /mcp/ es obligatoria. Sin ella, FastAPI redirige con 307 y HTTPX pierde el cuerpo POST.

speak vs speak_url: elige el correcto

Si el audio será...UsaPor qué
Enviado a Telegram / Discord / Slackspeak_urlLas APIs del canal aceptan una URL; sus servidores la obtienen. Cero hinchazón de bytes en el cable del agente.
Canalizado a una etiqueta <audio> del navegadorspeak_urlLos navegadores transmiten URLs; sin ida y vuelta base64.
Entregado a Home Assistant media_player.play_mediaspeak_urlHA quiere una URL para media_content_id.
Procesado en línea por el agente (unir, analizar, repetir)speakLos bytes ya están locales; una obtención de URL añadiría un salto.
Escrito a un archivo local en un script de shellcualquieraspeak_url + curl -o es más fácil que base64 + base64 -d.

Por defecto, usa speak_url. No le cuesta tokens al agente (la respuesta es un JSON pequeño) y funciona en todas las superficies de entrega excepto el procesamiento bruto de bytes en línea.

Respuesta de motor

GET /healthz informa qué motores están registrados y si cada uno está disponible:

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

El orquestador los prueba en orden. Cada respuesta speak_url / speak incluye engine: "voxcpm" o engine: "elevenlabs" para que puedas detectar cuándo se activó la respuesta. ElevenLabs se desactiva automáticamente cuando ELEVENLABS_API_KEY no está configurada.

La asignación por voz de ElevenLabs reside en la columna voices.elevenlabs_voice_id. NULL usa el valor predeterminado global (ELEVENLABS_DEFAULT_VOICE, Adam por defecto).

Las voces clonadas están vinculadas al motor. Una voz clonada mediante POST /voices almacena su referencia en vibevoice_ref_path y es servida primero por el motor vibevoice (enrutamiento preferred por solicitud en app/engines.py; todo lo demás sigue el orden VOX_ENGINES, voxcpm primero). Si vibevoice está caído, voxcpm aún recibe el clip de referencia — app/voices.py:46-48 usa wav_path para cualquier motor sin una anulación específica — por lo que el clon se degrada, no se borra. El síntoma es una lectura reconocible pero extraña, no una voz desconocida. Solución: docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice, luego confirma "name":"vibevoice","ready":true en /healthz.

El que reemplaza la voz por completo es la respuesta de ElevenLabs: si ambos motores GPU están caídos y ELEVENLABS_API_KEY está configurada, vox responde 200 con la voz de un desconocido, registrando vox: voice clone BYPASSED, y lo entrega de todos modos. Revisa el campo engine en cada síntesis clonada — vibevoice o voxcpm es el clon, elevenlabs no es tu voz.

El presupuesto de referencia es de 10 segundos, no 30. Dos límites diferentes se acumulan, y solo el segundo importa. POST /voices recorta la ingesta a VOX_REF_AUDIO_MAX_SECONDS = 30s (compose.yml:16, aplicado en app/main.py:578-584, manteniendo los primeros 30s). Pero el contenedor vibevoice establece la misma variable en 10 (compose.engines.yml:69), y engines/vibevoice/engine/synth.py:183,208 recarga la referencia con duration=10.0. Su /healthz lo dice directamente: "max_ref_seconds": 10.0. Por lo tanto, los segundos 10–30 de cualquier clip de referencia se almacenan, se respaldan y nunca los ve el modelo. Escribe pasajes de clonación para 8–10 segundos limpios y pon lo mejor, el discurso más neutral primero; todo lo demás después es peso muerto.

Procedimientos detallados

Lee flujos de trabajo de voz e integración para la implementación o diagnóstico relevante. La clonación de voz y la entrega externa requieren que el usuario solicite esas acciones.

Hoja de trucos de valores predeterminados

ParámetroValor predeterminadoNotas
cfg2.0Guía libre de clasificador; mayor = más fiel, menos variación
steps10Pasos de difusión; 4-6 para velocidad, 15-20 para máxima calidad
normalizefalseNormalización de texto (números → palabras, etc.)
denoisefalseCampo muerto. Declarado en app/main.py:98, no se lee en ninguna parte; POST /voices no tiene ningún parámetro denoise. Limpia el audio antes de subirlo.
TTL de caché (URLs de audio)3600sVariable de entorno VOX_AUDIO_TTL_SECONDS; 1h es suficiente para Telegram
Voz de respaldo (ElevenLabs)Adam (pNInz6obpgDQGcFmaJgB)Variable de entorno ELEVENLABS_DEFAULT_VOICE

La síntesis se ejecuta a aproximadamente 21 caracteres por segundo en una RTX 3090 con VOX_OPTIMIZE=1 — medido, no estimado: una línea de 60 caracteres toma ~2s, una línea de 1.665 caracteres toma ~35s. Presupuesta por longitud, no por el titular de 2s. La primera llamada después de reiniciar un contenedor añade ~15s (compilación JIT). La transcodificación OGG/Opus añade <100ms a través de ffmpeg.

Esto importa para cualquier llamante con un tiempo de espera. El plugin TTS vox de Hermes codifica un tiempo de espera httpx de 60s (plugins/tts/vox/__init__.py:29,316) e ignora tts.vox.timeout, por lo que un solo fragmento de más de aproximadamente 2.500 caracteres falla directamente. Limítalo con tts.vox.max_text_length (leído en tools/tts_tool.py:436-441), que divide en fragmentos en lugar de fallar.

Flujo de trabajo de actualización de motor

La topología de tres contenedores desacopla la orquestación central (voxxy-core, contenedor vox, solo CPU) de los motores laterales GPU (voxxy-engine-voxcpm, voxxy-engine-vibevoice). Cada contenedor de motor mantiene sus propios pyproject.toml, uv.lock y Dockerfile en engines/<name>/.

Procedimiento de actualización paso a paso

1. Descubrimiento de versiones y auditoría de tiempo de ejecución

  • Lanzamientos ascendentes: Revisa PyPI y los lanzamientos de GitHub:
    curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version'
    
  • Versión del contenedor en ejecución: Revisa la versión del paquete instalada a través de importlib.metadata:
    docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
      "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
    
    (Nunca uses voxcpm.__version__; el módulo no lo define y lanza AttributeError).
  • Pesos del modelo en Hugging Face: Comprueba si la instantánea de los pesos del modelo se ha actualizado:
    cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main
    curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
    
    Las actualizaciones de paquetes (código de inferencia, decodificadores VAE de transmisión, manejo de dispositivos) son distintas de las revisiones de los pesos del modelo.

2. Incremento de dependencias y actualización del archivo de bloqueo

  • Incrementa el pin de versión en engines/<name>/pyproject.toml (p. ej., voxcpm==2.0.3).
  • Vuelve a bloquear las dependencias con uv:
    cd engines/voxcpm && uv lock
    
  • Revisa el diff (git diff engines/voxcpm/uv.lock) para asegurarte de que PyTorch y torchaudio permanezcan fijados al índice explícito pytorch-cu124 y no se desvíen a las ruedas CPU de PyPI.

3. Reconstruir la imagen del contenedor del motor

Reconstruye la imagen del motor a través de compose:

docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# O a través del alias mise:
mise run build:voxcpm

El Dockerfile aprovisiona Python 3.12 a través de uv y ejecuta uv sync --frozen --no-install-project en /opt/venv.

4. Recrear el contenedor del motor con el perfil de compose

Los contenedores de motores se definen con perfiles de compose en compose.engines.yml (profiles: ["voxcpm"] / profiles: ["vibevoice"]). Debes pasar --profile o compose ignorará el servicio:

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

Verifica que el contenedor haya recogido la nueva versión:

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

5. Verificación y pruebas de humo

  • Inicio del contenedor: Inspecciona los registros para una carga exitosa del modelo:
    docker logs --tail 30 voxxy-engine-voxcpm
    # Busca: "Loaded VoxCPM2Model" y "Application startup complete."
    
  • Healthz del motor:
    docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz
    # Espera: {"engine":"voxcpm","ready":true,"model_loaded":true,...}
    
  • Prueba de síntesis directa: Envía un payload de síntesis sin procesar directamente desde el contenedor central vox a través de la red Docker:
    docker exec vox curl -s -X POST http://voxxy-engine-voxcpm:8000/v1/synthesize \
      -H 'content-type: application/json' \
      -d '{"text":"Probando síntesis."}' | jq -r '{engine, sample_rate, duration_s, bytes, has_wav: (.wav_b64 != null)}'
    
  • Verificación de clonación de voz: Prueba con una muestra de audio de referencia (/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": "Prueba de clon.", "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")))
    '
    
  • Pruebas de contrato y CLI:
    bash scripts/verify-engine-contract.sh
    (cd cli && uv run pytest)
    

6. Entrega

Confirma tanto pyproject.toml como uv.lock en el directorio del motor:

git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): actualizar voxcpm a <versión>"
git push origin main

Lecciones aprendidas y peculiaridades del motor

  1. Inspección de la versión del paquete voxcpm: voxcpm NO expone __version__. Llamar a python -c "import voxcpm; print(voxcpm.__version__)" lanza AttributeError. Siempre inspecciona los metadatos instalados con importlib.metadata.version('voxcpm').
  2. Requisito de perfiles de compose: En compose.engines.yml, cada motor tiene un perfil (profiles: ["voxcpm"]). Si ejecutas docker compose up voxxy-engine-voxcpm sin --profile voxcpm, Docker Compose omitirá silenciosamente el servicio.
  3. Los motores en espera se pueden probar directamente: Los motores locales en una sola tarjeta GPU son mutuamente excluyentes (VoxCPM ~5 GB VRAM, VibeVoice ~7,5 GB VRAM). Incluso si un motor está en standby en voxxy daemon status / .voxxy.state.json, su contenedor permanece en ejecución y saludable en la red Docker interna (http://voxxy-engine-<name>:8000). Puedes probarlo directamente a través de curl desde vox sin cambiar el motor activo.
  4. Ubicación del conjunto de pruebas de pytest: Ejecutar pytest desde la raíz del repositorio falla porque plugins/tts/vox/ es un complemento de Hermes que espera 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.

Skills relacionados