sweety-statechart-video

格物 · クレヨンの状態図

一コマずつ、物事をわかりやすく伝えます。

標準は参考作品です。

• デフォルトの見た目：Ann Nguyen の the making of nhang に倣います（TypingMind 上のアニメーション状態図で、彼女の動画はこのページの画面録画です）。
• ルールチェックと複数の描画スタイル：Kevin Ngo の statechart-art（MIT）に倣います。

どちらの描画スタイルもプレーヤーも、自分たちで実装しています。迷ったときは参考作品に立ち返り、それに従ってください。

成果物：

• outputs/film.mp4：デフォルトは 3:4、つまり 1080×1440、30 fps、2～3 分、ナレーション付きで、共有用です。ほかに outputs/film-master.mp4 もあり、約 11 Mbps のアップロード用マスターで、プラットフォーム側の再エンコードに余裕を持たせます；
• outputs/posters/01.png…：各章の完成ポスター 1 枚と、レイアウトを青枠で示した 01-layout.png；
• outputs/cover.png、script.txt、editing/captions.srt；
• 必要に応じて章ごとの短編、縦長画像、インタラクティブなウェブページ、ポートフォリオページ、公開パッケージも出力します（成果物を参照）。

動画の見た目

• カバーのオープニング。 デフォルトでは、最初に outputs/cover.png を 0.5 秒表示してから、0.5 秒かけてフェードアウトし、その後本編を再生します。オープニングは無音で、本編の音声と字幕は一緒に 1 秒後ろにずれます。
• 1 枚の紙が下へ伸びていく。 各章はポスター 1 枚で、前後をつなげます。前の章の出口矢印をポスターの下端から伸ばし、次の章の上端につなげます。
• ポスター：
  • 左上はヘッダーです。シリーズ名、タイトル、副題、赤い小さな文字を 1 行配置します；
  • 中央は状態図です。デフォルトではクリーム色の伝票カードに、画びょうと赤い小さなラベルを添えます；
  • 周囲には大きなカラフルなクレヨン画を配置します。
• 各ステップ：
  • 小さな点が新しい矢印に沿って動き、文字を 1 文字ずつ表示します；
  • カードが押しつぶされてから跳ね上がり、画びょうが落ちてカードを留め、カードが 2 回揺れます；
  • 現在の状態がピンク色に変わり、クレヨンで描くようにピンクの円がその周りを一周します；
  • カメラが動きを追い、ズームインすることもあります。
• 常に動き続けます：
  • 線は毎秒 5 回描き直します；
  • イラストは状態に合わせて動きます；
  • 登場人物はナレーションに合わせて口を動かし、現在のカードを指します。
• 字幕バー I.3 — 付了钱，商家叮的一声接了单：読み終えた文字は濃い色になります。「同時進行」の章では、各フローが現在どこにあるかを示す行を上部にもう 1 行追加します。
• ナレーション：各ステップの字幕をそのままナレーションにして、自分たちの声で読み上げます。音声を参照してください。
• ルールの章：
  • ルールを 1 つ以上記述すると、チェッカーが各ルールを破る最短経路を見つけて赤線で描き、スタンプを押します；
  • ポスターには凡例があり、各ルールが ✓ か ✗ か、また確認したケース数が表示されます；
  • 「先に破ってから正す」こともできます。条件を追加すると赤線が薄くなり、緑のスタンプが押されます。
• 冒頭と結末：質問（hook）から始めることもできます。エンディングではデフォルトですべてのポスターを映し、エンドカードで止まります。

実行方法（すべてのプラットフォーム共通）

• すべてのコマンドは絶対パスで記述します：python3 <本 Skill 目录>/scripts/scv.py <命令> <任务目录>。タスクディレクトリはユーザーの作業ディレクトリ内に置き、Skill ディレクトリには入れないでください。
• 新しいマシンで初めて使うときは、まず bash <本 Skill 目录>/scripts/setup.sh を実行します。レンダリング環境を構築し、Chromium をインストールします（Chrome がすでにある場合はそのまま使用します）。最後にスモークテストを実行します。
• 音声生成は Apple Silicon 上でのみ実行します（MLX）。環境が揃っていない場合は voice が不足しているものを表示します。ユーザーがナレーションを必要としない場合は、"voice": "none" と記述してください。
• voice と render はそれぞれ数十秒から数分かかります。プラットフォームによって 1 コマンドあたりの実行時間に制限がある場合は、分けて実行するか、バックグラウンドで実行してください。
• Codex、Claude Code、Grok Build で実機検証済みです。各プラットフォームの説明はプラットフォームを参照してください。

ワークフロー

1. 題材を分解します。 題材選びと図への分解を読み、2～5 章に分けます。各章では、フラットな図、複数の同時進行フロー、1 つの親状態、またはルールの章のいずれかを使います。
2. film.json を記述します。 フォーマットはfilm.json の仕様を参照してください（JSON Schemaがあります）。
   • scv.py new JOB --title … でひな形を作成します；
   • 既存の状態マシン（XState、Mermaid、SCXML、PlantUML、または /statechart スキルの chart ディレクトリ）がある場合は、scv.py import 文件 JOB でひな形を作成し、文字を変更して字幕を記述します。インポートとエクスポートを参照してください；
   • 完全な例は examples/ にあります。
3. scv.py check JOB：構造、ステップ、字幕の長さ、到達可能性を確認します。ルールの章では赤線を見つけ、修正を検証します。error があれば、先に修正してください。
4. scv.py layout JOB：レイアウトをすべて自動で配置します。
   • 各章の完成ポスターは work/layout/chN.png に出力されます。100 単位のグリッドと、緑の破線で示した空きスペースが含まれます；
   • 座標は chN.json に記録されます。
5. scenes.js を記述します。 各章に bg（静的）と fg（状態に応じて毎フレーム描画）を 1 つずつ用意します。
   • scv.py draft JOB で、空きスペースと状態名を基に草案を作成します（シーンパーツに小道具を加えます）。その後、細部を調整します；
   • 小道具、人物、シーンパーツ、ブラシについてはシーンを、型定義については scenes.d.tsを参照してください；
   • scv.py gallery で、すべての小道具とシーンパーツのギャラリーを出力します。
6. scv.py lint JOB：イラストの問題を 1 つずつ報告し、修正方法を提示します。問題がなくなるまで修正してください。
   • カード、文字、矢印にかぶっている；
   • 余白が多すぎる（クレヨンテーマでは 38％超、ペンと色鉛筆、リネンなどの余白を多く取るテーマでは 55％超）；
   • あるステップでイラストが変化しない；
   • 人物の大きさや地面の線が不適切。
7. scv.py voice JOB：1 文ずつ音声を生成し、各文にノイズゲートと ASR の検証を行います。結果はキャッシュされるため、1 文を変更した場合はその文だけを再生成します。
8. scv.py plan JOB → stills JOB：work/stills/contact.jpg を開き、各ステップを確認します。scv.py preview JOB を実行してブラウザー上でスクラブ再生することもでき、ファイルを変更すると自動で更新されます。
9. scv.py all JOB：音声生成、タイミングの設定、レンダリング、ポスター、完成動画、成果物、公開パッケージを一括で実行します。
   • 実測値：93 秒の動画は約 40 秒でレンダリングでき、ナレーション 36 文は約 3 分かかります；
   • 例：examples/intro/（2～3 分）、examples/takeout/（1.5 分）、examples/message/（1 分）。
10. バッチ処理：題材ごとにディレクトリを作り、それぞれで手順 4、6、8 を実行してから、scv.py batch JOB1 JOB2 … を実行します。

厳守するルール

• カードと矢印：
  • カードには見た目を表す言葉を 2～6 文字で記述します（「配送中」「べちゃべちゃ」など）。tag には小さな文字を 1 行記述します（英語が望ましいです）；
  • 矢印には何が起きたかを 8 文字以内で記述します。条件は if に入れ、赤い [有食材] として表示します；
  • チェッカーにも条件を認識させる必要がある場合は、when を追加します（vars、do と組み合わせます）。
• 規模： 各章のカードは約 8 枚、矢印は 12 本までです。それ以上になる場合は章を分けてください。縦長レイアウトに収まらない場合、ポスターの高さは自動で拡張され、check が章を分けるよう促します。
• 字幕： 各ステップにつき 1 行で、中国語は 24 文字以内（英語は約 42 文字）です。因果関係を説明し、カードの文言をそのまま読み上げないでください。字幕はナレーションも兼ねます。数字は漢数字で記述するか、読み方を say で指定してください。
• ステップの書き方：
  • 最初のステップは "go": "start" とします。前の章の出口につながる章では、最初のステップを "go": "entry" とします；
  • 最後にしか登場しないカードには、それを点灯させるステップを必ず用意してください。そうしないと表示されません；
  • ルールの章では、違反状態に至るまで順に進み、その後 {"trace": true} のステップで赤線を描きます；
  • 修正には rule.fix を使い、さらに {"fix": true} のステップを追加します；
  • 1 章に複数のルールを列挙する場合は、rules を使います。
• イラスト：
  • すべての空きスペースを活用し、ポスター 1 枚につき大きなシーンを 1 つ（シーンパーツ）配置します。下部または両側に配置してください；
  • 各状態に対応するイラストを用意し、状態に応じて動かします（S.on、S.since、S.step）。登場時には $.enter を使います；
  • 人物は 0.7～0.9 倍（主人公は最大 1.5 倍）で、全員が同じ地面の線に立つようにします。カード、矢印、文字にかぶせないでください；
  • すべてコードでその場で描画し、外部画像は使いません；
  • lint で問題がなくなってから納品してください。

デフォルト値と切り替え

• アスペクト比 3:4（1080×1440）。任意の "aspect": "W:H" を指定できます。短辺は 1080 です：
  • 縦型と正方形は、ポスターと画面が同じ形になり、カードの文字と矢印の文字が自動で大きくなるため、スマートフォンでも読みやすくなります；
  • 横型は「同一時間」枠がない場合、左から右に配置します。ポスターと画面は同じ形になり、長すぎる場合は自動で幅を広げます；枠がある場合は正方形のポスターを使い、カメラをスクロールさせます；
  • アスペクト比を変更したら、layout を再実行してください。イラストは新しい空きスペースに合わせて配置されます。
• 長さはデフォルトで 2〜3 分です。小紅書や抖音など、ほとんどのプラットフォームに適しています。別の長さにしたい場合は "duration" に指定してください：150、[60, 90]、"1分钟" などを指定できます。
  • check はナレーションの速度から長さを見積もり、ステップをいくつ追加または削除すべきかを知らせます；plan は目標との差がわずかな場合、各ステップに最大 0.7 秒を追加します；
  • 2〜3 分にする場合：通常は 4〜5 章、各章 9〜12 ステップ、各文 12〜20 文字が目安です；
  • カバーとオープニングは finalize の際に追加され、さらに 1 秒かかります。"cover_intro": false で無効にできます。work/timing.json は本編の時間、納品用字幕と outputs/editing/delivery-timing.json はオープニングを含む時間です。
• テンポ speed：
  • ナレーションありの場合、デフォルトは 2 です（各ステップのアニメーションは約 1.8 秒で、その後ナレーションが読み終わるまで待ちます）；
  • ナレーションなしの場合、デフォルトは 3 です。参考動画と同じく、アニメーションは 1.2 秒で、各ステップは字幕を読み終えられるまで表示されます。
• 画面については、画面 をご覧ください：
  • "theme"：crayon（デフォルト）、pencil（ペンと色鉛筆）、night、kraft、riso、linen、season:autumn など；"brand": [ブランドカラー] を指定すると、ブランドカラーをもとにテーマを生成します；
  • "look"：カードの描画スタイル。ticket / note / sign / soft / plate / tag / slide / patch。親ステートは店舗の外観として描画できます；
  • "arrows"：thread / cord / pencil；
  • カメラと開閉：「"camera": "push"」、「"hook": "問題"」、「"outro"」、「"episode" と "next"」、「"player": {"spotlight": true}」；
  • 状態：mood（雨、夜、警報、修理済み）と inset（顕微鏡の小窓）。
• 音声 "voice"：
  • デフォルトは crayon-sister（クレヨンお姉さん）です。blueprint-guy（設計図のお兄さん）、sunny-girl（元気な少女）や old-master（ベテラン職人）に変更できます。"none" を指定すると無音になります。4 種類とも純粋な合成音声で、著作権上の問題はありません；
  • 自分の声を使う：scv.py add-voice my-voice --audio 录音.m4a --start 12 --end 25 --text "逐字稿" --consent self --preview を実行し、"voice": "my-voice" と指定してください。詳しくは 音声 をご覧ください；
  • ステップには tone（例："驚き"、"とてもゆっくり"）と speaker（そのキャラクターが口を動かします）を指定できます；
  • 状態には sfx（点灯時の効果音）と ambience（点灯中の環境音）を指定できます；
  • "music": {"mood": "curious", "sync": true} を指定すると、インストゥルメンタル音楽を重ねます。ナレーション中は自動的に音量を下げ、章の冒頭とスタンプを強拍に合わせます；
  • 他の言語：翻訳文を i18n.<语言> に記述し、scv.py all JOB --lang en を実行すると英語版が出力されます。
• ウォーターマークはデフォルトで 制作：@leo_xiaolei/刘老板 となり、右上に固定されます。"watermark": null で無効にできます。
• AI 表示：ナレーションがある場合、冒頭の 4 秒間とエンドカードに「ナレーションは AI 合成です」（"ai_label"）と表示されます。完成動画、音声、ポスターのメタデータには、GB 45438 の AIGC フィールドが記録されます（"aigc" で変更できます）。
• フォント（同梱、すべて再配布可能）：
  • Special Elite（Apache-2.0）と Noto Serif SC Bold のサブセット（OFL）を組み合わせ、タイトルとカードに使用します。タイプライターのインク跡が付きます；
  • Courier Prime（OFL）と霞鶩文楷（OFL）を組み合わせ、矢印の文字と字幕に使用します；
  • テーマのフォントを変更する場合は、朱雀仿宋、霞鶩漫黒（OFL）、または Kevin Serif/Sans（MIT）を使用します。

実行と制約

• レンダリングには Chrome + Playwright を使用します（SCV_PYTHON、デフォルトでは setup.sh が作成する ~/.local/share/sweety-statechart-video/venv）。

• ナレーションにはローカルの VoxCPM2 MLX と Whisper を使用します（STATECHART_MLX_PYTHON）。すべてオフラインで動作します；環境の確認には scripts/audio_doctor.py を実行できます。

• レイアウトは自動で処理されます。個別のカードは "at": [列, 行] を指定して位置を固定できます。親ステートは 1 階層まで対応しており、それより深いネストはインポート時に複数の章に分割されます。

• scv.py export JOB --to mermaid|xstate|scxml を実行すると、動画内の図をドキュメントやコードにエクスポートできます。

• その他の納品物：

  • scv.py deliver JOB --what clips,longimage,social,gif,html,site：章ごとの短編動画、長尺画像、各プラットフォームのサイズに合わせた画像、アニメーション画像、インタラクティブなウェブページ（ステップ表示、スポットライト、顕微鏡）、ポートフォリオページ；
  • film.json に "deliver": [...] を記述すると、all の実行時にあわせて作成されます；
  • scv.py publish JOB を実行すると、公開用パッケージが作成されます。

  詳しくは 納品 をご覧ください。

• レンダリングに問題がある場合は --encoder legacy を追加してください。急ぐ場合は --encoder webcodecs（ハードウェアエンコード）を指定してください。

• エンジンの画面を変更した場合は、scv.py golden を実行して基準フレームと比較し、python3 scripts/test_engine.py で各種アスペクト比、テーマ、描画スタイルを確認してください。

• チェッカーは本プロジェクト独自の明示的状態チェック（TLC の手法を参考）であり、TLA+ は実行しません；/statechart スキルで TLC による確認済みの結果は、そのままインポートできます。

• 合成ナレーションは AI 生成コンテンツです。公開時はプラットフォームの要件に従って表示してください。

• 謝辞とライセンスについては、リポジトリの THIRD_PARTY_NOTICES.md をご覧ください。