marwanhattar94/remotion-motion-graphics

Remotion Motion Graphics

Remotion renderiza componentes React fotograma a fotograma en vídeo. La calidad del código no es el cuello de botella — la artesanía del diseño de movimiento lo es. La generación no entrenada produce interpolación lineal, fundidos solo de opacidad, entradas simultáneas, colores planos y sin textura. Ese es el aspecto de "vídeo IA genérico". Este skill existe para evitarlo.

Reglas no negociables (aplicar a TODA composición)

1. NUNCA uses interpolación lineal. Cada interpolate() obtiene una curva de easing; cada entrada prefiere spring(). Siempre extrapolateLeft/Right: "clamp".
2. Las entradas animan 2 o 3 propiedades juntas (opacidad + translateY + escala). Un fundido solitario está prohibido.
3. Escalona todo. Listas, palabras, rayos, tarjetas: desplazamientos de 3 a 6 fotogramas. Nada entra simultáneamente.
4. Las salidas existen y son más rápidas que las entradas (~10 fotogramas vs ~20).
5. Pila de cinco capas en cada escena, de abajo arriba: malla de fondo → activos → gráficos/tipografía → gradación de color → grano + viñeta. Nunca un fondo sólido plano.
6. Toda imagen fija obtiene Ken Burns (escala lenta 1→1.08 + paneo). Cada activo de vídeo usa <OffthreadVideo>, nunca <Video>.
7. Los elementos inactivos respiran: cualquier cosa en pantalla >2s obtiene micro-movimiento de onda sinusoidal.
8. Toda la sincronización se deriva de fps mediante useVideoConfig(). Sin números mágicos de fotogramas.
9. Un objeto de tema en la parte superior del proyecto (colores, easings, ajustes preestablecidos de spring, fuentes). Nunca se pone un color hexadecimal o easing en línea en un componente.
10. Renderizar, extraer fotogramas, MIRARLOS, corregir, volver a renderizar. Nunca entregues un renderizado no verificado. Este bucle es obligatorio — ver Verificación a continuación.

Flujo de trabajo

Paso 1 — Alcance

Determina: duración, fps (30 por defecto; 60 solo para movimiento rápido intenso), dimensiones (1080×1920 Reels/Shorts, 1920×1080 horizontal), qué activos existen (imágenes, metraje, audio, logotipos) y si se trata de una composición nueva o una edición de un proyecto existente. Si se edita un proyecto existente: leer src/ completamente primero, encontrar el tema (o crear uno), y refactorizar las violaciones de las reglas anteriores antes de añadir funcionalidades.

Paso 2 — Configuración

Proyecto nuevo:

npm install remotion @remotion/cli react react-dom
# opcional: @remotion/transitions @remotion/motion-blur @remotion/google-fonts

Copiar assets/theme.ts de este skill en src/theme.ts y ajustar la paleta a la marca del usuario. Estructura: src/index.ts (registerRoot) → src/Root.tsx (Composition, duración/fps/tamaño) → src/scenes/*.tsx → src/components/*.tsx. Los activos del usuario van en public/, cargados mediante staticFile().

Paso 3 — Construcción

Leer references/motion-patterns.md para las implementaciones de componentes reutilizables (BgMesh, Grade, Grain, Vignette, KenBurns, WordReveal, Stagger, Counter, Spark, transiciones, paralaje). Componer escenas a partir de esos patrones. Para ritmo, cadencia, tipografía, paletas de colores y reglas de diseño de sonido, leer references/design-rules.md.

Ritmo de escena: GOLPE → pausa (15–20 fotogramas fijos) → construcción → GOLPE. Algo debe moverse en los primeros 15 fotogramas. Nunca más de 90 fotogramas sin un nuevo elemento visual.

Paso 4 — Renderizado

npx remotion render src/index.ts <CompId> out/video.mp4 --codec h264 --crf 17

Remotion necesita un binario de Chromium. Si su descarga automática falla (sandboxes, CI sin conexión), encontrar uno y pasarlo explícitamente:

which chromium chromium-browser google-chrome 2>/dev/null
ls /opt/pw-browsers 2>/dev/null   # Las instalaciones de Playwright viven aquí
npx remotion render ... --browser-executable=<ruta>

Si Chrome completo da error de "El modo headless antiguo se ha eliminado", usar un binario headless_shell en su lugar (Playwright incluye uno como chromium_headless_shell-*/chrome-linux/headless_shell).

Paso 5 — VERIFICACIÓN (obligatoria, nunca saltar)

Extraer fotogramas en momentos clave e inspeccionar visualmente cada uno. El método portátil — funciona en máquinas sin ffmpeg de sistema, renderiza el fotograma exacto:

for f in 15 45 90 150; do
  npx remotion still src/index.ts <CompId> out/check_$f.png --frame $f --overwrite
done

Si ffmpeg de sistema SÍ está disponible, extraer del mp4 terminado también verifica la propia codificación (-ss para buscar es más portátil que los filtros select=, cuyas comillas se rompen en algunos shells y en el ffmpeg incluido de Remotion):

ffmpeg -v error -ss 1.5 -i out/video.mp4 -frames:v 1 check_1.png

Buscar y corregir, en orden de frecuencia:

• Errores de espaciado: gap/margin en em se resuelve contra el tamaño de fuente del PADRE (a menudo 16px), no contra el tamaño del texto — usar valores en px en contenedores flex alrededor de texto grande.
• Texto desbordando o tocando los bordes del fotograma (mantener el contenido crítico en el 75% central vertical para 9:16 — la interfaz de la plataforma cubre arriba/abajo).
• Elementos visibles antes de su entrada o después de su salida (falta de clamp).
• Fallos de color/contraste: color principal en >1 elemento por fotograma, texto oscuro ilegible sobre la gradación.
• Errores de orden de capas (grano/viñeta deben estar arriba, gradación sobre el contenido). Corregir → volver a renderizar → volver a extraer → volver a inspeccionar. Solo entregar después de una pasada limpia. Luego ejecutar la lista de verificación final al final de references/design-rules.md.

Editar el metraje existente del usuario

Para mejorar un mp4 existente (subtítulos, gradación, intro/outro) en lugar de construir desde cero: colocar el archivo en public/, renderizarlo como la capa de activos con <OffthreadVideo src={staticFile("clip.mp4")} />, establecer la duración de la composición a partir de la duración del clip, y apilar gráficos/gradación/grano encima. Obtener la duración y fps del clip con ffprobe antes de configurar la composición. Para subtítulos sincronizados con palabras sobre voz, ver la sección de subtítulos de references/motion-patterns.md.

Archivos de referencia

• references/motion-patterns.md — biblioteca de componentes para copiar y pegar: fondos, gradación/grano/viñeta, Ken Burns, revelados de texto, contadores, transiciones, paralaje, sincronización de audio, subtítulos. Leer antes de escribir componentes.
• references/design-rules.md — paletas, reglas tipográficas, arquitectura de escenas, diseño de sonido, lista de verificación previa a la entrega. Leer antes de diseñar escenas y antes de la entrega final.
• assets/theme.ts — la plantilla de tema para copiar en cada proyecto.

Modos de fallo comunes a evitar activamente

• Emojis como iconos. Los emojis se renderizan como glifos de plataforma a todo color (✳️ verde, 🌐 azul) que ignoran tu paleta y rompen silenciosamente la regla de un color principal, y se sitúan sobre el fondo que les hayas dado (mascota naranja sobre mosaico naranja = invisible). Dibujar glifos con CSS/SVG en colores del tema, o verificar cada emoji con los fotogramas extraídos.
• No tener activos de SFX no es motivo para entregar sin sonido. Sintetizar un kit mínimo como WAV de 16 bits desde un script de Node (explosión de ruido whoosh, pop de caída de tono, bombo/bajo de pulso sinusoidal, pad sinusoidal desafinado) en public/sfx/ — ver examples/scripts/ en el repositorio. Cero descargas, completamente determinista.
• Generar un componente gigante en lugar de piezas temáticas y reutilizables.
• Desajuste de durationInFrames entre Composition y el contenido de la escena (silencio muerto).
• Olvidar --overwrite en los re-renderizados, e inspeccionar el archivo obsoleto.
• Fuentes: nunca confiar en los valores predeterminados del sistema para el texto principal; cargar una fuente decorativa mediante @remotion/google-fonts o @font-face + staticFile.
• Intentar "describir" el resultado al usuario en lugar de renderizar y verificar.