chartreel 是做什麼的？
使用 chartreel CLI 製作簡短、真實的數據動畫影片。您可以選擇圖表類型、塑造數據、編寫故事、渲染並檢查結果。渲染器只會顯示來自 CSV 的值，或兩個相鄰行之間的直線插值。
0. 工具
chartreel doctor # 檢查 ffmpeg、Chromium 和字型
如果缺少 chartreel：
pip install "git+https://github.com/Xkongai/chartreel" # 或：uv tool install git+https://github.com/Xkongai/chartreel
python -m playwright install chromium # 如果已安裝 Chrome/Chromium 則跳過
# ffmpeg：macOS `brew install ffmpeg` · Ubuntu `sudo apt install ffmpeg` · Windows `winget install Gyan.FFmpeg`
# 在 Linux 上顯示中文/日文/韓文文字：`sudo apt install fonts-noto-cjk fonts-noto-color-emoji`
1. 取得真實數據——絕不發明數字
- 若使用者提供檔案，請直接使用。保持原樣；重塑為新的 CSV。
- 否則，從主要、可引用的來源獲取，並將原始回應保存在 CSV 旁邊。
請參閱
references/data-sources.md（世界銀行 API、Our World in Data、FRED、Eurostat、各國統計局）。 - 若使用者在聊天中輸入數字，請完全照用，並引用為「使用者提供」。
- 切勿憑記憶填補空白。允許空白儲存格：內部空白會被插值，
chartreel validate會報告插值數量；開頭/結尾空白表示該數列不存在。 - 記錄來源名稱、指標代碼或 URL 以及許可證；這些將用於
--source。
2. 選擇模板
| 故事類型 | 模板 | 資料形狀 |
|---|---|---|
| 誰是第一名、超越對手（「1990–2024 年 GDP 排名」） | race | 時間 × 系列（5–40 個系列） |
| 幾個事物如何增長或交叉（「中國 vs 印度人口」） | line | 時間 × 系列（2–8 個系列） |
| 一個驚人的數字，然後「×N」比較（「從 $191B 到 $18.7T」） | counter | label,value[,note]（2–5 行） |
| 整體如何分割與變化（「世界人口按地區」） | share | 時間 × 部分（2–10 個部分，非負） |
3. 整理 CSV
year,China,India,United States # 寬格式：第一欄 = 時間，每系列一欄
1990,361560229446,320979026420,5963144000000
year,name,value # 長格式：也接受，會自動進行樞紐轉換
1990,China,361560229446
label,value,note # 計數器
1980年,191487500000,改革開放初期
規則：時間遞增；純數字（逗號、$、% 會被移除）；UTF-8（BOM 可接受）。
對於長範圍，請保留每年一行——越多行能提供更平滑、更真實的動畫。
4. 撰寫數據故事
- 鉤子（標題）：問題或驚喜，≤ 2 行。例如「The world's largest economies, 1990–2024」、「中印人口之爭」。
- 背景（副標題）：單位和範圍——例如「GDP, current US$」。
- 關鍵時刻（
--note "PERIOD: text"）：1–3 個事件。每個事件必須在該時間點的數據中可見 （在寫下「X 超越 Y」之前檢查 CSV）。 - 結論（
--takeaway）：從 CSV 計算出的一句話。在程式碼中進行算術運算，例如python -c "print(18729668435848/361560229446)"→ 51.8 →「中國 GDP 在 34 年內增長了 52 倍」。誠實四捨五入。 - 來源（
--source）：務必加上。例如：World Bank WDI (NY.GDP.MKTP.CD), CC BY 4.0。
將所有內容放入 JSON 配置中，以便渲染可重現（references/options.md 列出了每個鍵）：
{
"template": "race", "theme": "dark", "aspect": "9:16", "duration": 15,
"title": "The world's largest economies, 1990–2024", "subtitle": "GDP, current US$",
"source": "World Bank WDI (NY.GDP.MKTP.CD), CC BY 4.0",
"takeaway": "China's GDP grew 52× in 34 years", "prefix": "$", "top": 10,
"notes": ["2010: China passes Japan"],
"series": {"China": {"emoji": "🇨🇳", "color": "#FF6B6B"}}
}
中文影片：加上 "locale": "zh"（數字顯示為萬/億/萬億）並用中文撰寫標題/註釋。
4b. 選擇風格預設（可選，建議用於社群影片）
--style 會捆綁主題、鉤子卡片、年份計數器、第一名裝飾和特效。每個預設都保持數字精確：鉤子僅涵蓋前 ~1.5 秒，在數據開始移動之前，並且不會在結論或（對於競賽圖）長條之間繪製任何內容。
--style | 外觀 | 適用於 |
|---|---|---|
classic（預設） | 乾淨，無鉤子 | 文件、簡報、X |
cinematic | 金配青色，信箱式鉤子，暗角，滾動年份，第一名皇冠，鏡頭推近 | YouTube Shorts、Bilibili |
news | 電視條："DATA" 鉤子條，排名數字，紅色年份徽章，來源條 | 嚴肅話題、微博/X |
editorial | 紙質，打字機鉤子，灰色長條 + --highlight "A,B"，大襯線年份 | 小紅書、電子報 |
arcade | 霓虹，長條進入前三時撒花 + 震動，排名上升 ▲，速度條紋 | 抖音/TikTok、遊戲 |
retro | VHS：掃描線，色差文字，PLAY 印章，打字機鉤子 | 懷舊話題 |
glass | 流動彩色團塊，磨砂圖表面板，頂部進度條 | 科技/產品話題 |
bold | 抖音大字：巨大高亮鉤子詞，超大年份，排名數字 | 抖音/快手 |
與預設搭配的故事選項：
--hook "Who has the world's biggest economy?"：第一秒的問題（預設為標題；--no-hook關閉它）。 問題必須能從數據中回答。--cta "Follow for more data stories"：結論下方的小字。- 微調：
--fx bg,vignette,letterbox,scanlines,punch,confetti,trails,arrows,glass替換預設的特效，--no-fx confetti移除一個；--year-style watermark|roll|row|badge，--progress timeline|top|both|none，--highlight leader|"A,B"，--leader/--no-leader，--ranks，--safe-zone/--no-safe-zone（預設會避開 抖音/Shorts 按鈕和字幕區域）。chartreel styles列出所有選項。 --audio music.mp3 [--audio-fade 1.0]放入使用者擁有或獲得授權的音樂曲目（修剪、淡入淡出）。 切勿下載受版權保護的音樂；chartreel 不附帶任何音樂。
當您在命令列傳遞 --style 時，配置檔中的 "theme" 會被忽略（請傳遞 --theme 來覆蓋）。
5. 驗證、渲染、檢查
chartreel validate data.csv -c story.json # 模式 + 選項檢查，清晰的列/行錯誤訊息
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/ # 可選：自包含的 HTML 播放器，可進行逐幀檢查
平台預設：抖音/TikTok/Shorts/Reels -a 9:16 -d 15（10–30 秒）· 小紅書 -a 3:4 或 9:16 ·
Bilibili/YouTube/X -a 16:9 · X/Instagram 動態 -a 1:1 或 4:5。速度：競賽圖大約每個時間點 0.3–0.6 秒。
快速草稿：--size 540 --fps 15。--jobs N 設定並行工作者數量。一個 12 秒 1080×1920 的競賽圖渲染
大約需要 10–30 秒，視 CPU 而定。
然後在交給使用者之前查看輸出：
ffmpeg -v error -i out/data.mp4 -vf "fps=1,scale=360:-1,tile=4x3" -frames:v 1 out/contact.png
打開封面和聯繫表。檢查：標題未裁剪、標籤可讀、無 CJK 豆腐框（□）、結論與數字相符、來源可見、 鉤子（第一秒）一目了然。如有問題請修正並重新渲染。
6. 交付
報告 MP4、GIF 和封面的路徑、來源和許可證，以及結論的計算方式。 如果任何儲存格被插值，請直接說明（validate 會列印）。不要聲稱數據未顯示的趨勢。
準確性規則（不可協商）
- 螢幕上的值 = 每個時間點的 CSV 值，之間的線性插值。計數器模板會計數到每個值，然後保持該精確數字； 如果被問及，請告知。
- 衍生數字（比率、增長、「超越」）必須從 CSV 計算，而非回憶。
- 切勿在同一圖表中混合單位或貨幣；切勿在未說明的情況下比較名義值和實際值。
- 務必顯示來源。保留原始下載，以便使用者可以審計。