Communitygithub.com

paper-explainer

将一篇论文(arXiv / PDF)、技术长文或多篇论文的综述,制作成6–8分钟横屏中文讲解视频:论文卡→观众问题链→口播→盲测+事实核查→分镜→渲染→成片。

paper-explainer とは?

Paper-Explainer 是一个将学术论文(如 arXiv PDF)转化为高信息密度、6-8分钟横屏中文讲解视频的AI Agent技能。它专为有技术背景但未读过原始论文的观众设计,目标是让观众能清晰复述论文的核心改进、有效性原理及可迁移经验,而不纠结于公式推导。该技能基于一整套严格的制作流水线,从精读论文、生成“论文卡”开始,通过构建“观众问题链”驱动口播写作,并强制执行多轮独立盲测与事实核查以确保内容准确易懂。在视觉呈现上,它摒弃PPT式静态翻页,采用3Blue1Brown式连续变形、实景论文“钻入”效果以及Kurzgesagt式大画布运镜,配合自定义风格卡(默认报刊数据新闻风)和本机Chrome WebCodecs硬件渲染。技能配套了完整的 `engine/` 代码库,涵盖画布外壳、配音对齐、混音、音效合成及逐帧渲染,支持并行化章节制作以提高效率,并强调“写的人不验收”的质量控制原则。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ningcodes/paper-explainer-skill/tree/HEAD/skill

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

論文 → 解説動画

対象視聴者:技術的なバックグラウンドを持つが、この論文を読んだことがない人。視聴後は「何を改良したのか」「なぜ有効なのか」「何を学べるか」を説明でき、具体的な例を使って何をしているかを復唱できること。式の導出は行わず、全体像をわかりやすく伝える。

完成品仕様:横画面 1920×1080、30fps、H.264 + AAC、長さ6~8分を基本とし、説明が優先(約10分以内まで許容)。最後のクレジットとチャンネル登録促進文は設定項目(プロジェクトディレクトリの film.json の outro 参照)であり、ハードコードしない。

本スキルとリポジトリ内のコードは連携する:engine/(キャンバスシェル、実体ペーパー、スタイルカード④、WebCodecs レンダリングページ、結合・ミックス、ナレーションアライメント、音楽・効果音)、examples/demo(25秒の最小サンプル)、examples/always-on(完全な1エピソードサンプル)。インターフェースドキュメント:engine/README.md。


一、厳格なルール(各項目は手戻りの経験に基づく。矛盾がある場合はこちらを優先)

  1. 作業開始前に本スキルの全文を読み、サブエージェントへのブリーフにはチェックリスト原文を貼り付け、記憶に基づいて転記しない。 原稿作成・レビュー用のブリーフにはさらに references/voiceover-selfcheck.md 全文を添付する。ブリーフの最初の行に本スキルのパスを記述し、全文を読むよう指示する。
  2. 順序は逆にしてはならない:論理チェーン → ナレーション確定 → 絵コンテ(ショット計画表)→ ナレーション収録 → ラフカットで流れ確認 → エフェクト/アート仕上げ → サムネイルは最後。ナレーションが確定するまで映像を作らない。絵コンテと原稿が確定するまでは、ナレーション以外の素材(オプションのアバターなど)を生成しない。スタイルを先に決めてから内容を変更すると手戻りが発生する。
  3. 書いた人は検収しない。 ナレーションをレビューに提出する前に、独立した「一回聴き」ブラインドテストとファクトチェックを通過する。完成品を著者に見せる前に、制作に関わっていないエージェントが完成動画全体を視聴し、references/review-checklist.md に照らしてレビューし、レビュー報告書を一緒に提出する。
  4. レンダリングは1つのパスのみ:ローカルChromeページ内でのフレームごとの render(t) + WebCodecsハードウェアエンコード(engine/common/shell-wc.html)。ブリーフにはこのパスのみを記述し、「ヘッドレスフレームキャプチャ → ffmpeg」という代替パスは提示しない。レンダリング開始前に10秒間のms/フレームとWebGLレンダラーを測定する。レンダラーがSwiftShader/llvmpipeなどのソフトレンダリングの場合は停止して報告し、他のレンダリング方法に切り替えない。合成では geq を使用禁止。レンダリングはバックグラウンドエージェント、独立したチャプターで並行して行い、メインセッションは常に会話可能な状態を保つ。
  5. ナレーション収録:任意のTTSでWAV出力 → engine/voice/align.py でアライメント。読み間違えた文はその文のみ再生成し、手動でタイミングを編集しない。
  6. 第0フレームから内容があり、最初の20~30秒が最も重要。 フックは直接:権威ある名前 + 最も直感に反する結果 + 視聴者の疑問(または「一度でわかるX」)。サスペンスは仕掛けない。
  7. 長さは説明のしやすさに従う、約10分以内を許容。文間の間は詰める(第10節参照)。
  8. 映像:可読性第一、暖白/アイボリーの編集スタイル。デフォルトスタイルカード④ 新聞(公開済みのエピソードで使用中)。連続的なカメラワーク、論文ページへのズームイン、ソフトなシンセサイザー音楽を好む。3Blue1Brown風の暗色背景を動画全体のベースには使用せず、Swissグリッドポスター風も使用しない。パワーポイント的な静的なカードのハードカットは行わない。
  9. 出演は任意:メイン画面はコンテンツ。著者の姿を入れる場合は、右下の小窓のみ、冒頭/章区切り/末尾のみに配置し、顔を大きく表示しない。ナレーションをそのまま大きな文字にして表示しない。
  10. 末尾:議論を促す質問(今回の核となるメカニズムに関連し、一言二言で答えられるもの)→ クレジット + チャンネル登録促進文(film.json の outro)。次回予告はしない。
  11. 文面:専門的に洗練され、推論過程があり、絵文字は少なめ。「〜ではなく…」という構文は使わない。実際に試していないことの体験談は書かない。公式の主張、実測値、推論は分けて記述する。ナレーションはセクションごとに著者にレビューしてもらう。一文ごとのセルフチェックリストは references/voiceover-selfcheck.md(このファイル内の古い記述よりも優先)。
  12. 検証済みの手法に基づいて計画を立て、新しいフォーマットを自分で発明しない。 新しいショットはまず examples/ で同様の書き方を探す。

著者が必ず行う工程(エージェントはここで止まり、何をしてほしいかを明確に伝え、確認を待つ):論理チェーンとナレーションのレビュー(第7節)、ナレーションWAVの生成(第9節、著者が利用可能なTTS方式を既に提供している場合を除く)、ショット計画表の確認(第8節)、サンプル動画と完成動画の確認(第11~12節)、公開。著者が確認を終えていない場合、同一の動画は次の工程に進めない(他の動画は続行可能)。

トークン節約:各レビュー版に対して、ファクトチェックは最大1ラウンド、ブラインドテストは最大1ラウンド。小さな問題はまとめて著者の意見と一緒に修正する。ファイルの検索・整理には小規模モデル、原稿作成・ファクト判断・レビューには強力なモデルを使用。大量の内容はファイルに書き、パスと結論のみを返信する。


二、フロー概要

  1. トピックスクリーニング:論文概要 + あなたの公開プラットフォームでの同テーマの人気度。必須条件:論文内に完全なケーススタディがあること。
  2. 精読 → 論文カード(references/paper-card.md)
  3. フックを見つける
  4. 三つの質問からなるアウトライン + 一貫した例 + 視聴者の質問チェーン(references/question-chain.md)
  5. ナレーションを書く(第4節 + references/voiceover-selfcheck.md)
  6. 「一回聴き」ブラインドテスト(2つの役割、サブエージェント、references/listen-test-brief.md)→ 原稿修正
  7. 独立したファクトチェック + 反対意見(サブエージェント、並行、references/factcheck-brief.md)→ 修正後 再度理解度テスト
  8. 著者がナレーションをセクションごとにレビュー(論理チェーン1ページ + セクション分割されたナレーション、確認を待つ)
  9. 絵コンテ:スタイルカード選択 + ショット計画表(references/shot-plan.md)+ 上部ナビゲーションプログレスバー →(著者がショット計画表を確認)
  10. ナレーション収録(任意のTTS)
  11. アライメント、オーディオトラック(ボーカル + 音楽 + 効果音)
  12. 共通部品 → チャプターごとに並行して scene.js を作成 → サンプル動画 → 独立レビュー → 全編 → チャプターごとのアート仕上げ → 再レビュー → .1 リビジョン
  13. フレーム抜けチェック → 納品。著者が見てから出した質問は、まず振り返ってから修正を開始する。

複数ソース「一度でわかるX」も本スキルを使用

サーベイ/複数論文の連続解説も同様に0~12のステップを踏む。本スキルをロードしない場合の結果:文に「組織 + 年 + 数字」が詰め込まれて一気に読まれる、章ごとにバラバラな内容、実際の論文ページがない、アニメーションや音楽がない、理解度テストがない、動画全体を手戻り。適用:

  • 1つの一貫した例 + 1つのマザー図 で動画全体を串刺しにする。各章で同じ用語を使ってマザー図を再訪する。マザー図は論文内の既存の分類を優先して使用し、本文はその分類に従って章立てし、独自の枠組みを作らない。
  • 各章は1つのメインストーリー、1つの主要な数字のみを語る。その他の数字は画面のソースカードに表示し、ナレーションでは「X は発見した」と言うだけにする。
  • 章は段階的に進む(易から難へ/パイプライン順)。最後の章で冒頭のフックに戻る。
  • 組織名や年号はナレーションの長い文に含めない。一文につき一つの情報。
  • サーベイの権威は「論文 + 大手企業のオープンソースコード」に由来する。フックは主語を一つだけにする。

0. トピックスクリーニング

  • 候補が多い場合は、まず論文のAI概要(例:alphaXiv)を確認する。これは精読するかどうかを決めるためだけに使い、事実のソースとしては使用しない。
  • あなたが公開するプラットフォームで同テーマの人気を調査する:誰かが徹底的に解説しているか、解説しているものの評判はどうか。学術的な人気(いいね、引用、論文数)はプラットフォームでの人気と必ずしも一致しない。プラットフォームで流行るのは通常、「コンセプトをわかりやすく解説」「これ一本で十分」、そして人名/企業名。証拠がないのに「最近話題」とは言わない。
  • 必須条件:論文内に完全なケーススタディがあること(入力 → 各層で何をしたか → 前後のスコア)。これで「一緒にトレースする」という体裁を支えられる。ない場合は選択を慎重に。
  • トピックを選ぶ際は4つのことを決める:読者の質問、私たちの主張、証拠、納品物(視聴後に何を持ち帰れるか)。

1. 精読:論文カード

  • 全文を入手:https://arxiv.org/pdf/<id>。可能なら同時にTeXソースも入手(/src/<id>、数字や図のキャプションがより正確、元の図を直接使用可能)。PDFダウンロードに失敗した場合は、まず arxiv.org/html/<id> を読む。使用権限のある素材のみダウンロードし、ライセンス(CC BYなど)を記録する。
  • PDF:pdftoppm -r 150 ですべてのページをレンダリングして内容を確認。映像で使用するページや部分は300dpi、ズームインする図は720dpiのベクターレンダリングを使用(2~3倍にズームインするため、150dpiや動画のフレームキャプチャではぼやける)。ワードボックス(蛍光ペンの位置特定用)は pdftotext -bbox を使用。これは一部のpopplerバージョンでクラッシュするため、PyMuPDFに切り替える(examples/demo/get-paper.sh 参照。NFKC正規化を忘れずに。そうしないと fi のような合字が文とマッチしない)。ウェブページの原文は engine/tools/capture.mjs を使用(3倍キャプチャ + フレーズワードボックス)。
  • 本文、付録、図のキャプションをすべて読む。付録、アブレーション、失敗例、限界は必ず個別に確認する。 コアメカニズムの「何を基準に判断するか」は、しばしばここにのみ書かれている。
  • 論文カードは references/paper-card.md の12項目に従って記述する。単一論文の分析では、まず論文自身のコアとなる図と構造を把握し、自分の枠組みを押し付けない。

2~3. フック、三つの質問、一貫した例、視聴者の質問チェーン

フック(一文3秒以内、一文につき一つの情報のみ):

  1. 権威ある名前は短くして一番最初に(「Googleの新論文:」)。
  2. その次に、この論文の最もユニークで最も直感に反する点を、一般の人がわかる言葉で説明する(「プロデューサーがスケジュール、人員、予算の複数の表を突き合わせるのを助け、スコアが43から78に向上」)。単一のケーススタディの場合は「実際の…」といった限定を付けて、平均的な結果のように語らない。
  3. 短い逆転で締めくくることができる(「モデルの重みは一行も変えていません。」)。
  4. 最後に完全な名前と所属機関を述べ、一言予告を加える(「次に、その完全なアーキテクチャを一緒に分解していきます」)。
  • 同じ数字が複数含まれる量を一文にまとめない(「8B」「70分の1」「12万8千」は聞き間違えられる)。
  • フックで、視聴者に専門用語を先に理解させなければ内容がわからないようにしてはいけない。まず平易な言葉でイベントを説明し、英語の原文は画面に表示するだけにする。視聴者が知らない用語は出現しても構わないが、次の段落で即座に定義する。
  • フック内の比較対象は検証し、限定条件を書き込む。フックとタイトル内のキーワードはすべて、本文で正面から説明する段落を設ける(「自己進化」と言ったなら、「これは自己進化と言えるか?どこに現れているか?」という段落が必要)。
  • 第0フレームは全画面のメインタイトルまたは最も直感に反する画像であること(132px 宋体、既に画面内にあり、空白から押し出されない)。重要な数字は、ナレーションが読み上げる時に初めて出現し、そのセクションの主役となる(200px以上)。冒頭で一瞬表示するだけにしない。

三つの質問の構成:何を改良したのか(階層)|なぜ機能するのか(著者の考え + メカニズム + なぜ失敗しないのか、半分以上を占める)|私たちは何を学べるか。

一貫した例:論文自体の例を一つ選び、すべての層をカバーし、すべてのメカニズムがその例に立ち返るようにする。

視聴者の質問チェーン(原稿を書く前に必ず行う):セクションごとに「視聴者はここで何を質問するか → 次の文でどう答えるか」を書く。テンプレートと必須カバー項目は references/question-chain.md 参照。質問チェーンは論理チェーンと一緒に著者にレビューしてもらう。必ず「冷水」セクションを設ける。

4. ナレーション

構成:フック → 問題提起(先行研究が特定の具体的な成果を挙げる)→ もしあなたが著者なら → 一言で表す本質 → アーキテクチャ(論文のグループ分けに従って説明)→ 論文の例を使って一通りトレース(ステップごと、各ステップに「なぜ」を添えて)→ サマリーカード(全ステップを一文でつなぐ) → タイトルコンセプトのQ&A → 結果(質問→回答)→ 冷水(番号付き)→ 私たちは何を学べるか → 末尾(議論を促す質問→クレジット+チャンネル登録促進文)。

説明を明確にするための厳格なルール

  • 名前を挙げるだけでは説明にならない。 各用語/メカニズムが最初に出現する際に、一文で操作定義を与える:誰が、何を見て、どう判断するか。論文の用語を翻訳するだけでは説明にならない。
  • ステップを飛ばさない。 アクション間には因果関係のつながりが必要(「この2つの問題を見て → Harnessのファイルを修正した」)。
  • 具体的なものから抽象的なものへ。 最初にどのファイルを修正したか、何を書いたかを述べ、それがどのカテゴリに属するか、何と呼ばれるかを後で述べる。
  • 新しい概念は、使用する前に導入する。 「候補」「ブラインド選択」といった言葉が、初出が冷水セクションにならないようにする。
  • 証拠はステップを説明した後に置く、ステップの途中に数字を挿入しない。対照実験を説明する場合は、まず対照群がどのように行われたかを述べ、次に結果を述べる。
  • 役割を明確にする:複数のモデルがある場合は、「ここには2つのモデルがあります:仕事をするのはX、Harnessを修正するのはYです」と明確に述べる。重みが変わるかどうか、強化学習があるかどうかを説明する。
  • ベンチマーク名は初出時に何かを説明する。単位は動画全体で統一する(「点」と「パーセンテージポイント」を混同しない)。「それ」が曖昧にならないようにする。
  • 画面上では、ナレーションで使用した呼称のみを使用する。

スタイル

  • 視聴者に馴染みのある英語の技術用語(Harness、agent、diff)はそのまま使用し、動画全体で同じ呼称を使い、別の日本語訳を付けない。業界の原語(RL環境、軌跡、verifier)を使用し、独自の比喩を作らない。
  • シナリオは一般の人がわかる言葉で説明する。タスクやベンチマーク名は、まず平易な一文に翻訳する。
  • もしあなたが著者なら:「あなたならどう考えますか?」と問いかけた後、1秒の間を置き(画面に「?」を表示)、「私は…だと思います」と言う。推測には必ず「私は…だと思います」と述べる。
  • 一言で表す本質:復唱可能であり、その後に補足の一文を続ける。スローガンのような短い文は書かない(セルフチェックリスト参照)。
  • 長いリストは論文自身のグループ分けに従って説明し、グループ分けは論文の元の表を基準とする。論文を直接説明し、無理に視聴者のツールに関連付けない。
  • 一通りトレース:「第一歩…第二歩…」と分けて、各ステップで誰が何を持って何をしたかを明確に述べ、「なぜ」を補足する。選んだケーススタディについては、「これは論文が特に選んで示したもので、平均的にはそれほど大きくない」と説明する。
  • 各メカニズムは「以前はどうしていたか → 何に問題があったか → 何に変更したか → なぜ良くなったか」で説明する。
  • 技術メカニズムには、最小限のbefore/afterコード比較を添える。原文があればそれを使用し(「原文抜粋・一部省略」と明記)、なければ「イメージ」と明記した疑似コードを書く。
  • アナロジーは補助的なものに留め、例の後に置く。試したが採用しなかった方式についても説明する。情報を削除する前に、削除したら視聴者が誤解しないか自問する。
  • 結果セクション:各数字は一つの質問に回答する。成績表を読み上げない。複数の数字を一文に詰め込まない。同じ「最大/最高」が異なる比較に由来する場合は、その範囲を明示する。
  • 冷水セクション:「3つの留保意見があります。第一に…」と番号を揃える。素材は反対意見サブエージェントから。有利な数字を引用する際は、逆方向の数字も同時に述べる。
  • 末尾は説教じみない:「そこから何を学べるでしょうか?」「私自身の最大の収穫は…」。「あなたが持ち帰れるもの」のような命令文は使わない。
  • 口語、短い文。字幕はアラビア数字を使用。
  • レビュー提出前に references/voiceover-selfcheck.md を一文ずつ確認する。

文字数とリズム:全体で約5.8字/秒(漢字、英単語、数字はそれぞれ1字とカウント)。6~8分 ≈ 2000~2700字。速度を上げるのではなく、間を詰めることで対応する。同じセクション内では文を続けて一気に読み、質問、逆転、重要な数字の前でのみ一拍置く。原稿内では「‖」で一拍置く箇所をマークする(各章3~5箇所)。目標とする間の割合は10~12%、平均5~6秒に一度の間。

ナレーションファイル形式(エンジンが直接読み込む):セクションタイトル ## 00 · セクション名。読み上げる文は一行ずつ、- で始める。> 画面カード および説明文は読み上げない。文ID = s<セクション>-<番号>。

5~6. ブラインドテスト + ファクトチェック + 反対意見(独立したサブエージェント、同時実行)

  • 一回聴きブラインドテスト:2つの役割(A:知識がない人、B:知識がある人)。固定された質問、誤解リスト、採点。閾値:Aのスコアが8点以上で初めてナレーション収録に進む。 ブリーフテンプレート references/listen-test-brief.md。ブラインドテストで指摘された問題は、一つずつ処理し、一句補足するだけでは済ませない。
  • ファクトチェック:ナレーションと論文を照らし合わせ、数字、帰属の強さ、限定条件、比較対象、「推測」が明示されているか、グループ分けが論文の元の表と一致しているかを項目ごとに確認する。出力はmust-fix(直接置き換え可能な文)。
  • 反対意見:論文のみを渡し、レビュアーの立場に立つ:最も脆弱な仮定、比較は公平か、ベースラインに負けているセル、サンプルサイズ、反例、1週間での再現性。冷水セクションの素材を生成する。ファクトチェックと反対意見のブリーフテンプレート references/factcheck-brief.md。
  • 原稿を修正するたびに(特にファクトチェック後に数字や限定条件を追加した場合)、ブラインドテスト + 修正された文のファクトチェックを再度実行する。 正確さとわかりやすさは両方ともクリアする必要がある。閾値は公開済みの原稿に合わせて調整する。

7. 著者によるナレーションレビュー(一旦停止して確認を待つ)

  • まず、論理チェーンを1ページで提示する。各セクション一行で「視聴者の質問 → このセクションでの回答」。
  • 一塊のテキストを貼り付けない。セクションごとに分割し、小見出し + 一句説明 + ナレーションを一行ずつ。重要な結論は太字にする。
  • セクションごとにレビュー。一度に1~3セクション。「現在 → 問題点 → 修正後」と書き、イエス/ノーで直接答えられる質問をし、背景を含めて平易な言葉で伝える。合理的なデフォルトがあればそれに従い、何をしたかを一句述べる。
  • 著者の好みを記録し、終了後にこのスキルを更新する。確認後にのみナレーション収録と制作を進める。

8. 絵コンテ:スタイルカード、ショット計画表、プログレスバー

スタイルカード

映像 = 骨格(構造、カメラワーク、論文へのズームイン、大きなキャンバス、トランジションのタイミング、動画全体で固定)+ スタイルカード(カラーパレット、フォント、マテリアル、シグネチャーアクション、固定要素のスタイル)。スタイルを変更する場合はカードのみを交換する。1つの動画では1枚のカードのみを使用し、シリーズ内では同じカードを維持する。ビートはナレーションに従い、各ショットの構図はカードに従って再設計する。

カード④ 新聞データビジュアライゼーション(デフォルト、engine/common/style.js に実装済み)

  • カラーパレット:紙 #FFF1E5|インク #33302E|セカンダリ #66605C|細線 #CCC1B7|ワインレッド #990F3D = 改良後/重要な数字/私たちの注釈|オックスフォードブルー #0F5499 = ベースライン/原版|ティール #0D7680 = 対応、接続、✓|グレー #B9AFA6 = 拒否/ニュートラル|麦色パネル #F2DFCE。
  • フォント:日本語タイトル Noto Serif SC Black(フック132px、チャプター/ショットメインタイトル92px、カード56~64px、行間1.1)。本文、ラベル Noto Sans SC。数字 Inter 800 + tnum。セクションラベル(kicker)Bold 28~30px、上に56×5のワインレッドの短線。フォントは style-cards/editorial/get-fonts.sh でダウンロード(OFL)。
  • レイアウト:kicker + 大見出し + リード文 + 図。左マージン120px、厳格なグリッド。1pxの細線と4pxの太線で階層化。グラフは横方向のグリッド線のみ描画し、ラベルは直接線と点に配置し、凡例は使用しない。注釈 = 細い引き出し線 + 短い説明文。各画面の左下にグレーのソース行(26px以上、chrome.js で統一描画)。
  • シグネチャーアクション:タイトルを行ごとにマスクで上に押し出す(easeOutQuart 0.55秒、ED.maskLine)。リード文を左からワイプイン(wipeText)。細線を左から伸ばす(growLine)。外枠を時計回りにストローク(strokeCW)。折れ線グラフを左から右に描画し、数字を同期スクロール。重要なフレーズにワインレッドの下線をスイープ(underlineSweep)。グラフのショットは3~4%ゆっくりズームイン。バウンドさせない、光らせない。
  • トランジション:チャプター間は全ページ横スライドの新聞めくり(0.6秒、chrome.js で統一描画)。チャプター内は連続変形/大きなキャンバス。
  • 固定要素:上部の新聞セクションナビゲーションプログレスバー、麦色の字幕バー(宋体 Bold 44px)、ソース行。すべて engine/common/chrome.js で描画し、各チャプターで個別に作成しない。
  • 欠点:ややクールな印象、文字が多く階層が多い。スマートフォンでは28pxの注釈でもやや小さいため、可能な限り削減する。

その他のカード(リポジトリに実装未添付、必要に応じて自分で style.js を書く):② ホワイトボード手描き風(Excalidraw風、アーキテクチャの分解に適する)。① 数学アニメーション(3Blue1Brown風、数式の導出に適する。厳格なルール8により動画全体の暗色背景は推奨しないが、どうしても使用する場合は、暗色背景上のPDF白ページの輝度を下げ、周辺を暗くする)。⑤ ダークディベロッパー(エンジニアリング実践に適する)。③ ニュー・ブルータリズム(短いフックに適するが、長い動画では疲れる)。A 暖色解説(背景 #FAFAF7、アクセントオレンジ #D4552A = 改良、スレートブルー #3E6A8A 破線 = ベースライン)。カードを変更する際は、アニメーションの方法は変えず、イージングの特性(④ はバウンドしない)とチャプタートランジションの外観のみを変更する。色の意味は固定:改良後 = カードのアクセントカラー、ベースライン = 寒色、拒否 = グレー。

高密度段落のルール(全カード共通)

  1. 一画面につき主役は一つ。説明しているものが約65%の幅を占め、1.3~1.5倍にズームイン。主役が変わるときは、前の主役を上部の要約細線に収める。関係性を指摘する文の時のみ、全体を1~2秒間引いて見せる。
  2. 文字数制限:字幕以外で一画面あたり約25文字以内、4つのビジュアルブロック以内。ナレーションで言ったことはラベルとして再度書かない。要素につきラベルは最大1つ。
  3. 日中二言語のラベルは使用しない。読む必要のある文字はすべて28px以上。ソース行は26pxでも可。
  4. 見えない論文の小さな切り抜きは配置しない。引用する場合は、フルサイズで1.5秒以上見えるようにズームインし、使用後はソース行または小さなコールアウトのみを残す。
  5. プレースホルダーは控えめに。次のセクションには細線1本と小さなセクションヘッダーのみを残し、大きなグレーの骨組みを敷き詰めない。
  6. 上部にはナビゲーションのみを残す:本章のステップをプログレスバーのサブ目盛りとして表示し、別途行を占有しない。

全カード共通の絵コンテルール

  • コアビート:原文ページ → 黄色の蛍光ペン rgba(250,199,117,0.7) をナレーションに合わせて左から右へ塗る(マーカーペンの音と共に)→ 原文がはっきりと3秒以上静止する(出入りとズームイン/アウトの時間を除く)。グラフを再描画する前に、元のグラフを表示し、説明する点を丸で囲む。
  • 蛍光ペンは2種類:原文のハイライト = 黄色(全カード共通)。私たちの注釈(引き出し線、丸、下線)= カードのアクセントカラー(④ はワインレッド)。視聴者は一目でどれが原文でどれが解説かを区別できる。
  • 固定ショット:一通りトレースショット|コード比較ショット|階層表ショット|著者の思考ショット(「推測」と明記)|対照実験ショット(実験群 vs 対照群の方法)|サマリーカード。
  • 字幕の背景パネルの不透明度は0.97以上、一行22文字以内、ナレーションと一字一句一致させる。
  • フォントサイズ:読ませる文字は28px以上。情報を伝える文字はインク色、グレーの文字はメタデータのみに使用。
  • 空の画面を残さない:内容で約70%を埋める。どの瞬間でも(変形やカメラチェンジの中間フレームを含む)、画面の半分が空の状態が2秒以上続かない。着地フレームにはすぐに主役がいること。
  • 画面の意味が誤解を招かないようにする:縦の矢印の連鎖はデータフローと読まれる可能性がある。次のロールに流れないものは横に配置し、破線の枠で囲みラベルを付ける。
  • 図は「イメージ」と明記。グラフは比率を守り、軸にラベルを付ける。論文のロゴは隠し、組織名はテキストのみ使用する。
  • ランダムノイズ(Math.random によるグレーのグリッド、バーコード、骨組みのような線)での埋め合わせは禁止。図は3~4段階のスムーズな色階調を使用する。
  • タイトルは新旧を重ねて表示しない(古いものが消えてから新しいものを表示する)。新しい画面が現れる前に、古い画面は完全に退場し、残像を残さない。
  • 文字を含むレイヤーは scale()>1 でビットマップを拡大せず、レイアウトサイズを変更して再描画する。
  • 3DはすべてThree.jsで照明を当てる(角丸ボックス、マットなマテリアル、半球光 + メインライト + フィルライト、ベイク処理されたコンタクトシャドウ、2倍レンダリング後に縮小)。CSS 3Dは禁止。

セーフエリア(絵コンテの段階でこのレイアウトに従う)

  • y 0~64:プログレスバーのみ。動画内要素の上端は y80 以上。通常のコンテンツは y 136~930、左右96px以内 に配置。
  • y 900~940:ソース行。y 952~1040:字幕バー。グラフの数字やラベルはこれらの領域に入れない。
  • オプションのアバター:右下、約 x>1660、y>840。読ませる内容は x<1640、y<940 に配置。
  • 後からプログレスバーやアバターを完成動画に重ねない(本文を縮小する場合のみ、字幕もそれに合わせて小さくなる)。

カメラワークとトランジション(3つの手法を内容に応じて使い分ける)

「フェードアウトして白紙のページからゼロから構築」、および全画面クロスディゾルブ(パワーポイントのよう)は禁止。

内容手法方法
解説の大部分:コンセプト、背景、一言で表す本質、結果、冷水連続変形(3Blue1Brown式)次のショットの要素が前のショットから生えてくる:ラベルが中央に飛んでメインの図形になる、タイトル語が縮小して数式に組み込まれる、子要素がナレーションで言及された時に親要素からポップアウトする、? が電球に変わる、質問カードが冷水カードにめくれる。すべての入場要素には来歴が必要
論文の原文・原図の引用論文へのズームイン(実体ペーパー)論文は影があり、約1.5~2°傾いた本物の紙(PDFの実際のページ、グレーのバーで代用しない)。普段は隅に縮小されている。引用する際にスライドインし、ページをめくり(0.8秒、紙の裏面を描画)、その文や図の部分に2~3倍ズームインし、蛍光ペンでなぞる。図を説明する際は、図のその部分を「浮かせて」飛び出させ、再描画したアニメーションカードにする。浮かせたキャプチャは隣に置き、対象のカードを覆わない。使用後は隅のミニマップに収める。ズームインはキャプチャの解像度を超えない
順序のあるステップの段落(一通りトレース、フロー)大きなキャンバスカメラワーク(Kurzgesagt式)複数のステップを同じ大きなキャンバス上に左から右に並べる。カメラはステップ間をパンする(0.5~0.9秒 easeInOutCubic + ウーッという音)。隅に論文のミニマップを配置。次のステーションの骨組みは事前に配置され、パン中に目的地が見える。キャンバス外で半分に切られた隣のカードは暗くなる。1エピソードで1~2段落のみ使用。終わったら全体を引いて見せ、サマリーチェーンに収める
  • 動画全体の骨格:連続変形をベースに → 論文に言及するたびにズームイン → ステップを説明する時は大きなキャンバス → 大きな段落の間は、0.6秒以下のチャプタートランジション(5~6回のみ)。
  • モーションの文法:入場はイーズアウト(④ バウンドしない)、子要素は60~120msずらす。カメラは easeInOutCubic。同じオブジェクトはショットを超えて同じ要素として維持する(位置/スケールを補間)、新しくコピーしてフェードインしない。カードの拡大縮小時は内容もそれに伴い縮小し、先にクリアしてから縮小しない。
  • モーションブラー:12~16の等重サンプリング、テールはフレーム変位の半分以内かつ40px以内。ズームイン/アウト時は方向ブラーを追加しない。カメラパン時の全画面ブラーは0.35秒以下。
  • 先にショット計画表を書く(references/shot-plan.md)。各段落に、どの手法を使うか、前のショットから何が残るか、次のショットはどの要素から生えるか、原文の出典、アンカーワードを記述する。著者が確認してから映像制作を開始する。

上部ナビゲーションプログレスバー

  • ナレーション段落に従って6~8のセクションに分割。画面上では2文字の新聞セクション名を使用する(導入/背景/構想/分析/結果/疑問/示唆…)。「フック」「冷水」は内部呼称であり、画面には表示しない。
  • 設定はプロジェクトディレクトリの film.json の nav:[{ "n": "01", "name": "導入", "sections": ["00"] }, ...]。開始・終了時間は timeline.json から取得。現在のセクションはワインレッドの宋体、再生済み部分はワインレッドの線、各セクションの最後2秒で次のセクションを脈動で予告。実装:engine/common/chrome.js。

アバター(オプション)

デフォルトでは配置しない。配置する場合は、自分が使用権限を持つ自身のイメージを使用し、透明背景のアバタートラックを用意し、合成の最終レイヤーとして右下のセーフエリアに配置する。動画全体に常駐、または冒頭/章区切り/末尾のみに出現させる。論文にズームインする際(1.4倍以上、または原文が右下に落ちる場合)は、アバター全体を画面外にスライドさせ、ズームアウト後にスライドバックさせる。各0.35秒。半透明は不可。 絵コンテの段階でセーフエリアに従ってレイアウトする。

9. ナレーション収録(任意のTTS)

  • wav/mp3 を出力できる任意のTTS(商用ウェブサービス、API、ローカルモデルいずれも可)を使用し、セクションごとに生成する(各バッチ約450文字以内。長すぎると文字が飛びやすい)。数字やバージョン番号は日本語の読み方に変換する(43.1、Opus 4.8)。英語の技術用語はそのまま保持する。字幕はアラビア数字を使用する(chapter.json の numfix)。
  • 各バッチで、まず音声認識を行い、頭尾の単語と英語の固有名詞を確認する(engine/voice/align.py asr)。読み間違えた文はその文のみ再生成し、voice.json の overrides に書き込む。
  • 検証済みの一例:ある商用TTSウェブサービスで、技術解説スタイルの音声を選択し、1倍速。各セクションで「原稿を貼り付け → 自動で感情タグを追加 → 生成 → 1番目をダウンロード」。ブラウザ自動化を使用する場合は、新しいタブを開いて実行し、ユーザーが見ているタブには触れない。音声とアカウントは各自で用意し、リポジトリと一緒に配布しない。
  • 納品前に、セクションごとに文字起こしを行い、元の音声の頭尾の単語と一致するか確認する。フェードアウトは2フレーム以下。

10. アライメントとオーディオトラック

  • uv run --with numpy python engine/voice/align.py voice.json:認識結果をナレーションに文字単位でアライメント → 文の境界を無音に吸着 → 各文の先頭と末尾の無音を除去、文内の長いポーズを0.30秒以下に圧縮、atempo 1.05、8ms フェードイン/アウト → 結合して voice/voice.wav、timeline.json、clauses.json を出力。
  • ポーズパラメータ(最新の公開済みエピソード):動画開始0.3秒、文間0.35秒、セクション間0.7秒、動画終了2.5秒。疑問文、「‖」の箇所、重要な数字の前では0.8~1.0秒に増やすことができる。
  • timeline.json は動画全体の唯一の時間ソース:プログレスバー、字幕、アンカーワード、効果音のキューはすべてこれから取得する。文を追加する場合は、新しいフラグメントを追加してアライメントを再実行するだけでよい。ナレーションがない場合は、engine/tools/mk_dummy_timeline.py で仮のタイムラインを生成し、先に映像制作を行う。
  • 背景音楽(engine/audio/audiolib.py music):numpy で合成し、著作権のある素材は使用しない。暖かいパッド + ソフトなアルペジオ + ベース、Fメジャー Fmaj7–Dm7–Bbmaj7–C7、84 BPM。約 –28 LUFS。ボーカル出現時は約 7 dB ダッキング(アタック 60ms / リリース 450ms)。動画開始と終了でフェードイン/アウト。
  • 効果音(sfx、ボーカルより約 19 dB 低く設定。24 dB ではスマートフォンで聞こえない場合がある):カメラ移動/チャプタートランジション = whoosh。蛍光ペン = marker。カード/ラベル/✓✗ = pop(要素が実際に入場するフレームに合わせる)。数字スクロール = tick。紙が浮く/ページめくり = paper。画面の動きがない瞬間には whoosh を配置しない。タイミングは scene 内の data.cue() で登録し、render(t) と同じ時間ソースを使用する。
  • ミキシング(mix):2パスの loudnorm I=-16:TP=-1.8:LRA=11 → AAC 192k。エンコード後、実測のトゥルーピークが –1.5 dBTP 以下であることを確認する。
  • 納品前に、ヘッドホンとスマートフォンのスピーカーでそれぞれ一度聴く(測定値だけで調整しない。エージェントは聴けないため、著者に聴いてもらい、ナレーションが最も密集している時間帯を指摘してもらう)。

11. 制作とレンダリング

共通部品を先に作成してから作業を割り振る(インターフェースドキュメント engine/README.md)

  • timeline.json / clauses.json:動画全体の時間。チャプター時間 = そのチャプターのセクションの開始から終了まで。チャプター内ではローカル秒を使用。
  • film.json:チャプターの順序、プログレスバーのセクション、末尾のクレジット。
  • engine/common/chrome.js:プログレスバー、字幕、ソース行、章頭の新聞めくり。各チャプターは renderContent のみを描画し、固定要素は自分で作成しない。これにより、結合時にUIが一貫する。
  • チャプター用ブリーフ:スタイルカード全文 + 高密度ルール + インターフェース + 事実に関するルール + 予算。最初から「版面を約70%埋める、どのフレームも(変形やカメラチェンジの中間フレームを含む)空の画面に近づけない、ショットメインタイトル92px、グレーのバーで埋めない」と書き込む。
  • マザー図:動画全体で共有するマザー図のコードは、仕様ファイルとして記述する(例:examples/always-on/MOTHER.md)。各チャプターはそれをそのままコピーする。

チャプターごとに並行処理:各チャプターに1つの制作エージェント。マスターは共通部品、統一レンダリング、結合のみを行う。

  • scene.js の renderContent(ctx, t, data) は t の純粋関数でなければならない:CSSアニメーションなし、タイマーなし、乱数はシード付きPRNGを使用。カットポイントはアンカーワードからのみ計算する(data.A(文ID, 部分文字列))。手動で秒数を書き込まない。
  • チャプターの接続:各チャプターの t=0 は既に完全なレイアウトであること。最後の0.5秒は静止して動かない。engine/tools/prep_render.mjs で前のチャプターの nochrome 最終フレームをエクスポートし、次のチャプターのページめくり用のベース画像(prev.png)として使用する。最初のチャプターは renderPrev を実装して、自分で「前のページ」を描画してもよい。
  • 長いチャプター(90秒超)は2つのエージェントに分割し、一度のカメラパンで引き継ぐ。引き継ぎフレーム上の要素の座標、キャンバス座標、終了速度をブリーフにハードコードする。
  • 共通部品を変更した場合は、すべてのチャプターエージェントに通知し、既にレンダリングしたチャプターは影響を受けるフレームを再レンダリングする。判断に迷う場合は、チャプター全体を再レンダリングする。
  • 制作エージェントのセルフチェックは静止フレームのみをキャプチャする(ヘッドレスでシェルページを開き seek(t) でスクリーンショット、各ラウンド10フレーム以内)。完成動画は WebCodecs のみを使用する。

レンダリング(唯一のパス)

  1. node engine/tools/serve.mjs 8771(127.0.0.1 のみをリッスン)。
  2. ローカルChromeで新しいタブを開く:http://127.0.0.1:8771/engine/common/shell-wc.html?ch=<チャプターディレクトリ>。
  3. コンソールで await probe():webglRenderer(実際のGPUであること。例:Apple Mシリーズ/Metal、NVIDIA、AMD)と prefer-hardware がサポートされているかを確認。software: true の場合は停止して報告。
  4. startRender({ to: 10, download: false }) で10秒間テストし、__prog.msPerFrame を確認(GPU上で通常5~15 ms/フレーム)。
  5. startRender({ name: 'chNN.mp4' }) → __prog.state === 'done' をポーリング → ブラウザがダウンロード。各タブで一度だけダウンロードさせる(2回目はChromeがサイレントにブロックする)。新しい出力には新しいタブを開き、レンダリング後に閉じる。
  6. ダウンロード後、cp(mv ではない)で <チャプター>/build/video.mp4 にコピー。ffprobe -count_frames でフレーム数 = ceil(T×30) を確認。
  7. node engine/common/assemble.mjs --project <プロジェクトディレクトリ>:フレーム単位で concat、音楽と効果音、ミキシング、エンコード。別途 30MB 未満の軽量版も出力。ミキシングに -shortest は使用しない。音声と映像のズレは1フレーム未満。

順序:サンプル動画 → 独立レビュー → 全編 → アート仕上げ → 再レビュー → .1 リビジョン

  1. 最初に2つの完全に合成されたサンプル動画を出力する:A = フック + 初めての論文ズームイン(約30秒)。B = 大きなキャンバスの最初の1~2ステーション(約40秒)。著者に効果と音量を確認してもらい、同時にレビューエージェントに渡す。
  2. レビューエージェントは制作から独立している(完成動画 + 本スキル + 論文カードのみを見る)。references/review-checklist.md に従って項目ごとにチェックし、must-fix / should / nice をタイムコードと具体的な修正方法と共に出力する。
  3. must-fix は全編で一貫して修正し、サンプル動画の範囲のみに留めない。
  4. チャプターごとのアート仕上げ:内容とタイムラインが確定した後、各チャプターをアートのみを担当するエージェントに渡す(ナレーション、ショットの順序、数字は変更しない)。各ショットから3フレームをキャプチャ(入場中/静止/退場前)、ポスターとして単独で切り出せて初めて合格とする。フォントの4階層、主役の十分な大きさ(重要な数字は200px以上)、シグネチャーアクションの使用、色の意味の混同の有無、グリッドへのアライメント、「デフォルトのグレーの枠 + 小さな文字」のパワーポイントカードがないことを確認する。内容の問題を見つけた場合はレビューに記録し、制作エージェントに戻す。
  5. 全編をもう一度レビューし、修正後に .1 版を出力する。一度もレビューを受けずに「最終版」をリリースしない。

12. セルフチェックと納品

  • references/review-checklist.m

関連スキル