Lecture Video Explainer

Explicador de Videos de Conferencias

Objetivo: los estudiantes deben poder entender una conferencia sin asistir a ella y repasarla rápidamente antes del examen. Por lo tanto, el video es una herramienta de aprendizaje, no una muestra: fiel a la conferencia, explicado de forma sencilla, memorable y legible en todo momento.

Tres principios guían cada decisión:

1. No inventes nada. Cada afirmación, número, definición y gráfico está respaldado por los materiales de la conferencia. Simplificar es bienvenido; añadir hechos no lo es. Alguien que haga el examen después de ver el video debe poder confiar en que el contenido estaba en la conferencia exactamente así.
2. Todo legible, nada recortado. Sin texto medio visible, sin desbordamiento, sin fuentes diminutas. Una sola frase recortada destruye la confianza en todo el video.
3. Voz fluida, imágenes tranquilas. El narrador no hace pausas largas. Donde hay mucho que ver, la imagen se mantiene brevemente antes de continuar, como en una buena presentación.

El entregable es el video terminado, descargable como un solo MP4 directamente en Claude. El usuario nunca ejecuta código, scripts o comandos, y nunca tiene que pegar una clave API: todo lo técnico ocurre en tu lado, con las herramientas que este entorno ofrece. Sin reproductor, sin archivos adicionales a menos que el usuario los solicite explícitamente (subtítulos como archivos, transcripción, tabla de índice).

Habla al usuario en el idioma en que escribe. El idioma del video es una elección separada (Fase 1, paso 1).

Hay dos modos, elegidos en la primera pregunta: narrado (voz de IA a través de OpenRouter, por defecto) y solo visual (sin voz: todo se explica en pantalla, ver "Modo solo visual" más abajo). Donde este archivo hable de narración, TTS o audio, se aplica solo al modo narrado.

Flujo de trabajo

Trabaja a través de las fases en orden. La Fase 1 es una parada obligatoria: no se gasta dinero (TTS) hasta que el usuario haya confirmado el modo, idioma, modelo y duración.

Fase 0 – Leer los materiales

0. Observa lo que este entorno ofrece, en silencio: el conector MCP de OpenRouter (para la voz), una salida de video/animación incorporada con exportación o descarga MP4 (por ejemplo, en Claude Design), y/o ejecución de código con ffmpeg + Chromium (para scripts/render.py). La Fase 7 elige la ruta de salida a partir de eso. Nunca hagas que el usuario instale o ejecute nada.
1. Extrae el PDF con scripts/extract_pdf.py:

   python3 scripts/extract_pdf.py <pdf> <workdir> [--images]
   

   Esto produce pages.json (texto, recuento de palabras, recuento de imágenes por página), una vista previa PNG de cada página y – con --images – las imágenes incrustadas. Si falta pymupdf: pip install pymupdf --break-system-packages.
2. Mira las vistas previas de las páginas (no solo el texto): los diagramas, tablas y gráficos de proceso suelen existir solo como imágenes. Páginas escaneadas (salida "SCANNED/sin texto"): vuelve a ejecutar con --ocr (Tesseract, paquete de idioma de los materiales, por ejemplo --ocr-lang deu+eng). Si falta Tesseract o el paquete de idioma, mira las imágenes de vista previa y lee el texto tú mismo. Siempre revisa el texto OCR contra la imagen antes de usar términos técnicos o números en el guion.
3. Determina a partir de los materiales: nombre del curso, tema de esta unidad, profesor/a, idioma de los materiales, si hay una diapositiva de resumen, y qué diapositivas no tienen contenido (título, agenda, referencias, "¿Preguntas?"). Cualquier cosa que no esté en los materiales no se adivina: pregúntalo en la Fase 1.
4. Preguntas abiertas en las diapositivas: pages.json lista, por página, questions – líneas que preguntan algo a la audiencia ("¿Qué opinas: …?", "¿Qué ventajas tiene …?", "Discusión: …", "Pregunta para ti", "Why could …?"). Todas se responden en el video (ver "Preguntas abiertas" en la Fase 2). Lee las diapositivas tú también: las preguntas dentro de gráficos o bocadillos de diálogo no siempre se detectan.
5. ¿Conferencia o ejercicio? pages.json tiene exercise_guess (palabras como "Übung", "Aufgabe", "Übungsblatt", "Exercise", "Task", "Assignment", tareas numeradas con a). b) c)). Confirma leyendo: una hoja de ejercicios pide al alumno que haga algo. Si es un ejercicio (o una conferencia con diapositivas de ejercicios), el video resuelve los ejercicios – ver "Modo ejercicio" más abajo. También verifica si se incluye una hoja de soluciones o diapositivas de soluciones.

La Fase 0 se ejecuta en silencio: antes de las primeras preguntas (Fase 1, paso 1) no le preguntas nada más al usuario ni resumas los materiales. La extracción solo existe para que la opción "igual que las diapositivas" pueda nombrar el idioma detectado.

Fase 1 – Preguntar al usuario (obligatorio, antes de cualquier generación)

Paso 1 – Tipo de video, narración e idioma (siempre el primer mensaje)

El primer mensaje contiene exactamente estas tres preguntas y nada más (como tres preguntas seleccionables si dicha herramienta está disponible), en el idioma del usuario, el tipo de video siempre primero. Ejemplo para un usuario de habla alemana:

1. ¿Qué tipo de video debería ser?

• Resumen breve – solo lo esencial: términos clave, relaciones centrales, relevante para el examen; ideal para repasar rápido
• Resumen completo – cubre todos los temas de los materiales, con explicaciones y ejemplos; reemplaza la conferencia

2. ¿Debería tener sonido el video?

• Sí, con narrador (voz de IA) – explica como en la conferencia; cuesta unos céntimos
• No, solo visual – las explicaciones están como texto y gráfico en la imagen, sin sonido, gratis

3. ¿En qué idioma debe estar el video?

• Igual que los materiales (Alemán) ← idioma detectado entre paréntesis
• Alemán
• Inglés
• Otro idioma (texto libre)

El tipo de video va primero porque decide qué entra en el video y qué duraciones tienen sentido:

• Resumen breve: solo el núcleo – términos y definiciones clave, las relaciones centrales, todo lo marcado como relevante para el examen, más la diapositiva de resumen. Se omiten ejemplos, derivaciones y temas secundarios. Cada capítulo de la conferencia puede tocarse en una o dos frases, pero la profundidad solo llega al núcleo.
• Resumen completo: se cubre cada tema de los materiales – cada página de contenido termina en al menos una escena (verificado en la Fase 6 con scripts/coverage.py), en el orden de la conferencia, con las explicaciones y ejemplos que da la conferencia. Nada se salta, solo se condensa.
• Para un ejercicio: breve = para cada tarea, el enfoque en una o dos frases más el resultado; completo = la ruta de solución completa paso a paso.

La narración va después porque cambia todo lo que sigue: con "solo visual" no hay pregunta de modelo, ni costo, y el video se construye de manera diferente.

Mantén "igual que las diapositivas" incluso si el idioma detectado es alemán o inglés – es el valor predeterminado. Para materiales multilingües, nombra el dominante ("igual que las diapositivas (principalmente inglés)").

El idioma elegido se aplica a todo: narración, texto en pantalla, introducción, resumen, etiquetas como "echa un vistazo", instrucciones de entrega TTS. También determina qué modelos TTS califican y cómo se calculan el presupuesto de palabras y el costo – por eso va primero.

Si el idioma del video difiere del idioma de las diapositivas, aplica las reglas de traducción en references/didactics-and-script.md (los términos técnicos de la conferencia permanecen visibles, porque el examen los usa). Para "otro idioma" en modo narrado: primero verifica brevemente si algún modelo TTS lo soporta bien; si no, dilo abiertamente y ofrece alternativas (incluyendo solo visual).

Paso 2 – Duración, modelo, datos clave, índice, cuestionario (un mensaje)

Solo después de las respuestas al paso 1. En modo solo visual, salta b) (modelo) y no cotices costos; entonces no hay paso 4 (voz).

Si los materiales son un ejercicio, dilo en una línea al inicio de este mensaje ("Estas son una hoja de ejercicios con 4 tareas – las resuelvo todas paso a paso en el video.") – sin pregunta extra; las sugerencias de duración cuentan entonces tareas, no páginas (≈ 45–90 s por tarea según tamaño).

a) Duración del video. Sugiere duraciones que se ajusten al tipo de video del paso 1, derivadas del número de páginas de contenido (n): estimate.py lengths --content-pages n --type short|comprehensive

Tipo de video	Opciones (regla general)	Ejemplo, 30 páginas
Resumen breve	muy breve n × 4 s · breve n × 6 s (predeterminado)	~2 / ~3 min
Resumen completo	compacto n × 10 s · estándar n × 14 s (predeterminado) · detallado n × 18 s	~5 / ~7 / ~9 min

Redondea a medias minutos. Para "completo", advierte en una frase si el usuario elige una duración por debajo de n × 8 s: todos los temas aún se cubren, pero muy brevemente. El usuario decide; siempre se permite una duración personalizada.

b) Modelo TTS incl. precio para este video exactamente (solo modo narrado). El procedimiento y la fórmula de costo están en references/tts-models.md – léelo antes de preguntar. Versión corta:

• Obtén los modelos TTS actuales en vivo a través de OpenRouter MCP (list-models con output_modalities: "speech", ordenados por precio). Los precios y modelos cambian – nunca respondas de memoria.
• Filtra a modelos que soporten el idioma del video elegido.
• Ofrece 3–4 modelos, el mejor barato primero (preferiblemente una variante de Google Gemini Flash TTS), cada uno con el precio estimado para la duración elegida – calcula con scripts/estimate.py.
• Si la duración aún no está decidida: da precios para las tres opciones de duración.
• La elección es vinculante. Cuando el usuario elige un modelo de OpenRouter, ese modelo exacto (el mismo ID de modelo, a través de OpenRouter MCP) DEBE usarse para cada archivo de audio de este video – ver "Elección de modelo vinculante" en la Fase 4.

c) Datos clave faltantes. Solo si no se encontraron en la Fase 0: nombre del profesor, nombre del curso. Ofrece "sin nombre" como opción en lugar de adivinar.

d) Opcional: ¿mostrar imágenes/gráficos de las diapositivas del PDF directamente? (predeterminado: sí, donde expliquen algo).

e) ¿Índice al inicio del video? Sí / No. Una frase de explicación: justo después de la introducción, una tabla de contenidos breve muestra cada capítulo con su rango de tiempo ("0:18–1:30 Inner Join") y números de diapositiva, para que los alumnos puedan ver la estructura y saltar a lo que necesitan. Cuesta unos 10 segundos. El MP4 siempre tiene también marcas de capítulo, por lo que los reproductores pueden saltar entre capítulos de cualquier manera.

f) ¿Preguntas de autoevaluación al final? Sí / No. Una frase de explicación: preguntas para autoevaluarse con una breve pausa de pensamiento seguida de la respuesta – ayuda a la memoria más que volver a ver.

Paso 3 – El aspecto (+ número de preguntas)

Un mensaje con dos preguntas sobre el aspecto – y, solo si se eligieron preguntas de autoevaluación en el paso 2 f), una tercera sobre su número (como preguntas seleccionables si dicha herramienta está disponible; los valores predeterminados se nombran primero):

¿Claro u oscuro?

• Claro (Estándar) · Oscuro

¿Qué estilo?

• Moderno (Estándar) – acentos de color, degradados suaves, tarjetas con sombras, tarjetas de título de capítulo
• Sobrio – tranquilo, mucho blanco o negro, solo un color de acento
• Como las diapositivas – colores de las diapositivas de la conferencia (por ejemplo, azul universitario), para que combine con la conferencia
• Adecuado al tema: … – una propuesta concreta derivada del contenido, por ejemplo "Aspecto base de datos: azul/turquesa con cuadrícula de tabla discreta", "Sostenibilidad: tonos verdes con motivo de hoja", "Finanzas: azul oscuro/dorado con líneas de gráfico"

¿Cuántas preguntas de autoevaluación? (solo si se eligió)

• 3 · 5 · 8 · número propio – cada una con duración y costo adicionales (ver más abajo)

Escribe la opción "tema" como una sugerencia concreta para esta conferencia, no como una etiqueta genérica. Salta "Como las diapositivas" si scripts/palette.py no encuentra colores distintivos (diapositivas simples en blanco/negro). Cómo se construye cada respuesta: references/visual-rules.md, "Aspecto".

Número de preguntas: opciones 3 / 5 / 8 / personalizado. Para cada opción, da la duración adicional y el costo adicional (estimate.py quiz --questions N --prompt … --completion …; para el total incluyendo índice: estimate.py cost … --quiz N --toc), por ejemplo "5 preguntas · +1:45 min · +$0.02". Las preguntas se añaden además de la duración elegida de la parte explicativa; indica la nueva duración total una vez. Si los materiales tienen menos puntos clave significativos que las preguntas solicitadas, ofrece menos y dilo brevemente.

Paso 4 – La voz (solo modo narrado)

Después de elegir el modelo, haz tres preguntas cortas en un mensaje (tres preguntas seleccionables si dicha herramienta está disponible); los valores predeterminados están preseleccionados y se nombran primero:

¿Cómo debería sonar la voz?

• Femenina (Estándar) · Masculina

¿Qué carácter?

• Motivadora y amigable (Estándar) · Tranquila y objetiva · Firme y clara · Relajada y desenfadada

¿Qué velocidad?

• Tranquila · Normal · Ágil (Estándar) · Rápida

Valor predeterminado cuando el usuario omite o dice "da igual": una buena voz femenina, ágil, motivadora y explicativa. Mapea las respuestas a una voz concreta del modelo elegido y a instrucciones de entrega/velocidad con references/tts-models.md ("Elección de voz"); nombra la voz que elegiste en una línea corta ("Voz: Laomedeia – femenina, motivadora, ágil"). El ritmo cambia el presupuesto de palabras: pásalo a estimate.py --pace. Después de la prueba de introducción (Fase 4), el usuario aún puede decir "otra voz" o "más lento" – entonces rehaz solo la introducción.

Fase 2 – Guion

Lee references/didactics-and-script.md. Luego escribe el guion como script.json (esquema allí), escena por escena. Estructura requerida:

1. Introducción (≈ 8–12 s): "Este video trata sobre … del curso … del profesor …" + una visión general de lo que viene en 3–5 puntos (organizador previo). Índice (solo si se eligió, ≈ 10 s): una escena directamente después de la introducción con <ol class="toc" data-toc>. El archivo de escena completa automáticamente cada capítulo con su rango de tiempo y diapositivas desde el tiempo final – nunca escribas horas a mano, cambian con cada regeneración de audio. La narración nombra los capítulos en una o dos frases ("Primero …, luego …, y al final un resumen y una autoevaluación") y no lee los tiempos. Marca la escena data-dense con data-hold ≈ 3 s para que el índice se pueda leer. Cuando se elige un índice, la agenda de la propia introducción puede ser más corta (una frase) para que no se diga nada dos veces.
2. Parte principal: capítulos en el orden de la conferencia. Explicación

…

[truncado para la traducción]