video-flow：コードレンダリングによる汎用解説動画ワークフロー は何をしますか？
一言で言えば：「何を教えるのか」を明確にし、それを計算可能なタイムラインに変換し、最終的にブラウザで1フレームずつ描画します。 完成品 = Canvas/HTML の
render(t)+ ヘッドレスChromeによるフレームキャプチャ + FFmpeg + オプションのTTS/BGM/字幕。
このSkillは、1本の動画を8つのチェック可能なフェーズに分割します。各フェーズには成果物と検収ポイントがあり、いずれかのステップで不合格となった場合は、次のステップに進まないでください。
0. いつ使用するか / 使用しないか
使用するケース:
- PDF、PPT、DOCX、記事、ウェブページ、動画、またはトピックから、1～5分の解説動画を作成する場合。
- 「テキストが明確で、データが正確で、1フレームを修正でき、再現可能な」動画が必要な場合（コードレンダリングによる構造的な優位性を活用）。
- 縦型/正方形/横型のマルチバージョン、または多言語バージョンが必要な場合。
- ナレーション、字幕、BGMが必要で、かつワークフロー全体が反復可能であることが望ましい場合。
使用しないケース:
- 実写/リアルな映像が必要な場合 → ビデオ生成モデルまたは実写を使用。このSkillは「コードレイヤー」のみを担当します。
- 既存の素材を編集するだけの場合 → 編集ツールまたはAgentを使用。
- ストーリーボードや脚本を決めずにMP4を生成したいだけの場合 → テンプレート的な動画になる可能性が高いため、ステップ1～2を先に行うことを推奨します。
1. 厳格なルール（違反した場合はやり直し）
- 画面は時間の純粋関数である: ページは
window.render(t)を公開する必要があります。与えられたtに対して、画面は一意に決定されなければなりません。Date.now()、シードのない乱数、requestAnimationFrameによる状態駆動、CSStransition/animation、フレーム間キャッシュは禁止。- 累積型アニメーション（パーティクル、水面など）は、固定ステップで0から
tまで計算するか、解析式に変更すること。
- タイムラインが唯一の情報源である: ストーリーボード、ナレーション、BGM、効果音、字幕はすべて同一の
timeline.jsonから派生すること。 - ストーリーボードの後にコードを書く:
storyboard.mdとscript.jsonがない状態でシーンコードを書いてはいけません。 - 原文の事実を捏造しない: 数字、年号、人名、数式はソースマテリアルから取得すること。不明な点は
[要確認]とマークし、納品時に別途リストアップすること。 - デフォルトではブランドや透かしを入れない: ユーザーからロゴやブランド名が提供された場合を除き、デフォルトのフッターにはコース/トピック情報のみを記載すること。
- エンコードは1回のみ: オーディオはWAV段階でミキシングとラウドネス処理を完了し、最終的にAACエンコードを1回だけ行うこと。トランスコードの繰り返しは避けること。
- 納品前にQAを通過すること: フレーム欠落、黒フレーム、ラウドネス、再生時間、字幕、音声と映像の同期を確認（ステップ8参照）。
2. 入力と成果物
入力（任意、組み合わせ可能）
| 種類 | 処理方法 |
|---|---|
scripts/ingest.py でテキスト抽出；スキャン文書や文字化けの場合は自動的にPNGにラスタライズし、モデルに「ページを見せる」 | |
| PPTX | ページごとにタイトル、本文、ノートを抽出；必要に応じてキーページを画像としてエクスポート |
| DOCX / Markdown / TXT | 直接 source/source.md に抽出 |
| ウェブページURL | 本文を取得；ソースリンクを保持 |
| 動画 | ffprobe メタデータと定点フレーム抽出；ASRがない場合は人間が内容を補足 |
| トピックのみ | ユーザーが指定した一言/アウトライン；最初にユーザーに「必須の事実」を確認させる |
各プロジェクトのディレクトリ構造
<project>/
project.json # メタ情報：タイトル/対象者/目標/アスペクト比/スタイル/声/音楽/ブランド
source/ # ソースマテリアル（source.md、pages/*.png、meta.json）
storyboard.md # ストーリーボード：各シーンの内容、映像、時間、ナレーション、ポイント
script.json # 機械可読：scenes[]（type/script/visual/vo/duration）
build/ # index.html + lib.js + theme.js + scenes.js + timeline.js
audio/ # vo/*.wav、bgm、mix.wav
frames/ # フレームごとのJPEG
out/ # final.mp4 / final.srt / poster.png
qa/ # report.md + contact sheets + フレームサンプル
scripts/init_project.py を使用して一度にスケルトンを生成します。
3. ワークフロー（8ステップ）
ステップ0：環境チェック
python scripts/check_env.py
必須：Python 3.10+、FFmpeg/ffprobe、Chromiumベースのブラウザ、numpy/scipy。
推奨：edge-tts（オンライン音声合成）、pypdf、python-pptx、python-docx、Pillow。
不足しているものは出力に従ってインストール。インストールできない場合は、機能を縮退（ナレーションなし / システム音声 / 手動音声ファイル）。
ステップ1：ソースマテリアルを読み、「教育構造」を抽出する
まず以下の5つの質問に答える（project.json の brief に記述）：
- 対象者は誰か？彼らはすでに何を知っているか？
- 視聴後に言える/できるようになることは何か？（1～3の検証可能な目標）
- 最も誤解されやすい/難しいポイントは何か？
- 必ず登場させるべき事実/数式/データは何か？それぞれのソースは何か？
- 再生時間とアスペクト比は？プラットフォームは（教室/スマートフォン/ソーシャルメディア）？
元のページ順にそのまま説明しないこと。 references/storytelling.md の4つの構造のいずれかを使用して再構成する：
- 因果連鎖（理系・工学系におすすめ）；
- 問題→解決策→検証；
- 誤解→修正→応用；
- タイムライン/プロセス。
ステップ2：スタイルとアスペクト比を決定する
references/styles.md から1つ選択（silicon / paper / blueprint / neon / swiss）、references/formats.md に従ってアスペクト比を決定。
ルール：
- 内容が「チップ/エンジニアリング/データ」寄り → silicon / blueprint；
- 「人文/生物学/歴史」寄り → paper；
- 「発表/マーケティング/若者向け」寄り → neon / swiss；
- 1画面で1つのことだけを説明する；縦型の場合は必ずレイアウトを再構築し、横型を単に切り取らない。
ステップ3：ストーリーボードと脚本を書く
storyboard.md（人間用）と script.json（機械用）を出力。各シーンには以下を必ず記述：
type（title/concept/process/compare/formula/bars/quote/recap/custom）kicker（サブタイトル）、headline（一言で結論）、points（≤3項目）vo（ナレーション、1～2文；ナレーションがない場合は空欄）visual（図/表/フロー/数式の具体的なデータ）duration（空欄可、ナレーション時間から自動決定）
脚本作成の5つの厳格な制約：
- 画面のテキスト ≠ ナレーション原稿：画面にはキーワードと結論のみを残し、ナレーションで説明する。
- 1画面につき最大1つの結論＋3つの補足ポイント；タイトルは18文字以内、本文は各行22文字以内。
- 2～4秒ごとに変化（要素/カメラ/強調）を入れるが、パーティクル爆発のような過剰な効果は避ける。
- 最初に「禁止リスト」を書く：グラデーション背景＋中央の大きなテキスト、すべての要素のフェードイン、画面いっぱいの小さなテキスト、無意味なグロー効果。
- 事実文には個別にソースを明記；不明な点は
[要確認]を追加。
ステップ4：ナレーションとタイムラインを生成する
# オプション：ナレーションがない場合はスキップし、各シーンに明示的に duration を記述
python scripts/tts.py --project . --voice zh-CN-XiaoxiaoNeural --rate +3%
python scripts/timeline.py --project .
tts.pyはaudio/vo/<id>.wav（48 kHz）を出力し、軽度のEQ/圧縮を自動適用；--from-dirで人間の録音を使用可能。timeline.pyは実際のナレーション時間を使用してbuild/timeline.jsとtimeline.jsonを生成：scene.duration = head + voDuration + tail、ナレーションのないシーンは明示的なdurationを使用。- 以降は
script.jsonのみを編集し、これらの2つのステップを再実行すること。タイムラインを手動で編集しないこと。
ステップ5：ページを構築し、シーンを実装する
テンプレートを使用：
python scripts/init_project.py --dir my-video --title "..." --format 16:9 --style silicon
# build/content は timeline.py が生成するように編集；汎用レンズはすでに実装済みなので、script.json を直接編集
- 汎用レンズ（8種類）は
build/scenes.jsにあり、CONTENTを読み込んでレンダリング；ほとんどの解説動画で十分。 - 専門的な図（チップ/回路/解剖図/地図/分子など）が必要な場合は、
build/custom.jsを作成：window.CUSTOM['s3'] = function(u, D, sc, ctx){ /* lib.js のヘルパーを使用して描画 */ };script.jsonで該当シーンのtypeをcustomに設定。 - 一度に1つのシーンだけを実装：最初に3つの静止フレームをレンダリング（
scripts/render.py --still 1.2,2.4,3.6）、テキストのはみ出し/重なり/主体のサイズを確認してから続行。
ステップ6：レンダリング
python scripts/render.py --project . --fps 30
# 特定のセグメントのみレンダリング：--start 8 --duration 4
# 既存のChromeを再利用：--cdp http://127.0.0.1:9333
# スクリプトにChromeを起動させる：--launch-chrome
出力は frames/f00000.jpg...；途中再開可能（既存のフレームで2KB以上のものはスキップ）。
ヘッドレスChromeとサンドボックス：実行環境がChromeのIPC/パイプを禁止している場合は、許可された環境で実行するか、
--cdpを使用して起動済みのChromeに接続すること。
ステップ7：BGM、効果音、ミキシング、字幕
python scripts/audio.py --project . # BGM合成 + ナレーション配置 + ダッキング + マスタリング
python scripts/srt.py --project . # out/final.srt を生成
- ナレーションなしの場合：
audio.py --no-bgmまたはユーザー提供の音楽のみを使用。 - ユーザーが音楽を提供する場合：
audio/music.*に配置。audio.pyが自動的にループ/トリミングおよびダッキングを行う。 - 目標ラウドネスはデフォルトで −14.2 LUFS、トゥルーピーク ≤ −1.5 dBFS；オーディオのエンコードは1回のみ。
ステップ8：エンコード + QA + 納品
python scripts/encode.py --project . # frames+mix+srt → out/final.mp4
python scripts/qa.py --project . # qa/report.md + フレームサンプル画像
QAはすべてパスする必要があります（references/qa.md 参照）：
- 再生時間/アスペクト比/フレームレート/オーディオトラック/字幕ストリームが正しいこと；
- 0.25秒以上の黒フレームがないこと；フレームサンプルに空白、テキスト重複、はみ出しがないこと；
- ラウドネスが目標値±1 LU以内、トゥルーピーク ≤ −1.5 dBFSであること；
- 最初のフレームが完全な黒でないこと；最後のシーンにまとまりがあること；
- 事実リストがソースマテリアルと一致していること；
[要確認]が別途リストアップされていること。
納品物：out/final.mp4、out/final.srt、poster.png、storyboard.md、script.json、qa/report.md、レンダリング所要時間と既知の不足点。
4. 汎用レンズタイプ（テンプレートで実装済み）
| type | 用途 | キーフィールド |
|---|---|---|
title | オープニング/チャプター | title/subtitle/kicker |
concept | 1つの概念＋3つのポイント | headline/points/visual |
process | フロー/ステップ（3～5ステップ） | steps[] |
compare | 二者比較 | left/right |
formula | 数式＋説明 | formula/notes[] |
bars | データ比較 | items[{label,value}] |
quote | 名言/結論 | quote/author |
recap | まとめマップ | nodes[]/takeaway |
custom | 専門図 | 自分で custom.js を記述 |
新しいタイプが必要な場合：scenes.js に window.SCENES_IMPL['type'] を追加し、references/pipeline.md にデータ契約を記録。
5. アスペクト比とセーフゾーン
| アスペクト比 | サイズ | セーフゾーン | タイトルフォントサイズ | 本文フォントサイズ |
|---|---|---|---|---|
| 16:9 | 1920×1080 | 左右 96 / 上下 64 | 72–120 | 28–40 |
| 9:16 | 1080×1920 | 左右 64 / 上下 160 | 64–96 | 32–44 |
| 1:1 | 1080×1080 | 四方 72 | 56–88 | 28–40 |
| 4:5 | 1080×1350 | 四方 80 | 60–92 | 30–42 |
縦型の場合はレイアウトを再構築：タイトルを上に、図を中央に、結論を下に；横方向に圧縮しないこと。テンプレートは layout() を使用してアスペクト比に応じて切り替え。references/formats.md を参照。
6. よくある失敗と修正方法
| 現象 | 根本原因 | 修正方法 |
|---|---|---|
| 黒画面/白画面 | JSエラー、render 未定義、canvasサイズ0 | render.py --still でコンソールを確認；明示的にcanvasの幅と高さを設定 |
| フォントが違う/最初のフレームでフォールバックフォント | フォントがロードされていない | document.fonts.ready を待ってから READY=true を設定；CJKはシステムのフォールバック文字列を使用 |
| 同じ t で2回異なる結果/パラレルフラッシュ | rAF/タイマー/乱数/フレーム間状態を使用 | 純粋関数に変更；hash(seed)；クローズドフォームのスプリング |
| テキスト重複/はみ出し | シーンごとに静止フレームをチェックしていない | 各シーン3枚の静止フレーム＋縦型は360px幅でフレームサンプリング |
| 音声と映像の同期ずれ | オーディオが0から始まる vs ビデオがstartから；TTSが文ごとに個別 | 同一のタイムライン；TTSは一括；-ss を -i の前に配置 |
| ラウドネスが不規則に変動 | 複数回のloudnorm/トランスコード | WAV段階で静的ゲインのみ；AACは1回のみ |
| レンダリングが遅すぎる | 4K/サブフレーム/ブラシ/WebGL | 最初は960×540の小規模サンプル；サブフレームは高速動作のみ；パラレルワーカー |
| Chromeが起動しない | サンドボックスがIPC/パイプを制限 | 許可された環境で実行するか、--cdp で起動済みのChromeに接続 |
7. 拡張ポイント
- 新しいスタイル：
templates/styles/*.jsonをコピーし、カラーパレット/フォント/背景タイプを変更；styles.mdにエントリを追加。 - 新しいレンズ：
build/scenes.jsに登録；またはbuild/custom.jsで専門図を記述。 - 人間のナレーション：録音を
<scene-id>.wavとしてaudio/vo_human/に配置；tts.py --from-dirでリサンプリングと軽度処理のみを実行。 - 多言語：
script.<lang>.jsonと対応するTTS音声；タイムラインは同じ画面を再利用可能（テキスト長の違いに注意）。 - マルチアスペクト比：同じ
script.jsonを使用し、異なるproject.formatで init/render を再実行；レイアウトはlayout()で適応。 - ブランディング：
project.json.brandでロゴテキスト/色/フッターを提供；デフォルトではオフ。
8. 参考ドキュメント
references/pipeline.md：完全な技術パイプライン、render(t)契約、CDPレンダリング、FFmpegパラメータ、タイムラインデータモデル。references/inputs.md：PDF/PPT/DOCX/URL/動画の抽出とOCRフォールバック。references/storytelling.md：4つの教育構造、テンポテーブル、脚本ルール。references/styles.md：5つのスタイルのカラーパレット/フォント/アニメーション/適用トピック。references/formats.md：アスペクト比、セーフゾーン、縦型レイアウトの再構築ルール。references/audio.md：TTSオプション、人間の録音、BGM合成、ダッキング、ラウドネス、単一エンコード。references/qa.md：検収リストと自動チェックコマンド。