iamryoman/remotion-best-practices

Mejores prácticas de Remotion

Construye la salida de Remotion como una función determinista del fotograma, las propiedades de entrada y los activos declarados. Conserva las ediciones del usuario y el gestor de paquetes, la arquitectura y el estilo existentes del proyecto, a menos que la tarea requiera un cambio.

Comienza con evidencia

1. Lee las instrucciones del repositorio e inspecciona package.json, el archivo de bloqueo, la configuración de Remotion, el punto de entrada, las composiciones registradas y las pruebas cercanas.
2. En un proyecto existente, ejecuta node <skill-directory>/scripts/audit-remotion-project.mjs <project-root>. Trata su resultado como evidencia, no como permiso para actualizar.
3. Registra la versión instalada de Remotion antes de elegir las API. Mantén todos los paquetes remotion y @remotion/* en la misma versión exacta. No añadas un segundo archivo de bloqueo.
4. Identifica si el entregable es un video, una imagen estática, un fotograma muestreado de un video o un lote de capturas de pantalla de tienda.
5. Define el ID de composición, dimensiones, FPS, duración, propiedades, ruta de salida y activos requeridos antes de la implementación.

Carga solo la referencia relevante

• Para <Composition>, <Still>, useCurrentFrame(), interpolate(), spring(), <Sequence> o <Series>, lee composición-y-tiempo.md.
• Para staticFile(), medios, fuentes, datos de red, useDelayRender(), delayRender() o calculateMetadata(), lee activos-y-async.md.
• Para CLI, renderStill(), renderizado del lado del servidor o Remotion Lambda, lee renderizado-y-lambda.md.
• Para renderizados lentos, alto uso de memoria, no determinismo o estrategia de verificación, lee rendimiento-y-pruebas.md.
• Para imágenes de App Store o Google Play, incluida la salida de 1284×2778 delegada por screenshot-studio, lee imagenes-de-tienda.md.
• Cuando una regla de API o plataforma pueda haber cambiado, consulta la fuente primaria en vivo vinculada en fuentes.md antes de codificar.

Reglas de implementación no negociables

• Deriva el tiempo de useCurrentFrame() y useVideoConfig(). No uses transiciones CSS, animaciones CSS con fotogramas clave, temporizadores de reloj de pared o aleatoriedad sin semilla para el movimiento renderizado.
• Limita las animaciones finitas a menos que la extrapolación sea intencional. Expresa los tiempos en segundos multiplicados por fps cuando representen tiempo, y centraliza las duraciones de escenas compartidas.
• Recuerda que useCurrentFrame() es relativo dentro de un componente temporizado. Pasa un fotograma absoluto desde la raíz de la composición solo cuando la sincronización global sea intencional.
• Usa <Sequence> para la colocación explícita en la línea de tiempo principal y <Series> para escenas contiguas. Dale a cada escena una duración explícita.
• Coloca los activos locales en public/ y resuélvelos con staticFile(). Utiliza componentes multimedia de Remotion en lugar de etiquetas HTML sin formato para que el renderizado espere correctamente a los medios.
• Prefiere useDelayRender() dentro de los componentes. Crea un identificador una vez, límpialo exactamente una vez y llama a cancelRender(error) en caso de fallo. Prefiere calculateMetadata() para los datos necesarios para determinar propiedades o metadatos una vez por renderizado.
• Mantén el código de tiempo de renderizado libre de suposiciones solo del navegador que no estén disponibles en Chromium sin cabeza o Lambda. Nunca expongas credenciales de AWS u otros secretos al paquete del navegador.
• Valida las dimensiones, el formato de archivo, la política de canal alfa y las reglas específicas de la plataforma de forma independiente para cada destino de tienda. Nunca asumas que un tamaño de retrato es aceptado tanto por Apple como por Google.

Trabaja en un bucle de renderizado ajustado

1. Verifica tipos y ejecuta pruebas enfocadas.
2. Renderiza fotogramas estáticos representativos: el inicio, cada límite de escena, un punto medio de movimiento y el último fotograma.
3. Inspecciona los píxeles reales, no solo la vista previa de Studio. Verifica el recorte, el ajuste de texto, los márgenes de seguridad, los activos faltantes y los fondos transparentes.
4. Renderiza un rango corto de fotogramas o un borrador de baja escala antes de un video completo y costoso.
5. Compara la concurrencia en la máquina de implementación en lugar de maximizarla a ciegas.
6. Renderiza el artefacto final con un ID de composición, propiedades, ruta de salida, dimensiones y formato explícitos.
7. Verifica el estado de salida, la existencia del archivo, las dimensiones de píxeles, la duración/recuento de fotogramas cuando sea relevante y una muestra visual final.

Realiza cambios de forma conservadora

• No actualices Remotion, reescribas la estructura del proyecto ni reemplaces los componentes multimedia a menos que la tarea lo requiera o el usuario lo apruebe.
• Protege las API más nuevas detrás de la versión instalada; proporciona una alternativa compatible cuando sea práctico.
• No ocultes fallos de renderizado con aumentos de tiempo de espera arbitrarios. Primero identifica el identificador no resuelto, la solicitud de red, el activo, la fuente o la decodificación de medios.
• No afirmes una mejora de rendimiento sin mediciones de renderizados comparables.