yyert123/video-captions

Subtítulos de video

Un solo comando convierte un archivo de video (o audio) en subtítulos agradables de leer y, opcionalmente, en un MP4 con subtítulos incrustados. Los segmentos sin procesar del reconocimiento de voz a menudo se cortan a medio camino ("ce" / "ntro") y son demasiado largos; este skill reconstruye palabras completas y las reorganiza en señales adecuadas.

Cuándo usarlo

• "Añadir subtítulos / leyendas a este video", "crear un SRT para mi charla", "incrustar subtítulos".
• "Hacer subtítulos estilo TikTok/Reels/Shorts" -> usar --style shorts --burn.
• El usuario necesita un archivo .vtt para una etiqueta <track> en un sitio web o para subir a YouTube.

Pasos

1. Verificar que MIRAGEA_API_KEY esté configurada (nunca imprimirla). Si falta, indicar al usuario que cree una clave en https://miragea.ai y ejecute export MIRAGEA_API_KEY=....

2. Ejecutar el script sobre el archivo del usuario:

   python3 scripts/captions.py ruta/al/video.mp4                 # -> video.srt + video.vtt
   python3 scripts/captions.py ruta/al/video.mp4 --burn          # + video.subtitulado.mp4
   python3 scripts/captions.py ruta/al/corto.mp4 --style shorts --burn   # subtítulos pop, centrados
   

3. Leer el JSON que imprime (srt, vtt, video, cues) y proporcionar al usuario las rutas.

4. Si el usuario desea corregir el texto, editar el archivo .srt (mantener las marcas de tiempo) y volver a ejecutar con --burn: la transcripción se guarda en caché en <archivo>.transcript.json, por lo que las re-ejecuciones no tienen costo.

Opciones

Opción	Por defecto	Qué hace
--style standard	sí	2 líneas x 42 caracteres, 1-7 s por señal (convenciones de radiodifusión)
--style shorts		1-3 palabras por señal, MAYÚSCULAS, centradas al incrustar
--burn	desactivado	Escribe <nombre>.subtitulado.mp4 (H.264, audio original copiado)
--upper	desactivado	Subtítulos estándar en mayúsculas
--out-dir DIR	junto al archivo de entrada	Directorio de salida
--force	desactivado	Ignorar transcripción en caché y volver a transcribir

Costo y límites

Solo se sube una pista de audio mono de 16 kHz (no el video), hasta 90 minutos / 1 GB por archivo. Miragea cobra 3 puntos por segundo de audio; las re-ejecuciones en caché son gratuitas. Consultar tarifas en vivo con GET https://miragea.ai/v1/capabilities.

Solución de problemas

• ffmpeg not found -> instalar ffmpeg (brew install ffmpeg, sudo apt install ffmpeg, winget install ffmpeg).
• 401 -> la clave es incorrecta; 402 -> recargar crédito en miragea.ai; 429 -> esperar y volver a ejecutar (seguro reintentar).
• Subtítulos ligeramente adelantados/retrasados en clips con mucha música: volver a ejecutar con --force después de recortar introducciones.

Ver examples/ para ejemplos de salida.