Vibe 知識短片（コードフレーム版）

Vibe 知識短編（コードフレーム版）

完成品仕様：1920×1080、30fps、約159秒（楽曲に合わせる）またはカスタム、ナレーションなし、1画面1行の中国語字幕、画面はすべてCanvasコードで描画。 サンプル「半減期」（examples/halflife/）はすべてコンポーネントで構成されており、再現検証済み：元のサンプル映像と67フレームがピクセル単位で一致、ミックス音声もサンプル単位で一致。examples/gallery/は、同じコンポーネントセットでテーマを変えたデモです。

この種の映像で視聴者が評価するのは、次の3点です。真実の事実（年、生データ、論文）、常に動き続ける画面、音楽に合わせた情報の提示。以下の各ルールは、この3点を守るためのものです。

基本ルール（それぞれに過去のトラブル事例あり）

• 画面に表示するすべての数字、人名、年、引用には出典が必要で、事実表に記載します。確認できない場合は表示せず、図示には「図示」と明記します。AIが引用文を作成するとき、非常に「それらしく」作ることがあります。旧版「半減期」のラザフォードの英文名言はその典型です。
• ウォーターマークは、ユーザー自身のアカウント名または映像タイトルのみを記述します。参考フレームを元に作成する際、AIが参考作者の名前を一緒に描画することがあります（旧デモの左上に「比特新語」と表示されていた）。これは無断使用にあたります。
• BGMは、ユーザーが提供し、使用許可のあるファイルのみを使用します。他人の動画から音声を抽出したり、信頼できないサイトからダウンロードしたりせず、スキルに楽曲を添付することもありません。Bilibiliで公開する場合は、Bilibiliの投稿フロー内で音楽を追加します。
• エンドカードと公開用テキストには、AI制作である旨の声明を記載します。
• renderFrame(t) はtのみに依存します。乱数は VF.rng(シード) を使用し、タイマーは使わず、フレーム間で状態を保持しません。そうしないと、エクスポート時にブレが生じ、レンダリングのたびに結果が異なります。

準備

SK=~/.claude/skills/vibe-knowledge-film
$SK/engine/setup.sh          # node / ffmpeg(libx264) / numpy の確認、playwrightパッケージのインストール、ローカルブラウザの検出

フロー（3つの確認ポイントあり。確認後に次のステップへ）

① テーマ選定と方針 → 確認1

AskUserQuestion で質問します（推奨項目を先に）。

• テーマ：ユーザーが方向性のみを示した場合、3つの候補を提案します。良いテーマとは、ハードコアな概念 × 「自分」に落とし込める感情的なポイント（エントロピー → 生活の無力感、半減期 → 忘却は裏切りか）であり、さらに直感に反する展開があるとなお良いです。references/story.md を参照。
• BGM：bgm（ユーザーが「開智小曲」などの使用許可ファイルを提供。映像は楽曲に合わせ、尺は楽曲の長さ）または synth（コードで合成、尺は任意）。
• クレジット（ウォーターマークに何を書くか）、尺（デフォルトは楽曲に合わせ159秒）。

② 事実確認 → 事実表

画面に表示する各事実について：表現 | 出典 | 信頼度（T1: 原文資料 / T2: 信頼できる二次資料 / T3: 「〜と言われている」程度）| 使用する字幕。 調査によってストーリーが変わることもあります：「半減期」で「忘却はべき乗則、古いほど安定する」という事実を発見し、元のサブタイトルを覆し、結果的にエンディングの逆転になりました。矛盾が見つかった場合は、いったん止めてユーザーに伝えます。

③ 字幕原稿 + コンテ → 確認2

6段落構成で記述します（フック → タイトル → 歴史的アンカー → メカニズムデモ → 直感に反する展開 → 視聴者への着地 → 献辞と参考文献）。1画面1行、≤ 6.5文字/秒、キーワードは {} で強調、出典が必要な文には4つ目の項目として小さな文字を表示します。 コンテは各段落に以下の内容を記述します：画面で何が起きているか（1字幕につき1つの画面上のアクション）、「実際に計算している」もの（実際のデータ、実際の数式、固定シードのシミュレーション）、効果音。テンプレート templates/事実表と字幕コンテ.md。事実表 + 字幕コンテをユーザーに提示し、承認を得てからコードを書き始めます。

④ プロジェクト作成、film.js の記述

$SK/engine/new_film.sh <プロジェクトディレクトリ> <プロジェクト名>                 # 6段落のスケルトン
$SK/engine/new_film.sh <プロジェクトディレクトリ> <プロジェクト名> --from halflife  # 「半減期」からスタート / 比較用

まず表示する内容に合わせてコンポーネントを選択します：references/components.md に「何を伝えるか → 何を使うか」の対応表、examples/gallery/コンポーネント図鑑.png に全コンポーネントの外観があります。スケルテンテンプレートはすでにコンポーネントで6段落を構成しており、データとテキストを差し替えるだけです。コンポーネントが不足する場合は、film.js 内でローカル関数を記述します（API は references/engine.md、完全な記述例は examples/halflife/film.js）。ルール：

• 最も難しいカットから先に作成し、静止フレームを表示して成り立つか確認してから、他のカットを作成します。
• 字幕、シーン、効果音はすべて「コンテ上の時間」で記述します。楽曲への合わせ込み（warp）はステップ⑤で行うため、個別に時間を調整する必要はありません。
• シーン内では2～3秒ごとに新しい動きを入れます。長く静止する部分にはマイクロモーション（流れる光、スキャン光、スローパン）を追加します。エンジン標準の呼吸効果は振幅が小さいため、これだけでは「静止」を防げません。
• 新しく出現する文字（シーン内に描画されるが、字幕にはないもの）は strings に追加します。

⑤ BGMとビート合わせ

• bgm：楽曲をプロジェクトディレクトリに配置し、python3 $SK/engine/analyze_bgm.py <楽曲> --json out/bgm.json を実行します。「開智小曲」の場合は、まず data/kaizhi-xiaoqu.json のsha256と比較します。一致すれば、その小節グリッドと推奨アンカーをそのまま使用します。一致しない場合（別のソースでは全体が0.1～0.3秒ずれる可能性あり）、新しく測定した 低域アタックポイント を基準にグリッドを再構築します。その後、meta.music.warp にアンカーを記述します。タイトルフラッシュ → 最初のドロップ、疑問/静寂 → 休息セクション、逆転の提示 → 2番目のドロップ、着地点と献辞 → フレーズの先頭。詳細は references/music.md。
• synth：meta.music.synth に、各セクションの各パートのレベルと無音エンベロープを記述します（サンプルの SYNTH を参考に変更）。

⑥ セルフチェック（全編レンダリング前）

node $SK/engine/export.mjs <プロジェクトディレクトリ> events          # 効果音表 + 字幕タイミング
node $SK/engine/export.mjs <プロジェクトディレクトリ> stills          # out/stills.png、16コマの概要。秒数を指定することも可能 3,16.9,43.6
cd <プロジェクトディレクトリ> && python3 -m http.server 8765 --bind 127.0.0.1   # ブラウザで film.html を開き、タイムラインをドラッグ、BGMを聴く

フレームごとに確認します。文字が枠からはみ出していないか、画面の半分が空いていないか、曲線がデータポイントに適合しているか、何かが間違った位置に漂っていないか、字幕とアクションが一致しているか。これらの問題はコードエラーとしては検出されず、目視でしか確認できません。「半減期」ではこのステップで5つの問題を発見しました。

⑦ レンダリング + 品質チェック

$SK/engine/build.sh <プロジェクトディレクトリ>        # 効果音表 → BGM → フレームごとのレンダリング → -14 LUFS で合成 → qa.py（バックグラウンド実行、約5～12分）
$SK/engine/build.sh <プロジェクトディレクトリ> --skip-render   # 音声のみ変更

qa.py が ✗ を報告した場合は必ず修正します。! は、修正するか、納品時に意図的であることを説明する必要があります。機械も誤判定することがあります。「黒画面」と報告された場合は、まずフレームを確認します。暗い背景は誤判定されやすいです。読み方は references/qa.md を参照。

⑧ 納品 → 確認3

ユーザーに以下を提供します。完成品パス、尺、品質チェック結果、まだ改善すべき点。制作ログ.md を補完します（各トラブル：現象 → 原因 → 修正方法。チュートリアルとして利用する場合、これが各カットのリストになります）。公開用テキストが必要な場合は references/publish.md を参照。

コマンド一覧

コマンド	機能
engine/setup.sh	環境確認とインストール
engine/new_film.sh <ディレクトリ> <プロジェクト名> [--from halflife]	新規プロジェクト作成（エンジンのスナップショットをプロジェクト内にコピー。後でエンジンをアップグレードしても旧プロジェクトに影響なし）
node engine/export.mjs <ディレクトリ> events / stills [秒数,...] / render [開始 終了]	効果音表 / 概要画像 / 動画のエクスポート（開始・終了秒数を指定すると、その区間のみレンダリング）
python3 engine/audio.py <ディレクトリ>	BGM + 効果音 → out/mix.wav
python3 engine/analyze_bgm.py <楽曲> [--json ファイル]	BPM、小節、エネルギープロファイル、低域アタックポイント
engine/build.sh <ディレクトリ> [--skip-render]	ワンクリック作成 + 品質チェック
python3 engine/qa.py <ディレクトリ> [完成品]	単独品質チェック

参考ファイル（必要に応じて参照）

ファイル	いつ読むか
references/story.md	テーマ選定、6段落構成、字幕ルール、事実表の階層
references/style.md	ビジュアル仕様：配色、フォント、5層の画面、レイアウト座標、動きの密度
references/components.md	シーン作成前：21のコンポーネント + 5つのデータファクトリー、「何を伝えるか → 何を使うか」、パラメータ
references/engine.md	VF 基本API、metaフィールド、シーンの記述方法
references/music.md	BGMの2つのモード、開智小曲の構造、ドロップ検出、warpアンカー、効果音表
references/qa.md	品質チェック項目の意味、しきい値、よくある誤検出
references/pitfalls.md	着手前の注意点：「半減期」で踏んだ30の落とし穴 + 類似プロジェクトの落とし穴
references/publish.md	公開テキスト、AI声明、音楽と引用の取り扱い
examples/halflife/	完全なサンプル：film.js（コンポーネント版）、事実表と字幕コンテ、制作ログ
examples/gallery/	コンポーネント図鑑：同じコンポーネントセットでテーマを変更。コンポーネント図鑑.png 概要
data/kaizhi-xiaoqu.json	開智小曲の実測構造と推奨アンカー