Communitygithub.com

MattiaIppoliti/tia-skills

Gerencia o ciclo de desenvolvimento do Remotion CLI: scaffolding, estúdio, verificação de tipos, composições, sondagens de stills, renderização única e em lote, bundle, renderização em Lambda e Cloud Run, benchmark, versões, upgrade e verificações de GPU. Também usado ao diagnosticar uma falha de build ou renderização, ou ao buscar uma capacidade que o antigo CLI HyperFrames costumava ter.

O que é tia-skills?

Esta skill automatiza o ciclo completo de desenvolvimento com o Remotion CLI, desde a criação de um novo projeto até a renderização remota em lote. Ela é projetada para desenvolvedores que usam o Remotion para gerar vídeos programaticamente, oferecendo comandos essenciais como `npx remotion still` para sondagens rápidas de frames, `npx remotion studio` para revisão visual, e `npx remotion render` para produção final. A skill também fornece diagnósticos detalhados para falhas comuns de build e renderização, além de um mapeamento completo das capacidades do antigo CLI HyperFrames para seus equivalentes no Remotion. Ela suporta plataformas como AWS Lambda e Google Cloud Run para renderização distribuída.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MattiaIppoliti/tia-skills/tree/HEAD/skills/video/hyperframes-cli

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Remotion CLI

A ferramenta é remotion, do pacote @remotion/cli. Cada comando é executado através de npx remotion <comando>, e todos eles empacotam o projeto primeiro, para que um erro de tipo ou uma importação ruim apareça como uma falha de empacotamento, e não como uma falha de renderização.

npx remotion --help e npx remotion <comando> --help são a autoridade máxima sobre flags. As flags mudam entre versões; leia a saída de ajuda em vez de confiar em uma lista, inclusive esta. O que está abaixo é o ciclo e os modos de falha, não uma referência de flags.

O ciclo

EtapaComandoPor quê
Scaffoldnpx create-video@latest --blankescreve um package.json, remotion.config.ts, tsconfig compatíveis
Verificar tiposnpx tsc --noEmita verificação mais barata; captura drift de esquema/prop antes da render
Listarnpx remotion compositionsconfirme que o id que você está prestes a renderizar realmente existe
Sondar um framenpx remotion still <id> out/probe.png --frame=<n>segundos, não minutos; o cavalo de batalha da iteração
Revisarnpx remotion studioentregue ao usuário; ele navega e edita props por conta própria
Renderizarnpx remotion render <id> out/video.mp4somente após a aprovação do usuário
Enviar remotonpx remotion bundle → npx remotion lambda render <url> <id>renderização distribuída; precisa de infraestrutura AWS implantada

Sondar stills antes de renderizar

Uma renderização completa de uma composição de 45 segundos em 1080p leva minutos. Um still leva segundos e responde à maioria das perguntas: o texto está dentro do quadro, o asset carregou, a cor está certa. Sondar o ponto médio de cada cena, olhar para cada imagem, e só então renderizar.

npx remotion still launch out/s1.png --frame=45
npx remotion still launch out/s2.png --frame=180

Nunca relate que uma composição está funcionando com base em um empacotamento bem-sucedido. Olhe para os pixels.

O Studio é a superfície de revisão, não seu depurador

npx remotion studio serve o projeto com uma linha do tempo, um editor de props orientado pelo esquema Zod e navegação quadro a quadro precisa. Entregue ao usuário para aprovação. Para sua própria verificação, prefira as sondagens com still: elas são programáveis e você pode olhar a saída sem pedir ao usuário para descrever o que vê.

Passando props

--props aceita uma string JSON ou um caminho para um arquivo JSON e substitui defaultProps:

npx remotion render launch out/video.mp4 --props='{"productName":"Acme"}'

Uma prop que falha no esquema Zod da composição falha a renderização de forma ruidosa. Esse é o objetivo de declarar o esquema, então mantenha-o preciso.

Renderização em lote

Não há subcomando de lote. Faça um loop no shell sobre ids ou cargas de props:

for id in $(npx remotion compositions --quiet); do
  npx remotion render "$id" "out/$id.mp4"
done

Para muitas renderizações de uma composição sobre um conjunto de dados, prefira renderMedia() do pacote @remotion/renderer em um script Node: ele empacota uma vez em vez de uma vez por renderização, o que domina o tempo real.

Performance de renderização

  • --concurrency=<n> define o número de workers paralelos. O padrão é metade dos núcleos da CPU, limitado a 8; o máximo é o número de núcleos, e pedir mais é um erro, não um ajuste. Em uma máquina com pouca memória, reduzi-lo corrige travamentos que parecem bugs do renderizador.
  • --jpeg (em vez do formato de quadro PNG padrão) é uma grande aceleração quando a composição não tem transparência para preservar.
  • npx remotion benchmark mede uma renderização real, então use-o para justificar uma mudança de concorrência ou codec em vez de adivinhar.
  • npx remotion gpu informa o que o navegador realmente irá acelerar. Vale a pena verificar antes de culpar um shader ou um filtro pesado por uma renderização lenta.

Diagnosticando falhas

SintomaCausa provável
Empacotamento falhaUm erro de tipo ou uma importação ruim. Execute npx tsc --noEmit para a versão legível do mesmo erro.
"Nenhuma composição com id …"O id em Root.tsx difere daquele que você passou. npx remotion compositions resolve.
Renderização trava e depois expiraUm delayRender() sem um continueRender() correspondente. Cada handle de atraso deve ser liberado.
Todo quadro parece o quadro 0Uma animação/transição CSS, ou requestAnimationFrame. O renderizador não avança o relógio do navegador.
Animação pisca ou tremula quadro a quadroMath.random() sem semente. Use random(seed).
Movimento funciona ao avançar, mas quebra em um saltoAnimação orientada por estado. Derive de useCurrentFrame().
Asset 404 apenas em Lambda ou renderização empacotadaUm caminho fixo em vez de staticFile().
Erro de versões sem sentidoPacotes Remotion incompatíveis. npx remotion versions relata a divergência.
Falta de memória durante a renderizaçãoConcorrência muito alta para a máquina. Reduza --concurrency.

Mostre a saída de erro real ao relatar uma falha. Não parafraseie um stack trace.

Para onde foram as capacidades do antigo CLI HyperFrames

O antigo CLI hyperframes agrupava comandos de autoria, mídia e controle de qualidade que o CLI do Remotion não possui. Nada abaixo é um comando do Remotion, então não tente executá-los:

Comando retiradoOnde a capacidade está agora
initnpx create-video@latest --blank, depois /hyperframes-core → references/project-structure.md
lint, check, layout, validatenpx tsc --noEmit mais sondagens still. O contrato data-* que essas verificações impunham não existe mais.
snapshot, compare, grade-comparenpx remotion still nos quadros escolhidos; compare os PNGs com suas próprias ferramentas.
preview, play, presentnpx remotion studio
add, catalog/hyperframes-registry
capture/product-launch-video (captura de site) e /media-use
tts, transcribe, remove-background/media-use
beats, keyframes/hyperframes-creative (planejamento de batidas), /hyperframes-keyframes
cloud, publishnpx remotion bundle + remotion lambda / remotion cloudrun, ou sua própria hospedagem
skills, docs, upgrade, doctorestas skills são fornecidas neste repositório; npx remotion upgrade e npx remotion versions

Se um arquivo de skill ou referência de workflow ainda instruir você a executar npx hyperframes <qualquer-coisa>, essa instrução está desatualizada. Faça o equivalente no Remotion da tabela acima e diga em seu resumo que encontrou um ponteiro desatualizado, para que possa ser corrigido.

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

MattiaIppoliti/tia-skills

The technique catalog: five velocity-matched SEAMS (zoom-through, INVERSE zoom-through, cut-the-curve, waterfall cut, rack-focus blur-cut) plus the two in-scene techniques — waterfall ENTRY (staggered arrival cascades for title cards / segment openers) and the nudge curve (slow-fast-slow three-phase group slides). Covers partial-travel (~12% of frame) velocity matching via mirrored power4 eases, the Z scale-sign rule, size-scaled blur (10px text / 18-20px full-frame), word-by-word staggered cuts, cascade pacing by element weight, and the 10/65/25 slide ratio. Read before authoring any transition, text-beat handoff, kinetic text entry, or group reposition. [depth, zoom, inverse-zoom, scale-sign, mirrored-zoom, rack-focus, pacing, velocity, cut-the-curve, waterfall, stagger, cascade, kinetic-text, title-card, segment-opener, nudge, slide, easing, group-motion, z-depth, motion-graphics, cinematic, transition, blur, directional-continuity]

MattiaIppoliti/tia-skills

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

MattiaIppoliti/tia-skills

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

MattiaIppoliti/tia-skills

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

MattiaIppoliti/tia-skills

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), or automation envelopes drawn on a track's volume or any effect parameter. Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

MattiaIppoliti/tia-skills

The composition contract for building one renderable Remotion project. Use for project structure, `<Composition>` registration, `<Sequence>` timing, layer/track ordering, scene components, props and schemas, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition code.

Habilidades Relacionadas