Productor de Videos de Lección

¿Qué hace Productor de Videos de Lección?

Convierte la presentación de diapositivas de una lección en un video educativo terminado: una voz sintética lee la narración, cada tarjeta, paso o fila aparece exactamente cuando la voz la alcanza, las transiciones varían, efectos de sonido suaves marcan cada revelación, un fondo musical de piano se reduce bajo la voz, un contador se ejecuta donde los alumnos hacen una pausa, los elementos clave obtienen un círculo dibujado a mano, los subtítulos vienen como archivos separados, y las grabaciones de pantalla reales se insertan en lecciones prácticas. Una lección a la vez; ejecútalo, míralo, luego entrégalo.

Entrada, del skill lesson-slide-designer: slides/<course>/<lesson>/slides.json, <file_name>.pptx y _preview/slide-NN.png. Si faltan, primero construye la presentación. También se leen presentaciones de la edición vietnamita (kieu, loi_doc, _kiem/).

Salida en videos/<course>/<lesson>/ (refleja la ruta de las diapositivas; de lo contrario <slides folder>/video/):

Archivo	Qué es
<file_name>.mp4	El video: 1920x1080, 30 fps, H.264, AAC 48 kHz, -16 LUFS
<file_name>.<lang>.vtt / .srt	Subtítulos como archivos separados, nunca incrustados (cubrirían el texto de la diapositiva); sube el .vtt como subtítulos
<file_name>.narration.txt	Narración limpia, un latido hablado por línea; `
<file_name>.storyboard.json / .md	Qué sucede cuándo: regiones medidas del pptx, la línea en la que aparece cada una, efectos, transiciones, círculos, zooms, contadores; el .md es para revisión visual
<file_name>.voice.mp3 + .timeline.json	La narración y el inicio y final exactos de cada línea (las líneas se almacenan en caché en .voice.mp3.cache/)
<file_name>.events.json, .audio.mp3	Eventos de sonido y la mezcla de tres capas
video.json (opcional, lo escribes tú)	Anulaciones por diapositiva: líneas de revelado, transición, retención, círculo, zoom, grabación de pantalla
_check/	contact-NN.png (fotogramas del video terminado), <file_name>.report.md (mediciones), voice-review.txt (Whisper), voice-exceptions.txt
_segments/	Un segmento renderizado por diapositiva, reutilizado cuando esa diapositiva no ha cambiado

Herramientas: Python 3.10+ con python-pptx, numpy, Pillow (opencv-python para suavizar grabaciones, faster-whisper para la revisión de voz); Node 18+ con puppeteer-core (npm install en assets/engine) y Chrome, Chromium o Edge; ffmpeg/ffprobe. Voces: Kokoro (pip install kokoro soundfile) o VieNeu-TTS, ambos Apache 2.0 y locales. Si un motor vive en su propio entorno virtual, configura KOKORO_PYTHON o VIENEU_PYTHON con ese Python. Una GPU ayuda pero es opcional.

Flujo de Trabajo

Paso 0. Lee la presentación y establece el resumen

1. Lee slides.json (narración, notas de producción, tipos de diapositivas) y echa un vistazo a _preview/contact-sheet.png. Si existe la fuente de la lección, léela para saber dónde practican los alumnos y dónde se les hacen preguntas.
2. Lee references/video-standards.md (el estándar: un tema, guión, apertura-cuerpo-cierre, transiciones, interacción) y references/motion-and-sound.md (qué recibe cada tipo de diapositiva, y por qué el video debe moverse sin volverse ocupado).
3. Establece: idioma y voz (language en slides.json; inglés por defecto a Kokoro am_michael, af_heart para voz femenina, otros idiomas Kokoro por prefijo de voz, vietnamita a VieNeu); si la lección necesita grabaciones de pantalla reales (cualquier lección que enseñe clics, escritura o software: sí, ver Paso 2); qué diapositivas de pregunta hacen pausa y por cuánto tiempo; cualquier cosa a la que hacer un círculo o zoom. La narración fue escrita para texto a voz en el paso de la diapositiva. No reescribas el contenido didáctico aquí; corrige solo cómo se pronuncia una palabra cuando la voz se equivoca.

Paso 1. Construye el storyboard y revísalo

python scripts/storyboard.py slides/<course>/<lesson>/slides.json

Lee <file_name>.storyboard.md: regiones por diapositiva, la línea en la que aparece cada una, transiciones, retenciones, círculos. Verifícalo contra la sección 4 de motion-and-sound.md: la tercera tarjeta aparece cuando la voz alcanza la tercera idea; las vecinas nunca comparten una transición; las diapositivas de pregunta se mantienen; una nota como "haz círculo a respuesta B" produjo un círculo. Corrige con video.json (ver templates/video.example.json) y ejecuta de nuevo. "No se encontraron regiones" significa que la diapositiva aparece completa: está bien para image, verifica el pptx para otros tipos.

Paso 2. Grabaciones de pantalla reales (lecciones prácticas, hands-on y de software)

Cuando la lección enseña una acción, muestra la acción real. Nunca la reemplaces con una captura de pantalla o una página simulada. Reglas en references/screen-recording.md. En resumen:

1. Prepara la ventana: una ventana de navegador privada o una cuenta limpia, sin notificaciones, sin nombres reales en las barras laterales. En Windows, python scripts/record_screen.py --list da los títulos de las ventanas.
2. Graba: python scripts/record_screen.py videos/<course>/<lesson>/clips/S07-name.mp4 --window "<title>" --seconds 40 --size 1280x720 [--crop-top 90] [--scroll "6:200:4"] (Windows; en otros sistemas usa OBS o ffmpeg). Conduce los clics y la escritura tú mismo a través de herramientas del navegador, o deja que el usuario lo haga. Desplázate solo con --scroll o un desplazamiento suave dentro de la página (window.scrollBy({top: 200, behavior: 'smooth'}) cada 0.6 a 0.8 s), nunca paso a paso. Mantén quieto de 3 a 5 s después de cada resultado; desplaza los resultados largos lentamente (150 a 250 px/s) para que los alumnos puedan leerlos.
3. check_motion.py se ejecuta después de cada grabación. Si queda algún salto: python scripts/smooth_scroll.py <in> <out>, luego mide de nuevo hasta que sea cero. Mira la banda superior del clip en busca de nombres de cuenta y pestañas perdidas.
4. Decláralo en video.json: "S07": {"clip": {"file": "clips/S07-name.mp4", "mode": "frame", "speed": "auto"}}. La diapositiva debe ser una diapositiva image o two-column con un marco grande; coloca el primer fotograma del clip en ella (composite_clips.py --first-frame clips/S07-name.mp4 slides/<course>/<lesson>/S07-first-frame.png) y reconstruye la presentación, para que el clip aparezca sin un salto.
5. Ejecuta make_video.py ... --extend: agrega silencio donde una grabación dura más que su narración. Nunca aceleres una grabación más allá de 1.25x.

Paso 3. Renderiza con un solo comando

python scripts/make_video.py slides/<course>/<lesson>/slides.json [--extend]

Nueve pasos: storyboard, narración (a través de gpu_lock.py), revisión Whisper, plan de renderizado, mezcla de tres capas, imagen (Chrome sin cabeza, diapositiva por diapositiva), grabaciones de pantalla, subtítulos, verificación final. Ejecútalo en segundo plano para lecciones de más de 3 minutos (el renderizado toma aproximadamente de uno a dos minutos por minuto de video la primera vez, segundos para una corrección a nivel de diapositiva). Cuando se detenga:

• Revisión de voz (_check/voice-review.txt): Whisper escucha el archivo completo una vez, luego solo las líneas sospechosas se regeneran y se vuelven a verificar, hasta 3 rondas. Filtra los propios errores de Whisper en palabras cortas, frases que inventa sobre música, y cualquier cosa que una segunda escucha preparada escuche correctamente; se detiene solo en palabras largas, términos, nombres o varias palabras seguidas. Escucha el lugar (ffmpeg -ss 1:23 -t 4 -i <voice.mp3> clip.wav). Si la voz es incorrecta, agrega una reescritura a PRONUNCIATION en make_voice.py (los subtítulos mantienen la ortografía real) o cambia la palabra en slides.json; si Whisper escuchó mal, agrega la palabra a _check/voice-exceptions.txt. Luego --from-step 2 (las líneas en caché no se regeneran).
• Verificación final FALLIDA (_check/<file_name>.report.md): corrige la causa (volumen con --music-db, saltos suavizando la grabación, duración re-renderizando) y vuelve a ejecutar desde ese paso.

Paso 4. Mira antes de informar

1. Mira _check/contact-NN.png (tres fotogramas por diapositiva: llegando, estable, a punto de salir) con la lista de verificación en references/quality-checks.md: un parche de portada dejado sobre el texto, texto recortado por un zoom, dos diapositivas visibles a la vez durante una transición, un contador sobre el texto, una grabación fuera de su marco, un primer fotograma vacío. Para inspeccionar un momento de cerca: node assets/engine/render.mjs sheet <storyboard.json> <timeline.json> _check/zoom --from 40 --to 46 --every 0.25.
2. Escucha dos lugares: los primeros 20 s y una transición (ffmpeg -ss 0 -t 20 -i <mp4> -vn test.mp3). Efectos audibles pero claramente por debajo de la voz, música baja.
3. Corrige con video.json o los scripts, renderiza de nuevo (solo se re-renderizan las diapositivas cambiadas), mira de nuevo hasta que una pasada completa no encuentre nada. Nunca informes un video como terminado antes de mirar las hojas de contacto del último renderizado.

Paso 5. Informa

Dale al usuario: las rutas del mp4 y vtt; duración real; voz y ritmo (palabras por segundo); diapositivas, efectos, pausas; el informe de verificación (veredicto, LUFS, saltos); qué grabaciones se combinaron; palabras agregadas a la tabla de pronunciación o a las excepciones de Whisper; advertencias dejadas y por qué. Muestra una hoja de contacto.

Varias lecciones seguidas

Mantén la voz, el nivel de música y los sonidos iguales en todo un curso; las lecciones no deben diferir en más de 1.5 LU (compara la línea LUFS de cada informe). La tabla de pronunciación y las excepciones de Whisper crecen con el tiempo; no las reinicies. Mantén las grabaciones en videos/<course>/<lesson>/clips/, un nombre de archivo nuevo por toma. Una presentación dividida en videos de tema (V<k>-<name>/slides.json) se renderiza una sub-presentación a la vez.

Principios

• El estándar es fijo (video-standards.md): un tema por video, un guión, apertura-cuerpo-cierre, transiciones habladas entre partes, interacción. El ritmo, la imagen y el sonido son donde creas.
• La imagen y la voz se complementan; la voz nunca lee la diapositiva. Una región aparece cuando la voz la alcanza; el texto que se está leyendo no se mueve.
• Pausas que están de acuerdo con la pantalla: la narración que dice "pausa el video" obtiene una retención de 3 s y sin contador (el alumno presiona pausa; un temporizador en ejecución junto a una etiqueta de "60 segundos" lo contradeciría). Una pregunta sin esa frase se mantiene por su tiempo indicado, como máximo 60 s, con un contador.
• Círculos de atención: las respuestas y notas como "círculo B" obtienen un círculo deliberado; una idea leída con una palabra de énfasis obtiene un círculo automático que se desvanece; elipses para tarjetas, cajas redondeadas para filas; como máximo tres por diapositiva.
• Cursor desactivado por defecto. Un puntero dibujado se lee como un ratón perdido para la mayoría de los espectadores. Actívalo con {"_all": {"cursor": true}} en video.json para videos de demostración; se mueve en curvas, descansa fuera del texto y nunca aparece en diapositivas de título, sección, mensaje clave o cierre.
• Animado, no ocupado: algo cambia cada 5 a 10 segundos y nada permanece quieto por más de 25; pero un punto focal por fotograma, sin giros ni volteretas, como máximo 16 efectos de sonido por minuto, sonidos de transición solo en cambios de diapositiva, música de 17 a 23 dB por debajo de la voz.
• La voz es la calidad que la gente escucha primero. No estires el tiempo de un modelo que suena mal estirado (VieNeu); ralentízalo con pausas más largas en su lugar. La revisión de Whisper no es opcional: un término mal pronunciado es un error didáctico.
• Los subtítulos son archivos separados, nunca incrustados.
• El contenido no cambia en el paso del video: sin nuevas ideas, sin números inventados. Un problema de narración regresa al paso de la lección o diapositiva.
• Ejecútalo, mídelo, míralo antes de entregar: volumen, saltos, duración, hojas de contacto.
• Una grabación es una grabación: sin capturas de pantalla que sustituyan acciones; el desplazamiento debe medirse suave.
• Para agregar una transición, efecto o sonido: extiende assets/engine/video.js, las tablas en scripts/storyboard.py y references/motion-and-sound.md, renderiza una prueba, mírala, luego úsala.

Referencias

• references/video-standards.md: el estándar instructivo para materiales de aprendizaje de audio y video, mapeado a tipos de diapositivas, más especificaciones de plataforma (Udemy y similares).
• references/motion-and-sound.md: cómo se infieren regiones y acciones, la tabla de tipos de diapositivas, números de movimiento, la banda sonora, la sintaxis de video.json, cómo mantener despiertos a los alumnos.
• references/narration-voice.md: Kokoro y VieNeu, ritmo, correcciones de pronunciación, la revisión de Whisper.
• references/screen-recording.md: grabar una ventana, desplazamiento suave, medir y suavizar saltos, composición, privacidad.
• references/quality-checks.md: umbrales de la verificación final y la lista de verificación de la hoja de contacto.
• templates/video.example.json: anulaciones por diapositiva.