Antonod1988/code-explainer-film

Película en código

La película es un programa. Cada fotograma es una función pura del tiempo, dibujado por el código que escribes, y la voz, la música y cada sonido provienen también del código. No interviene ningún generador de imágenes o video. Así, cualquier segundo se puede cambiar y renderizar de nuevo, y otro idioma es una re-ejecución, no una nueva edición.

Este pipeline produjo una película de 5:16 en ruso e inglés: 16 compases, 57 señales, diez inserciones 3D, aproximadamente de 1.5 a 2 horas desde el guion hasta el primer idioma, y de 14 a 16 minutos de renderizado por idioma en un portátil. El código de esa película está en assets/examples/court-astronomer/.

La idea clave: la voz primero

Escribe el guion con marcadores. Deja que el servicio de voz lo recite e informe la hora de cada palabra. Un marcador se convierte entonces en un segundo absoluto, y tanto la imagen como el sonido dependen de esos segundos.

Придворные астрономы {plant}поставили её на карту и {cut}записали дату.

CUE.plant = 9.21    la mano coloca la estrella: golpe seco, chispas
CUE.cut   = 10.50   corte a la escritura, la pluma empieza a escribir

Cada idioma obtiene su propia línea de tiempo a partir de su propia grabación, así que una película en ruso y otra en inglés se editan de manera diferente sin trabajo adicional, y una frase reescrita desplaza todo lo que viene después. Por eso el orden es: guion, voz, imagen, sonido, y nunca imagen primero.

script/script.json ─ tools/tts.py ─> audio/voice/<lang>/  +  web/timing_<lang>.js
                                                                   │
                         ┌─────────────────────────────────────────┴───────┐
                  web/film.js + shots + space.js                    audio/score.py
                         │ render.py                                       │
                  renders/film_<lang>/film_<lang>.mp4               audio/mix/<lang>.wav
                         └───────────────── tools/finish_film.py ──────────┘
                                 final/<stem>.mp4, -phone.mp4, .srt

Iniciar un proyecto

python <this-skill>/scripts/check_env.py
python <this-skill>/scripts/new_project.py <carpeta>

Coloca el proyecto en una unidad con espacio, en una carpeta con el nombre de la película, en una ruta corta. Los fotogramas se transmiten al codificador y nunca se almacenan, así que una película de 5 minutos necesita aproximadamente 1 GiB.

El nuevo proyecto es una demostración funcional de 25 segundos sobre las fases de la Luna, en dos idiomas. Ejecuta los comandos que imprime new_project.py y mira la hoja de contactos antes de cambiar nada: si la demo funciona, cada fallo posterior es tuyo y no de la máquina.

Estado de la plantilla. El pipeline produjo la película real, pero esta plantilla se extrajo de ella después. En la demo, se han ejecutado tts.py, la mezcla y las comprobaciones de sonido. Las herramientas de entrega se han ejecutado sobre un clip negro, render.py sobre páginas simuladas, y la lógica de imagen plana sobre cada fotograma contra un lienzo simulado en ambos idiomas. La plantilla nunca ha dibujado un fotograma real, y su toma 3D nunca se ha ejecutado. Por lo tanto, las primeras imágenes fijas son también la prueba de la plantilla: si fallan, compara con assets/examples/court-astronomer/, que es el código que sí renderizó.

Luego reemplaza el contenido y conserva la maquinaria:

Reemplazar por cada película	Normalmente dejar igual
script/script.json	tools/
web/shots.js (tomas planas)	render.py, server.py
web/film.js: SHOT y SEQ	web/main.js, web/lib.js, web/labels.js
web/space.js: los constructores	web/space.js: el kit sobre ellos
audio/score.py	audio/mixlib.py, audio/synth.py

Flujo de trabajo

Ejecuta comandos que tomen más de dos minutos en segundo plano. Si la máquina tiene una cola de trabajos o una regla térmica (consulta las notas del proyecto y la memoria), ejecuta los renders a través de ella.

1. Definir la solicitud

Pregunta solo aquello que no puedas asumir: el tema, los idiomas, dónde se publicará. Por defecto: 1920x1080, 24 fps, -15 LUFS, una duración que se derive del guion. Construye una película preliminar completa antes de pulir cualquier parte. La gente juzga mucho mejor una película entera que diez segundos perfectos, y a menudo dicen directamente que la máxima calidad puede esperar.

2. Leer la referencia, si la hay

Mídela en lugar de adivinar: cortes, ritmo, paleta, frecuencia con la que se actualiza el personaje, grosor de línea, grano. Puedes hacerlo fotograma a fotograma en un navegador sin descargar el video. Lee references/reference-analysis.md. Anota los números como una breve hoja de estilo en el README del proyecto.

Toma la técnica y deja el contenido. Inventa tu propio personaje, historia y diseños. No reutilices fotogramas, personajes, logotipos o una melodía reconocible de la referencia, y no recrees una obra específica ni siquiera con un nombre nuevo.

3. Haz una prueba de 10 segundos

Una toma con el aspecto final, en silencio. Los tiempos codificados son aceptables aquí porque esto solo prueba el aspecto. Envíalo al usuario. Este es el momento más barato de todo el proyecto para cambiar de dirección.

4. Recopilar datos, escribir el guion

Lee references/script-and-voice.md. Divide la película en compases de 10 a 35 segundos, cada uno una idea y generalmente una toma. Presupuesto de palabras: aproximadamente 125 por minuto en ruso y 150 en inglés, incluidas las pausas. Coloca señales en las palabras donde deba ocurrir algo en pantalla.

Mantén los hechos exactos y la interpretación visiblemente separados, en la película y no solo en tus notas. Si calculas algo, guarda los datos en un archivo que la película lea, para que lo que aparece en pantalla sea lo que dicen los datos.

Muestra el guion al usuario si el tema es delicado o si pidió aprobarlo. De lo contrario, continúa y deja que reaccione a la película.

5. Voz, luego línea de tiempo

python tools/tts.py

Imprime cada señal como nombre=palabra@segundos. Lee esas líneas: detectar una señal en la palabra equivocada es mucho más barato aquí. Verifica el total contra el objetivo. Si se alarga, corta texto; no aceleres la voz más de aproximadamente un +10%.

6. Escribir las tomas

Lee references/picture.md. Todo en pantalla es una función de (g, t) y cada vez se deriva de CUE o BEAT. Las tomas planas dibujan con el kit de Canvas; las tomas 3D se renderizan a través del compositor en el mismo lienzo 2D. Un paso de grano al final de cada fotograma y un conjunto de etiquetas hacen que ambos se lean como una sola película.

7. Mirar imágenes fijas, corregir, repetir

python render.py renders/check "lang=ru&times=25,66,241,273"
python tools/contact.py renders/check 4

Lee references/review-and-render.md para saber cómo elegir momentos y qué buscar. Abre la hoja e inspecciónala realmente: la mayoría de los defectos son invisibles en el código y obvios en una imagen. Agrupa tus preguntas. Las revisiones consecutivas de renderizado son lo que calienta un portátil y ralentiza una sesión.

8. Escribir el sonido

Lee references/sound.md. Las secciones comienzan en los compases de voz, los efectos se sitúan en los mismos nombres de señal que la imagen, la música se atenúa bajo la voz y la mezcla se sitúa en -15 LUFS.

python audio/score.py ru
python tools/bands.py ru
python tools/qa_audio.py ru whisper

No puedes oírlo, así que usa los números. Apunta a unos 10 dB de voz sobre el resto en cada compás; la película real obtuvo de 6.7 a 14.2 dB, principalmente de 7 a 9, así que no bajes de ese rango. Di claramente que nadie lo ha escuchado todavía.

9. Imágenes fijas en cada idioma, luego el renderizado completo

python render.py renders/check_en "lang=en&times=25,66,241,273"
THREADS=6 CRF=17 python render.py renders/film_ru "lang=ru&fps=24&file=film_ru.mp4"

Primero verifica que las imágenes fijas pasen en cada idioma. Una coma decimal incorrecta en un idioma cuesta un re-renderizado completo después. Ejecuta un trabajo pesado a la vez. Los cambios solo de sonido no necesitan renderizado de imagen: rehaz la mezcla y ejecuta finish_film.py de nuevo.

10. Entregar, limpiar, informar

python tools/finish_film.py ru
python tools/telegram_copy.py ru
python tools/chapters.py ru

Lee references/delivery.md para las copias de plataforma, descripciones y el informe. Nunca subas ni publiques en nombre del usuario a menos que haya solicitado esa publicación específica. Mueve los borradores a la Papelera de reciclaje en lugar de eliminarlos, y conserva los archivos finales y todo lo necesario para rehacerlos.

Reglas que ahorran más reelaboración

• Un fotograma depende solo de t. Sin relojes, sin aleatoriedad no seed, sin estado heredado del fotograma anterior. De lo contrario, una imagen fija no coincide con la película y un re-renderizado parcial no coincide con sus vecinos.
• Los tiempos provienen de las señales. Un desplazamiento desde una señal está bien. Un segundo absoluto escrito a mano se rompe en el otro idioma y después de cualquier reescritura.
• Todo el texto en pantalla pasa por T_, incluidos los números. 29,5 дня y 29.5 days son cadenas diferentes. Este es el error que se envió en la copia maestra en inglés de la película real: un 23,4°.
• No asumas el orden de las señales entre idiomas. El orden de las palabras difiere, por lo que CUE.a < CUE.b puede cumplirse solo en uno de ellos. Protege los intervalos construidos a partir de dos señales.
• Las etiquetas son 2D, colocadas con project(). Así comparten tipografía, grano y manejo de idiomas con las tomas planas.
• Mantén la cámara fuera de todo lo que rota. Verifica los extremos de un movimiento en una hoja, no solo su punto medio.
• Las capas estáticas van en un plate(). Redibujar un fondo detallado en cada fotograma es lo que hace lento un renderizado.
• Cambia, luego mira, luego informa. No digas que algo está arreglado hasta que hayas visto el fotograma.

Lo que no puedes comprobar, y debes decir

• Sonido. Ves volumen, equilibrio, espectrogramas y una transcripción. No sabes cómo suena.
• Flujo. Ves fotogramas, no la experiencia de un espectador, por lo que el ritmo es tu juicio más débil. Pregunta al usuario específicamente sobre el ritmo.
• Plataformas. No puedes ver cómo se comporta un archivo dentro de la cuenta de Telegram o YouTube del usuario.

Informa qué se verificó y qué no, con esas palabras. Las decisiones (idea, dirección, qué cortar) son del usuario.

Archivos incluidos

Ruta	Qué es	Cuándo leerlo
references/reference-analysis.md	Fragmentos de navegador probados para medir un video, plantilla de hoja de estilo	Hay un video de referencia
references/script-and-voice.md	script.json, gramática de señales, presupuesto de palabras, voces, datos	Antes de escribir el guion
references/picture.md	Línea de tiempo, kit plano, actuación sobre señales, texto, grano, kit 3D, mapa del código de ejemplo	Antes de escribir las tomas
references/sound.md	Instrumentos, estructura de la partitura, cadena de voz, números de mezcla, comprobaciones	Antes de escribir la partitura
references/review-and-render.md	Qué buscar en las hojas, modos y opciones de renderizado, carga	Antes de la primera revisión, antes del renderizado completo
references/delivery.md	Copia maestra, teléfono, Telegram, YouTube, X, subtítulos, limpieza, el informe	Al final
references/pitfalls.md	Síntoma, causa, solución, en todo el pipeline	Cuando algo se ve mal
scripts/check_env.py	Lo que tiene la máquina	Primero
scripts/new_project.py	Crea un proyecto a partir de la plantilla	Segundo
assets/template/	El esqueleto del proyecto, una demo funcional	Copiado por new_project.py
assets/examples/court-astronomer/	El código de la película real: 10 constructores 3D, tomas planas, un rig de mano, una partitura completa	Búscalo para una técnica; no se ejecuta por sí solo