Lecciones en vídeo (Lesson Film)

Películas de lección

Una película de lección enseña un mecanismo lo suficientemente bien como para que un recién llegado pueda explicarlo después de verla una vez. Cada imagen está dibujada mediante código, la voz del narrador es el reloj, y la música suena en los huecos que deja la voz. Se sitúa sobre code-film: esa habilidad posee el aspecto, la galería, el gusto y las comprobaciones de defectos. Esta habilidad posee la enseñanza, las palabras, la voz, el ritmo, el final y el lado de YouTube.

El ejemplo práctico es examples/parcel42-lesson/, una lección de 130 s sobre cómo las operaciones upsert de Apache Pinot ocultan filas antiguas. Kartik, el autor de la habilidad, la calificó de "perfecta" tras ocho versiones, y cada nota en el camino vive en el archivo de referencia que la posee. Lee su README para el método, nunca el aspecto.

El núcleo: sigue al espectador

Una película de lección es la mitad de una conversación, y el espectador proporciona la otra mitad en silencio. En cada segundo tienen tres cosas:

• Lo que saben. Solo lo que la película ha mostrado y dicho hasta ahora, más el conocimiento cotidiano. No el código fuente, ni lo que leíste para hacerla.
• Lo que preguntan. Cada imagen y cada afirmación plantea la siguiente pregunta: "¿entonces qué le pasa a la anterior?", "¿y si llega tarde?", "¿eso no desperdicia espacio?"
• Lo que creen. Un modelo del mecanismo construido solo a partir de la película. Una palabra incorrecta instala un modelo equivocado. "Pinot nunca derriba la casa vieja" enseñó que nunca se elimina nada, y luego la película mostró la compactación eliminándolo.

Hacer la película es ejecutar ese modelo segundo a segundo, a través de la voz y la imagen juntos:

1. Responde la pregunta donde la tienen. La carta tardía llega justo después de la regla, y "¿Y las casas oscuras?" justo después de la consulta.
2. Déjalos llegar antes de anunciar. La imagen muestra la evidencia un instante antes de que la voz la nombre. Un título, una etiqueta o un nombre de capítulo nunca dan la respuesta antes de que se haya formulado la pregunta.
3. Nunca cortes el hilo. Una línea que promete algo posee la siguiente imagen. Después de "dos interruptores cambian", lo siguiente en pantalla son los interruptores.
4. Entrega cada palabra antes de gastarla. Cada término en pantalla se dice en voz alta una vez, donde la imagen lo muestra, y ninguno llega a la primera línea. Primero viene la cosa en el mundo, y el término se nombra después. Fuera de esa línea de nombre, una oración permanece en un mundo: una flor ha dejado de crecer, nunca está "cerrada". Una película entera mostró "segmento 7" en señales de tráfico sin decir nunca segmento.
5. Enseña el mecanismo, no el código. Muestra un nombre real solo cuando el espectador lo buscaría (validDocIds), nunca un nombre de función que solo etiqueta maquinaria.

Cada regla en las referencias es una de estas cinco aplicada. Cuando una regla parece entrar en conflicto con otra, o nada cubre un caso, ejecuta el modelo del espectador y él decide.

Una nota nunca trata sobre una instancia. Cuando la persona para la que haces la película señala un momento, está señalando un lugar donde el modelo se rompió. Encuentra todos los demás lugares donde se rompió de la misma manera, arréglalos todos y reporta el recuento. El "golpe doloroso" de Kartik fueron los rellenos y también los tintineos y chasquidos. Sus letras faltantes eran cualquier evento temporizado desde un fotograma fijo, por lo que existe shiftcheck.py. Su "frase incorrecta" era cada palabra absoluta, por lo que existe scriptcheck.py para listarlas.

Configuración

Esta habilidad necesita code-film instalado junto a ella, en la misma carpeta de habilidades. Su construcción, puerta, captura, costuras y comprobaciones de sonido y su escritura a mano provienen todas de ahí, y cada script lo encuentra ahí o en $CODE_FILM.

Ejecuta bash assets/setup.sh una vez. Comprueba el doctor de code-film, luego construye un entorno virtual Python 3.12 en ~/.cache/lesson-film/venv con Kokoro, soundfile, faster-whisper y el modelo de inglés de spaCy, y verifica que ffmpeg tenga loudnorm.

Cómo se ve el éxito

• Un recién llegado puede repetirlo. Sus dos oraciones coinciden con la línea de conclusión de la tarjeta de intención, con los términos reales en los lugares correctos.
• Suena como una persona explicándotelo a ti. Cada oración lleva a la siguiente, y cada cambio de escena arrastra la pregunta viva. Lee el guion en voz alta sin las imágenes. Si suena como una lista de etiquetas, no está terminado (reference/words.md).
• Respira. El espectador tiene tiempo para ver cada cambio antes del siguiente. Kartik encontró un corte de 64 s a 0.36 cortes por segundo "demasiado rápido". El corte aprobado dura 130 s a 0.16 cortes por segundo, con la voz a velocidad normal y respiraciones reales (reference/pace-and-ending.md).
• Cada afirmación es cierta y verificada. Escribe las afirmaciones en facts.md contra la fuente antes de cualquier dibujo. La imagen muestra exactamente ese estado.
• La imagen cambia con la palabra. Cada cosa aparece en el momento en que la voz la nombra. El movimiento y el color se centran solo en la parte que se está explicando (reference/teaching.md).
• Comienza suavemente y termina lentamente. Una primera línea que cualquiera pueda asimilar, con la imagen y la melodía ya en marcha, una apertura en frío que termina con la pregunta, luego un golpe de título de unos cinco segundos, como lo hace Kurzgesagt. "El comienzo se siente abrupto" fue la nota de Kartik sobre una película que abría con un personaje que el espectador no había conocido (reference/pace-and-ending.md).
• Termina, no se detiene. Un resumen, una recompensa, una línea de cierre que responde a la apertura, el acorde final, luego la imagen y el sonido se desvanecen juntos durante varios segundos. "El final es abrupto" es la nota que nunca debes volver a recibir.
• Los defectos son cero. Sin destello, sin chasquido, sin recorte, volumen a -14 LUFS, cada palabra escuchada.

Estos son juicios, no reglas. Rompe una cuando la tarjeta diga por qué.

Flujo de trabajo

Copia esto en tus notas e informa cada línea a medida que la termines. Una línea no se puede marcar sin decir cómo.

[ ] 0 referencia  solo si compartieron una. Un clip, una imagen fija o una página HTML. Informa qué forma, qué hace, qué brechas se pueden cerrar y qué tomas y dejas.
[ ] 1 hechos      facts.md escrito contra la fuente. Informa las afirmaciones y dónde se verificó cada una.
[ ] 2 intención   assets/intent.md copiado a <pieza>.intent.md, conclusión, sentimiento, pregunta, suposición. Infórmalos.
[ ] 3 galería     reference/gallery.md de code-film, las dos o tres películas más cercanas. Informa qué tomas y qué no copiarás.
[ ] 4 bocetos     tres nuevas historias, cada una una imagen fija con aspecto terminado dibujada con el kit (sketch.py), una de ellas un mundo en el que podrías vivir, ninguna tomada del ejemplo o de una referencia compartida. sketchcheck.py limpio de BLOQUEOS, luego juzgado contra la hoja. Muéstralos. Informa la línea de cada historia, las tres respuestas de evaluación y la elección.
[ ] 5 palabras    el guion completo como un párrafo en <pieza>.chain.txt, luego cortado en líneas con sus "términos", "cosas" y "tecnología". Antes del párrafo, escribe la cosa de cada término y el verbo del mundo para cada estado real que tiene. scriptcheck.py limpio de BLOQUEOS. Informa ese mapa, el guion leído en voz alta una vez, cada bisagra y una decisión sobre cada REVISIÓN.
[ ] 6 voz         <pieza>.lines.json -> voice.py -> heard.py --write. Informa la duración y cada palabra escuchada o por qué no.
[ ] 7 plan        escenas, cada una vinculada a las palabras que la cambian y al estado del mundo que comparten. Informa el plan, con la cosa en el mundo que muestra cada término y el verbo del mundo para cada estado real.
[ ] 8 construcción página desde assets/template/. Escenas comprobadas solas en borrador primero. Informa qué redibujaste después de mirar.
[ ] 9 sonido      <pieza>.score.py desde assets/score_template.py. Informa los acordes, la melodía en los huecos y los sonidos del mundo.
[ ] 10 renderizado assets/build.sh. DRAFT=1 primero. Informa los números.
[ ] 11 verificación las tres capas a continuación. Informa cada una.
[ ] 12 entrega    un nuevo archivo cada construcción, nunca sobrescribas. El máster para YouTube, una vista previa pequeña de menos de 30 MB para enviar.

Los pasos 1 a 5 son donde se ganan las lecciones. El paso 5 en particular: escribe el guion como prosa primero, luego córtalo en líneas. Cortar primero es cómo un guion se convierte en una pila de subtítulos.

Verificar

Informa las tres capas en la nota de entrega, por separado.

• Bloque de defectos. build.sh ejecuta scriptcheck.py (cada término dicho, ninguno en la primera línea, vínculos que existen) y check.py y seamcheck.py de code-film, masteriza a -14 LUFS integrado con pico verdadero a -1.5 dBTP, y codifica según las especificaciones de YouTube (reference/youtube.md).
• La lección se mide. verify.py comprueba la duración, el ritmo y el sonido de la tarjeta. heard.py transcribe la voz y dice qué palabras no se escucharon y cuánto se retrasa el sonido con respecto a los tiempos de referencia. wordsync.py comprueba que el movimiento aumenta en cada palabra a la que está vinculada la imagen. shiftcheck.py renderiza la película con la voz desplazada dos segundos después y falla en cualquier escena que cambie, que es cómo aparece un evento temporizado desde un fotograma fijo. captions.py escribe un SRT exacto a partir de las mismas referencias.
• La prueba de visualización es tuya, luego de la persona. Vuelve a contarla como un recién llegado. Nombra cada mosaico de la hoja de contactos. Mírala sin sonido. Lee el guion en voz alta sin imágenes. Juzga los últimos diez segundos por sí solos. Luego di claramente lo que no comprobaste, como la voz de oído.

Cuándo leer qué

Lee cada archivo completo, con una llamada por archivo, y vuelve a leer un archivo por sí solo si la lectura dice que los tokens se truncaron. "Cuándo leer qué" de code-film dice lo que cuesta una lectura por lotes.

• Cuando compartan una referencia, lee reference/references.md de code-film. Cubre las tres formas. Un clip y una imagen fija se desarman con ffmpeg. Una página HTML, nuestra o suya, se procesa con assets/refpage.mjs de code-film, que observa cómo se dibuja la página e informa su paleta, marcas, capas y kit de audio, y escribe un MP4 para que las comprobaciones de clip también se ejecuten en él.
• Antes de los hechos y la tarjeta de intención, lee reference/teaching.md.
• Antes de los bocetos, lee reference/sketches.md de esta habilidad y la sección de Historia de su propio reference/traps.md. Luego lee reference/story.md de code-film para "Elige una forma primero" y "Qué persiste", y reference/traps-story.md de code-film.
• Antes de escribir una sola línea del guion, lee reference/words.md.
• Cuando planifiques la apertura o el final, y cuando establezcas la velocidad de la voz, las pausas y las respiraciones, lee reference/pace-and-ending.md.
• Cuando hagas o arregles la voz, lee reference/voice.md.
• Cuando planifiques escenas, las dividas entre ayudantes o construyas la página, lee reference/film.md, y reference/moves.md de code-film, que posee los movimientos entre dos imágenes.
• Cuando hagas el sonido, lee reference/sound.md, y reference/sound.md de code-film para los instrumentos y su reference/traps-sound.md.
• Antes del primer renderizado y después de cualquier nota sobre uno, lee reference/traps.md.
• Antes de publicar, lee reference/youtube.md.
• Cuando una regla necesite su fuente, o alguien pregunte por qué la habilidad hace algo, lee reference/research.md: la evidencia, los tamaños del efecto y los enlaces.
• Para el aspecto, el gusto y el acabado de impresión, lee gallery.md, taste.md y press.md de code-film, y su traps-print.md antes de ajustar el acabado.

Los archivos

archivo	qué es
assets/setup.sh	configuración única: el entorno virtual de voz y audición, y las comprobaciones
assets/intent.md	la tarjeta de intención de la lección, la tarjeta de code-film más las líneas de enseñanza
assets/voice.py	habla <pieza>.lines.json con Kokoro, coloca las líneas en una cuadrícula de ritmo, escribe la voz y las referencias
assets/heard.py	transcribe la voz con Whisper, informa las palabras faltantes y el retraso, --write almacena el retraso en las referencias
assets/saytest.py	prueba las reescrituras de una palabra que Kokoro dice mal, y dice cuál Whisper escucha bien
assets/captions.py, assets/wordsync.py	el SRT a partir de las referencias, y la comprobación de que el movimiento aumenta en cada palabra vinculada
assets/shiftcheck.py	la comprobación de que cada escena está temporizada desde la voz, no desde fotogramas fijos
assets/scriptcheck.py	la comprobación del guion: términos dichos, ninguno en la primera línea, la cosa de cada término dicha antes del término, vínculos que existen, y una lista de palabras absolutas, palabras en pantalla no dichas y oraciones que mezclan el mundo con el sistema real para leer
assets/sketchcheck.py, assets/barsheet.py	la comprobación de bocetos de code-film, ejecutada con los fotogramas aprobados de esta habilidad, la ciudad del ejemplo y el stub de la plantilla. Y el script que reconstruye la hoja de evaluación
assets/score_template.py	una cama por línea, la melodía en los huecos, sonidos del mundo en cambios de estado, una reducción de 16 dB bajo el habla, el outro que se desvanece
assets/build.sh	página, puerta, captura en paralelo, costuras, partitura, máster -14 LUFS, codificación, subtítulos, hoja de contactos, cada comprobación
assets/template/	la página para copiar: assemble.py, film/kit.js (la artesanía sin mundo en ella: tinta, puntos, bordes, luz, escritura a mano, el acabado de impresión), film/core.js (reloj de voz, capas, cámara, movimientos de inmersión e iris), film/main.js, film/SCENES.md, una escena de ejemplo que construye un objeto provisional, y sketch.py con sketches/sketch.js para las tres imágenes fijas de la historia
reference/stills/	fotogramas de la lección aprobada, subtitulados, para las dos reglas que la prosa por sí sola no logra: los tiempos de apertura y final, y una imagen que cambia con su palabra. También la hoja de evaluación de bocetos sketch-bar.jpg, abierta solo después de que existan tus tres propios bocetos, y sent-back.jpg
examples/parcel42-lesson/	la fuente completa de la lección aprobada, su pista de voz, un enlace a una vista previa de la película para ver, su README, hoja de contactos y miniaturas

La captura en paralelo vive en code-film (assets/capture-range.mjs, assets/capture-par.sh), porque cualquier película larga la necesita.

Cambiar esta habilidad

Declara la intención y el juicio, y verifica el resultado contra la intención. Una nueva lección que alguien aprueba se convierte en un segundo ejemplo, con una línea en este archivo sobre por qué funciona. Una lección aprendida va al archivo de referencia que la posee, y cada otro archivo apunta allí en una línea.