Screen Recording Voiceover

Locución de grabación de pantalla

La parte lenta de narrar una grabación de pantalla no es la voz, es la sincronización: alinear cada frase con el clic que describe, y arreglar los lugares donde la frase es más larga que la acción. Este skill hace ambas cosas automáticamente y nunca permite que la narración se desvíe o se superponga.

Cuándo usarlo

• "Añade una locución a esta demo / tutorial / grabación de pantalla."
• "Grabé mi pantalla en silencio, narrala" o "No quiero usar mi propia voz / acento."
• "Haz que la narración coincida con lo que se ve en pantalla."

Pasos

1. Verifica que MIRAGEA_API_KEY esté configurada (nunca la imprimas). Voz: pregunta una vez por el id de voz de Miragea del usuario, o una URL pública de un clip de su voz más las palabras exactas. Sugiere export MIRAGEA_VOICE_ID=... para que nunca se vuelva a preguntar. Solo clona una voz que el usuario posea o tenga permiso para usar.

2. Encuentra los pasos y crea una plantilla de guion:

   python3 scripts/scenes.py demo.mp4      # -> demo.frames/*.jpg, demo.frames/steps.json, demo.script.txt
   

3. Mira los fotogramas en demo.frames/ (puedes leer imágenes) y escribe una frase clara por paso en demo.script.txt después de cada marca de tiempo, reemplazando el comentario # step. Mantente dentro de la sugerencia ~N palabras para que la línea quepa antes del siguiente paso. Fusiona, mueve o elimina pasos libremente. Si el usuario proporcionó su propio guion, coloca sus frases en las marcas de tiempo correspondientes en su lugar.

4. Verifica la sincronización sin gastar nada:

   python3 scripts/voiceover.py demo.mp4 demo.script.txt --dry-run
   

   Acorta cualquier línea marcada como will freeze si el usuario quiere cero fotogramas congelados.

5. Renderiza:

   python3 scripts/voiceover.py demo.mp4 demo.script.txt --voice ID_DE_VOZ            # subtítulos como archivos
   python3 scripts/voiceover.py demo.mp4 demo.script.txt --burn --music fondo.mp3      # subtítulos quemados + música con ducking
   

6. Entrega al usuario las rutas del JSON impreso: video (MP4 narrado), voice_track (WAV para su editor), srt/vtt. Menciona frozen_seconds si es mayor que cero.

7. Para cambiar una línea, edita el guion y ejecuta el paso 5 de nuevo: las líneas sin cambios provienen de la caché sin costo.

Formato del guion

[00:00] Bienvenido a Acme. Este es el panel que ves después de iniciar sesión.
[00:04] Haz clic en Nuevo Proyecto, escribe un nombre y elige el equipo que debe ser propietario.
[01:02.5] Eso es todo. Tu proyecto está listo.

Marcas de tiempo aceptadas: [mm:ss], [h:mm:ss], mm:ss.s, 12.5s. Las líneas que comienzan con # son comentarios.

Cómo funciona la sincronización

• Cada línea comienza exactamente en su marca de tiempo; se mantienen 0.25 s de margen antes del siguiente paso.
• Una línea más larga que su espacio se acelera, como máximo --max-speed (por defecto 1.15x, aún natural).
• Si aún no cabe, el video mantiene el último fotograma de ese paso hasta que la frase termina, luego continúa. Las líneas posteriores se desplazan la misma cantidad, por lo que la sincronización nunca se pierde.
• Los subtítulos se sincronizan según la duración real hablada de cada línea (máximo 2 líneas x 42 caracteres).
• El volumen se normaliza a aproximadamente -16 LUFS (estándar de YouTube/web). La música, si se proporciona, se atenúa debajo del habla.

Opciones

Bandera	Predeterminado	Qué hace
--voice ID / --ref-url URL --ref-text TEXTO	env	Voz guardada de Miragea, o clonar a partir de un clip público (texto exacto = tarifa 1x más barata)
--model	expressive	o standard
--max-speed	1.15	Velocidad máxima antes de congelar fotogramas
--burn	off	Quemar subtítulos en el video
--music ARCHIVO	ninguno	Música de fondo, en bucle y con ducking automático
--keep-audio	off	Mantener el sonido propio de la grabación, en voz baja, debajo de la locución
--dry-run		Mostrar el plan de espacios con una velocidad de habla estimada; sin llamadas a la API
-o ARCHIVO	VIDEO.voiceover.mp4	Ruta de salida; el original nunca se modifica

Costo y límites

El habla se factura por carácter mediante Miragea (1x con una voz guardada o texto de referencia exacto; tarifas en vivo en GET https://miragea.ai/v1/capabilities). Una demo de 3 minutos suele tener entre 2000 y 3000 caracteres. Cada línea debe tener menos de 2000 caracteres. Los clips de referencia deben ser URL públicas hasta que el endpoint de carga de Miragea esté disponible.

Solución de problemas

• no timestamp / not after the previous line -> corrige la línea del guion mencionada en el error.
• no voice chosen -> pasa --voice o configura MIRAGEA_VOICE_ID.
• 401 clave incorrecta, 402 recarga en miragea.ai, 429 espera y vuelve a ejecutar (las líneas en caché no se facturan de nuevo).
• Demasiados o muy pocos pasos de scenes.py -> --threshold 0.02 (más) / 0.08 (menos), --min-gap.

Consulta examples/ para ver un guion real, el JSON del plan y los subtítulos que produjo.