Motor Seek (paso 07 del curso)
Aquí, una película es un programa, no un video. La página pinta el fotograma exacto para cualquier tiempo t; el renderizador recorre el tiempo,
captura cada fotograma y lo envía a ffmpeg. Nada depende de un reloj, por lo que un render es idéntico en cada ejecución y una
corrección es una edición de una línea más un re-render. Esta es la ruta A, la ruta que Opus elige por defecto. Úsala a menos que el usuario
mencione Remotion o HyperFrames (entonces lee references/route-b.md).
Ejecuta todo desde la raíz del proyecto de la película (la carpeta con studio.json). Si no hay ninguna, ejecuta
/motion-studio:studio-init primero. Los archivos de este skill residen en ${CLAUDE_SKILL_DIR}; los enlaces relativos a continuación apuntan
allí (${CLAUDE_SKILL_DIR}/references/determinism.md, ${CLAUDE_SKILL_DIR}/references/route-b.md).
1. Las dos mitades
| Mitad | Archivos | Trabajo |
|---|---|---|
| Página | index.html, film/film.js, lib/runtime.js (+ lib/*.js) | boot(film) carga studio.json, audio/beats.json (opcional) y fuentes empaquetadas, luego expone window.seek(t) y window.__studio |
| Controlador | tools/render.mjs (+ tools/studio.mjs) | sirve el proyecto en http://127.0.0.1:<aleatorio>, lanza un navegador headless (Windows: shell headless de Playwright, nunca un Chrome o Edge instalado; macOS y Linux: Chrome, Edge, luego el empaquetado), abre N páginas worker, captura fotogramas en orden, codifica un stream H.264 |
La página siempre se sirve sobre http. file:// rompe fetch('studio.json'), los módulos ES y las rutas que contienen # o %.
2. El contrato de renderizado
| Miembro | Contrato |
|---|---|
?format=9x16&scale=1&render=1 | consulta que envía el controlador; format por defecto es studio.primaryFormat, scale de 0.1 a 1 |
window.seek(t, blur?) | pintura síncrona del tiempo t; las películas en bucle se envuelven con loopT, otras se sujetan a [0, duration]; devuelve true. El segundo argumento opcional { frameT, sub, subs } indica que esta pintura es el subfotograma sub de subs del fotograma de salida centrado en frameT (la captura de página lo envía para cada captura de pantalla) |
__studio.ready | Promise; se resuelve después de que la configuración, la cuadrícula de beats, las fuentes (loadFonts afirma cada tipo) y setup() estén listos |
__studio.error | string del stack cuando el arranque falló (el controlador lo imprime) |
__studio.meta | { title, duration, fps, format, width, height, logicalWidth, logicalHeight, scale, bpm, loop, capture } |
__studio.frame({ t, sub, shutter, fps, wrap }) | URL de datos PNG del fotograma t; sub > 1 acumula subfotogramas centrados en la página (desenfoque de movimiento); wrap: false pinta el tiempo bruto sujeto a [0, duration] incluso en una película en bucle |
__studio.hash(t, { wrap, sub, shutter, fps }) | sha256 de los píxeles brutos después de paint(t) (comprobaciones de determinismo); hash({ t, wrap: false }) también se acepta. hash(0) versus hash(duration, { wrap: false }) es el invariante de cierre de bucle |
__studio.pixels(t, w) | miniatura RGBA pequeña como base64 (métricas de crítica); siempre envuelve en películas en bucle |
__studio.cues() / shots() / grid | Cues de SFX, ventanas de tomas, cuadrícula de beats como JSON (leído por sfx.mjs, stills.mjs --shots, critique.mjs). shots() está en orden temporal y solo enumera escenas, nunca overlays; grid lleva hits |
__studio.textUse() / coverage(family, weight, style, chars) / textTrack | la comprobación de glifos de la crítica. Con window.__TEXT_TRACK__ = true antes de la carga (o ?texttrack=1) lib/draw.js registra los caracteres que text(), kinetic() y textWidth() dibujan por fuente; textUse() resuelve [{ family, weight, style, chars }] para los fotogramas pintados hasta ahora (primero seek() a través de la película), coverage() resuelve { missing, checked } para un tipo. Desactivado por defecto, nunca cambia un píxel; text() y kinetic() no lanzan una excepción para una familia no registrada |
Lo que una escena ve en c mientras se crea un fotograma con desenfoque de movimiento: c.t es el tiempo que se está pintando (el tiempo del SUBFOTOGRAMA, por lo que
el desenfoque de movimiento ocurre por sí mismo), c.frameT el tiempo central del fotograma de salida (el mismo para cada subfotograma), c.frame el índice del fotograma de salida
floor(frameT x fps) (el mismo para cada subfotograma), c.sub / c.subs el índice y recuento de subfotogramas. El ruido indexado por fotograma
usa c.frame (grain(g, W, H, c.frame) entonces se ve igual en imágenes fijas, vista previa y el resultado final), y "en doses" usa
stepTime(c.frameLt, 12). Detalles: docs/ARCHITECTURE.md sección 5.2 en el plugin.
El código de la película obedece las reglas en references/determinism.md. La forma corta: cada valor es una
función de t; aleatoriedad con semilla por elemento usando rngFor(name, i); no Math.random, Date, performance.now,
temporizadores, requestAnimationFrame, transiciones CSS o estado entre fotogramas; las fuentes y los activos son archivos locales.
npm run lint comprueba esto, y el hook del plugin verifica cada edición en film/, lib/ y index.html.
3. Comandos
| Objetivo | Comando |
|---|---|
Vista previa en vivo (arrastrar, Espacio, flechas, [/] tomas, F formatos, G guías de seguridad) | npm run preview |
| Verificación de entorno (Node, Playwright, navegador, ffmpeg, fuentes, claves presentes) | npm run doctor |
| Instalar el navegador predeterminado de Windows (shell headless de Playwright, aproximadamente 115 MB) | npx playwright install chromium-headless-shell (npm run setup:browser) |
| Comprobación rápida de ritmo (media escala, 30 fps, sin desenfoque) | npm run animatic (escribe out/animatic/<fmt>/silent.mp4) |
| Renderizar el formato principal | npm run render |
| Renderizar un rango temporal para una comprobación | node tools/render.mjs --from 4 --to 6 --draft --out out/check (escribe out/check/<fmt>/clip_4.00-6.00.mp4) |
| Renderizar todos los formatos | npm run render:all |
| Render final, todos los formatos (bloqueado hasta que pase la puerta de crítica; aproximadamente 4 min para la demo de 12 s, así que ejecútalo en segundo plano) | npm run render:final |
| Forma larga, segmentos reanudables | node tools/render.mjs --format all --final --chunk 10 |
| Manifiesto hash por fotograma | node tools/render.mjs --hash (escribe frames.sha256; un rango escribe clip_<desde>-<hasta>.sha256) |
Salida por formato: out/<fmt>/silent.mp4, out/<fmt>/poster.png (en studio.poster o 0.35 x duración) y
out/<fmt>/render.json (fps, fotogramas, workers, versión del navegador, captura, configuración de codificación, segundos). mix.mjs lee
render.json para la duración exacta del audio. Todo se construye en out/<fmt>/.staging/ y se publica como una unidad: los
archivos antiguos se mueven primero, los nuevos se mueven con silent.mp4 al final, y cualquier fallo devuelve los antiguos. Si
otro programa mantiene abierta una salida (un reproductor de video, un visor de imágenes en Windows), el render espera hasta 30 s
(MOTION_PUBLISH_WAIT_MS), advierte al inicio qué archivos están abiertos, y de lo contrario se detiene con cannot replace <archivo>: EBUSY … y MANTIENE el render terminado en out/<fmt>/.staging/ (las salidas anteriores permanecen intactas). Cierra el
programa y copia los archivos desde .staging/, o renderiza de nuevo. Un render completo con --no-poster elimina el poster.png
anterior, y uno sin --hash elimina el frames.sha256 anterior, por lo que ninguna salida describe un corte más antiguo.
Un render de rango es parcial solo cuando --from/--to dejan fotogramas fuera; escribe clip_<desde>-<hasta>.mp4 con su propio
.json y .sha256 en su lugar, nunca reemplaza silent.mp4, y no puede ser --final. Un rango que cubre toda la película
(o un --to después del final) es un render completo. Mantén los renders de verificación bajo --out out/check para que out/<fmt>/ contenga solo la
película real.
4. Modos de captura
| Modo | Establecido por | Cómo se hace un fotograma | Usar para |
|---|---|---|---|
canvas (predeterminado) | nada | __studio.frame pinta sub subfotogramas en t + ((j + 0.5) / sub - 0.5) * shutter / fps, suma píxeles en la página, devuelve un PNG | todo lo dibujado en <canvas id="stage"> |
page | la fábrica devuelve capture: 'page' o studio.json "capture": "page" | seek(t) luego page.screenshot por subfotograma; ffmpeg tmix + select mezcla cada grupo | películas DOM (elementos con estilo actualizados desde t) |
shutter 0.5 es un obturador de 180 grados: el desenfoque abarca la mitad de un intervalo de fotograma. Los movimientos rápidos de cámara y los paneos pueden mostrar copias fantasma
con --sub 4; aumenta a --sub 8 para esas películas. La captura de página es más lenta (una captura de pantalla por subfotograma) y hereda
diferencias de renderizado DOM, por lo que es preferible canvas.
5. Perillas de rendimiento
Recuento de pinturas = fotogramas x subfotogramas. Una película de 12 s a 60 fps con --sub 4 son 2,880 pinturas por formato.
| Bandera | Predeterminado | Efecto | Cuándo |
|---|---|---|---|
--workers N | min(4, max(1, floor(cpus / 3))) | páginas paralelas en un navegador alimentan un codificador ordenado | aumentar en máquinas grandes; reducir si la RAM es escasa |
--scale s | 1 | canvas = even(round(W x s)); 0.5 = un cuarto de los píxeles | borradores, imágenes fijas de películas largas |
--sub N | studio.subframes (4) | subfotogramas por fotograma | --sub 1 para borradores; 8 para movimiento rápido |
--fps N | studio.fps (60) | tasa de fotogramas de salida | 30 para animáticas |
--draft | desactivado | encode.previewPreset + CRF 23 | cualquier render no final |
--crf N / --preset p | 16 / slow | calidad / velocidad de x264 | dejar para finales |
--chunk S | desactivado | reanudable out/<fmt>/.parts/seg_<a>_<b>.mp4, luego concat -c copy | películas de más de ~30 s, un final de tres formatos, ejecuciones nocturnas (una interrupción luego reanuda en lugar de reiniciar) |
--no-poster | poster activado | omitir la imagen fija del póster | comprobaciones por lotes |
Medido en el portátil de referencia (i7-1255U de 12 hilos, Chrome instalado, 1080x1920, 60 fps, 4 subfotogramas, 4 workers; el valor predeterminado en Windows es ahora el shell headless, cuya velocidad por fotograma no se volvió a medir, y que añade de 15 a 25 s por ejecución de herramienta para el arranque en una máquina con antivirus en tiempo real, medido):
| Configuración | Tiempo por fotograma de salida | Tiempo para 15 s a 60 fps |
|---|---|---|
| el bucle de captura por subfotograma del curso (solo captura, escena sintética de 200 arcos, texto y un degradado) | aproximadamente 1,575 ms | aproximadamente 24 min |
| acumulación en página con 4 páginas (la misma escena sintética, solo captura, píxel idéntico) | aproximadamente 148 ms | aproximadamente 2.2 min |
| este renderizador de extremo a extremo en la película de demostración de 12 s de la plantilla, codificación final x264 | 123 ms en 9x16, 75 ms en 1x1, 118 ms en 16x9 | 1.8 min en 9x16 (aproximadamente 4 min para los tres formatos de la película de 12 s) |
Las dos primeras filas son el benchmark de solo captura que eligió el diseño; la última fila es lo que cuesta una película real, y es
la cifra a citar como estimación (aumenta con la complejidad de la escena y con otros programas que cargan la máquina, hasta
aproximadamente 5 min para los tres formatos). x264 -preset slow codifica aproximadamente 18 fps en ese tamaño, por lo que la captura es el
cuello de botella. El progreso, fps y ETA se imprimen en stderr una vez por segundo de película. Inicia un render final en segundo plano y consulta
el registro; nunca esperes en primer plano.
6. Probar el determinismo
npm run critiqueejecuta la comprobación de determinismo:__studio.hashen tiempos que cruzan cada límite de toma y cue (más y menos un fotograma), pase A en orden, pase B mezclado, pase C después de una recarga.out/review/<fmt>/metrics.jsonenumera cadatque no coincide.- Después de un render de rango, prueba que el rango es determinista con dos renders con hash del mismo rango. Varía el recuento de
workers para que el paralelismo también esté cubierto:
node tools/render.mjs --from 0 --to 2 --hash --draft --no-poster --json --workers 1 --out out/check/aynode tools/render.mjs --from 0 --to 2 --hash --draft --no-poster --json --workers 4 --out out/check/b. Un rango nunca tocasilent.mp4. Cada ejecución escribeout/check/<a|b>/<fmt>/clip_0.00-2.00.mp4más.jsony.sha256(una línea por fotograma:index t sha256), y su línea--jsonreportaframesDigest, el sha256 de la columna de hash unida por nuevas líneas. Valores iguales deframesDigesten cada formato significan fotogramas idénticos. Si difieren, compara los dos archivos.sha256:git diff --no-index --quiet out/check/a/<fmt>/clip_0.00-2.00.sha256 out/check/b/<fmt>/clip_0.00-2.00.sha256sale 0 cuando coinciden ygit diff --no-indexmuestra el primer fotograma que difiere. Nunca usesmd5, que no existe en Windows o Linux. - No hagas hash del mp4: la salida de x264 cambia con el recuento de hilos, por lo que los hashes de mp4 difieren entre máquinas. El
framesDigestcubre los PNG de fotograma que entran en el codificador, que es de lo que trata el determinismo.
La promesa son fotogramas bit-idénticos en la misma máquina y compilación del navegador (registrada en render.json). Entre
máquinas, las fuentes se rasterizan de manera diferente (DirectWrite, CoreText, FreeType); compara visualmente.
7. Solución de problemas
| Síntoma | Causa | Solución |
|---|---|---|
Executable doesn't exist ... chromium_headless_shell, o could not launch a browser: no safe browser found. (Windows) | El shell headless de Playwright no está descargado (npm install no lo obtiene) | npx playwright install chromium-headless-shell. En macOS y Linux, un Chrome o Edge instalado también funciona; en Windows, uno instalado es una aceptación protegida (studio.json "browser": "chrome", MOTION_BROWSER=chrome) porque cada inicio con perfil nuevo cuenta como un intento fallido de inicio de sesión de Windows |
Cuenta de Windows bloqueada, eventos de registro de seguridad 4625 de chrome.exe, o refusing to start chrome: N launches ... | se inició un Chrome o Edge instalado con un perfil nuevo (prueba de contraseña en blanco = inicio de sesión fallido) | cambia al shell headless como se indicó anteriormente y desactiva MOTION_BROWSER / MOTION_CHROME_PATH; los comandos de confirmación y las razones están en ${CLAUDE_SKILL_DIR}/../studio-init/references/troubleshooting.md, "Windows account gets locked out while rendering or testing" |
ffmpeg not found | no está en PATH, falta ffmpeg-static | npm i -D ffmpeg-static o configura FFMPEG_PATH; npm run doctor imprime comandos por sistema operativo |
spawn EINVAL en tu propio script en Windows | ejecutar shims .cmd de npm/npx sin un shell | usa spawn('npm.cmd', args, { shell: true }); las herramientas ya lo hacen |
font missing: 700 64px "X" o tiempo de espera de ready | familia no empaquetada o mal escrita | npm run fonts -- add "X:400,700"; usa los nombres en studio.json brand.fonts |
| fotogramas en blanco o parciales, errores de página en el registro | excepción dentro de un dibujo de escena | el controlador imprime __studio.error y errores de consola; reproduce con npm run preview en ese tiempo |