¿Qué hace chartreel?
Crea videos cortos de animación de datos honestos con la CLI chartreel. Tú eliges el gráfico,
das forma a los datos, escribes la historia, renderizas y verificas el resultado. El renderizador solo
muestra valores del CSV o interpolaciones lineales entre dos filas adyacentes.
0. Herramientas
chartreel doctor # verifica ffmpeg, Chromium y fuentes
Si falta chartreel:
pip install "git+https://github.com/Xkongai/chartreel" # o: uv tool install git+https://github.com/Xkongai/chartreel
python -m playwright install chromium # omitir si Chrome/Chromium ya está instalado
# ffmpeg: macOS `brew install ffmpeg` · Ubuntu `sudo apt install ffmpeg` · Windows `winget install Gyan.FFmpeg`
# Texto chino/japonés/coreano en Linux: `sudo apt install fonts-noto-cjk fonts-noto-color-emoji`
1. Obtén datos reales — nunca inventes números
- Usa el archivo del usuario cuando lo proporcione. Mantenlo sin cambios; remodela a un nuevo CSV.
- De lo contrario, obtén los datos de una fuente primaria y citable y guarda la respuesta cruda junto al CSV.
Consulta
references/data-sources.md(API del Banco Mundial, Our World in Data, FRED, Eurostat, oficinas nacionales de estadística). - Si el usuario escribe números en el chat, usa exactamente esos y cítalos como "proporcionados por el usuario".
- Nunca llenes vacíos de memoria. Las celdas en blanco están permitidas: los vacíos interiores se interpolan y
chartreel validateinforma cuántos; los vacíos iniciales/finales significan que la serie está ausente. - Registra el nombre de la fuente, el código del indicador o la URL, y la licencia; van en
--source.
2. Elige la plantilla
| Historia | Plantilla | Forma de los datos |
|---|---|---|
| Quién es el #1 a lo largo del tiempo, adelantamientos ("Ranking PIB 1990–2024") | race | período × series (5–40 series) |
| Cómo crecieron o se cruzaron algunas cosas ("Población China vs India") | line | período × series (2–8 series) |
| Un número impactante, luego comparaciones "×N" ("de $191B a $18.7T") | counter | etiqueta,valor[,nota] (2–5 filas) |
| Cómo se divide y cambia un total ("población mundial por región") | share | período × partes (2–10 partes, no negativas) |
3. Dale forma al CSV
año,China,India,Estados Unidos # ancho: primera columna = período, una columna por serie
1990,361560229446,320979026420,5963144000000
año,nombre,valor # largo: también aceptado, pivotado automáticamente
1990,China,361560229446
etiqueta,valor,nota # counter
1980年,191487500000,Inicio de la reforma y apertura
Reglas: períodos ascendentes; números simples (comas, $, % se eliminan); UTF-8 (BOM permitido).
Para rangos largos, mantén filas anuales — más filas dan un movimiento más suave y veraz.
4. Escribe la historia de los datos
- Gancho (título): la pregunta o la sorpresa, ≤ 2 líneas cortas. "Las economías más grandes del mundo, 1990–2024", "La lucha demográfica China-India".
- Contexto (subtítulo): unidades y alcance — "PIB, US$ corrientes".
- Momentos clave (
--note "PERÍODO: texto"): 1–3 eventos. Cada uno debe ser visible en los datos en ese período (verifica el CSV antes de escribir "X supera a Y"). - Conclusión (
--takeaway): una oración calculada a partir del CSV. Haz la aritmética en código, p. ej.python -c "print(18729668435848/361560229446)"→ 51.8 → "El PIB de China creció 52 veces en 34 años". Redondea honestamente. - Fuente (
--source): siempre. Ejemplo:Banco Mundial WDI (NY.GDP.MKTP.CD), CC BY 4.0.
Pon todo en un archivo de configuración JSON para que el renderizado sea reproducible (references/options.md lista cada clave):
{
"template": "race", "theme": "dark", "aspect": "9:16", "duration": 15,
"title": "Las economías más grandes del mundo, 1990–2024", "subtitle": "PIB, US$ corrientes",
"source": "Banco Mundial WDI (NY.GDP.MKTP.CD), CC BY 4.0",
"takeaway": "El PIB de China creció 52 veces en 34 años", "prefix": "$", "top": 10,
"notes": ["2010: China supera a Japón"],
"series": {"China": {"emoji": "🇨🇳", "color": "#FF6B6B"}}
}
Videos en chino: añade "locale": "zh" (números en 万/亿/万亿) y escribe el título/notas en chino.
4b. Elige un estilo predefinido (opcional, recomendado para video social)
--style agrupa un tema, una tarjeta de gancho, un contador de año, la decoración del #1 y efectos. Cada estilo mantiene
los números exactos: el gancho solo cubre los primeros ~1.5 s, antes de que los datos comiencen a moverse, y no se dibuja nada
sobre la conclusión ni (en carreras) entre barras.
--style | Aspecto | Bueno para |
|---|---|---|
classic (predeterminado) | limpio, sin gancho | documentos, diapositivas, X |
cinematic | dorado sobre verde azulado, gancho en letterbox, viñeta, año rodante, corona en el #1, acercamiento | YouTube Shorts, Bilibili |
news | bandas TV: banda de gancho "DATOS", números de rango, insignia de año roja, banda de fuente | temas serios, Weibo/X |
editorial | papel, gancho de máquina de escribir, barras grises + --highlight "A,B", año serif grande | Xiaohongshu, boletines |
arcade | neón, confeti + golpe cuando una barra llega al top 3, ascenso ▲, estelas de velocidad | Douyin/TikTok, juegos |
retro | VHS: líneas de barrido, texto cromático, sello PLAY, gancho de máquina de escribir | temas nostálgicos |
glass | manchas de color flotantes, panel de gráfico esmerilado, barra de progreso superior | temas tech/producto |
bold | texto grande estilo Douyin: palabras de gancho destacadas gigantes, año enorme, números de rango | Douyin/Kuaishou |
Opciones de historia que van con los estilos:
--hook "¿Quién tiene la economía más grande del mundo?": la pregunta del primer segundo (por defecto el título;--no-hooklo desactiva). Debe poder responderse desde los datos.--cta "Sígueme para más historias de datos": una línea pequeña debajo de la conclusión.- Ajuste fino:
--fx bg,vignette,letterbox,scanlines,punch,confetti,trails,arrows,glassreemplaza los efectos del estilo,--no-fx confettielimina uno;--year-style watermark|roll|row|badge,--progress timeline|top|both|none,--highlight leader|"A,B",--leader/--no-leader,--ranks,--safe-zone/--no-safe-zone(los estilos mantienen distancia de los botones de Douyin/Shorts y el área de subtítulos).chartreel styleslo lista todo. --audio music.mp3 [--audio-fade 1.0]coloca una pista que el usuario posee o tiene licencia bajo el MP4 (recortada, con fundido de entrada/salida). Nunca descargues música con derechos de autor; chartreel no incluye ninguna.
El "theme" del archivo de configuración se ignora cuando pasas --style en la línea de comandos (usa --theme para anularlo).
5. Valida, renderiza, verifica
chartreel validate data.csv -c story.json # verificación de esquema + opciones, errores claros de fila/columna
chartreel render data.csv -c story.json -o out/ # out/data.mp4, out/data.gif, out/data-cover.png
chartreel preview data.csv -c story.json -o out/ # opcional: reproductor HTML autónomo para examinar
Estilos por plataforma: Douyin/TikTok/Shorts/Reels -a 9:16 -d 15 (10–30 s) · Xiaohongshu -a 3:4 o 9:16 ·
Bilibili/YouTube/X -a 16:9 · X/Instagram feed -a 1:1 o 4:5. Ritmo: aproximadamente 0.3–0.6 s por período para una carrera.
Borradores rápidos: --size 540 --fps 15. --jobs N establece trabajadores paralelos. Una carrera de 12 s en 1080×1920 se renderiza en
aproximadamente 10–30 s dependiendo de la CPU.
Luego mira la salida antes de entregarla:
ffmpeg -v error -i out/data.mp4 -vf "fps=1,scale=360:-1,tile=4x3" -frames:v 1 out/contact.png
Abre la portada y la hoja de contacto. Verifica: título no cortado, etiquetas legibles, sin recuadros de tofu CJK (□), la conclusión coincide con los números, la fuente es visible, el gancho (primer segundo) se lee de un vistazo. Corrige y vuelve a renderizar si es necesario.
6. Entrega
Informa las rutas del MP4, GIF y portada, la fuente y licencia, y cómo se calculó la conclusión. Di claramente si alguna celda fue interpolada (validate lo imprime). No afirmes una tendencia que los datos no muestren.
Reglas de precisión (no negociables)
- Valores en pantalla = valores del CSV en cada período, interpolación lineal entre ellos. La plantilla counter cuenta hasta cada valor y luego mantiene el número exacto; dilo si te preguntan.
- Los números derivados (ratios, crecimiento, "supera a") deben calcularse a partir del CSV, no recordarse.
- Nunca mezcles unidades o monedas en un mismo gráfico; nunca compares valores nominales y reales en silencio.
- Siempre muestra la fuente. Conserva la descarga original para que el usuario pueda auditarla.