Remotion CLI
La herramienta es remotion, de @remotion/cli. Cada comando se ejecuta a través de npx remotion <comando>, y cada uno de ellos empaqueta el proyecto primero, por lo que un error de tipo o una importación incorrecta se manifiesta como un fallo de empaquetado, no como un fallo de renderizado.
npx remotion --help y npx remotion <comando> --help son la autoridad en cuanto a banderas. Las banderas cambian entre versiones; lee la salida de ayuda en lugar de confiar en una lista, incluida esta. Lo que sigue a continuación es el ciclo y los modos de fallo, no una referencia de banderas.
El ciclo
| Etapa | Comando | Por qué |
|---|---|---|
| Scaffolding | npx create-video@latest --blank | Escribe un package.json, remotion.config.ts y tsconfig correctos |
| Verificación de tipos | npx tsc --noEmit | La puerta más barata; detecta desviaciones de esquema/prop antes de cualquier renderizado |
| Listar | npx remotion compositions | Confirma que el id que estás a punto de renderizar realmente existe |
| Probar un fotograma | npx remotion still <id> out/probe.png --frame=<n> | Segundos, no minutos; el caballo de batalla de la iteración |
| Revisar | npx remotion studio | Ponlo en manos del usuario; ellos exploran y editan las props ellos mismos |
| Renderizar | npx remotion render <id> out/video.mp4 | Solo después de que el usuario lo apruebe |
| Enviar remotamente | npx remotion bundle → npx remotion lambda render <url> <id> | Renderizado distribuido; necesita infraestructura AWS desplegada |
Prueba fotogramas fijos antes de renderizar
Un renderizado completo de una composición de 45 segundos a 1080p cuesta minutos. Un fotograma fijo cuesta segundos y responde la mayoría de las preguntas: ¿está el texto dentro del encuadre?, ¿se cargó el recurso?, ¿es correcto el color?. Prueba el punto medio de cada escena, mira cada imagen, y solo entonces renderiza.
npx remotion still launch out/s1.png --frame=45
npx remotion still launch out/s2.png --frame=180
Nunca reportes una composición como funcional basándote únicamente en un empaquetado exitoso. Mira los píxeles.
Studio es la superficie de revisión, no tu depurador
npx remotion studio sirve el proyecto con una línea de tiempo, un editor de props impulsado por el esquema Zod, y una exploración fotograma a fotograma precisa. Ponlo en manos del usuario para su aprobación. Para tu propia verificación, prefiere las pruebas con still: son programables y puedes ver el resultado sin pedirle al usuario que describa lo que ve.
Paso de props
--props toma una cadena JSON o una ruta a un archivo JSON, y sobrescribe defaultProps:
npx remotion render launch out/video.mp4 --props='{"productName":"Acme"}'
Una prop que falla el esquema Zod de la composición hace que el renderizado falle estrepitosamente. Ese es el propósito de declarar el esquema, así que manténlo preciso.
Renderizado por lotes
No hay un subcomando de lote. Itera en el shell sobre ids o cargas de props:
for id in $(npx remotion compositions --quiet); do
npx remotion render "$id" "out/$id.mp4"
done
Para muchos renderizados de una misma composición sobre un conjunto de datos, prefiere renderMedia() de @remotion/renderer en un script de Node: empaqueta una vez en lugar de una vez por renderizado, lo que domina el tiempo real.
Rendimiento del renderizado
--concurrency=<n>establece trabajadores en paralelo. El valor predeterminado es la mitad de los núcleos de la CPU con un máximo de 8; el máximo es el número de núcleos, y pedir más es un error, no un límite. En una máquina con poca memoria, reducirlo soluciona fallos que parecen errores del renderizador.--jpeg(en lugar del formato predeterminado PNG) es una gran aceleración cuando la composición no tiene transparencia que preservar.npx remotion benchmarkmide un renderizado real, así que úsalo para justificar un cambio de concurrencia o códec en lugar de adivinar.npx remotion gpuinforma qué acelerará realmente el navegador. Vale la pena verificarlo antes de culpar a un sombreador o un filtro pesado por un renderizado lento.
Diagnóstico de fallos
| Síntoma | Causa probable |
|---|---|
| El empaquetado falla | Un error de tipo o una importación incorrecta. Ejecuta npx tsc --noEmit para la versión legible del mismo error. |
| "No composition with id …" (No hay composición con id …) | El id en Root.tsx difiere del que pasaste. npx remotion compositions lo resuelve. |
| El renderizado se cuelga y luego agota el tiempo | Un delayRender() sin su correspondiente continueRender(). Cada manejador de retardo debe ser liberado. |
| Cada fotograma se ve como el fotograma 0 | Una animación/transición CSS, o requestAnimationFrame. El renderizador no avanza el reloj del navegador. |
| La animación parpadea o titila fotograma a fotograma | Math.random() sin semilla. Usa random(seed). |
| El movimiento funciona al explorar hacia adelante, se rompe en un salto | Animación basada en estado. En su lugar, deriva de useCurrentFrame(). |
| Recurso 404 solo en un renderizado Lambda o empaquetado | Una ruta hardcodeada en lugar de staticFile(). |
| Error de versiones sin sentido | Paquetes Remotion no coincidentes. npx remotion versions reporta la discrepancia. |
| Falta de memoria a mitad del renderizado | Concurrencia demasiado alta para la máquina. Reduce --concurrency. |
Muestra la salida de error real cuando reportes un fallo. No parafrasees un stack trace.
Dónde fueron a parar las capacidades de la CLI retirada HyperFrames
La antigua CLI hyperframes agrupaba comandos de autoría, medios y QA que el CLI de Remotion no tiene. Nada de lo siguiente es un comando de Remotion, así que no intentes ejecutarlos:
| Comando retirado | Dónde vive la capacidad ahora |
|---|---|
init | npx create-video@latest --blank, luego /hyperframes-core → references/project-structure.md |
lint, check, layout, validate | npx tsc --noEmit más pruebas con still. El contrato data-* que esas pasarelas imponían ya no existe. |
snapshot, compare, grade-compare | npx remotion still en fotogramas elegidos; compara los PNGs con tus propias herramientas. |
preview, play, present | npx remotion studio |
add, catalog | /hyperframes-registry |
capture | /product-launch-video (captura de sitio) y /media-use |
tts, transcribe, remove-background | /media-use |
beats, keyframes | /hyperframes-creative (planificación de ritmos), /hyperframes-keyframes |
cloud, publish | npx remotion bundle + remotion lambda / remotion cloudrun, o tu propio hosting |
skills, docs, upgrade, doctor | estas skills están distribuidas en este repositorio; npx remotion upgrade y npx remotion versions |
Si un workflow, skill o archivo de referencia aún te indica que ejecutes npx hyperframes <cualquier cosa>, esa instrucción está desactualizada. Haz el equivalente en Remotion de la tabla anterior y menciona en tu resumen que encontraste un puntero obsoleto, para que pueda ser corregido.