O que chartreel faz?
Crie vídeos curtos e honestos de animação de dados com o CLI chartreel. Você escolhe o gráfico,
modela os dados, escreve a história, renderiza e verifica o resultado. O renderizador só exibe
valores do CSV ou interpolações lineares entre duas linhas adjacentes.
0. Ferramentas
chartreel doctor # verifica ffmpeg, Chromium e fontes
Se chartreel estiver faltando:
pip install "git+https://github.com/Xkongai/chartreel" # ou: uv tool install git+https://github.com/Xkongai/chartreel
python -m playwright install chromium # ignore se Chrome/Chromium já estiver instalado
# ffmpeg: macOS `brew install ffmpeg` · Ubuntu `sudo apt install ffmpeg` · Windows `winget install Gyan.FFmpeg`
# Texto chinês/japonês/coreano no Linux: `sudo apt install fonts-noto-cjk fonts-noto-color-emoji`
1. Obtenha dados reais — nunca invente números
- Use o arquivo do usuário quando ele fornecer um. Mantenha-o inalterado; remodele em um novo CSV.
- Caso contrário, busque de uma fonte primária e citável e salve a resposta bruta ao lado do CSV.
Veja
references/data-sources.md(API do Banco Mundial, Our World in Data, FRED, Eurostat, institutos nacionais de estatística). - Se o usuário digitar números no chat, use exatamente esses e cite-os como "fornecido pelo usuário".
- Nunca preencha lacunas de memória. Células em branco são permitidas: lacunas internas são interpoladas e
chartreel validaterelata quantas; lacunas iniciais/finais significam que a série está ausente. - Registre o nome da fonte, código do indicador ou URL e licença; eles vão em
--source.
2. Escolha o modelo
| História | Modelo | Formato dos dados |
|---|---|---|
| Quem é o #1 ao longo do tempo, ultrapassagens ("Ranking do PIB 1990–2024") | race | período × série (5–40 séries) |
| Como algumas coisas cresceram ou se cruzaram ("China vs Índia população") | line | período × série (2–8 séries) |
| Um número impressionante, depois comparações "× N" ("de US$ 191B para US$ 18,7T") | counter | label,value[,note] (2–5 linhas) |
| Como um todo é dividido e muda ("população mundial por região") | share | período × partes (2–10 partes, não negativas) |
3. Modele o CSV
ano,China,Índia,Estados Unidos # largo: primeira coluna = período, uma coluna por série
1990,361560229446,320979026420,5963144000000
ano,nome,valor # longo: também aceito, pivotado automaticamente
1990,China,361560229446
rótulo,valor,nota # counter
1980年,191487500000,Início da reforma e abertura
Regras: períodos em ordem crescente; números simples (vírgulas, $, % são removidos); UTF-8 (BOM ok).
Para intervalos longos, mantenha linhas anuais — mais linhas fornecem movimento mais suave e mais verdadeiro.
4. Escreva a história dos dados
- Gancho (título): a pergunta ou a surpresa, ≤ 2 linhas curtas. "As maiores economias do mundo, 1990–2024", "中印人口之争".
- Contexto (subtítulo): unidades e escopo — "PIB, US$ corrente".
- Momentos-chave (
--note "PERÍODO: texto"): 1–3 eventos. Cada um deve ser visível nos dados naquele período (verifique o CSV antes de escrever "X passa Y"). - Conclusão (
--takeaway): uma frase calculada a partir do CSV. Faça a aritmética no código, por exemplo,python -c "print(18729668435848/361560229446)"→ 51,8 → "O PIB da China cresceu 52× em 34 anos". Arredonde honestamente. - Fonte (
--source): sempre. Exemplo:Banco Mundial WDI (NY.GDP.MKTP.CD), CC BY 4.0.
Coloque tudo em uma configuração JSON para que a renderização seja reproduzível (references/options.md lista cada chave):
{
"template": "race", "theme": "dark", "aspect": "9:16", "duration": 15,
"title": "As maiores economias do mundo, 1990–2024", "subtitle": "PIB, US$ corrente",
"source": "Banco Mundial WDI (NY.GDP.MKTP.CD), CC BY 4.0",
"takeaway": "O PIB da China cresceu 52× em 34 anos", "prefix": "$", "top": 10,
"notes": ["2010: China ultrapassa o Japão"],
"series": {"China": {"emoji": "🇨🇳", "color": "#FF6B6B"}}
}
Vídeos em chinês: adicione "locale": "zh" (números em 万/亿/万亿) e escreva título/notas em chinês.
4b. Escolha um preset de estilo (opcional, recomendado para vídeo social)
--style agrupa um tema, um cartão de gancho, um contador de ano, a decoração do #1 e efeitos. Cada preset mantém
os números exatos: o gancho cobre apenas os primeiros ~1,5 s, antes dos dados começarem a se mover, e nada é desenhado
sobre a conclusão ou (para corridas) entre as barras.
--style | Aparência | Bom para |
|---|---|---|
classic (padrão) | limpo, sem gancho | docs, slides, X |
cinematic | dourado sobre verde-marinho, gancho letterbox, vinheta, ano rolante, coroa no #1, zoom | YouTube Shorts, Bilibili |
news | faixas de TV: faixa de gancho "DADOS", números de classificação, medalhão de ano vermelho, faixa de fonte | tópicos sérios, Weibo/X |
editorial | papel, gancho de máquina de escrever, barras cinza + --highlight "A,B", ano serifado grande | Xiaohongshu, newsletters |
arcade | néon, confete + soco quando uma barra atinge o top 3, subida ▲, listras de velocidade | Douyin/TikTok, jogos |
retro | VHS: linhas de varredura, texto cromático, selo PLAY, gancho de máquina de escrever | tópicos nostálgicos |
glass | bolhas de cor flutuantes, painel de gráfico fosco, barra de progresso superior | tópicos de tecnologia/produto |
bold | texto grande do Douyin: palavras de gancho destacadas gigantes, ano enorme, números de classificação | Douyin/Kuaishou |
Opções de história que acompanham os presets:
--hook "Quem tem a maior economia do mundo?": a pergunta do primeiro segundo (padrão é o título;--no-hookdesliga). Deve ser respondível a partir dos dados.--cta "Siga para mais histórias de dados": uma pequena linha sob a conclusão.- Ajuste fino:
--fx bg,vignette,letterbox,scanlines,punch,confetti,trails,arrows,glasssubstitui os efeitos do preset,--no-fx confettiremove um;--year-style watermark|roll|row|badge,--progress timeline|top|both|none,--highlight leader|"A,B",--leader/--no-leader,--ranks,--safe-zone/--no-safe-zone(presets mantêm distância dos botões do Douyin/Shorts e área de legenda).chartreel styleslista tudo. --audio musica.mp3 [--audio-fade 1.0]coloca uma faixa que o usuário possui ou licenciada sob o MP4 (cortada, fade in/out). Nunca baixe música com direitos autorais; o chartreel não inclui nenhuma.
O "theme" de um arquivo de configuração é ignorado quando você passa --style na linha de comando (passe --theme para substituir).
5. Valide, renderize, verifique
chartreel validate dados.csv -c historia.json # verificação de esquema + opções, erros de linha/coluna claros
chartreel render dados.csv -c historia.json -o saida/ # saida/dados.mp4, saida/dados.gif, saida/dados-capa.png
chartreel preview dados.csv -c historia.json -o saida/ # opcional: player HTML autossuficiente para navegar
Presets de plataforma: Douyin/TikTok/Shorts/Reels -a 9:16 -d 15 (10–30 s) · Xiaohongshu -a 3:4 ou 9:16 ·
Bilibili/YouTube/X -a 16:9 · Feed do X/Instagram -a 1:1 ou 4:5. Ritmo: cerca de 0,3–0,6 s por período para uma corrida.
Rascunhos rápidos: --size 540 --fps 15. --jobs N define trabalhadores paralelos. Uma corrida de 12 s 1080×1920 renderiza em
cerca de 10–30 s dependendo da CPU.
Em seguida, olhe para a saída antes de entregá-la:
ffmpeg -v error -i saida/dados.mp4 -vf "fps=1,scale=360:-1,tile=4x3" -frames:v 1 saida/contato.png
Abra a capa e a folha de contato. Verifique: título não cortado, rótulos legíveis, sem caixas CJK tofu (□), a conclusão corresponde aos números, a fonte está visível, o gancho (primeiro segundo) é lido de uma só vez. Corrija e renderize novamente se necessário.
6. Entregue
Relate os caminhos do MP4, GIF e capa, a fonte e licença, e como a conclusão foi calculada. Diga claramente se alguma célula foi interpolada (validate imprime). Não afirme uma tendência que os dados não mostram.
Regras de precisão (não negociáveis)
- Valores na tela = valores do CSV em cada período, interpolação linear entre eles. O modelo de contador conta até cada valor e depois mantém o número exato; diga isso se perguntado.
- Números derivados (proporções, crescimento, "ultrapassagens") devem ser calculados a partir do CSV, não lembrados.
- Nunca misture unidades ou moedas em um único gráfico; nunca compare valores nominais e reais silenciosamente.
- Sempre mostre a fonte. Mantenha o download bruto para que o usuário possa auditá-lo.