Liのコードアニメーションスキル

一言で言うと：数学の授業で「説明しづらい」箇所を、約90秒で一時停止して繰り返し見られ、数式が常に正しく配置されたコードアニメーション動画に変換します。

コア技術チェーンは4ステップで固定され、AIによる画像生成は行いません：HTML/CSS/SVGで画面を定義 → GSAPでタイムラインを構築 → ヘッドレスChromiumでフレームごとにスクリーンショット → FFmpegでH.264 MP4にエンコード。HyperFramesは工程管理とスケジューリングのみを行い、フレームは一切生成しません。印刷機のようなもので、原稿は自分で書く必要があります。

前提条件（作業開始前に確認し、不足があれば先に進まないこと）

プロジェクトルートで npx -y [email protected] doctor を実行し、以下の4項目すべてが緑色であることを確認してください。

ソフトウェア	バージョン	用途	不足時の影響	インストール方法（Linux/クラウドPC）
Node.js	≥22	CLIとスクリプト実行	全体のワークフローが起動しない	`nvm install 22`
FFmpeg と ffprobe	4.x	エンコード、フレーム抽出、パラメータ確認	ffmpegのみでffprobeがない場合、エクスポートと確認が失敗する	`apt install ffmpeg`（ffprobeも含む）、サードパーティのパッケージマネージャーは避けること。不完全なインストールになりがち
Chromium / Chrome ヘッドレス	近年のバージョン	フレームごとのキャプチャ	画像が出力されない	`apt install chromium`、クラウドPCでは通常 `/usr/local/bin/chromium` に配置
GSAP	3.x ローカルファイル	タイムラインとトゥイーン	CDNを参照するとエラーなしで画面が真っ黒になる	本スキルの `assets/gsap.min.js` をプロジェクトの `assets/` にコピー

自己チェックにはさらに3つのツールが必要（なくても出力には影響しないが、チェックの精度が下がる）：

ツール	用途	不足時の対応
playwright-core	6シーンの自動スクリーンショット	`npm i playwright-core`
ffmpegのscaleフィルター	スクリーンショットの明るさ診断	DOM診断のみに自動的にダウングレード
zip	ソースコードのパッケージ化	tar.gzを使用し、納品時にその旨を明記

必ずハマる5つの落とし穴

ffmpeg と ffprobe が両方存在する必要があります。多くのシステムでは前者しかインストールされていません。
wingetやポータブルパッケージを混在させないでください。PATHのバージョンが一致しなくなります。
GSAPは常にローカルファイルを使用し、CDNは禁止です。CDNが切断されると、エラーなしで動画全体が真っ黒になります。
ブラウザはソフトウェアレンダリングで動作します（ログに BeginFrame did not run が表示されるのは正常です）。GPUを気にする必要はありません。
レンダリングのデフォルトビットレートは約500 kbpsのみです。1080pでは通常3～8 Mbpsが必要です。ビットレートを明示的に指定しないと、暗い色の細い線がぼやけます。セクション6を参照してください。

ルート選択：デフォルトはA、ナレーションや複雑な画面が必要な場合のみB

	Aトラック・純粋なグラフィック（デフォルト）	Bトラック・ナレーション/複雑な画面
適している	関数グラフ、幾何学、公式導出、概念の識別	ナレーション解説、手/キャラクター/地図/3D、BGM付き動画
画面	本スキルの6シーンHTML+SVG、座標固定	`code2video` スキルを呼び出し：film.json スクリプト + ブロックライブラリ
音声	デフォルトではナレーションなし、字幕は画面内のテキスト。BGMは後でユーザーが編集	TTSナレーション + BGM + ラウドネス調整
コマンド	`npx [email protected] render`	`node $C/tools/make.mjs <動画ディレクトリ> film`
いつ変更するか	ユーザーが「解説音声/ナレーションが欲しい」と明示した場合、または実際の動作、地図、キャラクターが必要な場合	ユーザーが画面とテキストのみを必要とする場合

Bトラックの機能は継承されますが、コピーはされません。code2video のengine/kits/presetsを本スキルにコピーする（約20MB、両スキルのアップグレード後のバージョンずれを引き起こす可能性がある）代わりに、すでにインストールされているものを呼び出します。詳細は references/two-tracks.md を参照してください。ストーリーボードは両トラックで共通で、AトラックのストーリーボードはBトラックの film.json に変換できます（scripts/story-to-filmjson.mjs）。

タスク受領後の実行フロー

0 · 環境自己チェック

npx -y [email protected] doctor
ls assets/gsap.min.js

不足がある場合は、インストールコマンドを表示し、ユーザーがインストールを完了するまで待機します。実行できるふりをしないでください。

1 · 質問による補完（ユーザーは通常、一言だけしか言いません）

先生はだいたい20文字程度で話し始めます：「コードで動画を作ってください。虚数について、x²=-4 となる x は存在するのか」。残りの仕様はあなたが補完します。質問は4つだけで、それぞれに選択肢を提示します：

質問	なぜ質問が必要か	推奨デフォルト値
説明をどこで止めるか	数学的な結論が決まり、動画全体で唯一「間違う」可能性がある箇所	新しい概念を必要としない手前で止める
尺と段落	シーンの分割数が決まる	90秒・6シーン
ストーリーボードは誰が決めるか	ユーザーがすでに板書の順序を持っている可能性がある	あなたが書き、最初にユーザーに見せる
対象学年	内容の深さと語彙が決まる	テーマが属する学年に基づく

テーマスタイルは質問しません：デフォルトは深夜の光跡ダークテーマ（ユーザーは固定済み）。ユーザーが白背景を指定した場合のみ変更します。

ユーザーが「お任せします」と言った場合、デフォルト値を一文にまとめて返します（「なるべくダーク、90秒、6シーン、この手前で止める形で進めます。問題があれば止めてください」）。彼がうなずくだけでOKです。

2 · 6シーンのストーリーボードを作成し、ユーザーの承認を待つ

セクション3の骨格に従って、ストーリーボード表を作成します：シーン番号、尺、画面要素、字幕の原文、そのシーンで解決すべき問題。ストーリーボードのみを提示し、コードは書きません。ユーザーが「OK」と言ったら、ステップ3に進みます。このステップでのやり直しコストが最も低いため、必ず確認を取ってください。

3 · プロジェクトを作成する

node <スキルディレクトリ>/scripts/init-project.mjs --name <プロジェクトディレクトリ> --title "<動画タイトル>" --scenes 6

スクリプトは以下を実行します：assets/project-template/ の6シーン骨格とindex.htmlをコピー、GSAPをコピー、verify-seeks.json 骨格を生成。手動で npx hyperframes init を実行する必要はありません。テンプレートはすでに契約に準拠しています。

テンプレートの内容は「反比例kの幾何学的意味」の完全な6シーン（ダークテーマ版）です。そのまま再レンダリングして同じものを作成できます。テーマを変更する場合は、座標系、タイムライン、スタイルはそのままに、テキストとK値のみを変更します。ゼロから書くよりもはるかに高速です。

4 · シーンごとに画面を書く

6シーンそれぞれに1つのファイル：compositions/scene-1-hook.html … scene-6-outro.html。index.html はマウントのみを行います。すべての内容を1つの巨大なHTMLに記述しないでください。
すべての座標はハードコードされ、フローレイアウトは使用しません。まず原点と縮尺を定義します（例：OX=460, OY=620, S=96、1単位 = 96ピクセル）。すべての点はそこから計算します。
曲線は関数に従ってサンプリングしてpathを生成します。手描きの近似は禁止です。
数式と配色は references/visuals.md に従います。議論範囲は references/math-rules.md に従います。

5 · lint

npx -y [email protected] lint

エラー0、警告0である必要があります。エラーがある場合は、エラーに従って修正し、再実行します。

6 · 6シーンのスクリーンショット（自己チェック1～3）

node <スキルディレクトリ>/scripts/verify.mjs --browser=/usr/local/bin/chromium

各シーンで最も情報量の多い秒にシークし、verify-shots/ にスクリーンショットを保存します。同時に、GSAPが読み込まれているか、タイムラインが登録されているか、要素がはみ出していないか、JSエラーがないかを診断します。各スクリーンショットを自分で確認してください。実行が完了したら終わりではありません。

7 · フレーム抽出による確認（自己チェック4）

前回のバージョンの完成動画から16フレームを抽出してパネルにまとめ、各キー要素が実際に主張したタイミングで表示されていることを確認します。方法は references/qa.md を参照してください。

8 · 全編をレンダリング（必ずビットレートを明示的に指定すること）

npx -y [email protected] render --output <name>.mp4 --quality delivery --video-bitrate 3M

--video-bitrate と --crf は排他的で、どちらか一方を選択します。90秒の1080p完成品は通常15～25MBになります。10MB未満の場合は圧縮が強すぎます。

9 · 完成品パラメータの確認（自己チェック6）

node <スキルディレクトリ>/scripts/inspect-video.mjs <name>.mp4 --expect-duration 90

解像度、フレームレート、総フレーム数、尺、ビットレート、ファイルサイズを確認します。いずれかの項目が不合格の場合は、ステップ8に戻って再レンダリングします。

10 · 納品

zip -qr <name>-project.zip <プロジェクトディレクトリ> \
  -x "<プロジェクトディレクトリ>/node_modules/*" -x "<プロジェクトディレクトリ>/verify-shots/*" \
  -x "<プロジェクトディレクトリ>/.verify-tmp/*" -x "<プロジェクトディレクトリ>/*.mp4"

納品物は3点：完成品mp4、ソースコードのみのプロジェクトパッケージ（mp4は除外）、3つの説明（何についてか、ユーザーに代わって何を決定したか、どこを先生に確認してもらうべきか）。ファイルを送付するだけでは納品とはみなされません。

三、6シーン骨格（90秒基準）

尺は要求に応じて拡大縮小可能ですが、構造の順序は変更しないでください：まず引きつけ、次に一歩進み、次に一般化し、次に結論を導き、次に誤りを訂正し、最後にまとめる。

#	シーンID	開始/尺	このシーンの役割	必須要素
1	`s1-hook`	0 / 10	本当の疑問を投げかけ、見続けたいと思わせる	メイングラフィック固定 + 右側に行質問3行 + 下部に図の注釈
2	`s2-q1`	10 / 20	最も単純なケースでキーとなる量を計算する	座標軸、曲線、動点、矩形/三角形、行ごとに表示される字幕
3	`s3-other`	30 / 18	別の象限で同じ結論を検証する	4つの曲線を順にハイライト + 結論カード
4	`s4-triangle`	48 / 15	結論を半分に分割し、大前提を示す	幾何学ブロック + 直角マーク + 推論3行
5	`s5-table`	63 / 12	最も一般的な間違いを訂正する	細線テーブル + エラーカード（取り消し線付き）+ 正解カード + キーフレーズ
6	`s6-outro`	75 / 15	座標尺度を変えて結論を繰り返し、締めくくる	同じ構成の縮小版 + 中央揃え3行 + パルス強調

index.html のマウントポイント：body の背景色は固定（ダーク #050a14）、6シーンの track-index は0～5で連続、start/duration は上記の表と一致、動画全体の title は「テーマ｜サブタイトル名」とします。

四、数学的議論のクイックリファレンス（間違えると教育事故）

ハード制約です。各項目を画面に反映させる必要があります。完全なリストと逆の例は references/math-rules.md を参照してください。

記号のみを導出し、数値は代入しない。反比例の説明は |k| と ½|k| までとし、「4」のような具体的な値は動画全体に登場させない。一般的な結論についても同様。
分数は常に水平分数線を使用。スラッシュや a/b の表記は使用しない。
三角形の記号はSの右下添え字にする。文字と横並びにしない。
「共有点」を使用し、「交点」は使用しない。
負の数の場合の表現は固定：「k<0 のとき、第2・第4象限でも同様」。
同じ概念は動画全体で一つの単語を使用し、言い換えない。字幕の用語は教科書と一致させる。
結論が現れる前に、画面にはその根拠がすでに描かれている必要がある。「結論が先に出て、根拠が後から」は許されない。

五、ビジュアルクイックリファレンス（デフォルト：深夜の光跡）

完全な色の値と実装は references/visuals.md を参照してください。暗い背景の3つの鉄則を覚えておけば、他は調整可能です：

面の塗りつぶしは18%までに抑え、ストロークを追加する。暗い背景で40%の塗りつぶしは霧のようにぼやけます。
三角形/幾何学ブロックは「琥珀色の輪郭 + 非常に薄いシアン色の塗りつぶし」を使用する。金色のベタ塗りを濃い青の上に重ねると、汚れたオリーブ色になります。
表には背景色を使用せず、細い線で区切る。白い背景の表をそのまま使用すると、3行がつながって1行のように見えます。

フォントサイズは全体に白背景版よりも4号大きくなります。左上の角のサブタイトルは固定で Vibe 知識大賞｜本コーナー小タイトル、26px、文字間隔5px、left 84 / top 70。

**フォントの鉄則：3つの役割に分類――日本語はNoto Sans CJK SC（源ノ角ゴシック）、ラテン文字ラベルと数字はInter、数学記号はTeX Gyre Termesセリフ斜体（Timesと同族で、教科書の文字形状と一致）。@font-face は <template> 内の <style> に記述する必要があります（headに置くとキャプチャハーネスによって破棄され、フォントは静かに読み込まれません）。詳細と4つの落とし穴は references/visuals.md のセクション0を参照してください。

六、レンダリングとビットレート

パラメータ	値	説明
`--quality`	`delivery`	高画質モード。デフォルトモードではビットレートが低下する
`--video-bitrate`	`3M`	必ず明示的に指定すること。`--crf` とは排他的
`--resolution`	デフォルト landscape（1920×1080）	4Kは明確な要求がある場合のみ使用
`--resume`	中断後のレンダリング再開	レンダリング済みフレームは再度レンダリングしない

判定基準：90秒 → ファイルサイズ15～25MB、ビットレート1.5Mbps以上、2700フレーム、尺90.000000秒。数値が合わない場合は再レンダリングし、納品しないでください。

画質が不十分な場合（実測：`--video-bitrate` が機能しない）

2026-11実測：--video-bitrate 30M でレンダリングしても、依然として1.8Mbps。--quality delivery でも同様。 つまり、内蔵エンコーダのビットレートパラメータは基本的に無視されます。納品品質の画質を実現するには、自分でエンコードを制御する必要があります。ユーザーが「見づらい」と言った場合は、この手順に従ってください。--video-bitrate を繰り返し調整しないでください：

# 1) フレームのみレンダリング、エンコードはしない（2700フレーム / 約2.4GB / 16分）
npx -y [email protected] render --format png-sequence --output pngseq

# 2) 自分でエンコード。静止コンテンツが多く、文字が細いため、CRFではなくCBRを使用する必要があります（CRFは0.5Mbpsしか出力できず、プラットフォームでの再エンコードでぼやける）
ffmpeg -v error -framerate 30 -i pngseq/frame_%06d.png \
  -c:v libx264 -b:v 4M -minrate 4M -maxrate 4M -bufsize 8M \
  -preset slow -tune animation \
  -x264-params "nal-hrd=cbr:aq-mode=3:chroma-qp-offset=-2" \
  -pix_fmt yuv420p -movflags +faststart -y out.mp4

chroma-qp-offset=-2 はカラーの細い線画用です。シアン色の文字、琥珀色の文字は4:2:0の色差サンプリングでエッジの色が落ちることがあります。この設定により、色差が輝度よりもわずかに多くのビットレートを得られるようになります。

エンコードには約2分かかり、90秒 / 43MB / 4Mbpsになります。40MBというラインは「教室で再生でき、プラットフォームでの再エンコード後も鮮明」というバランス点です。10MB未満のファイルはスマートフォンで見るとぼやけて見えます。プラットフォーム（ビデオ番号/抖音）にアップロードする場合は、さらに -b:v 8M のマスター版（約85MB）を追加します。プラットフォームでの再エンコード後も文字を保持できます。

4Kのアップサンプリングは期待しないでください。ソフトウェアGPUでは2700フレームのレンダリングに1時間以上かかります（実測では20分で8%）。単一の動画の制作期間では対応できません。

エンコード後は、1:1で1フレームを確認する必要があります（crop=760:300 で文字のエッジにブロックノイズやリンギングがないか確認）。サムネイル全体だけではぼやけを確認できません。

効果音（ポイント効果音。BGMではない）

ユーザーが「音を追加して」「静かすぎる」と言ったが、BGMは要求していない場合、ポイント効果音のみを追加します：画面でアクションが発生するたびに1回だけ鳴らし、鳴ったら終わり。数学解説動画にBGMを入れると、考える感覚が弱まり、先生自身のナレーションもかき消されます。

# 1) ストーリーボードのアクションポイントに従ってタイムラインを記述（絶対秒）。サンプルは assets/sfx-events.example.json を参照
python3 <スキルディレクトリ>/scripts/make-sfx.py events.json -o sfx.wav --duration 90

# 2) ビデオストリームをコピーし、オーディオトラックのみをミックス（画面のピクセルは一切変更しない）
ffmpeg -v error -i in.mp4 -i sfx.wav -c:v copy -c:a aac -b:a 128k -shortest \
  -movflags +faststart -y out.mp4

6種類の効果音はそれぞれ異なる役割を持ちます：brush 曲線/線分の成長、slide 動点の等速スライド、tick テキスト1行の出現、ding カード/タイトル/疑問文、thump 最も重要な量、chime ✓/キーフレーズ/エンディング。

3つのルール：

すべての行に音を鳴らさない――「画面のアクション」のみを選びます。90秒の動画で約30ポイントあれば十分で、多くなるとうるさくなります。
ピークは -16dBFS 以内に抑える。tick は約 -29dB、thump/ding は約 -24dB に設定します。このレベルであれば「聞こえるが、邪魔にならない」。
ミックス後、ffmpeg -ss <t> -t 0.6 -af volumedetect でスポットチェックします。効果音がある場所は -24～-30dB、無音部分は -91dB（真の無音）である必要があります。効果音がある場所で -18dB より大きい場合は、音量を下げます。

七、6つの自己チェック（納品前にすべて合格する必要あり）

#	チェック内容	コマンド	合格基準
1	構造の準拠	`npx -y [email protected] lint`	0/0
2	6シーンに画面がある	`scripts/verify.mjs`	6シーンすべてが画像を出力。黒画面、JSエラーなし
3	要素が範囲外に出ていない	同上、診断レポートを確認	はみ出しエントリなし。字幕の下端からの距離 ≥80px
4	タイミングが実際に合っている	フレーム抽出でパネル化（qa.md参照）	各セグメントの要素が主張したタイミングで表示されており、空のセグメントがない
5	議論が正しい	math-rules.mdと照らし合わせてシーンごとに字幕を読む	7つのルールすべてをパス
6	完成品パラメータ	`scripts/inspect-video.mjs`	解像度/フレーム数/尺/ビットレート/ファイルサイズがすべて基準を満たす

チェック1、2、3、4、6は機械が判断し、人間が再確認します。チェック5は人間のみが実施可能です。これは教育事故を防ぐことができる唯一のチェックです。

八、修正・反復のルール

ユーザーから意見があった場合は、「3点セット」で受け付けます：どのシーン / 何秒目 / 何に変更するか。あいまいな「ここがちょっと」という意見には、場所を特定するための質問を返します。セクション全体を作り直さないでください。

修正後は、必ず再実行する必要があります。変更が座標やフォントサイズに関わる場合は → 1+2+3。テキストに関わる場合は → 5。複数のシーンに関わる場合は → すべての6チェック。

一度に複数の修正をまとめた方が、小規模な修正を繰り返すよりも高速ですが、シーンをまたぐ大きな修正の場合は、ストーリーボードを再作成して確認を取る必要があります。

実際の修正プロセス（10の実例）は references/revisions.md を参照してください。

九、禁止事項

assets/gsap.min.js が存在しない、またはCDNを使用する
scaleX/scaleY + transformOrigin を使用してSVGの線分を成長させる（一端からのみ成長する）
onUpdate を使用してSVG属性を駆動する（シーク時にトリガーされず、スクリーンショットがずれる）
letterSpacing、width など、リフローを引き起こすプロパティをトゥイーンする
d="" のときに先に getTotalLength() を呼び出す（最初にダミーのdを与える必要がある）
レンダリング時にビットレートを指定しない
すべての内容を1つのHTMLに記述する
分数をスラッシュで表現する
納品時にmp4のみを送り、何を変更したかを説明しない
SVG <text> 内に <sup> を入れる（HTMLタグをSVGに入れると、テキスト全体の位置がずれる。上付き文字は常に ² 文字を使用する）
全幅（1920）のコンテナでスケールパルスを実行する（4%拡大すると境界に衝突し、チェック3で範囲外と判定される。スケールはコンテナ内のインラインブロックに適用する）
絶対配置の取り消し線を、対象テキストの兄弟要素に配置する（列全体にまたがることになる。テキスト自身の相対配置コンテナ内に配置する）
循環パルスに repeat: -1 を使用する（子コンポジションに data-duration がない場合、lintは必ずエラーを報告する。有限の繰り返し回数に変更する）
プロジェクトルートに一時的な .html ファイルを残す（2つ目のルートとして認識され、lintは「1つのindex.htmlのみ許可」と報告する）
曲線を2つのパス（明るい線 + グロー）で描画する場合、明るい線にのみ dasharray/dashoffset を設定する（グロー全体が早期に表示され、「まだ描画が完了していないのに影の部分がある」ように見える。両方に設定し、同じタイミングでトゥイーンする）
--video-bitrate で画質を追求する（実測では機能しない。セクション6を参照）
エンコードをCRFのみに依存し、ファイルサイズを確認しない（静止コンテンツではCRFは0.5Mbpsしか出力できず、プラットフォームでの再エンコードでぼやける）
英数字のレンダリングにシステムデフォルトフォントを使用する（system-ui はヘッドレスChromiumではDejaVu Sansになり、英数字がのっぺりとする。常に "Inter", sans-serif を使用する）
font-family に日本語名を記述する（例："Noto Sans SC"。インストールされていない場合、lintは font_family_without_font_face を報告する）
座標軸を2本の直線のみで描画し、端点に正の方向の矢印を描画しない（教科書の標準：xは右向き、yは上向き。それぞれに中実の矢印。書き方は references/visuals.md の「座標軸」セクションを参照）

九・五、古いプロジェクトにフォントを追加する

古いプロジェクト（フォントがまだ system-ui）を再構築する必要はありません。1つのコマンドを実行するだけで、3つの役割のフォントにアップグレードできます：

node scripts/apply-fonts.mjs --project <プロジェクトディレクトリ>

これにより5つの処理が行われます：フォントを assets/fonts/ にコピー、@font-face を <template> の <style> に統合（headにあるものはキャプチャハーネスによって破棄される）、.row/.cap/.tag コンテナに Inter をロック、本文中の裸の変数 x/y/k/S を1つずつ <i> で囲む（純粋なCSSセレクタでは裸のテキストを制御できない。これは「フォントを変更したのに変わらない」という最も一般的な原因）、SVGの font-family を 'Termes', serif に変更し、x/y/k に斜体を追加。数学記号は一律 calc(1em + 2px) で、セリフ体のサンセリフ体に対する視覚的な縮小を補正。冪等で、再実行しても重複して挿入されません。

変更後は通常通り実行します：lint → verify → render。必ず再レンダリングする必要があります。フォントは古い完成品には適用されません。

十、参考ファイル

ファイル	いつ読むか
references/pipeline.md	初めて作業する場合、または4つのステップの連携を誰かに説明する必要がある場合
references/math-rules.md	数式や結論を書く前
references/visuals.md	配色、フォントサイズ、カード、数式のレイアウトを決める時
references/prompts.md	質問による補完、ストーリーボード作成、他の人に最初の一言をどう言うか教える時
references/revisions.md	ユーザーから意見があった時、または教研グループに「10回の修正がどういうことか」説明する必要がある時
references/qa.md	各ラウンドの自己チェック、動画を納品できるかどうかの判断
references/two-tracks.md	ナレーション/BGM/手/地図/キャラクターが必要で、Bトラックに変更する時
`assets/project-template/`	プロジェクト作成時に `init-project.mjs` によってコピーされる。手動で変更しないこと
`assets/gsap.min.js`	プロジェクト作成時にプロジェクトの `assets/` にコピーされる

Li的代码动画技能