Web Video Presentation

記事またはナレーション原稿を段々と、スクリーンショット可能な「ビデオに偽装されたウェブページ」に仕上げ、オプションでナレーション音声を合成できます。成果物 = Vite + React + TS プロジェクト + 章ごとに分割された音声。

適用シーン

• 「ナレーション原稿 / 記事があり、ビデオにしてほしい」—— ナレーション駆動のコンテンツ
• 「動的 PPT」を制作したい
• 16:9 横画面スクリーンショット、大文字、余白、各画面に動きが必要
• 教学 / 製品デモ / keynote に映画感を出したい
• B 站 / YouTube / 抖音 ビデオコンテンツ

本 Skill は 方法論 + 協業フロー をコア としています。スカッフォルドテンプレートはトークンとプリミティブを提供しますが、美学的な決定（配色、フォント、動きの気質）は全てあなたのテーマに合わせて再設計すべきです —— そのままコピーしないでください。

---

ワークフロー全体像

Phase 1   コンテンツ編集
   1.1  ユーザー入力を認識
   1.2  一度の産出 script.md + outline.md
        （ナレーション原稿 + 開発計画）
   ▼
[Checkpoint Plan]      ← 必ず停止。一度整合 5 つのもの：
                         原稿 / outline / テーマ / 素材 / 開発モード
   ▼
Phase 2   ウェブ開発
   2.1  スカッフォルド（選定したテーマ別）
   2.2  第 1 章 = メインスレッド + 完全版（強制 anchor）
        ▼
        [ハードノード] ユーザー検収第 1 章 ← スキップ不可
        ▼
   2.3  第 2~N 章（選定したモード：A 章ごと / B 順序 / C 並列）
   ▼
[Checkpoint Audio]     ← 必ず停止。音声合成するかどうか
   ▼
Phase 3   音声合成（オプション）
   ▼
Phase 4   スクリーンショット + 後期処理

作業ディレクトリ約定（agent がユーザーの現在のディレクトリ下で作成 / 編集）：

my-video/
├── article.md          # ユーザーが元の文を与えた時は必須 —— 削除不可！開発段階の画面情報源
├── script.md           # 必須：B 站スタイルナレーション原稿（リズムを決定）
├── outline.md          # 必須：開発計画（章分割 + 各ステップ内容 + 情報プール）
└── presentation/       # スカッフォルドが産出した Vite + React + TS プロジェクト
    ├── src/chapters/<NN>-<id>/
    │   ├── <Chapter>.tsx     # ビジュアル実装
    │   ├── <Chapter>.css
    │   └── narrations.ts     # ★ ステップ数 + ナレーション文本の唯一の真実源
    ├── scripts/
    │   ├── extract-narrations.ts   # 全 narrations.ts をスキャン → audio-segments.json
    │   └── synthesize-audio.sh     # mmx を呼び出して合成 mp3
    ├── audio-segments.json         # extract の産出（合成前の review）
    └── public/audio/<id>/<N>.mp3   # オプション：合成された音声

キー：narrations.ts はステップ数と音声合成の 唯一の真実源 です。 章の .tsx で if (step === N) が出現する最大 N + 1 は narrations.length に等しくなければなりません。これで 5 つの場所（script / outline / 章コード / chapters.ts / 音声ファイル）がずっと漂流しないことを保証します。

---

ハード自検プロトコル（本 Skill 全体を通じて）

下記の 3 つの成果物は、それぞれ 完成後に必ず自検 → 修正 → 報告 / 進行をします：

成果物	自検チェックリスト出典
script.md	SCRIPT-STYLE.md 3 層自検（形式 / 骨格 / 読み上げ）
outline.md	OUTLINE-FORMAT.md 自検
単章実装完了	CHAPTER-CRAFT.md 完工自検

実行方式（能力低下による、より隔離された方式を優先使用）：

1. Agent Teams（最適）：独立のレビュアー agent を開き、「産出ファイル パス + 対応チェックリスト + キー文脈」を与え、項目ごとに厳密にチェック して 厳密に結論を報告させます （どの項目が pass / どの項目が fail + 証拠 + 修正提案）。
2. subAgent（次善）：Teams 能力がないが subagent を開くことができれば subagent で同じフロー。
3. 自検（フォールバック）：上記の能力がなければ、現在の agent が 厳密に項目ごとに チェックします —— 目測で一回見て終わりは許されません。

鉄律：結論を得た後、先に fail 項目に従って成果物を修正してから ユーザーに報告します「完成 + 自検結論 + 何を修正したか」。最初の結論のままで修正しないで報告 = 違規。

---

各段階のファイル読取ガイド

異なる段階で異なるファイルを読みます。長い会話の中で agent は原則を忘れやすいです、特に Phase 2.4 の「単章実装」は N 回繰り返されます —— 毎回もコア制約を見直す必要があります。

段階	必読（毎回見る）	一度見終わる / 必要に応じて確認
Phase 1.1-1.2 コンテンツ編集	references/SCRIPT-STYLE.md + references/OUTLINE-FORMAT.md + article.md（ユーザーの元の文、あれば）	——
Checkpoint Plan テーマ選択	——	themes/*/theme.json（動的に全テーマを読み、リストを作成 + bestFor 推奨 + descriptionZh）；references/THEMES.md（ユーザーがテーマシステムを理解したい時）
Phase 2.1 スカッフォルド	——	本セクション SKILL.md を一度見る
Phase 2.4 単章実装（×N 回、2.2 / 2.3 に呼ばれる）	references/CHAPTER-CRAFT.md 単一入口 —— Part 0 十条原則 / Part 1 開工 5 問 / Part 2 関係→動作決策木 / Part 3 ビジュアルツールボックス / Part 4 時間参考 / Part 5 反 AI 味反パターン / Part 6 コード硬規則（narrations.ts 強制制約を含む）/ Part 7 完工自検 / Part 8 反馈速查 + 現在のテーマの themes/<id>/theme.json + 現在の章の outline.md パラグラフ + article.md 本章対応パラグラフ + 素材リスト	references/EXAMPLES/（構造ヒント、抄袋テンプレートではない）；references/THEMES.md 完全トークン契約
Phase 3 音声合成	references/AUDIO.md（narrations.ts → segments.json → mmx フロー を含む）	——
Phase 4 スクリーンショット + 後期処理	references/RECORDING.md（?auto=1 自動スクリーンショット を含む）	——
テーマ選択 / 製作 / 変更	——	references/THEMES.md

章を書く時は CHAPTER-CRAFT.md 一ファイルだけを読みます。十条原則 / 開工 self-prompting / 決策木 / 反 AI 味反パターン / 完工自検は全てこの一ファイルに含まれます。EXAMPLES/ は必読ではありません —— 先にコンテンツで自由に設計してください、詰まったら翻す（anchor で「形」を翻す、そのままコピーしないでください）。

---

Phase 1 —— コンテンツ編集（一度の産出）

1.1 ユーザー入力を認識

ユーザーが与えたもの	すべき事
元の記事（書き言葉 / 公众号 / 論文 / ブログ）	一度の産出 script.md + outline.md（1.2），Checkpoint Plan へ
直接のナレーション原稿 / ビデオスクリプト	script.md に保存、一度の産出 outline.md（1.2 簡略版），Checkpoint Plan へ
何もなし、只「X テーマのビデオを手伝ってください」	質問を返す：先に素材または大綱を与えてください。Skill はユーザーのためにコンテンツを構想しません

1.2 一度の産出 script.md + outline.md

二つの成果物は一度の思考で完了します：

1. script.md を生成：references/SCRIPT-STYLE.md の規則に従い article を B 站スタイルナレーション原稿に変換します。article.md を削除しないでください —— outline を書く時や章実装で画面時の細部情報源です（二源則）。
2. outline.md を生成：references/OUTLINE-FORMAT.md 規則に従い章を分割 + ステップを分割 + 各章の最初の段落から 情報プール を抽出します。

outline の境界（キー）：

outline は必ず書く	outline に書かない
章分割 / 各章ステップ数 / 推定時間	具体的なアニメーションタイプ（blur clear / wipe / バネ）
各ステップの画面内容（hero / データ / タグライン / リスト項目）	CSS 実装手段（filter / SVG / clip-path）
章レベル 情報プール：article から抽出した数字 / 引用 / ケース / タグ	時間数値（2.5s / 80120ms と書かない）
ステップレベルの関係名前プレフィックス（「対比」/ 「段階列」/ 「金言」など可選 hint）	持続微動 / ずれ量などマイクロリズム

outline にアニメーションを書かない理由：アニメーション固定 = chapter agent は翻訳機に退化； 留白で chapter agent が各ステップ開工時に CHAPTER-CRAFT.md の「内容駆動決策木」に従って自由に設計すれば、真のビデオ感が出ます。詳しくは CHAPTER-CRAFT.md Part 0 原則 7。

保存後は必ず自検をしてから Checkpoint Plan へ：上記「ハード自検プロトコル」に従い script.md / outline.md をそれぞれ実施（優先 Agent Teams → subAgent → 自検）、結論に従い修正完了後に Checkpoint Plan へ進みます。

---

Checkpoint Plan —— 5 つのもの一度整合（ハードノード）

script.md + outline.md 完成後は必ず停止します。ユーザーはこの 1 つのノードで同時に 5 つのもの を確認します。

agent がこの時点で準備すべき事

1. 全ての themes/*/theme.json を読み nameZh / descriptionZh / bestFor / mood を取得 —— ハードコードされたリストを使わない
2. script.md のコンテンツタイプ / キーワード / トーンに従い、主動的に テーマから 2~3 套の 最もマッチした推奨（bestFor フィールドをマッチ）を選定
3. outline.md 末尾の「素材リスト」部分をスキャン

要約テンプレート（骨組み、agent が状況に応じて埋める）

コンテンツ計画完成、成果物ファイル：
  📄 article.md     {ユーザーが元の文を与えた場合は保持}
  📄 script.md      {X} 字 / ~{T} 分钟
  📄 outline.md     {N} 章 / {M} ステップ + 各章情報プール + 末尾素材リスト

章概览：
  1. <id>     <章タイトル>    <S> ステップ ~<T>s
  2. ...

次は一度整合 5 つのもの：

  1. 原稿 (script.md) を修正したいですか？
     ファイルを直接編集するか、修正方向を口頭で教えてください。

  2. 開発計画 (outline.md) を修正したいですか？重点を見てください：
     - 章分割 / ステップ数 / 推定時間は合理的ですか（合理性判断：各章 30~60s）
     - 各ステップの画面内容は明確ですか
     - 各章の最初の段落「情報プール」は article の細部が十分にありますか
     - 末尾の素材リストは完全ですか

  3. どのテーマを選びますか？私の推奨：
     ★ <推奨 1：nameZh (id)> — 理由 <bestFor 命中>；<descriptionZh 要約>
     ★ <推奨 2 / 推奨 3>
     その他可選：<残りテーマ、nameZh + 一文>
     また新テーマを製作する手もあります（詳しくは references/THEMES.md）。

  4. 素材はどう準備しますか？大体このビデオに必要な画像：<粗いリスト>
     a) <既存素材パス> から手伝い   b) 自分で提供   c) 全て placeholder

  5. 開発モード どれを選びますか？

     **第 1 章はどのモードでもメインスレッドで完了 + ユーザー検収**（強制 anchor）。
     第 2 章以降の差は：

     A) デフォルト · 章ごと確認（推奨）
        各章完成後に暂停検収 → リスク管理 / リズム最安定
     B) 第 1 章後順序開発（並列なし）
        第 2~N 章メインスレッド順序完成後に統一検収 → 速度中 / agent が並列に対応していない場合に適合
     C) 第 1 章後並列開発（subagent）
        第 2~N 章は subagent で並列 → 最速 / ユーザーが並列数を管理（一度 4 章など）
        ⚠️ 各章のスタイルに差異が生じます（これが期待値、テーマ禁止区で兜底）

反馬後：

• 原稿 / outline を修正：ファイルを直接編集、編集完成後に ping（または口頭で agent に修正を依頼）
• テーマは明確にする必要があります Phase 2 へ進むために。ユーザーが「テーマを手伝ってください」 → 推奨の最初のものを取得、 ユーザーに何を選んだか、なぜか説明してください、反悔の機会を提供
• モード確定 → Phase 2 へ

---

Phase 2 —— ウェブ開発

2.1 スカッフォルド

bash <path-to-web-video-presentation>/scripts/scaffold.sh \
  ./presentation \
  --theme=<ユーザーが選んだテーマ id>

bash <path-to-web-video-presentation>/scripts/scaffold.sh --list-themes

カスタムテーマ → 先に references/THEMES.md 「新テーマ製作」フロー に従い themes/<my-theme>/ を製作してから --theme=<my-theme> を使用。

スカッフォルドは 01-example デモを含みます。最初の実章コンテンツを書く前に 削除してください：

rm -rf presentation/src/chapters/01-example

そして presentation/src/registry/chapters.ts の EXAMPLE_CHAPTER の import と配列項目を削除します。

2.2 第 1 章 —— メインスレッド + 強制検収

コア：第 1 章 = 完全版一度で完了（リズム + ビジュアル + 実際の素材完整）。 「骨架版」の概念はありません —— 第 1 章から ユーザーが直接検収可能な 見本を作ります。

第 1 章がメインスレッド必須の理由：

• それは CHAPTER-CRAFT.md このセットの指引が 現在の テーマ + 現在の題材 で最初に落地した実装
• 指引に盲区がある / テーマの色 / フォント token が不足していれば、第 1 章で必ず露出します —— この時人間の反馬があれば、指引 / テーマを早く修正できます、成本が最低です
• 後続章（順序 / 並列いずれでも）も第 1 章のコード様式を参考にするので、第 1 章 = このプロジェクトの「スタイルアンカー（章間完全一致は強制ではありませんが、単章自体は完全な説得力を）」

第 1 章完成後は必ず停止してユーザー検収を待ちます：

第 1 章 <id> 完成、dev server は localhost:5173 で実行。

検収重点：
  □ ビジュアルの雰囲気は対ですか？<theme nameZh> の期待に符合していますか？
  □ リズムは対ですか？いくつかのステップは速すぎる / 遅すぎる / 情報が薄すぎる？
  □ コンテンツ駆動アニメーションは到達していますか？それとも幾つかのステップは無思考入場アニメーション？
  □ 二源則：画面の画像には「ナレーションは念じていないが article から吊り下げられる」細部がありますか？
  □ 反 AI 味チェック：紫ピンク勾配 / 丸角カラー枠線 / 偽イラスト / emoji がありますか？

問題を教えてください、私が対象的に修正します。OK なら「続行」と教えてください、選定したモードで第 2 章以降をします。

2.3 第 2~N 章 —— 選定したモードに従う

全モード下の共通規則：各章は独立して CHAPTER-CRAFT.md に従い開発。章間スタイル完全一致は強制しません —— テーマの色 / フォント token は視覚統一を兜底し、アニメーション / リズム / ビジュアル演示は章の自由発揮です。

モード A · デフォルト · 章ごと確認

第 2 章完成 → 暂停検収 → OK → 第 3 章 → 暂停 → ... → 第 N 章。各章は 独立検収、問題は随時修正、リスク最低、リズム最安定。ユーザーがモードを明示しない時は このモードがデフォルトです。

モード B · 第 1 章後順序開発

第 2 章 → 第 3 章 → ... → 第 N 章 メインスレッド順序完成、最後に統一検収。 速度中程度、agent が並列タスクに対応していない環境に適合。

モード C · 第 1 章後並列開発（subagent）

subagent で第 2~N 章を並列で完成、最大並列数はユーザーが管理（「一度 4 章」 / 「一度 2 章」）。最速ですが、各章のスタイルに差異が生じます —— これが期待値、理由は：

1. 各 subagent は他の subagent の産出が見えず、機械的に対齐できない
2. 章コードは物理的に分離（各章 1 フォルダ / 自分の CSS プレフィックス）、相互に破壊しない
3. テーマ token は視覚統一を兜底（色 / フォント / hero 数字 / カード / 分割線 キャラクター / 装飾）、気質は漂流しない
4. スタイル不一致 = 人手で書いたビデオの呼吸感（マルチボイス / マルチ視角）

並列 subagent の prompt は以下を含む必要があります：

• 現在の章 outline パラグラフ（情報プール含む）
• references/CHAPTER-CRAFT.md のパス（単一必読 —— ビジュアル演示要求 + 段階揭示 + 二源則 + 反 AI 味 + コード赤線 + 完工自検は全てこのファイルに）
• 現在のテーマ theme.json の descriptionZh / mood / bestFor（気質参考のみ、アニメーション / 時間 / フォントサイズ / emoji は chapter agent が自由）
• 第 1 章コードを「コード様式」参考とする（「ビジュアル模倣対象」ではない）
• ハード規則：各章独立 CSS プレフィックス（.cd- / .mg- / .pm- / ...）； chapters.ts を修正しない；完工後 npx tsc --noEmit を実行

重要：どのモードを選んでも、ユーザーはいつでもモードを切り替えられます。第 2 章 OK 後にユーザーが「残りは並列」/ 「残りは章ごと」と言ってもいいです。

2.4 単章実装（各章必須）

詳細ガイドは references/CHAPTER-CRAFT.md —— 単一必読入口、対象：ビジュアル演示要求 / 段階揭示 / コンテンツ取捨 / 二源則 / ビデオ演示基本審美 / 反 AI 味 / コード赤線 / 完工自検。

コアポイント（CHAPTER-CRAFT.md 詳述）：

• 各章は必ず CSS / SVG / Canvas / JS ビジュアル演示を持つ、純文字章は禁止
• 段階揭示：清单 / リスト は必ず 1 項目 = 1 ステップ、一度に全表示は禁止
• 二源則：リズムはナレーション原稿に従う（順序乱さない）、細部は元の記事から抽出（情報プール + 本章 article パラグラフ）
• 完工自検は項目ごとに通す、達成できなければ戻して修正 —— 上記「ハード自検プロトコル」に従い実施 （優先 Agent Teams → subAgent → 自検）、修正後ユーザーに本章交付を報告

2.5 大きな修正後は STORAGE_KEY を bump

chapters.ts を修正後（章を追加 / 削除 / 並び替え、または某章 narrations.ts の長さが変わる）、presentation/src/hooks/useStepper.ts の STORAGE_KEY を bump（例 v4 → v5）、永続化したゲームカウンタが存在しないステップに落ちるのを避けます。

---

Checkpoint Audio —— 音声合成するかどうか（ハードノード）

Phase 2 完了後は必ず停止し、ユーザーに質問：

ウェブ完成、{N} 章 {M} ステップ、dev server は localhost:5173 で稼働。

音声を合成して「自動再生スクリーンショット」を作りたいですか？
  ✓ 合成 → 全章節の narrations.ts をスキャンして audio-segments.json を出力、
           mmx-cli を呼び出して各ステップ 1 つの mp3 を public/audio/ に合成。
           合成完了後 ?auto=1 モードで一鏡到底スクリーンショット可（音ビデオ自然同期）。
           本機に mmx がなければ TTS を聞きます。
  ✗ 非合成 → Phase 3 をスキップ、直接 Phase 4 手動スクリーンショット + 後期配音。

合成 → Phase 3。非合成 → 直接 Phase 4。

---

Phase 3 —— 音声合成（オプション）

詳細フロー は references/AUDIO.md。簡略版：

cd presentation
npm run extract-narrations   # 全 narrations.ts をスキャン → audio-segments.json
# ユーザーに audio-segments.json のテキストを確認させる
npm run synthesize-audio     # mmx を呼び出して串列合成；増量、既存をスキップ

合成完了後ユーザーに報告：出力位置 / 合計セグメント / どのセグメント時間が異常（長い = ステップを分割；短い = 文案が薄い）—— 最後のリズム校準の機会を与えます。その後 Phase 4 へ。

---

Phase 4 —— スクリーンショット + 後期処理

詳しくは references/RECORDING.md。二つのパス：

場景	推奨パス
Phase 3 が既に音声合成	Auto モード一鏡到底：ブラウザで localhost:5173/?auto=1 を開く → SPACE を押す → 全片自動再生完了 → 録画停止 → 頭尾をカット完成、後期音轨対齐不要
Phase 3 をスキップ	デフォルト Manual モード手動クリック推進 → 後期任意編集ツール配音

agent は Phase 3 / Checkpoint Audio ユーザーに適切なスクリーンショット パスを主動告知。

---

十条原則（一文清单）

完全展開は references/CHAPTER-CRAFT.md Part 0 —— 章を書く時そこで確認、下記は索引のみ。

#	原則	一文
1	16:9 固定舞台	コンテンツ 1920×1080 + transform scale、レスポンシブなし
2	全局 ステップ計数器	章はステップの純函数、定時器なし
3	各ステップはフル画面独占	if (step === N) return <FullScene />
4	ナレーション拍子 = ステップ	一拍子 = 一ステップ = 一集约想法
5	隠れた边角コントロール	進捗バー / ページャーはデフォルト opacity 0
6	舞台は chrome なし	header / footer / ページ数 / ブランド行なし
7	コンテンツ駆動アニメーション	先に内在動作を見つけ、見つからなければ入場アニメーション兜底；持続微動は慎重に
8	マルチ点段階揭示	1 項目 = 1 ステップ、同期 stagger で N 項目は禁止
9	整片同一テーマ	章間で表面色を翻さない；色 / フォント token を歩く、その他スケール章の自由
10	二源則	script がリズムを定め、article が画面密度を定める（情報プール に落とす）

---

常見ユーザー反馬速查

簡略表は references/CHAPTER-CRAFT.md Part 8「常見反馬速查」。キー：先にどの層か定位（リズム / ビジュアル / コンテンツ / コード）、最小スライスを修正、整章を再做しない。

---

関連リソース

「いつ読むか」でマーク、一度全て読まないようにします：

ファイル	いつ読むか	内容
references/SCRIPT-STYLE.md	Phase 1.2 必読	記事 → ナレーション原稿規則、プラットフォーム変体
references/OUTLINE-FORMAT.md	Phase 1.2 必読	outline.md フィールド spec、命名約定、章分割、情報プール
references/CHAPTER-CRAFT.md	Phase 2.4 各章単一必読入口	Part 0 十条原則 / Part 1 開工 5 問 / Part 2 関係→動作決策木 / Part 3 ビジュアルツールボックス / Part 4 時間 / Part 5 反 AI 味反パターン / Part 6 コード硬規則 / Part 7 完工自検 / Part 8 反馬速查
references/EXAMPLES/	可選 —— 構造を見る	章構造ヒント（hook / list-reveal / case-tech-review）；抄袋テンプレートではない
references/THEMES.md	テーマ選択 / 製作 / 変更時	完全トークン契約 + 内蔵テーマ清单 + 製作フロー
references/AUDIO.md	Phase 3 の時のみ読む	MiniMax CLI、TTS 退化パス、故障排查
references/RECORDING.md	Phase 4 の時のみ読む	スクリーンショットツール + 後期合成
themes/	Checkpoint Plan / Phase 1.2 時に翻す	内蔵テーマ（各テーマは theme.json + tokens.css を含む）
scripts/scaffold.sh	Phase 2.1 一度実行	ワンキー项目スカッフォルド