gnipbao/framevelo

O que framevelo faz?

O FrameVelo transforma uma página que desenha seus quadros a partir de código em um MP4. Os quadros permanecem na GPU (drawElementImage ou no canvas da página) e vão diretamente para o codificador de hardware, então uma renderização consome uma fração da CPU e memória de renderizadores baseados em captura de tela. Projetos HyperFrames são compilados pelo pipeline oficial do HyperFrames; o FrameVelo substitui apenas a captura e a codificação.

Como chamar

Use as ferramentas MCP deste plugin quando estiverem disponíveis. Na primeira inicialização, o plugin instala o FrameVelo em ~/.cache/framevelo (cerca de um minuto); se as ferramentas estiverem ausentes logo após instalar o plugin, aguarde e reconecte (/mcp), ou use a CLI abaixo.

• render: renderiza; retorna o caminho de saída, contagem de quadros, tamanho, tempos, avisos e as últimas linhas de log.
• doctor: verifica suporte a Node, FFmpeg, Chrome, drawElementImage, codificadores de hardware e HyperFrames.
• install_browser: baixa o chrome-headless-shell (cerca de 100 MB) quando nenhum Chrome 151+ está instalado.

Sem as ferramentas, execute a CLI. --json imprime o resultado (ou {"error": ...}) no stdout:

npx -y -p github:gnipbao/framevelo -p @hyperframes/[email protected] -p @hyperframes/[email protected] framevelo render /abs/project -o /abs/out.mp4 --json -q

A primeira execução do npx instala por cerca de meio minuto. Se você for renderizar com frequência, sugira que o usuário instale uma vez: npm install -g github:gnipbao/framevelo @hyperframes/[email protected] @hyperframes/[email protected]. A CLI aceita as mesmas opções da ferramenta, como flags (--frames 30 --quality draft). framevelo render --help lista todas.

Use caminhos absolutos. Execute uma renderização por vez: elas compartilham o único codificador de hardware, e o servidor MCP as enfileira de qualquer forma.

Fluxo de trabalho

1. Encontre a entrada: um diretório de projeto com index.html, ou um arquivo .html. Duração, fps e tamanho vêm da página (HyperFrames data-duration/data-fps/data-width, window.__framevelo.duration, o comprimento da timeline GSAP, window.__comp). Passe-os apenas para sobrescrever.
2. Pré-visualize um trecho quando a composição é nova ou acabou de ser alterada: { input, output: "/tmp/preview.mp4", start: 2, frames: 30, quality: "draft" }. Isso leva segundos. Veja um quadro: ffmpeg -v error -ss 0.5 -i /tmp/preview.mp4 -frames:v 1 /tmp/preview.png, depois visualize o PNG.
3. Renderize por completo com os padrões. Adicione scale: 2 para 4K a partir de um layout 1080p, ou subframes: 3 para motion blur.
4. Verifique o resultado: frames é a contagem que você esperava; audio é verdadeiro quando a composição tem som; leia warnings. screenshotFrames > 0 significa que alguns intervalos falharam na verificação e foram capturados por screenshot (ainda corretos, apenas mais lentos).
5. Relate o caminho de saída, duração, tamanho e quanto tempo levou (wallMs).

Tornando uma página renderizável

Cada quadro deve ser uma função pura do tempo. O FrameVelo busca a página através do primeiro destes que encontrar:

1. window.__framevelo = { seek(t), duration, fps }. seek pode retornar uma promise.
2. window.__seek(t), com um window.__duration opcional.
3. Uma timeline GSAP pausada em window.__timelines.main (ou na primeira chave).

<canvas id="scene" width="1920" height="1080"></canvas>
<script>
  const g = document.getElementById("scene").getContext("2d");
  function draw(t) {
    g.fillStyle = "#05060a";
    g.fillRect(0, 0, 1920, 1080);
    g.fillStyle = "#6cf";
    g.fillRect(200 + 300 * t, 500, 120, 120);
  }
  window.__framevelo = { duration: 4, seek: draw };
</script>

• Coloque filmagens na timeline com <video data-start="1.5" src="clip.mp4"> (opcional data-media-start, data-duration, data-playback-rate). O FrameVelo busca o quadro exato; fontes long-GOP recebem um proxy all-intra em cache.
• Math.random é seedado, então as renderizações se repetem.
• Loops de requestAnimationFrame, transições CSS, animações com Date.now() e performance.now() não podem ser buscadas. Mova-as para seek(t) ou uma timeline GSAP pausada.
• Aguarde ativos dentro da página (fontes, imagens) antes de expor o driver, ou retorne uma promise de seek.

Opções que vale a pena conhecer

Necessidade	Argumentos
Verificação rápida	frames: 30, quality: "draft", start: <s>
4K a partir de um layout 1080p	scale: 2
Página vertical sem tamanho declarado	viewport: "1080x1920"
Arquivos menores	codec: "hevc"
Motion blur	subframes: 3 (e shutter, padrão 0.5)
Substituir a trilha sonora	audio: "/abs/music.m4a"
Capturar um elemento	selector: "#stage"
DOM transparente sobre uma cor	background: "#000"
Skill code-video não encontrada	mounts: {"/@skill/": "/abs/path/to/code-video"}
Projeto HyperFrames como página simples	hyperframes: false

Quando falha

Mensagem	O que fazer
Chrome not found	Chame install_browser (ou execute framevelo browser install), depois renderize novamente.
FFmpeg / FFprobe falhando em doctor	Peça ao usuário para instalar o FFmpeg (brew install ffmpeg). Não instale software do sistema por conta própria.
The page exposes no way to seek time	A página precisa de um driver de tempo; veja "Tornando uma página renderizável".
Unknown duration	Passe duration ou frames, ou declare a duração na página.
The composition failed to set up	Um erro de script na composição. Corrija a página; a mensagem carrega o erro da página.
No element matches selector / Nothing to capture / has no size	Aponte selector para um elemento visível com tamanho, ou corrija o layout.
Rendering a HyperFrames project needs ... @hyperframes/producer	Use o comando npx -p @hyperframes/... acima, ou instale os pacotes ao lado do FrameVelo.
No paint event within ...	A página parou de pintar; geralmente um script travado. Verifique em um navegador.

As renderizações são atômicas: uma renderização falha ou cancelada não deixa arquivo de saída.