captjt/skill-tts

Texto a voz

Ejecuta el lanzador en ${CLAUDE_SKILL_DIR}/scripts/tts, que es scripts/tts en el directorio de esta skill. A continuación, se escribe como tts. La primera ejecución descarga un binario de ~7 MB y verifica su SHA-256 antes de ejecutarlo.

Ejecuta cada comando tts como una llamada Bash independiente. No lo encadenes con ;, && o tuberías, para que permanezca cubierto por el permiso preaprobado de la skill.

Hay dos trabajos:

• Locuciones para videos: tts render. Produce archivos más un manifiesto de temporización para el resto del pipeline de video.
• Lectura en voz alta: tts "texto". Reproduce a través de los altavoces y regresa inmediatamente.

Locuciones para videos

1. Escribe un guión

Coloca un segmento por escena o toma, y reutiliza los identificadores de escena del video para que el audio y las imágenes se alineen:

{
  "provider": "elevenlabs",
  "voice": "JBFqnCBsd6RMkjVDRZzb",
  "instructions": "narrador de producto cálido y seguro",
  "pause": 0.5,
  "segments": [
    {"id": "01-intro",   "text": "Conoce el nuevo panel de Insights."},
    {"id": "02-filters", "text": "Filtra cualquier gráfico con un clic: por equipo, por servicio o por versión."},
    {"id": "03-alerts",  "text": "Configura una alerta una vez, y te avisaremos en el momento en que una métrica se desvíe.", "pause": 1.0},
    {"id": "04-outro",   "text": "Insights está disponible hoy, en todos los planes."}
  ]
}

• Los campos de nivel superior (provider, voice, model, instructions, speed, pause) se aplican a cada segmento. Cada segmento puede sobrescribir voice, model, instructions, speed y pause, que es el silencio posterior en la pista combinada.
• Mantén un mismo proveedor y voz para todo el video para que suene como un solo narrador.
• Escribe para el oído: oraciones cortas, números como se pronuncian ("cuarenta por ciento", "versión dos"), sin markdown. Si un nombre de producto se pronuncia mal, escríbelo fonéticamente en text.
• Elegir un proveedor y una voz. Si el guión no establece un proveedor y tts config show no tiene voiceover_provider, pregunta al usuario qué proveedor y voz usar. Para permitirles comparar, renderiza muestras cortas con tts -o sample-NOMBRE.wav -p PROVEEDOR -v VOZ "Una línea del guión.". Ofrece guardar su elección con tts config set voiceover_provider NOMBRE y tts config set NOMBRE.voice VOZ. Kokoro y system son gratuitos y locales; el resto son de pago. ElevenLabs, OpenAI con instructions y Gemini suenan más naturales.

2. Renderizar

"${CLAUDE_SKILL_DIR}/scripts/tts" render guion.json -o locucion/

Esto escribe:

• locucion/<id>.wav para cada segmento, con el silencio inicial y final recortado para que las duraciones sean exactas.
• locucion/locucion.wav, todos los segmentos unidos con sus pausas.
• locucion/locucion.srt, subtítulos.
• locucion/manifest.json, que también se imprime en la salida estándar:

{"provider": "elevenlabs", "sample_rate": 24000, "channels": 1, "duration": 17.08,
 "combined": {"file": "/abs/locucion/locucion.wav", "duration": 17.08},
 "captions": "/abs/locucion/locucion.srt",
 "segments": [{"id": "01-intro", "file": "/abs/locucion/01-intro.wav", "duration": 3.872,
               "start": 0, "end": 3.872, "text": "...", "voice": "...", "cached": false}, ...]}

Opciones de renderizado:

• --format mp3|m4a establece el formato de la pista combinada.
• --no-combine escribe solo los archivos por segmento.
• -p/-v/-i/-s establecen valores predeterminados que el guión no especifica.
• --jobs N establece el paralelismo.

render utiliza el modelo de mayor fidelidad de cada proveedor a menos que se establezca uno: eleven_multilingual_v2 y gemini-3.8-flash-tts.

3. Usar las temporizaciones

• Duraciones de escenas: cada escena debe durar al menos la duration de su segmento. Añade un poco de margen de respiración o extiende la escena para que coincida.
• Colocar el audio: coloca el archivo de cada segmento en el tiempo de inicio de su escena, o usa locucion.wav como una sola pista con start/end como desplazamientos.
• Multiplexar con ffmpeg:
  • La pista completa: ffmpeg -i video.mp4 -i locucion/locucion.wav -map 0:v -map 1:a -c:v copy -c:a aac -shortest out.mp4
  • Un segmento a los 4.47 s: añade la entrada -i locucion/02-filters.wav, luego -filter_complex "[1]adelay=4470:all=1[a]" -map 0:v -map "[a]".

4. Iterar

Edita el guión y ejecuta el mismo comando de nuevo. Los segmentos cuyo texto, voz, modelo, estilo y velocidad no hayan cambiado se reutilizan de la última renderización ("cached": true). Solo los segmentos modificados se renderizan de nuevo y se facturan. Usa --force para volver a renderizar todo. Si algunos segmentos fallan, los demás se conservan, y al volver a ejecutar solo se reintentan los fallos.

Lectura en voz alta

"${CLAUDE_SKILL_DIR}/scripts/tts" "La compilación pasó y las 214 pruebas están en verde."
"${CLAUDE_SKILL_DIR}/scripts/tts" <<'EOF'
Texto más largo, o cualquier cosa con comillas, va por la entrada estándar.
EOF

Esto regresa una vez que el audio comienza a reproducirse, y la reproducción continúa en segundo plano. El nuevo discurso interrumpe el discurso actual; -q lo pone en cola en su lugar, y tts stop silencia todo.

Otras opciones:

• -p proveedor, -v voz, -i "estilo", -s velocidad.
• -w espera a que termine la reproducción.
• -o ARCHIVO [--json] escribe un archivo en lugar de reproducir. --json imprime su duración y ruta.

Al leer en voz alta:

• Resume; no recites. Usa de dos a cuatro oraciones habladas a menos que se te pida leer el texto completo.
• Describe el código con palabras en lugar de leerlo. El markdown y los bloques de código se eliminan automáticamente.
• Mantén las notificaciones cortas y usa -q para una serie de ellas.

Proveedores, costo y privacidad

• Usa las configuraciones predeterminadas (tts config show). Pasa -p solo cuando el usuario o el guión nombren un proveedor.
• system y kokoro permanecen en esta máquina y son gratuitos. Los otros proveedores envían el texto a esa empresa y facturan la cuenta del usuario. Nunca cambies el proveedor predeterminado sin preguntar.
• Nunca envíes secretos, credenciales o datos privados a un proveedor en la nube.
• Los proveedores de pago rechazan más de 20,000 caracteres nuevos por comando. Acorta el texto o pasa --max-chars N si el usuario lo desea.

Configuración y solución de problemas

• tts doctor muestra la salida de audio, el proveedor predeterminado y qué proveedores están listos.
• tts providers y tts voices -p NOMBRE [filtro] listan proveedores y voces.
• tts config set CLAVE VALOR establece valores predeterminados. Las claves son provider, voiceover_provider, max_chars y NOMBRE.voice|model|speed|instructions|base_url.
• Clave API faltante: dile al usuario que configure la variable de entorno (ej. ELEVENLABS_API_KEY) o que ejecute tts auth set elevenlabs en su propia terminal. Nunca le pidas al usuario que pegue una clave en el chat ni la pongas en una línea de comandos.
• Proveedores en la nube no probados: openai, gemini, cartesia y deepgram no se han probado con sus API en vivo aún. Solo system, kokoro y elevenlabs lo han sido. Si uno de ellos falla con un error sobre la solicitud en sí (un campo desconocido, parámetro inválido o respuesta inesperada), probablemente sea un error en esta skill, no algo que haya hecho el usuario. Muéstrale al usuario el error exacto, sugiérele que lo reporte en github.com/captjt/skill-tts/issues y ofrécele kokoro o system como alternativa. No sigas reintentando con parámetros adivinados. Los errores de autenticación (401/403) y cuota (429) son responsabilidad del usuario resolverlos como de costumbre.
• Kokoro no accesible: inícialo con docker run -d --name kokoro -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.9.0.
• Sin dispositivo de audio (SSH, contenedores): usa render o -o; no necesitan altavoces.

Las voces, modelos y opciones para cada proveedor están en references/providers.md.