Communitygithub.com

yazzang-homelab/motion-studio

Construye, depura y acelera el motor de renderizado Seek(t): contrato de renderizado, captura de canvas vs página, workers/subframes/chunks, correcciones de determinismo, transferencia a Remotion o HyperFrames. Úsalo cuando el render sea lento, los fotogramas difieran, o quieras usar Remotion.

¿Qué es motion-studio?

Este skill define el motor de renderizado **Seek(t)**, un sistema determinista y sin reloj para generar películas programáticas (no videos tradicionales). Cada fotograma se pinta de forma síncrona para un tiempo `t` dado, lo que garantiza renders bit-idénticos en cada ejecución. El skill cubre la ruta A (por defecto) en Opus, con soporte para transferencia a Remotion o HyperFrames si es necesario. El motor se divide en dos mitades: la **página** (`index.html`, `film/film.js`, `lib/runtime.js`) expone `window.seek(t)` y el objeto `__studio`; el **controlador** (`tools/render.mjs`) sirve el proyecto sobre HTTP, lanza un navegador headless (Playwright con shell headless en Windows, Chrome/Edge en macOS/Linux), abre páginas worker, captura fotogramas en orden y codifica un stream H.264. El contrato de renderizado detalla propiedades como `format`, `seek`, `__studio.frame`, `__studio.hash` y `__studio.pixels`, así como modos de captura (`canvas` por defecto, `page` para elementos DOM). Incluye comandos `npm run render`/`render:all`/`render:final`, bandas de rendimiento (workers, escala, subframes, draft, chunk), y herramientas de determinismo (hash por fotograma, comparación con `git diff`). El troubleshooting cubre problemas comunes: shell headless no descargado, cuentas bloqueadas en Windows, ffmpeg faltante, y fuentes no incluidas.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/yazzang-homelab/motion-studio/tree/HEAD/skills/seek-engine

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

MitadArchivosTrabajo
Páginaindex.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
Controladortools/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

MiembroContrato
?format=9x16&scale=1&render=1consulta 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.readyPromise; 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.errorstring 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() / gridCues 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) / textTrackla 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

ObjetivoComando
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 principalnpm run render
Renderizar un rango temporal para una comprobaciónnode tools/render.mjs --from 4 --to 6 --draft --out out/check (escribe out/check/<fmt>/clip_4.00-6.00.mp4)
Renderizar todos los formatosnpm 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 reanudablesnode tools/render.mjs --format all --final --chunk 10
Manifiesto hash por fotogramanode 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

ModoEstablecido porCómo se hace un fotogramaUsar 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 PNGtodo lo dibujado en <canvas id="stage">
pagela fábrica devuelve capture: 'page' o studio.json "capture": "page"seek(t) luego page.screenshot por subfotograma; ffmpeg tmix + select mezcla cada grupopelí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.

BanderaPredeterminadoEfectoCuándo
--workers Nmin(4, max(1, floor(cpus / 3)))páginas paralelas en un navegador alimentan un codificador ordenadoaumentar en máquinas grandes; reducir si la RAM es escasa
--scale s1canvas = even(round(W x s)); 0.5 = un cuarto de los píxelesborradores, imágenes fijas de películas largas
--sub Nstudio.subframes (4)subfotogramas por fotograma--sub 1 para borradores; 8 para movimiento rápido
--fps Nstudio.fps (60)tasa de fotogramas de salida30 para animáticas
--draftdesactivadoencode.previewPreset + CRF 23cualquier render no final
--crf N / --preset p16 / slowcalidad / velocidad de x264dejar para finales
--chunk Sdesactivadoreanudable out/<fmt>/.parts/seg_<a>_<b>.mp4, luego concat -c copypelículas de más de ~30 s, un final de tres formatos, ejecuciones nocturnas (una interrupción luego reanuda en lugar de reiniciar)
--no-posterposter activadoomitir la imagen fija del póstercomprobaciones 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ónTiempo por fotograma de salidaTiempo 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 msaproximadamente 24 min
acumulación en página con 4 páginas (la misma escena sintética, solo captura, píxel idéntico)aproximadamente 148 msaproximadamente 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 x264123 ms en 9x16, 75 ms en 1x1, 118 ms en 16x91.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

  1. npm run critique ejecuta la comprobación de determinismo: __studio.hash en 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.json enumera cada t que no coincide.
  2. 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/a y node tools/render.mjs --from 0 --to 2 --hash --draft --no-poster --json --workers 4 --out out/check/b. Un rango nunca toca silent.mp4. Cada ejecución escribe out/check/<a|b>/<fmt>/clip_0.00-2.00.mp4 más .json y .sha256 (una línea por fotograma: index t sha256), y su línea --json reporta framesDigest, el sha256 de la columna de hash unida por nuevas líneas. Valores iguales de framesDigest en 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.sha256 sale 0 cuando coinciden y git diff --no-index muestra el primer fotograma que difiere. Nunca uses md5, que no existe en Windows o Linux.
  3. 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 framesDigest cubre 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íntomaCausaSolució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 foundno está en PATH, falta ffmpeg-staticnpm i -D ffmpeg-static o configura FFMPEG_PATH; npm run doctor imprime comandos por sistema operativo
spawn EINVAL en tu propio script en Windowsejecutar shims .cmd de npm/npx sin un shellusa spawn('npm.cmd', args, { shell: true }); las herramientas ya lo hacen
font missing: 700 64px "X" o tiempo de espera de readyfamilia no empaquetada o mal escritanpm 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 registroexcepción dentro de un dibujo de escenael controlador imprime __studio.error y errores de consola; reproduce con npm run preview en ese tiempo

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

yazzang-homelab/motion-studio

Make Claude watch its own frames: critique.mjs evidence, harsh 7-axis scores, timestamped P0/P1/P2 problems in docs/review_log.md, fix the 3 worst, re-check, pass the gate. Use for 'critique it', 'review the frames', 'is it good'.

yazzang-homelab/motion-studio

Plan long-form or overnight films: director's brief (PLAN FIRST or GO, budget, definition of done), ANIMATION_GUIDE + STORYBOARD, chapter subagents, gates, chunked render. Use for 'overnight film', 'music video', '2-minute film'.

yazzang-homelab/motion-studio

Make a launch video, app or product reel, explainer or motion ad from code, end to end: brand assets from a URL, beat-grid shot list, synced sound, critique loop, all formats. Default for new video requests; not footage edits.

yazzang-homelab/motion-studio

Brand-asset stage of a product film (motion-reel runs the whole film): capture real screenshots, logo, colors and fonts from a URL, never redraw UI; brand story beats; voice + mascot. Use to grab or fix a brand's assets.

yazzang-homelab/motion-studio

Turn a reference (a frame, a video or an image library) into docs/style_guide.md and a beat-grid shot list: measure cuts, palette and pace, take grammar not content, wait for OK. Use when the user supplies or names a look.

yazzang-homelab/motion-studio

Ship every format from one timeline, then package it: layout() reframing (never crop), render all formats, per-format checks, deliver.mjs, a brand skill, a service offer. Use for 'export 9:16 and 16:9', 'deliver', 'make a skill'.

yazzang-homelab/motion-studio

The viral one-line 'showreel for a résumé' prompt: why it works (anatomy), the credited quote, and seeded variants that avoid look-alike reels; runs it as an engine test. Use for that prompt, its variations, or a showreel.

yazzang-homelab/motion-studio

Score a film to its beat grid: measure a track (beats.mjs) or synthesize one (score.mjs), cue SFX from the film, add voice, mix to -14 LUFS / -1 dBTP at exact length. Use for 'add music', 'sync to the beat', 'SFX', 'loudness'.

yazzang-homelab/motion-studio

Make motion feel physical with closed-form springs from lib/motion.js: presets, springFromFeel, track() for multi-target values, loopTrack loops, indicators, text swaps. Use for 'feels linear', 'add bounce', 'easing to springs'.

yazzang-homelab/motion-studio

Scaffold a motion-studio film project (seek(t) renderer, springs, beat grid, synthesized sound, critique tools), install it, set up the browser, run doctor. Use for 'set up the motion studio', 'new film project', 'init studio'.

yazzang-homelab/motion-studio

Write a six-part XML state spec for a one-shape UI morph film (inputs, direction, structure, build, gotchas, start): states on downbeats, cursor-driven changes, seamless loop, approval gate. Use for 'UI morph', 'state list'.

Skills relacionados