aleksanderstevens191-sudo/course-video-skill

Video de curso

Conviertes los materiales del curso del estudiante en videos de estudio. La regla que distingue a esta skill:

Cada número, ejemplo y afirmación proviene del material del curso del estudiante. Nada se inventa. Los estudiantes usan estos videos para estudiar para exámenes calificados por su profesor. Un ejemplo "más bonito" con números inventados, una fórmula con notación diferente o un hecho externo al curso es un error, incluso si es correcto en economía/física/etc.

0. Requisitos (verificar una vez)

python3 -m pip install -r requirements.txt && python3 -m playwright install chromium
ffmpeg -version | head -1          # brew install ffmpeg  /  apt install ffmpeg

Opcional: Blender 4.2+ para escenas 3D y el presentador mascota (BLENDER=/path/to/blender si no está en PATH), pdftotext (poppler) o pip install pypdf para leer diapositivas PDF, openai-whisper para transcribir grabaciones, XAI_API_KEY para la voz Grok (de lo contrario se usa la voz neuronal gratuita de Microsoft).

1. Recopilar las fuentes

Crea una carpeta <curso>/sources/ y coloca solo material del curso en ella: transcripciones de clases (.txt/.srt/.vtt), diapositivas (.pdf o texto exportado), apuntes del estudiante, sets de problemas, exámenes de práctica.

• Grabación sin transcripción → whisper lecture.mp4 --model base --output_format txt --output_dir sources/
• .docx → textutil -convert txt file.docx (macOS) o pandoc file.docx -t plain -o file.txt
• Pregunta al estudiante qué clases/temas debe cubrir el video. No añadas material de otras semanas a menos que se te pida.

Lee las fuentes por completo antes de escribir nada. Anota la notación exacta del profesor, términos, ejemplos resueltos y números.

2. Escribir el guion (JSON de contenido)

Escribe <curso>/<nombre>.json siguiendo engine/SCHEMA.md (tipos visuales, palabras clave, formato de cuestionario, límites de diseño). examples/lemonade/ es un ejemplo pequeño completo.

Reglas:

• Ejemplos: usa los ejemplos resueltos de la clase con los números de la clase. Si la clase usa "precio $4, 3 unidades", el video usa "precio $4, 3 unidades", no "precio $10, 5 unidades".
• Cuestionarios: tómalos de los problemas de práctica del curso, preguntas de clicker o ejemplos resueltos. Si escribes una pregunta nueva, constrúyela solo con números de las fuentes, e indícalo en la etiqueta del cuestionario ("Práctica", no "Pregunta de examen").
• Números derivados (un total que calculaste, una diferencia) están bien, pero declara cada uno en el mapa "derived" de nivel superior con la aritmética, usando solo números de las fuentes: "derived": {"16": "4 * 4", "-6": "120 - 126"}.
• Conteos pequeños que no sean datos ("Tres cosas para recordar", "Paso 2") van en "allow": ["3"]. 0 y 1 siempre están permitidos.
• Notación y términos: usa los del profesor (si la clase escribe "MR = MC", no cambies a "∂R/∂q").
• Si un hecho que el video necesita no está en las fuentes, detente y pregúntale al estudiante por el material, o déjalo fuera. Nunca llenes el vacío con conocimiento general.
• La narración (say) está escrita para el oído: palabras, no símbolos ("4 por 4 es 16 dólares").

3. Verificar cada número contra las fuentes (obligatorio, antes de construir)

python3 tools/check_sources.py <curso>/<nombre>.json <curso>/sources --report <curso>/<nombre>.sources.md

Extrae cada número de la narración, texto en pantalla, opciones de cuestionario y etiquetas de escenas 3D, y encuentra cada uno en las fuentes (dígitos o palabras escritas, ej. "ciento veinte"). Los números derivados se recalculan y se verifican sus operandos. Debe salir con código 0 antes de construir. Para cada problema reporta:

• el número es un error tipográfico o inventado → corrige el guion para usar el número de la fuente;
• es un cálculo real → agrégalo a "derived";
• está en las fuentes en una forma que el verificador no detectó (ej. en una imagen) → pide al estudiante que confirme, luego agrégalo a "derived" o "allow" con una nota en tu respuesta.

Luego lee tú mismo la sección de Evidencia del informe, verificando por muestreo que cada número se use con el mismo significado que en la fuente (el verificador empareja valores, no significados: "$40" el precio vs. "40 unidades" la cantidad).

4. Construir y renderizar

cd engine
python3 build.py ../<curso>/<nombre>.json              # voz, temporización, subtítulos, música (TTS=xai XAI_API_KEY=... para Grok)
python3 lint.py build/<video-id>/spec.json            # visuales que llegan tarde
python3 qa.py <video-id>                              # capturas de cada beat + hojas de contacto: MÍRALAS
OUT=../out python3 render.py <video-id> --workers 6   # renderizado completo 1080p -> ../out/<video-id>.mp4 + .srt

Mira las hojas de contacto de QA antes de renderizar: texto superpuesto, pantallas vacías, números incorrectos en pantalla.

5. Opcional: escenas 3D, mascota, efectos de sonido

Un beat con "v": {"type": "clip", "scene": "<nombre>"} reproduce una escena de Blender desde engine/blender/scene_defs/<nombre>.py (ver el docstring en engine/blender/scenelib.py; market.py y safe.py son ejemplos completos, escritos para un curso de economía, por lo que sus etiquetas llevan los números de ese curso. Cambia las etiquetas para que coincidan con tus fuentes). Las etiquetas de escenas también son verificadas por check_sources.py.

cd engine
python3 blend.py prep <video-id>                         # línea de tiempo de mascota + entradas por escena
python3 blender/stills.py <scene> --dry                  # detecta errores rápido, luego sin --dry para imágenes fijas
python3 blend.py clips <video-id>                        # renderiza las escenas 3D (lento: minutos por escena)
python3 blend.py mascot <video-id> && python3 blend.py pack <video-id>
python3 sfx.py mix <video-id>                            # efectos de sonido debajo de la narración
OUT=../out python3 blend.py comp <video-id>              # -> ../out/<video-id>-3d.mp4
OUT=../out python3 blend.py site <id1>,<id2> --title "Mi curso" --out ../out/site   # una página web con capítulos

El renderizado es lento y consume mucho espacio en disco (varios GB de fotogramas por video mientras se ejecuta). Verifica el espacio libre primero, renderiza una escena a la vez en laptops y mantén la máquina despierta.

6. Entrega

Informa al estudiante: dónde está el video, cuánto dura, qué clases cubre y el resultado de la verificación de fuentes (números verificados, cualesquiera derivados o permitidos). Si algo en las fuentes era ambiguo, indica qué supusiste. Recuérdales que el video es una ayuda de estudio construida a partir de sus materiales, no un reemplazo de la clase, y que los materiales del curso pueden no ser de su propiedad para publicar: verifica antes de publicar un video públicamente.