Remotion
Construye y mantén proyectos de Remotion preservando los cambios del usuario. Si un archivo cambió inesperadamente, trátalo como intencional a menos que el usuario confirme lo contrario.
Flujo de trabajo
- Inspecciona
package.json, el archivo de bloqueo, las composiciones existentes, el diff actual ynpx remotion versions. Reutiliza el gestor de paquetes y la estructura del proyecto; mantén todos los paquetesremotion/@remotion/*en una versión exacta. - Confirma el resultado solicitado: cambios en composiciones/código fuente, vista previa en Studio, medios renderizados, un Player incrustado o un servicio de renderizado.
- Implementa imágenes deterministas basadas en fotogramas y mantén las entradas de renderizado serializables.
- Previsualiza en Studio. Renderiza solo cuando el usuario solicite un archivo multimedia.
- Verifica los medios renderizados con
ffprobee inspecciona fotogramas representativos. - Reporta los archivos modificados, la evidencia de previsualización/renderizado y el comprobante de entrega. En Prismer, una ruta suelta dentro del sandbox no es un resultado entregado.
Artefacto de Prismer y contrato de entrega
Cuando el usuario solicite medios renderizados, escribe el archivo final en $PRISMER_ARTIFACTS_DIR (el <artifacts_dir> del envío). Coloca los scaffolds del proyecto, fotogramas, probes y otros archivos intermedios en $PRISMER_SCRATCH_DIR o en el árbol del proyecto existente. Luego, entrega cada archivo final solicitado exactamente una vez:
cloud deliver "$PRISMER_ARTIFACTS_DIR/launch-video.mp4"
Escribir o renderizar un archivo no lo adjunta. Un comprobante exitoso de cloud deliver es el oráculo de entrega. No entregues fotogramas de previsualización, audio temporal ni codificaciones duplicadas a menos que el usuario los haya solicitado. Si no existe un directorio de artefactos de envío, mantén el resultado en la ruta de salida del proyecto aprobada por el usuario e informa que la entrega no estuvo disponible en lugar de inventar un comprobante.
Creación de proyectos y composiciones
No sobrescribas un proyecto que no esté vacío. Cuando no exista un proyecto adecuado, confirma que Node.js y Git estén disponibles, luego ejecuta:
npx create-video@latest --yes --blank --no-tailwind my-video
cd my-video
npm install
Usa un nombre de directorio significativo. Añade Tailwind solo cuando el usuario lo solicite o el proyecto ya lo use. Inspecciona el manifiesto, la configuración y el CSS global generados antes de continuar: las versiones del generador aún pueden emitir dependencias e importaciones de Tailwind cuando se solicitó --no-tailwind. Elimínalas solo cuando el proyecto no las use y mantén alineadas las versiones de los paquetes de Remotion.
En las imágenes sandbox de Prismer, usa un caché npm escribible con ámbito de comando para cada comando que pueda instalar o invocar un paquete faltante, incluidos scaffolding, npm ci, remotion add, probes y renders:
npm_config_cache="${PRISMER_SCRATCH_DIR:-/tmp}/npm-cache" npm ci
No cambies la configuración global de npm del usuario para solucionar un problema de coincidencia de propiedad en el sandbox.
Mantén los metadatos de las composiciones estáticas en línea:
<Composition
id="LaunchVideo"
component={LaunchVideo}
durationInFrames={300}
fps={30}
width={1920}
height={1080}
defaultProps={{title: 'Launch day'}}
/>
Usa calculateMetadata() solo cuando la duración, las dimensiones o las props dependan genuinamente de entradas, datos remotos o inspección de medios. Mantén defaultProps en línea para que Studio pueda guardar las ediciones de props de vuelta al código. Para videos de múltiples escenas, usa límites de <Sequence> con nombre y deriva toda la temporización de un plan único que tenga en cuenta los fps.
Animación basada en fotogramas
Impulsa la animación renderizada desde useCurrentFrame(), interpolate(), springs o easing. No uses transiciones CSS, animaciones CSS, temporizadores de tiempo real o utilidades de animación de Tailwind; no producen renders deterministas.
import {
AbsoluteFill,
Easing,
Interactive,
interpolate,
useCurrentFrame,
useVideoConfig,
} from 'remotion';
export const Hero = () => {
const frame = useCurrentFrame();
const {fps} = useVideoConfig();
return (
<AbsoluteFill style={{justifyContent: 'center', alignItems: 'center'}}>
<Interactive.Div
name="Hero title"
style={{
opacity: interpolate(frame, [0, fps], [0, 1], {
extrapolateLeft: 'clamp',
extrapolateRight: 'clamp',
easing: Easing.bezier(0.16, 1, 0.3, 1),
}),
scale: interpolate(frame, [0, fps], [0.9, 1], {
extrapolateLeft: 'clamp',
extrapolateRight: 'clamp',
easing: Easing.spring({damping: 200}),
output: 'perceptual-scale',
}),
fontSize: 88,
}}
>
Launch day
</Interactive.Div>
</AbsoluteFill>
);
};
Prefiere las propiedades CSS individuales scale, translate y rotate sobre una cadena transform compuesta. Ajusta ambos extremos de las animaciones finitas a menos que la extrapolación sea intencional.
Marcado editable en Studio
Usa Interactive.* para elementos HTML y SVG que deban ser seleccionables, arrastrables, redimensionables, rotables, estilizados o con fotogramas clave en Studio. <Img> ya es interactivo.
- Dale a cada elemento interactivo un nombre corto, fijo y descriptivo.
- Mantén el texto único directamente dentro del elemento.
- Mantén los objetos de estilo, los rangos de
interpolate(), las salidas, el easing y la extrapolación en línea cuando la reescritura en Studio sea importante. - Desestructura solo valores compatibles como
fps,width,heightydurationInFramesdeuseVideoConfig(). - Evita constantes de estilo extraídas, propagación de objetos, arrays de efectos calculados y variables arbitrarias dentro de rangos de fotogramas clave editables.
Para componentes personalizados, consulta la API actual de make-component-interactive en la documentación oficial de Remotion antes de implementarla.
Activos, medios y temporización
Coloca los activos locales en public/ y refiérete a ellos con staticFile():
import {Audio, Video} from '@remotion/media';
import {AnimatedImage, CanvasImage, staticFile} from 'remotion';
export const MediaLayer = () => (
<>
<Video src={staticFile('clip.mp4')} />
<Audio src={staticFile('music.mp3')} />
<CanvasImage src={staticFile('logo.png')} />
<AnimatedImage src={staticFile('sticker.gif')} />
</>
);
Usa @remotion/gif cuando la ruta de imagen animada respaldada por Chrome no sea adecuada. Instala paquetes del ecosistema con npx remotion add <package> para que las versiones de los paquetes de Remotion se mantengan alineadas.
Prefiere medios locales o direccionados por contenido para renders reproducibles en el sandbox. No incorpores cookies, tokens de portador, URLs firmadas o credenciales de mapas en el código fuente o las props de la composición. Para activos asíncronos, fuentes, subtítulos y mosaicos de mapas, empareja delayRender() / continueRender() con cancelRender() en caso de fallo para que una dependencia faltante falle explícitamente en lugar de quedarse colgada hasta el tiempo de espera.
Usa from, durationInFrames y trimBefore en componentes compatibles. Envuelve los componentes no compatibles en <Sequence>:
<Sequence name="Product demo" from={2 * fps} durationInFrames={6 * fps}>
<Video src={staticFile('demo.mp4')} trimBefore={1 * fps} />
</Sequence>
Ajusta la duración de los medios al segmento utilizable previsto. Mantén la temporización de las escenas en un solo plan para que las transiciones no se superpongan accidentalmente ni dejen fotogramas en blanco.
Para los efectos, usa la técnica menos compleja que produzca la toma:
- HTML, SVG y CSS.
- Un efecto de Remotion en el elemento o un wrapper
HtmlInCanvas. - Un efecto personalizado o shader solo cuando los dos primeros no puedan producirlo.
Mantén los arrays de efectos estables. Renderiza elementos separados en lugar de cambiar condicionalmente la forma de un array de efectos.
Subtítulos e inspección multimedia
Normaliza los subtítulos a la forma Caption[] de Remotion y mantén las marcas de tiempo de ingesta en milisegundos:
import type {Caption} from '@remotion/captions';
const caption: Caption = {
text: 'Hello',
startMs: 0,
endMs: 800,
timestampMs: null,
confidence: null,
};
Convierte milisegundos a fotogramas solo en el límite de la composición usando los fps de la composición. Conserva la temporización de palabras cuando esté disponible, agrupa los subtítulos en páginas legibles, anima desde el reloj de fotogramas y verifica el ajuste de línea y las áreas seguras en las dimensiones de salida reales.
Usa el analizador actual de @remotion/captions para SRT en lugar de escribir un analizador de marcas de tiempo. Antes de implementar subtítulos, confirma las APIs actuales para parse-srt, createTikTokStyleCaptions y el proveedor de transcripción elegido.
Para la visualización de audio, usa @remotion/media-utils con datos de audio por ventana de fotograma; nunca impulses barras o formas de onda desde un analizador en tiempo real. Para gráficos y animación de texto, calcula primero la geometría final y muéstrala con recorte, opacidad o transformaciones basadas en fotogramas para que las barras, etiquetas y el diseño de glifos se mantengan estables.
Usa Mediabunny para la duración, dimensiones, recorte, recorte de precisión, metadatos y manejo de contenedores en el lado del navegador. Lee https://mediabunny.dev/llms.txt antes de usar APIs desconocidas. Mantén las versiones de mediabunny y @mediabunny/* compatibles con la versión de Remotion del proyecto.
Mapas
Elige una técnica para la toma:
| Técnica | Úsala cuando |
|---|---|
| Ráster preparado | La imagen estática/satelital determinista con superposiciones animadas es suficiente. |
| Mapbox | Se requieren estilos pulidos, renderizado global o edificios 3D. |
| MapLibre | Se prefiere un runtime vectorial de código abierto sin una clave API de Mapbox. |
| MapTiler | Los estilos alojados o las anotaciones geográficas se ajustan al proyecto. |
| CesiumJS | Se requiere terreno, 3D a escala global o movimiento de cámara de vuelo. |
Nunca confirmes credenciales de mapas. Confirma la licencia y la atribución de imágenes, mosaicos y estilos. Antes de la captura de fotogramas, espera la inicialización de mosaicos, imágenes, fuentes y cámara. Impulsa el movimiento de la cámara desde el reloj de fotogramas de Remotion, mantén las entradas geográficas locales o direccionadas por contenido cuando la repetibilidad sea importante y verifica Chromium/WebGL sin cabeza en el entorno de renderizado real.
Studio, renderizado y verificación
Inicia Studio sin abrir un navegador externo:
npx remotion studio --no-open
Usa la URL impresa. Abre una composición directamente en /<composition-id>, por ejemplo http://localhost:3000/LaunchVideo.
Banderas útiles de Studio:
| Argumento | Propósito |
|---|---|
--log=<level> | Establece error, warn, info o verbose. |
--port=<number> | Solicita un puerto específico. |
--force-new | Inicia otra instancia para el mismo proyecto y puerto. |
Para una verificación rápida y determinista del diseño, renderiza un fotograma:
npx remotion still LaunchVideo out.png --scale=0.25 --frame=30
A 30 fps, el fotograma 30 es un segundo. Omite esto cuando una prueba visual existente ya proporcione suficiente evidencia.
Antes de renderizar, verifica que la CLI vea la composición prevista:
npx remotion versions
npx remotion compositions
Deja que Remotion gestione su navegador compatible por defecto. Una imagen de Prismer también puede incluir un navegador Playwright, pero su presencia no es una garantía de compatibilidad: el binario completo de Chrome puede fallar bajo la política de crashpad del sandbox, mientras que un Headless Shell más nuevo puede pasar un renderizado de un fotograma pero fallar en un renderizado de múltiples fotogramas. Pasa --browser-executable solo para un ejecutable propiedad de la imagen y emparejado por versión que haya pasado una prueba de renderizado de fotogramas adyacentes. Nunca busques en todo el sistema de archivos un navegador ni trates un lanzamiento exitoso como evidencia de compatibilidad.
Renderiza solo cuando el usuario solicite un archivo multimedia:
npx remotion render LaunchVideo out.mp4 --codec=h264
npx remotion still LaunchVideo out.png --frame=0
El sandbox de Prismer proporciona Node y FFmpeg, y Remotion gestiona un navegador compatible en el caché del proyecto. Prefiere video H.264 más audio AAC en MP4 para una reproducción amplia a menos que se requiera transparencia o salida sin pérdida. Mantén la anulación del caché npm escribible limitada a cada comando:
npm_config_cache=/tmp/npm-cache npx remotion render LaunchVideo out.mp4 --codec=h264
Para contenido CJK, carga y espera explícitamente una fuente fija; no confíes solo en que una familia de respaldo del sistema esté presente. Inspecciona los fotogramas codificados adyacentes, así como los fotogramas fijos aislados: un renderizador sin cabeza puede producir un fotograma fijo correcto mientras que una ejecución de fuente de respaldo parpadea o pierde glifos durante un renderizado completo.
Trata la inspección de medios como el oráculo de entrega:
ffprobe -v error \
-show_entries format=duration:stream=codec_name,width,height \
-of compact out.mp4
Confirma la duración, las dimensiones, los códecs y el flujo de audio esperado. Inspecciona los fotogramas representativos, incluidos varios fotogramas adyacentes en secciones animadas o con mucho texto, o reproduce el resultado cuando sea posible. Un comando de renderizado exitoso por sí solo no es evidencia de entrega. Si los fotogramas fijos aislados son correctos pero el renderizado codificado tiene fotogramas parciales o parpadeantes, usa la API programática renderStill() con una URL de serve empaquetada y una instancia de navegador para emitir la secuencia de fotogramas verificada, luego ensámblala con el FFmpeg del sandbox. No bucles la CLI y reempaqueta una vez por fotograma; informa la alternativa y vuelve a probar el archivo ensamblado.
Players, editores y servicios de renderizado
Usa el <Player> de Remotion para una vista previa interactiva de React. Mantén la composición utilizable tanto por el Player como por las rutas de renderizado; no bifurques la lógica visual.
Elige la arquitectura de renderizado según la carga de trabajo:
- Renderizado en navegador/cliente para trabajo limitado y local del usuario.
- Un worker de Node y una cola para un servidor controlado.
- Remotion Lambda para renderizado elástico nativo de AWS.
- La integración oficial actual de Vercel o Cloudflare cuando coincida con la plataforma de alojamiento y la versión de Remotion instalada.
El renderizado no trivial debe ser asíncrono: devuelve un ID de trabajo, expón el progreso y los fallos, almacena la salida de forma duradera y haz que los reintentos sean idempotentes.
Para los editores, modela las props de la composición y el estado de la línea de tiempo explícitamente. Mantén las entradas de renderizado serializables y versionadas, valida las props no confiables, limita el acceso a activos remotos y separa el estado de previsualización del estado duradero del proyecto.
La superficie de renderizado de Remotion es React. Para hosts de Vue, Angular o Svelte, usa la integración oficial actual y mantén el límite de la composición de React explícito en lugar de confiar en un starter memorizado.
Documentación actual y actualizaciones
Prefiere la documentación oficial actual sobre las APIs memorizadas. Añade .md a una URL de la documentación de Remotion para obtener Markdown, por ejemplo:
https://www.remotion.dev/docs/sequence.md
La búsqueda de la documentación de Remotion puede ayudar a encontrar la página correcta. Antes de aplicar una actualización de versión de Remotion o Mediabunny, lee las guías de actualización. Para actualizaciones de Remotion, consulta https://www.remotion.dev/docs/versioning. Para Mediabunny, consulta la documentación más reciente.
Mantén los cambios actualizados con la versión de Remotion del proyecto; si una API está obsoleta, utiliza el reemplazo documentado. Reporta los cambios de versión y las migraciones aplicadas como parte del resumen del cambio.