JustinChenzeting/Lecture-notes-to-videos

Apuntes de clase → video de clase narrado

Escribes exactamente un archivo: un lecture.tex de beamer que contiene las diapositivas, diagramas y narración juntos. Los scripts incluidos hacen todo lo demás (instalación, LaTeX → páginas PNG → texto a voz → ffmpeg → MP4), por lo que el costo es aproximadamente una respuesta larga por clase, y las ediciones posteriores re-sintetizan solo las líneas que cambiaron.

Inicio rápido: el pipeline completo

Cada paso es un comando: python3 <directorio-habilidad>/scripts/lv.py <comando>, donde <directorio-habilidad> es la ruta absoluta de la carpeta que contiene este archivo (en Windows usa py -3 en lugar de python3). A continuación, lv es una abreviatura de todo ese comando; escríbelo completo cada vez, porque las variables de shell generalmente no persisten entre tus comandos.

lv setup                           # 0. instalación única; dale un tiempo de espera de 10 minutos o ejecútalo en segundo plano
lv init FISICA101-L05              # 1. imprime la carpeta de trabajo (WORK) y copia la plantilla en ella
lv ingest apuntes.pdf --out WORK   #    cualquier combinación de .pdf .png .jpg .heic .md .txt; varios archivos están bien
#                                       lee los apuntes (§1), planifica (§2), escribe WORK/lecture.tex (§3-4)
lv check WORK/lecture.tex          # 2. compila + hojas de contacto numeradas + advertencias de diseño, sin audio
lv render WORK/lecture.tex         # 3. -> WORK/FISICA101-L05.mp4 (o proporciona una ruta de salida)

• El paso 0 instala todo (uv, un Python 3.12 privado, TinyTeX solo cuando no hay un LaTeX funcional, ffmpeg, voces Kokoro) en una caché por usuario: unos 3 minutos en una conexión rápida, hasta 10 en una lenta, sin necesidad de derechos de administrador. Es idempotente: cuando ya está hecho, termina en segundos, y si se interrumpe, ejecutarlo de nuevo lo reanuda. Dile al usuario que es una instalación única. Termina con una línea que comienza con [setup] READY; cualquier otro final es un error con una solución en el mensaje o en references/troubleshooting.md. lv doctor muestra lo que está instalado sin cambiar nada. Los otros comandos también ejecutan la configuración si falta.
• Ejecuta el pipeline de principio a fin sin pedir confirmación en cada paso. Detente solo ante bloqueos reales: apuntes que no puedas abrir o leer, un paso de configuración que necesite una contraseña de administrador, o una solicitud ambigua de una manera que cambie el video.
• WORK por defecto es ./lecture-videos/<nombre> (o el work_root configurado por el usuario). Pon el MP4 donde el usuario lo pidió; de lo contrario, el valor predeterminado en WORK está bien. Conserva WORK: el .tex, la transcripción y la caché de audio hacen que las ediciones posteriores sean económicas.

1. Lee los apuntes tú mismo primero

ingest escribe WORK/source.txt (páginas con una capa de texto), WORK/manifest.tsv (cómo se leyó cada página), imágenes a tamaño completo de las páginas que necesitan revisión visual (WORK/pages/), y hojas de vistazo (WORK/glance-*.jpg, seis páginas cada una).

• Mira cada hoja de vistazo. Capturan anotaciones al margen, pasajes resaltados y figuras que la extracción de texto pasa por alto, aproximadamente por el costo de tokens de una página completa por hoja. Si una hoja muestra escritura a mano o anotaciones en una página mecanografiada, vuelve a ejecutar con --visual 3,7-9 para obtener esas páginas a tamaño completo.
• Páginas escritas a mano o escaneadas ([handwritten/scanned], [image]) deben leerse a tamaño completo: abre cada una de esas imágenes y escribe WORK/transcript.md con el contenido en orden, ecuaciones en LaTeX, y una descripción de una línea de cada figura (ejes, etiquetas, números clave). Marca cualquier cosa ilegible como [illegible] en lugar de inventarla. Los apuntes manuscritos suelen ser los apuntes de clase del propio usuario, así que trátalos como la fuente principal. Si no puedes ver imágenes, dilo y pide una versión mecanografiada en lugar de adivinar.
• Páginas mecanografiadas con figuras ([has figure]): abre la imagen a tamaño completo solo cuando necesites un valor o etiqueta que no puedas leer en la hoja de vistazo.
• A partir de ahí, planifica solo con source.txt + transcript.md; no vuelvas a leer imágenes.
• Apuntes .docx, .pptx o .key: expórtalos a PDF primero (por ejemplo, con LibreOffice soffice --headless --convert-to pdf), luego ingiere el PDF.

Mientras lees, anota errores o inconsistencias en los apuntes (erratas en números, etiquetas intercambiadas). Usa el valor correcto en el video y enumera cada corrección en tu informe final.

1b. Rellena las lagunas de fuentes confiables

Los apuntes suelen ser escuetos: un paso de derivación omitido, un término usado antes de definirlo, una figura sin explicación. Cuando algo confundiría a un estudiante y tienes acceso a la web, busca brevemente (2-5 consultas específicas, no una revisión bibliográfica) una explicación clara al nivel adecuado: apuntes de cursos universitarios y OCW, LibreTexts, libros de texto estándar, artículos de revisión para puntos de nivel de posgrado. Prefiere fuentes que coincidan con la notación de los apuntes; cuando entren en conflicto, sigue los apuntes y menciona la diferencia. Mantén las adiciones breves y al servicio del contenido de los apuntes, planteadas primero para estudiantes de pregrado con un comentario opcional de posgrado, y enumera las fuentes que usaste en el informe final. No añadas temas que la clase no cubre.

2. Planifica antes de escribir (en tu cabeza o en unas pocas líneas)

• Duración: apunta a unos 10 minutos (9-11) a menos que el usuario dé otra duración. La profundidad supera a la cobertura: si los apuntes contienen más de lo que se puede explicar en 10 minutos sin saltar pasos, cubre el núcleo a fondo, luego dile al usuario lo que se omitió y ofrécele una parte 2. Calcula la narración a ≈ 155 palabras por minuto de la duración objetivo, menos 15 s por punto de control (la voz por defecto habla ~165 ppm; las pausas entre líneas usan el resto). Un video de 10 minutos ≈ 1.350 palabras + 4 puntos de control (medido: 1.481 palabras + 4 puntos de control = 9,9 min).
• Arco: título → motivación → conceptos en el orden de los apuntes → ejemplo(s) resuelto(s) → resumen. Una idea por diapositiva, 1-5 pasos de superposición por diapositiva, ~40-70 páginas en total.
• Cadena lógica: enumera la cadena de razonamiento como pasos numerados (qué se asume, qué sigue y por qué). Cada derivación va desde su principio inicial hasta el resultado sin pasos saltados: cada movimiento de álgebra tiene su propia línea, cada suposición se establece donde se usa y cada símbolo nuevo se define antes de que aparezca. Si los apuntes saltan ("puede demostrarse que…"), llena el vacío (§1b). Un estudiante nunca debería tener que preguntarse "¿de dónde salió eso?".
• Los elementos visuales transmiten la clase: planifica la imagen antes que las palabras. Cada diapositiva de concepto necesita un elemento visual: un diagrama, gráfico o modelo físico (átomos, una red, una imagen de tanque y tubería de un balance de masa, una palanca para la regla de la palanca). Muestra qué representan físicamente los símbolos, no solo las ecuaciones. Redibuja cada figura como TikZ/pgfplots original (nunca pegues las imágenes del documento original). Construye los diagramas paso a paso con superposiciones y usa 3-6 animaciones cortas donde el movimiento sea el punto (una ruta de enfriamiento, una línea de atadura que se mueve, una dislocación que se desliza). Patrones: references/visual-cookbook.md.

Cómo explicar (esto es lo que hace que valga la pena ver el video)

• Habla como un buen tutor, no como un libro de texto. Lenguaje cotidiano ("básicamente", "aquí está el truco", "piensa en ello como…"), frases cortas y el por qué antes del qué. Anticípate a la confusión ("esto parece al revés al principio, y aquí está por qué no lo es").
• Explica cada ecuación importante dos veces:
  1. Matemáticamente: de dónde viene, paso a paso, y qué es cada término.
  2. Físicamente / intuitivamente: qué significa en el sistema real, con una analogía o un caso límite ("si c está justo en c′, la aleación es todo líquido, y la fórmula da exactamente eso"). Pon ambos en pantalla: las líneas de matemáticas, luego una nota de una línea "físicamente:" o una imagen.
• Después de cada derivación, haz una comprobación de cordura rápida en voz alta: unidades, un caso límite o un número del diagrama.
• Puntos de control: 3-5 por cada 10 minutos, colocados justo después del concepto que evalúan (§4).

3. Escribe WORK/lecture.tex

init ya copió assets/template.tex en WORK/lecture.tex; muestra cada construcción. Reemplaza sus diapositivas de ejemplo con la clase. Reglas que importan:

• \usepackage{lecturevideo} carga el tema (papel marfil, tinta oscura, un acento rojo, o la marca personalizada del usuario si está configurada), la paleta (accent, ink, mute, blu, grn, gold), los estilos de figuras (eje pd, dot, lab, note, tie, atom, atomA, atomB) y los comandos de narración. No cambies el estilo del tema dentro de la clase.
• Narración: \say<n>{...}, uno por página de superposición n, colocado en la parte superior de la diapositiva. \say<2-13>{...} narra un intervalo de animación. \wait<n>{2} mantiene una página en silencio. Cada página necesita uno; el renderizador nombra cualquier página que falte.
• El texto hablado es inglés sencillo: números y símbolos como palabras ("cuarenta y seis por ciento", "T tres", "setecientos setenta y nueve grados", "alfa más beta"). Sin LaTeX y sin %, &, #, $ dentro de \say. Di qué mirar ("observa el punto", "nota la línea de atadura"), luego por qué importa. Amplía el texto de la diapositiva en lugar de leerlo palabra por palabra.
• Las diapositivas llevan una explicación real. Un espectador que pause, retroceda o repase desde el PDF debería poder seguir solo con las diapositivas. Junto a cada elemento visual, pon de 3 a 5 viñetas de hasta ~15 palabras cada una (hecho clave, condición, consecuencia, significado físico). Para las derivaciones, muestra cada paso como su propia línea con una breve razón al lado ("balance de masa en B", "dividir por W"), revelada a medida que la narración la alcanza, terminando con una línea "físicamente:" en el color de acento. Si una derivación necesita más de ~6 líneas, continúa en la siguiente diapositiva (repite la última línea en la parte superior) en lugar de apretujarlo.
• Diseño: elemento visual a un lado (aproximadamente el 55%), texto al otro (columns), o el elemento visual arriba y 2-3 líneas abajo. Académico y sin desorden: una idea por diapositiva, el color de acento solo para énfasis, resultados y marcadores de estado.
• Las macros de figuras que toman #1 van en el preámbulo (un # en el cuerpo de una diapositiva rompe beamer).
• Se puede usar cualquier paquete LaTeX que la clase necesite (siunitx, chemfig, …); cuando se usa TinyTeX privado, los paquetes faltantes se instalan automáticamente en la primera compilación.

4. Puntos de control tipo examen

\examq[5]{Punto de control: regla de la palanca}
  {pregunta en diapositiva}{pregunta hablada}{respuesta en diapositiva}{respuesta hablada}

Esto hace 1 página de pregunta (narrada, luego "Tienes 5 segundos."), 5 páginas de cuenta atrás de un segundo en silencio con un anillo que se encoge, y 1 página de respuesta narrada.

Escribe preguntas como un examen real sobre esta clase: números dados concretos, una tarea clara, que se pueda responder en ~30 s por alguien que haya seguido el video, con una respuesta resuelta breve. Mezcla tipos:

• Calcular: "Una aleación de 35 % en peso de B a T₃ con c′ = 20, c″ = 85: ¿qué fracción es líquida?"
• Leer el diagrama: "Una aleación de 20 % en peso de Ag está a 900 °C. ¿Qué fases y aproximadamente qué composiciones?"
• Predecir: "Una aleación de 5 % en peso de Ag se enfría lentamente de 800 °C a 500 °C. ¿Qué se forma y dónde?"
• Identificar / clasificar: "Líquido → α + β a una temperatura: ¿qué reacción invariante es esta?"
• Detectar el error: "Un estudiante usa c″ − c sobre la línea de atadura para la fracción sólida. ¿Qué salió mal?"

Evita indicaciones vagas ("¿qué es una fase?"), trivialidades no enseñadas en los apuntes y preguntas de varias partes. La respuesta debe mostrar el razonamiento paso a paso, no solo el resultado. Toma los números del diagrama o la ecuación que el video acaba de mostrar, para que la pregunta, la figura y la respuesta coincidan. Las preguntas basadas en un concepto erróneo común funcionan bien ("duplicar la separación de los pines duplica la tensión de la fuente: ¿verdadero o falso?"). Mantén la cuenta atrás de 5 segundos (la diapositiva dice "pausa si necesitas más tiempo"); usa \examq[8] solo si el usuario pide pausas más largas.

5. Verifica, luego renderiza

lv check WORK/lecture.tex

Compila, imprime páginas, palabras narradas, una duración estimada y advertencias de layout: (contenido demasiado alto o líneas demasiado anchas, con números de línea de origen), y escribe hojas de contacto numeradas WORK/lecture_build/sheet-*.png. Mira las hojas para detectar colisiones, etiquetas cortadas, marcadores fuera de la curva o diapositivas vacías; corrígelas y vuelve a ejecutar (económico). Si no puedes ver imágenes, corrige cada advertencia de layout: y mantén las figuras simples. Si la estimación se desvía de la duración objetivo en más de ~10%, recorta o extiende la narración ahora (no los puntos de control). Luego:

lv render WORK/lecture.tex ["OUT/Título de la clase.mp4"]

Narrador: voz neural de Microsoft Edge en-GB-SoniaNeural (gratuita, necesita internet) a +10%, 720p. Sin conexión o si Edge falla, vuelve automáticamente a la voz Kokoro incluida bf_emma. Opciones: --tts edge|kokoro|say, --voice <id o perfil>, --rate, --height. Cuando el usuario nombre una voz o quiera la suya propia (incluyendo una voz clonada), lee references/voices.md.

Los subtítulos vienen gratis. Cada renderizado también escribe OUT.srt y OUT.vtt junto al MP4 e incrusta una pista de subtítulos seleccionable, construida a partir del texto \say y sincronizada con el audio sintetizado, por lo que no cuestan tokens y se mantienen sincronizados después de las ediciones. Nunca transcribas el video ni escribas subtítulos a mano. Muestran la narración tal como está escrita (antes de las reescrituras de lexicon.tsv). --no-subs los desactiva.

Las correcciones de pronunciación van en WORK/lexicon.tsv (escrito<TAB>hablado), aplicadas solo al audio. Volver a renderizar después de una edición toma segundos, porque las líneas sin cambios provienen de la caché de audio.

6. Informa

Proporciona la ruta del video (y sus subtítulos .srt/.vtt), la duración, el recuento de páginas y puntos de control, cualquier corrección a los apuntes, las fuentes utilizadas para llenar las lagunas, qué figuras son redibujos esquemáticos y qué se omitió (ofrece una parte 2). Conserva WORK para ediciones.

Configuración personal

La marca (logotipo, colores, un tema beamer de una institución), la voz predeterminada, las carpetas de trabajo y salida residen fuera de la habilidad, en la carpeta de configuración del usuario, por lo que la habilidad se mantiene portátil: references/customization.md. Nunca edites los activos propios de la habilidad para las preferencias de un usuario.

Por qué está construido así

• Un archivo fuente mantiene las diapositivas y la narración alineadas; LaTeX escribe el mapa de narración preciso por página (.narr) por sí mismo

…

[truncado para la traducción]