Xkongai/chartreel

chartreel は何をしますか？

chartreel CLI を使って、短くて正直なデータアニメーション動画を作成します。ユーザーがチャートを選び、データを整形し、ストーリーを書き、レンダリングして結果を確認します。レンダラーはCSVの値か、隣接する2行の間の線形補間のみを表示します。

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. テンプレートを選択する

ストーリー	テンプレート	データ形状
時間とともに誰が1位か、追い越し（「1990〜2024年のGDPランキング」）	race	期間 × 系列（5〜40系列）
いくつかの項目がどのように成長または交差したか（「中国 vs インドの人口」）	line	期間 × 系列（2〜8系列）
驚くべき1つの数字、次に「×N」比較（「1910億ドルから187兆ドルへ」）	counter	label,value[,note]（2〜5行）
全体がどのように分割されシフトするか（「地域別世界人口」）	share	期間 × 構成要素（2〜10要素、非負）

3. CSVを整形する

year,China,India,United States        # wide: 最初の列＝期間、系列ごとに1列
1990,361560229446,320979026420,5963144000000

year,name,value                       # long: こちらも受け付け、自動でピボット
1990,China,361560229446

label,value,note                      # counter
1980年,191487500000,改革开放初期

ルール: 期間は昇順。プレーンな数値（カンマ、$、% は除去）。UTF-8（BOM可）。長期間の場合は年ごとの行を維持 — 行数が多いほど、よりスムーズで真実味のある動きになります。

4. データストーリーを書く

1. フック（タイトル）: 疑問または驚き、2行以内。 「世界最大の経済圏、1990〜2024」、「中印人口之争」。
2. コンテキスト（サブタイトル）: 単位と範囲 — 「GDP、現在の米ドル」。
3. キーモーメント (--note "PERIOD: テキスト"): 1〜3つのイベント。それぞれがその期間のデータで確認可能でなければなりません （「XがYを追い越す」と書く前にCSVを確認）。
4. テイクアウェイ (--takeaway): CSVから計算された1文。コードで演算を行います。例: python -c "print(18729668435848/361560229446)" → 51.8 → 「中国のGDPは34年間で52倍に成長」。正直に四捨五入。
5. ソース (--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": "世界最大の経済圏、1990〜2024", "subtitle": "GDP、現在の米ドル",
  "source": "World Bank WDI (NY.GDP.MKTP.CD), CC BY 4.0",
  "takeaway": "中国のGDPは34年間で52倍に成長", "prefix": "$", "top": 10,
  "notes": ["2010年: 中国が日本を追い越す"],
  "series": {"中国": {"emoji": "🇨🇳", "color": "#FF6B6B"}}
}

中国語動画: "locale": "zh" を追加（数値を万/億/兆で表示）し、タイトルと注釈を中国語で記述します。

4b. スタイルプリセットを選択する（オプション、ソーシャル動画に推奨）

--style は、テーマ、フックカード、年カウンター、1位の装飾およびエフェクトをバンドルします。すべてのプリセットは数値を正確に保ちます。フックはデータが動き始める前の最初の約1.5秒のみをカバーし、テイクアウェイや（レースの場合は）バーの間には何も描画されません。

--style	見た目	用途
classic（デフォルト）	クリーン、フックなし	ドキュメント、スライド、X
cinematic	ゴールドオンティール、レターボックスフック、ビネット、回転する年、1位に王冠、ズームイン	YouTube Shorts、Bilibili
news	TV風ストラップ: 「DATA」フックストラップ、ランク番号、赤い年バッジ、ソースストラップ	シリアスな話題、Weibo/X
editorial	紙、タイプライターフック、グレーのバー + --highlight "A,B"、大きなセリフ体の年	小红书、ニュースレター
arcade	ネオン、バーがトップ3に達したときの紙吹雪＋パンチ、ランクアップ ▲、スピードストリーク	抖音/TikTok、ゲーム
retro	VHS: スキャンライン、クロマチックテキスト、PLAYスタンプ、タイプライターフック	ノスタルジックな話題
glass	漂うカラーブロブ、曇りガラスのチャートパネル、トップの進行バー	テック/プロダクトの話題
bold	抖音ビッグテキスト: 巨大なハイライトのフックワード、巨大な年、ランク番号	抖音/快手

プリセットで使用するストーリーオプション:

• --hook "世界最大の経済圏はどこ？": 最初の1秒の質問（デフォルトはタイトル、--no-hook でオフに）。 データから回答可能でなければなりません。
• --cta "フォローしてデータストーリーを": テイクアウェイの下の小さな行。
• 微調整: --fx bg,vignette,letterbox,scanlines,punch,confetti,trails,arrows,glass でプリセットのエフェクトを置き換え、 --no-fx confetti で1つ削除。--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] で、ユーザーが所有またはライセンスを持つトラックをMP4に追加（トリミング、フェードイン/アウト）。 著作権のある音楽をダウンロードしないでください。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レースは CPUにもよりますが約10〜30秒でレンダリングされます。

その後、出力を確認してからユーザーに渡します:

ffmpeg -v error -i out/data.mp4 -vf "fps=1,scale=360:-1,tile=4x3" -frames:v 1 out/contact.png

カバーとコンタクトシートを開きます。確認: タイトルが切れていない、ラベルが読める、CJKの豆腐ボックス（□）がない、 テイクアウェイが数値と一致している、ソースが表示されている、フック（最初の1秒）が一目で読める。 必要に応じて修正し再レンダリング。

6. 引き渡し

MP4、GIF、カバーパス、ソースとライセンス、テイクアウェイの計算方法を報告します。 補間されたセルがある場合は（validateが表示します）そのまま伝えます。データが示さない傾向を主張しないでください。

正確性ルール（交渉不可）

• 画面上の値 = 各期間のCSVの値、間は線形補間。counterテンプレートは各値までカウントアップし、その後正確な数値を保持します。質問された場合はそう伝えます。
• 派生数値（比率、成長率、「追い越し」）はCSVから計算する必要があり、記憶から呼び出してはいけません。
• 1つのチャートで単位や通貨を混在させないでください。名目値と実質値を暗に比較しないでください。
• 常にソースを表示します。ユーザーが監査できるように生のダウンロードを保持します。