説明動画(Explainer video)
リポジトリのルートから uv run で作業します。README.md にコマンドとファイル形式が、EDITORIAL.md に標準ルールが記載されています。以下が作業の順序であり、ユーザーのチェックポイントです。
0. 会話 — 動画の出発点
動画は、オーナーが考えていることから生まれます。話題リストからではありません。リサーチの前に、オーナーにインタビューしてください。
- 一度に1~2つの質問を、簡潔な会話形式で。オーナーは口述で答えるため、5つも同時に質問すると答えきれず、混乱します。ラウンドごとに質問の種類を混ぜてください:自由質問(「それぞれの側は何を守ろうとしているのか?」)、クイズ(「その割合はどれくらいだと思いますか?」)、スティールマンテスト(「相手の主張を、相手が署名するような形で述べてください」)、そして餌(相手が言ったことに対する最も強い反論を率直に)。リストの次の質問ではなく、あなたを驚かせた答えを追ってください。
- オーナーの間違った推測は画面に表示して構いません(承諾済みです)。ただし、数字が推測として提示された場合のみ。例の中の数字(「例えば収入の70%を家賃に使うとすると…」)はあくまで例示です。そのように記録し、決して点数化したり推測として表示したりせず、どちらか不明な場合は確認してください。
- 回答の裏にある主張を聞き取ってください:間違っている可能性のあるテーゼ、繰り返し使われる区別、オーナー自身のストーリー。それが動画になります。「中絶」のようなトピックはアイデアではなく、「両陣営は異なる質問に答えている」というのがアイデアです。
- オーナーの言葉をそのまま保持してください。回答を逐語的に、日付付きで
notes/<topic>.mdに保存します(git で無視されるファイルです)。ノートは生のプライベートデータであり、スクリプトが公開版です。自分の要約は自分のものと明記してください。 - 発言を、スクリプトで必要になる順に整理してください。確認できるものはリサーチに回し、その後
fact、estimate、viewのビートにします。オーナー固有のものはopinionまたはspeculationにします。曖昧な言葉は先に進む前に特定してください(「設計された」:誰によって、どうやってわかるのか?)。オーナーが信じていることをソースが裏付けていない場合は、率直に伝えてください。 - テーゼ、それを支える3~4つの展開、およびそれに対する最も強い反論が出たら一旦止めてください。それを数行で要約し、リサーチに入る前に同意を得てください。
オーナーは「今、どうなっているか」を知りたがっています。物事の由来は動画内の短い余談に留め、動画そのものの主題にはしません。
1. リサーチ — スクリプトの前に
- 動画が答える問いを一文で確定し、視聴者が視聴後に言えるようになるべき3~4のポイントを定めてください。
- ファクトシートを作成します:1行1主張、それぞれにこのセッションで取得・読了したソースと、それを裏付ける引用を添えます。初日から
videos/NAME/sources.tomlにソースを保存し(このファイルのみを含むフォルダはリサーチ中または中断中の動画を示します)、主張はnotes/NAME.mdに保存します。サブエージェントでのリサーチも可能ですが、逐語引用を返すよう指示し、裏付けられなかった部分を明示させてください。開かなかったURLは決して受け入れないでください。 - 争点のあるトピックについては、各陣営の最も強い主張者からそれぞれの立場を収集し、事実に関する不一致と価値観に関する不一致を区別してください。
- ソースが支持していないことも書き留めてください。よく知られたストーリーのバージョンは、証拠よりもすっきりしていることがよくあります。
2. スクリプト(チェックポイント:ユーザーの承認が必要)
python -m explainers.new NAMEを実行します(既存のsources.tomlをもとにテンプレートを生成)。その後script.mdを作成します。- 動画の長さは12~25分:オーナーの朗読ペースで約2,100~4,400語(間を含めて約175語/分)。視聴者が節目を感じられるようなセクションに分割し、各セクションに独自の問いを設けてください。
- 1ビート1アイデア、1ビート1ブレス:15~40語。耳に優しい書き方に:短い文、重要な単語を文末に、聞き手が覚えられるよう数字は丸め、括弧や略語は避けてください。
- 冒頭は挨拶ではなく、問いや驚きで始めてください。各セクションは、視聴者が次のセクションを求めるように閉じてください。
- 文の約束に基づいてラベル付けし、確信度に基づかないでください。種類が混ざっているビートは分割します。スクリプトは主に
factとviewで構成し、明確にラベル付けされたopinionビートを少数含むのが目標です。checkで割合を表示します。 - チャンネルの
opinionを争点のある質問について自分で書かないでください。空白のままにするか、下書きを提示して「これは下書きであり、ユーザーが承認、変更、削除できる」と明記してください。 - 各セクションの下に
>で注釈を入れ、画面に何が表示されるかを示します。すべてのビートには、少なくとも5秒ごとに変わる画像が必要です。 python -m explainers.check videos/NAME --urlsがパスする必要があります。スクリプトとその内訳、ソースリストをユーザーに提示してください。
3. 音声(チェックポイント:ユーザーが収録)
- 合成音声で下書き:
python -m explainers.narrate videos/NAME。say.txtで音声が間違って読んだ単語を修正します。画像を表示するために時間が必要なビートにはpauseを追加します。この下書きで画像を作成し、スクリプトを確定できます。 - 文言が確定したら、ユーザー自身のターミナルで収録します:
python -m explainers.record videos/NAMEで各ビートを表示し、収録し、レベルとスクリプトの単語をチェックします。--roomは無音部屋を1回収録し、間を埋めるために使います。その後再度narrateを実行:新しく収録されたテイクがあればそれを使用します。画像は単語に基づいてキューが検索されるため、その単語の位置に留まりますが、ビートの長さは変わります:レンダリング前にsweepを実行し、コンタクトシートを確認してください。 - ユーザーは一字一句読み直す必要はありません。テイクがスクリプトから逸脱した場合、
recordは差分を表示し、ユーザーがそのまま保持する場合は script.md のビートを発言通りに書き換えます。したがって、収録前にスクリプトをコミットし、収録後にgit diffで差分を確認してください:新しい単語のスペルと句読点を整えます(それでテイクが無効になることはありません)。変更されたfact、estimate、viewのビートについては、ソースの引用と新しい単語を照らし合わせてください。裏付けられなくなった場合はユーザーに伝えてください:ビートは再収録されるか、ラベルを変更されます。放置してはいけません。 - 自分で収録済みビートを言い換えると、ユーザーは新しい読み直しを強いられます。そのような変更はまとめて、まずユーザーに確認を取ってください。
--audition VOICE ...で下書き用の合成音声を比較できます。スクリプトのvoice:行で1つを選択します。
4. 画像
- テンプレートの
video.pyから始め、シーンごとに置き換えます。通常は1セクション1シーン。theme.scenesでシーン間をカットします。 - 動画はセット(
explainers/sets.py)上で進行します:現時点ではプロジェクタースクリーン付きの教室。これはオーナーが依頼したものです。チャート、カード、図をスライド(1920x1080の画像)として描き、セットに渡します:同じスライドが引きのショットではスクリーンに表示され、カメラが寄るとフレームを埋めます(移動にはsets.shotsを使用)。スライドが読まれる必要があるときは寄り、ホストが何かをするときは引き、ホストが意見を述べるときはプロジェクターを暗くします(on)。セクションのタイトルを黒板に書き(chalk)、ラベルにはplateを付けて部屋越しに読めるようにします。スクリプトの>注釈に「Wide」または「Projector」と記載します。他のセットも後で追加されます:スライドは部屋から独立させておいてください。 - すべての動きをキューに紐付けます:
N.at(beat, word)。秒単位の時間は絶対にタイプしないでください。 - ホストは説明中は小さく片側に位置し、自分自身を語るとき(冒頭、意見、締め)は大きく表示されます。話している対象を見て、指を指します。
- チャート、グラフ、数学的なものは Manim の
Insertを使用します。それ以外はすべて Skia です。 - 議論の両側は
theme.SIDE_A/theme.SIDE_Bで表現します。チャートが描画するデータセットは、出典と日付とともに動画のdata/に保存します。 - ループ:セクションを
previewし、シートを確認し、修正し、繰り返します。レンダリング前には必ずsweepを実行します。
5. レンダリングと引き渡し(チェックポイント:ユーザーが視聴)
python -m explainers.render videos/NAME --fresh、続けてpython -m explainers.describe videos/NAMEを実行します。- ファクトチェック済みのものと未チェックのもの、ラベルが判断に委ねられたビート、音声が不自然に聞こえる箇所を報告します。