Fluxo de Criação de Animação de Gráfico de Velas (Candlestick) no Remotion
Este skill documenta o processo completo de criação de um gráfico de velas do S&P 500 no projeto Remotion vibe-motion-app.
Pré-requisitos
- Projeto Remotion 4.0.438 configurado com React 19 + TailwindCSS v4
- Arquitetura de plugins:
motion/define as cenas,remotion/gerencia o pipeline de composições Remotion - pnpm como gerenciador de pacotes
Passo 1: Obter Dados Financeiros
A API do Yahoo Finance fornece dados históricos gratuitos de OHLC (sem necessidade de chave de API).
Crie o arquivo scripts/fetch-sp500-data.mjs:
// Principal: chamada à API Yahoo Finance Chart
const url = `https://query1.finance.yahoo.com/v8/finance/chart/%5EGSPC?period1=${PERIOD1}&period2=${PERIOD2}&interval=1wk`;
const resp = await fetch(url);
const json = await resp.json();
const result = json.chart?.result?.[0];
const ts = result.timestamp;
const quote = result.indicators.quote[0];
// Extrair { t: timestamp, o: open, h: high, l: low, c: close }
Salve em public/data/sp500-weekly.json, para ser carregado pelo Remotion via staticFile().
Parâmetros:
%5EGSPC= Símbolo Yahoo do S&P 500 (codificação URL de^GSPC)interval=1wk= Semanal; opções:1d,1moperiod1/period2= Timestamps Unix, cobrindo aproximadamente 40 anos (1984-2026)
Passo 2: Criar a Estrutura de Arquivos do Plugin
Cada plugin Remotion precisa de 4 arquivos principais + uma predefinição de renderização:
motion/plugin-exemplo/
config.js → Parâmetros padrão
timeline.js → Contexto da cena + cálculo da animação quadro a quadro
Scene.jsx → Componente React (desenho no Canvas)
plugin.js → Objeto de registro do plugin
render-presets/
default.json → Predefinição de renderização
2a. config.js — Parâmetros Padrão
export const DEFAULT_LAYOUT_PARAMS = Object.freeze({
videoWidth: 1920, // 16:9 paisagem
videoHeight: 1080,
});
export const DEFAULT_ANIMATION_PARAMS = Object.freeze({
durationSeconds: 28, // Duração total da animação
title: "S&P 500",
subtitle: "Últimos 40 anos · Gráfico Semanal de Velas",
});
export const DEFAULT_MOTION_PROPS = Object.freeze({
...DEFAULT_LAYOUT_PARAMS,
...DEFAULT_ANIMATION_PARAMS,
});
2b. timeline.js — Lógica de Animação
Deve implementar três funções principais:
// 1. Contexto da cena: validar e converter tipos de todos os parâmetros
export const resolveXxxSceneContext = (pluginParams) => { ... }
// 2. Cálculo da duração: durationSeconds * fps
export const getXxxDurationInFrames = ({ fps, sceneContext }) => { ... }
// 3. Props por quadro: calcular progress e outros valores de animação a partir de frame/fps
export const buildXxxSceneProps = ({ frame, fps, loop, sceneContext }) => { ... }
Princípio de design fundamental: todo estado da animação depende apenas do parâmetro frame, atendendo aos requisitos de renderização paralela do Remotion.
2c. Scene.jsx — Componente de Desenho no Canvas
Use <canvas> em vez de muitos elementos DOM para melhor desempenho.
Modo de carregamento de dados:
const [dataHandle] = useState(() => delayRender("Carregando dados"));
useEffect(() => {
fetch(staticFile("data/exemplo.json"))
.then(r => r.json())
.then(data => { setData(data); continueRender(dataHandle); })
.catch(err => cancelRender(err));
}, [dataHandle]);
Lógica principal de desenho no Canvas:
const draw = useCallback(() => {
const ctx = canvas.getContext("2d");
const dpr = window.devicePixelRatio || 1;
// Adaptação para telas de alta resolução
canvas.width = W * dpr;
canvas.height = H * dpr;
ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
// 1. Preenchimento de fundo
// 2. Linhas de grade + escala de preços no eixo Y
// 3. Desenho das velas (pavio + corpo)
// 4. Rótulos de anos no eixo X
// 5. Título/subtítulo/informações estatísticas
// 6. Barra de progresso
}, [data, progress, ...]);
useEffect(() => { draw(); }, [draw]);
Parâmetros chave do desenho das velas:
const CANDLE_GAP_RATIO = 0.28; // Proporção do espaçamento entre velas
const CANDLE_FADE_FRAMES = 22; // Quadros da animação de entrada
const MAX_CANDLE_W = 8; // Largura máxima da vela (após escala)
const MIN_CANDLE_W = 0.6; // Largura mínima da vela
// Largura da vela se ajusta automaticamente conforme o número visível
const slotW = plotWidth / visibleCount;
const bodyW = Math.max(MIN_CANDLE_W, Math.min(MAX_CANDLE_W * scale, slotW * (1 - GAP_RATIO)));
Animação de entrada (fade-in + crescimento a partir da base):
const appearFrame = (i / (N - 1)) * revealEndFrame;
const candleAge = currentFrame - appearFrame;
const fadeAlpha = Math.min(1, Math.max(0, candleAge / CANDLE_FADE_FRAMES));
// Animação de crescimento
if (candleAge < CANDLE_FADE_FRAMES && candleAge > 0) {
const growT = easeOutCubic(candleAge / CANDLE_FADE_FRAMES);
displayBodyBottom = lerp(lowY, bodyBottom, growT);
}
ctx.globalAlpha = fadeAlpha;
// ... desenhar pavio + corpo ...
ctx.globalAlpha = 1;
Cores do tema escuro:
const COLORS = {
bg: "#1a1a19",
grid: "#2c2c2a",
upBorder: "#e66767", // Borda da vela de alta (vermelho)
upFill: "rgba(230,103,103,0.15)", // Preenchimento da vela de alta (semitransparente)
downFill: "#199e70", // Preenchimento da vela de baixa (verde)
textPrimary: "#ffffff",
textSecondary: "#c3c2b7",
textMuted: "#898781",
accent: "#3987e5",
};
2d. plugin.js — Registro do Plugin
export const xxxPlugin = Object.freeze({
id: "ID do Plugin",
defaultProps: DEFAULT_MOTION_PROPS,
SceneComponent: XxxScene,
waitForSceneLayoutReady: true, // Aguarda o carregamento dos dados
resolveSceneContext: (params) => ...,
getDurationInFrames: ({ fps, sceneContext }) => ...,
buildSceneProps: ({ frame, fps, loop, sceneContext }) => ...,
getLayout: ({ sceneContext }) => sceneContext.layout,
});
waitForSceneLayoutReady: true garante que o componente Scene chame onAutoLayoutReady() somente após o carregamento dos dados antes de iniciar a renderização dos quadros.
2e. render-presets/default.json
{
"title": "S&P 500",
"subtitle": "Últimos 40 anos · Gráfico Semanal de Velas",
"videoWidth": 1920,
"videoHeight": 1080,
"durationSeconds": 28
}
Passo 3: Registrar a Composição
Modifique motion/project.js para alternar ACTIVE_COMPOSITION para o novo plugin:
import { xxxPlugin } from "./plugin-exemplo/plugin.js";
export const ACTIVE_COMPOSITION = Object.freeze({
id: "SP500Kline",
fps: 30,
plugin: xxxPlugin,
});
Passo 4: Validar e Renderizar
# Validar o registro da composição
pnpm run remotion:compositions
# Iniciar o Studio (suporta arrastar linha do tempo, ajustar parâmetros)
pnpm run dev
# Renderizar um quadro estático
npx remotion still SP500Kline out/frame.png --frame=420
# Renderizar o vídeo completo
npx remotion render SP500Kline out/output.mp4
# Renderizar usando uma predefinição
REMOTION_PROPS_FILE=motion/plugin-exemplo/render-presets/default.json pnpm run remotion:render
Problemas Comuns
Problema de CORS com a API Yahoo Finance
No ambiente de renderização do Remotion (navegador headless Node.js) não há problemas de CORS.
Se houver CORS na pré-visualização do navegador, use staticFile() para carregar um JSON local pré-obtido.
Canvas borrado em telas de alta DPI
Sempre multiplique por devicePixelRatio:
canvas.width = W * dpr;
canvas.height = H * dpr;
ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
Largura muito pequena devido a muitas velas
Defina uma largura mínima de 0.6px. Quando slotW < 1, reduza a proporção de espaçamento ou agregue os dados.
Controle da progressão da animação
Use funções de easing segmentadas:
- Os primeiros 3% estabelecem rapidamente a linha de base
- Os 90% intermediários revelam em velocidade constante
- O final pode desacelerar ligeiramente para aumentar o impacto dramático