Was macht chartreel?
Erstelle kurze, ehrliche Datenanimationsvideos mit dem chartreel CLI. Du wählst das Diagramm aus, formst die Daten, schreibst die Geschichte, renderst und prüfst das Ergebnis. Der Renderer zeigt nur Werte aus der CSV oder lineare Interpolationen zwischen zwei benachbarten Zeilen an.
0. Werkzeuge
chartreel doctor # prüft ffmpeg, Chromium und Schriftarten
Falls chartreel fehlt:
pip install "git+https://github.com/Xkongai/chartreel" # oder: uv tool install git+https://github.com/Xkongai/chartreel
python -m playwright install chromium # überspringen, falls Chrome/Chromium bereits installiert ist
# ffmpeg: macOS `brew install ffmpeg` · Ubuntu `sudo apt install ffmpeg` · Windows `winget install Gyan.FFmpeg`
# Chinesische/japanische/koreanische Schriftzeichen unter Linux: `sudo apt install fonts-noto-cjk fonts-noto-color-emoji`
1. Echte Daten beschaffen – niemals Zahlen erfinden
- Verwende die Datei des Benutzers, wenn er eine angibt. Behalte sie unverändert; forme sie in eine neue CSV um.
- Andernfalls rufe Daten von einer primären, zitierfähigen Quelle ab und speichere die rohe Antwort neben der CSV.
Siehe
references/data-sources.md(World Bank API, Our World in Data, FRED, Eurostat, nationale Statistikämter). - Wenn der Benutzer Zahlen im Chat eingibt, verwende genau diese und zitiere sie als "vom Benutzer bereitgestellt".
- Fülle Lücken niemals aus dem Gedächtnis. Leere Zellen sind erlaubt: innere Lücken werden interpoliert und
chartreel validatemeldet, wie viele; führende/nachfolgende Leerzeichen bedeuten, dass die Reihe fehlt. - Notiere den Quellnamen, den Indikatorcode oder die URL sowie die Lizenz; sie werden in
--sourceeingetragen.
2. Wähle die Vorlage
| Geschichte | Vorlage | Datenform |
|---|---|---|
| Wer ist #1 im Zeitverlauf, Überholmanöver ("BIP-Ranking 1990–2024") | race | Periode × Reihe (5–40 Reihen) |
| Wie einige wenige Dinge wuchsen oder sich kreuzten ("China vs. Indien Bevölkerung") | line | Periode × Reihe (2–8 Reihen) |
| Eine atemberaubende Zahl, dann "×N"-Vergleiche ("von 191 Mrd. $ auf 18,7 Billionen $") | counter | label,value[,note] (2–5 Zeilen) |
| Wie sich ein Ganzes aufteilt und verschiebt ("Weltbevölkerung nach Regionen") | share | Periode × Teile (2–10 Teile, nicht negativ) |
3. Forme die CSV
jahr,China,Indien,Vereinigte Staaten # breit: erste Spalte = Periode, eine Spalte pro Reihe
1990,361560229446,320979026420,5963144000000
jahr,name,value # lang: ebenfalls akzeptiert, wird automatisch gepivotet
1990,China,361560229446
label,value,note # Zähler
1980年,191487500000,Anfang der Reform- und Öffnungspolitik
Regeln: Perioden aufsteigend; einfache Zahlen (Kommas, $, % werden entfernt); UTF-8 (BOM ok).
Bei langen Bereichen behalte jährliche Zeilen bei – mehr Zeilen ergeben flüssigere, wahrheitsgetreuere Bewegungen.
4. Schreibe die Datengeschichte
- Aufhänger (Titel): die Frage oder die Überraschung, ≤ 2 kurze Zeilen. "Die größten Volkswirtschaften der Welt, 1990–2024", "中印人口之争".
- Kontext (Untertitel): Einheiten und Umfang – "BIP, aktuelle US-$".
- Schlüsselmomente (
--note "PERIOD: text"): 1–3 Ereignisse. Jedes muss in den Daten zu diesem Zeitpunkt sichtbar sein (prüfe die CSV, bevor du "X überholt Y" schreibst). - Fazit (
--takeaway): ein Satz, der aus der CSV berechnet wird. Führe die Berechnung im Code durch, z.B.python -c "print(18729668435848/361560229446)"→ 51,8 → "Chinas BIP wuchs in 34 Jahren um das 52-fache". Runde ehrlich. - Quelle (
--source): immer. Beispiel:World Bank WDI (NY.GDP.MKTP.CD), CC BY 4.0.
Alles in eine JSON-Konfiguration packen, damit der Render reproduzierbar ist (references/options.md listet jeden Schlüssel):
{
"template": "race", "theme": "dark", "aspect": "9:16", "duration": 15,
"title": "Die größten Volkswirtschaften der Welt, 1990–2024", "subtitle": "BIP, aktuelle US-$",
"source": "World Bank WDI (NY.GDP.MKTP.CD), CC BY 4.0",
"takeaway": "Chinas BIP wuchs um das 52-fache in 34 Jahren", "prefix": "$", "top": 10,
"notes": ["2010: China überholt Japan"],
"series": {"China": {"emoji": "🇨🇳", "color": "#FF6B6B"}}
}
Chinesische Videos: füge "locale": "zh" hinzu (Zahlen als 万/亿/万亿) und schreibe Titel/Notizen auf Chinesisch.
4b. Wähle eine Stilvorlage (optional, empfohlen für Social Videos)
--style bündelt ein Theme, eine Aufhängerkarte, einen Jahreszähler, die #1-Dekoration und Effekte. Jede Vorlage bewahrt die Zahlen exakt: Der Aufhänger deckt nur die ersten ~1,5 s ab, bevor sich die Daten bewegen, und es wird nichts über das Fazit oder (bei Rennen) zwischen Balken gezeichnet.
--style | Aussehen | Geeignet für |
|---|---|---|
classic (Standard) | sauber, kein Aufhänger | Dokumentation, Folien, X |
cinematic | Gold auf Blaugrün, Letterbox-Aufhänger, Vignette, rollendes Jahr, Krone auf #1, Punch-In | YouTube Shorts, Bilibili |
news | TV-Einblendungen: "DATA"-Aufhängereinblendung, Rangnummern, rotes Jahresabzeichen, Quelleneinblendung | ernste Themen, Weibo/X |
editorial | Papier, Schreibmaschinen-Aufhänger, graue Balken + --highlight "A,B", große Serifen-Jahreszahl | Xiaohongshu, Newsletter |
arcade | Neon, Konfetti + Punch, wenn ein Balken die Top 3 erreicht, Rangaufstieg ▲, Geschwindigkeitsstreifen | Douyin/TikTok, Gaming |
retro | VHS: Scanlines, chromatischer Text, PLAY-Stempel, Schreibmaschinen-Aufhänger | nostalgische Themen |
glass | schwebende Farbkleckse, matterte Diagrammtafel, oberer Fortschrittsbalken | Tech/Produkt-Themen |
bold | Douyin-Großtext: riesige hervorgehobene Aufhängerwörter, große Jahreszahl, Rangnummern | Douyin/Kuaishou |
Story-Optionen, die zu Vorlagen passen:
--hook "Wer hat die größte Volkswirtschaft der Welt?": die erste-Sekunde-Frage (Standard ist der Titel;--no-hookschaltet ihn aus). Sie muss aus den Daten beantwortbar sein.--cta "Folge für mehr Datengeschichten": eine kleine Zeile unter dem Fazit.- Feinabstimmung:
--fx bg,vignette,letterbox,scanlines,punch,confetti,trails,arrows,glassersetzt die Effekte der Vorlage,--no-fx confettientfernt einen;--year-style watermark|roll|row|badge,--progress timeline|top|both|none,--highlight leader|"A,B",--leader/--no-leader,--ranks,--safe-zone/--no-safe-zone(Vorlagen halten Abstand von den Douyin/Shorts-Tasten und dem Untertitelbereich).chartreel styleslistet alles auf. --audio music.mp3 [--audio-fade 1.0]legt einen Track, den der Benutzer besitzt oder lizenziert hat, unter das MP4 (getrimmt, ein-/ausgeblendet). Lade niemals urheberrechtlich geschützte Musik herunter; chartreel enthält keine.
Das "theme" einer Konfigurationsdatei wird ignoriert, wenn du --style in der Befehlszeile übergibst (übergib --theme, um es zu überschreiben).
5. Validieren, rendern, prüfen
chartreel validate data.csv -c story.json # Schema- + Optionsprüfung, klare Zeilen-/Spaltenfehler
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/ # optional: eigenständiger HTML-Player zum Durchblättern
Plattform-Voreinstellungen: Douyin/TikTok/Shorts/Reels -a 9:16 -d 15 (10–30 s) · Xiaohongshu -a 3:4 oder 9:16 ·
Bilibili/YouTube/X -a 16:9 · X/Instagram-Feed -a 1:1 oder 4:5. Tempo: etwa 0,3–0,6 s pro Periode für ein Rennen.
Schnelle Entwürfe: --size 540 --fps 15. --jobs N setzt parallele Arbeiter. Ein 12 s 1080×1920 Rennen rendert in
etwa 10–30 s, abhängig von der CPU.
Dann sicht prüfen das Ergebnis, bevor du es übergibst:
ffmpeg -v error -i out/data.mp4 -vf "fps=1,scale=360:-1,tile=4x3" -frames:v 1 out/contact.png
Öffne das Cover und das Kontaktblatt. Prüfe: Titel nicht abgeschnitten, Beschriftungen lesbar, keine CJK-Toast-Boxen (□), das Fazit stimmt mit den Zahlen überein, die Quelle ist sichtbar, der Aufhänger (erste Sekunde) ist auf einen Blick lesbar. Korrigiere und rendere bei Bedarf neu.
6. Übergeben
Melde die Pfade von MP4, GIF und Cover, die Quelle und Lizenz sowie wie das Fazit berechnet wurde. Sage deutlich, ob Zellen interpoliert wurden (validate gibt es aus). Behaupete keinen Trend, den die Daten nicht zeigen.
Genauigkeitsregeln (nicht verhandelbar)
- Auf dem Bildschirm angezeigte Werte = CSV-Werte zu jedem Zeitpunkt, lineare Interpolation dazwischen. Die Zählervorlage zählt bis zu jedem Wert hoch und hält dann die exakte Zahl; sage dies, wenn gefragt wird.
- Abgeleitete Zahlen (Verhältnisse, Wachstum, "überholt") müssen aus der CSV berechnet werden, nicht aus dem Gedächtnis abgerufen.
- Mische niemals Einheiten oder Währungen in einem Diagramm; vergleiche niemals stillschweigend nominale und reale Werte.
- Zeige immer die Quelle. Behalte den Rohdownload, damit der Benutzer ihn überprüfen kann.