DISEÑO DE MOVIMIENTO CON REMOTION — Habilidad de Implementación
1. Revisión antes de codificar
- Lee
CLAUDE.md,MASTER_PROMPT.mdy los documentos de arquitectura. - Verifica las versiones reales de Remotion/React/TypeScript y el gestor de paquetes.
- Encuentra el punto de entrada existente y el registro de composiciones.
- Sigue las convenciones del repositorio; no cambies dependencias sin necesidad.
- Usa la salida de
beyond-video, el guion, el storyboard y la Biblia de Estilo como especificación de producción. - Verifica las API que usas contra el código fuente de Remotion de la versión instalada (por ejemplo,
packages/core/srcen un clon de referencia) antes de confiar en la memoria.
2. Perfil de composición
Valores por defecto:
- ancho: 1080
- alto: 1920
- fps: 60
- relación de aspecto: 9:16
- duración: entero positivo en fotogramas
Cada composición necesita un ID único y metadatos explícitos. No almacenes valores de FPS diferentes en varias capas sin una razón.
<Composition> acepta id, fps, width, height, durationInFrames, defaultProps, y opcionalmente calculateMetadata (duración/metadatos dinámicos a partir de props) y schema. durationInFrames debe ser positivo.
3. Ingeniería de la línea de tiempo
- Mantén las duraciones y los fotogramas de inicio en datos/configuración centralizados.
- Usa una convención de intervalo de fotogramas; se recomienda
[inicio, fin). durationInFramesde la escena debe ser positivo.- Asegúrate de que la duración total de la composición contenga todas las escenas más el cierre/cola.
- Valida superposiciones y huecos; superpón solo cuando sea intencionado para una transición/composición.
- No confíes en números de punto flotante para el límite del fotograma final.
4. Animación determinista — API de tiempo/fotogramas (Remotion 4.x)
Fuentes de tiempo:
useCurrentFrame()— el fotograma actual, indexado desde 0. Solo se puede usar dentro de un componente de composición; fuera de una composición lanza un error.useVideoConfig()— devuelve{width, height, fps, durationInFrames, id, defaultProps, defaultVideoImageFormat, ...}; lanza un error fuera de una composición.
Interpolación y resorte:
interpolate(input, inputRange, outputRange, options?)— sobrecargas para salida de tipo número, cadena, booleano y array. Opciones:easing,extrapolateLeft/extrapolateRight('extend' | 'identity' | 'clamp' | 'wrap'),output,outputType,posterize. Usa extrapolación clamp cuando el movimiento no deba extenderse más allá del rango.spring({frame, fps, config?, from=0, to=1, durationInFrames?, durationRestThreshold?, delay=0, reverse=false}).SpringConfig:damping(por defecto 10),mass(1),stiffness(100),overshootClamping(false).damping <= 0hace que la animación nunca se establezca (error de bucle infinito).measureSpring({fps, config?, threshold=0.005})— número de fotogramas hasta que el resorte se estabilice;threshold=0devuelveInfinity.
Reglas:
- El movimiento debe ser una función del fotograma y las props.
- Siempre inicializa valores de partículas/ruido/aleatorios.
- Evita
setInterval,setTimeout,requestAnimationFrame,Date.now()y keyframes CSS auto-ejecutados como fuente principal de movimiento de video. - No obtengas datos de red mientras la composición se renderiza.
- No incluyas audio/video de URLs inestables o que requieran inicio de sesión.
delayRender(label?, options?)mantiene el renderizado hasta que se llame acontinueRender(handle)(por ejemplo, assets asíncronos); su tiempo de espera se establece con el CLI--timeout.
5. Sequence, Series y fotogramas locales vs globales
Esta es la regla que más a menudo se aplica incorrectamente — un error real ocurrió una vez porque un componente calculó el fotograma global dentro de un Series.Sequence:
- Dentro de un
<Sequence>,useCurrentFrame()devuelve el fotograma RELATIVO al inicio de la secuencia:(frame - (cumulatedFrom + relativeFrom)) * playbackRate. Los componentes dentro de una secuencia NO ven el fotograma global. - Props de
<Sequence>:from?,name?,durationInFrames?(debe ser positivo; requerido cuando se usaloop),layout('absolute-fill'|'none'),premountFor,loopy props de recorte (solo conlayout="absolute-fill"). <Series.Sequence>solo puede usarse dentro de<Series>; unSeries.Sequencefuera de<Series>lanza "This component must be inside a<Series />component."- Dos patrones de enrutamiento válidos — elige uno y mantente consistente:
- Enrutador de fotograma global (usado en el proyecto de video): un componente enrutador usa el
useCurrentFrame()global y selecciona el beat por su rango[inicio, fin); los componentes del beat calculan a partir del fotograma global. - Series: cada
Series.Sequencecontiene un beat; los componentes del beat calculan a partir del fotograma local (0 al inicio de la secuencia).
- Enrutador de fotograma global (usado en el proyecto de video): un componente enrutador usa el
- No mezcles ambos patrones en una misma composición sin una razón explícita.
6. Estructura de escena/componente
- Una escena tiene una responsabilidad narrativa/visual.
- Las props de la escena se definen en TypeScript.
- Los componentes reutilizables resuelven una tarea visual clara.
- Evita que un solo archivo contenga todo el video.
- Separa la configuración de contenido, el renderizador, los tokens de estilo y las referencias de assets.
- Añade fallbacks diseñados para assets opcionales; nunca ocultes un asset crítico faltante.
7. Componentes multimedia y assets
<Img src>— una imagen que falla al cargar sinonErrorcancela el renderizado (cancelRender). Siempre proporcionaonErrorpara assets críticos, o asegúrate de que el asset exista antes de renderizar.staticFile(path)— mapea un archivo enpublic/; úsalo para cada asset local (imágenes, audio, video).<Audio>— consultasound-designpara mapear una hoja de pautas a props (trimBefore/After— alias antiguostartFrom/endAt—volume,playbackRate). La posición de una pauta en la línea de tiempo se establece con<Sequence from>; las props de recorte solo cortan qué parte del archivo se reproduce.<Audio>no tiene propmuted; el silencio es una bandera del CLI (--muted).<Video>/<OffthreadVideo>y<Still>siguen las mismas reglas de fotogramas; la duración del medio debe programarse a partir de fotogramas, no de los metadatos del archivo.
8. Movimiento 2D
Usa SVG/formas/CSS/rasters según sea necesario. Ten en cuenta anclas, orígenes de transformación, anti-aliasing, capas, recortes y el área segura. Cada transformación debe estar impulsada por fotogramas.
9. Soporte para píxeles y figuras de palo
Arte pixelado:
- bloquea el lienzo lógico y la escala de píxeles;
- usa vecino más cercano al escalar sprites;
- ajusta las posiciones a la cuadrícula cuando sea necesario;
- bloquea la paleta y las dimensiones del sprite;
- evita el desenfoque y el parpadeo subpíxel.
Figura de palo:
- mantén las proporciones y los pivotes consistentes;
- usa una librería de poses/rig cuando la escala del proyecto lo justifique;
- anima la silueta y el gesto para que se lean;
- sincroniza expresiones/poses con los beats de la historia.
Para ciclos de caminata, seguimiento y movimiento inactivo, consulta character-animation.
10. Movimiento 3D
- Añade 3D solo cuando aporte valor creativo.
- Verifica las versiones de
three,@react-three/fiber,@remotion/threey sus documentos. - Para la integración con Remotion ThreeCanvas, sigue el enfoque impulsado por fotogramas de la versión de la API instalada; no asumas que los patrones en tiempo real de R3F son automáticamente deterministas.
- Controla la cámara, transformaciones, materiales, iluminación y partículas desde el fotograma.
- Considera la compatibilidad con renderizador/headless, tamaño de textura, geometría y costo de cómputo.
- Separa la capa 3D de la tipografía/superposiciones 2D cuando ayude a la legibilidad y mantenibilidad.
- Para dirigir escenas 3D en detalle, consulta
3d-scene-director.
11. Tipografía y transiciones
- Prioriza la jerarquía y legibilidad.
- Nunca cubras una copia importante con una transición.
- Cada transición conecta dos beats; no añadas efectos sin una función.
- Mantén las curvas de movimiento y la intensidad consistentes a través de la Biblia de Estilo.
- Ajusta la duración del texto a las necesidades de lectura.
12. Implementación del cierre
Implementa el logo de cierre + CTA de acuerdo con la hoja de trabajo de beyond-video. El logo debe provenir de un asset oficial o un placeholder aprobado. El texto, la sincronización, el motivo y la composición deben sentirse hechos para el video en cuestión.
13. QA antes de la entrega
Verifica el ID de la composición, metadatos, rangos de fotogramas, importaciones, tipos, assets estáticos, fuentes, consistencia de estilo, área segura, cierre y licencias de assets. Ejecuta lint/typecheck/pruebas disponibles. No renderices MP4. No hagas commit/push.
Formato de salida
- Registro de composiciones: ID, 1080×1920, 60 FPS, durationInFrames, lista de escenas + rangos de fotogramas.
- APIs usadas: nombre de la API + firma relevante + dónde se verificó (versión instalada de Remotion).
- Patrón de enrutamiento de fotogramas: global o Series — una opción, consistente en toda la composición.
- Registro de assets: archivo,
staticFile, fallback/onErrorpor asset crítico. - Lista de verificación QA + resultados de typecheck/lint.
Ejemplo mini
Enrutador de fotograma global (patrón de proyecto de video):
const frame = useCurrentFrame();
const beat = BEATS.find((b) => frame >= b.start && frame < b.end);
return (
<AbsoluteFill>
{beat?.id === 'S01-B01' && <Hook />}
{beat?.id === 'S01-B02' && <Problem />}
</AbsoluteFill>
);
Resorte con duración medida:
const settle = measureSpring({fps, config: {damping: 12}});
const progress = spring({frame, fps, config: {damping: 12}});
Modos de fallo
- Un componente dentro de
Series.Sequencecalcula el fotograma global → beat incorrecto, las escenas se muestran en el momento equivocado. Solución: calcula a partir del fotograma local, o cambia a un enrutador de fotograma global. Series.Sequenceusado sin<Series>→ lanza un error al renderizar. Envuélvelo en<Series>, o usa<Sequence>directamente (noSeries.Sequence).springcondamping <= 0→ la animación nunca se estabiliza. Manténdamping > 0.- Imagen faltante sin
onError→ el renderizado se cancela. AñadeonErroro asegúrate de que el asset exista antes de renderizar. useCurrentFrame()/useVideoConfig()fuera de una composición → lanza un error. Llámalos solo dentro de componentes de composición.