KKcorps/lesson-film

レッスンフィルム

レッスンフィルムは、一度見た初心者が仕組みを説明できるようになるまで、1つの仕組みを教えます。すべての映像はコードで描画され、ナレーターの声が時計の役割を果たし、音楽は声の隙間を埋めます。このスキルはcode-filmの上に構築されています。code-filmは見た目、ギャラリー、テイスト、欠陥チェックを担当します。このスキルは、教育、言葉、声、ペース、エンディング、そしてYouTube側を担当します。

実例はexamples/parcel42-lesson/にあり、Apache Pinotのアップサートが古い行を隠す仕組みを説明する130秒のレッスンです。スキルの作者であるKartikは、8回のバージョンを経てこれを「完璧」と呼び、その過程のすべてのメモはそれを所有するリファレンスファイルに記録されています。方法論についてはREADMEを読んでください。見た目については読まないでください。

核となる考え方：視聴者を追跡する

レッスンフィルムは会話の半分であり、視聴者は静かに残りの半分を提供します。どの瞬間においても、視聴者は次の3つのものを持っています：

• 知っていること。 フィルムがこれまでに示し、語ったことだけ、そして日常的な知識。ソースコードは含みません。また、あなたがそれを作るために読んだものも含みません。
• 疑問に思っていること。 すべての映像とすべての主張が次の質問を引き起こします：「では、古いものはどうなるの？」「遅れて到着したら？」「それってスペースを無駄にしない？」
• 信じていること。 フィルムからのみ構築された仕組みのモデル。間違った一言が間違ったモデルを植え付けます。「Pinotは決して古い家を取り壊さない」と教えると、何も削除されないことが示され、その後フィルムがコンパクションでそれを削除する様子を示します。

フィルムを作ることは、そのモデルを秒単位で、声と映像の両方にわたって実行することです：

1. 視聴者が疑問を持っている場所で質問に答える。 遅れた手紙はルールの直後に来て、「そして暗い家は？」はクエリの直後に来ます。
2. あなたが発表する前に、視聴者が答えにたどり着くのを許す。 映像は、声がそれを名付ける一拍前に証拠を示します。タイトル、ラベル、チャプター名は、質問がされる前に答えを与えてはいけません。
3. 糸を決して切らない。 何かを約束するセリフは、次の映像を所有します。「2つのスイッチが切り替わる」の後、画面に次に現れるのはスイッチです。
4. 使う前にそれぞれの言葉を視聴者に手渡す。 画面上のすべての用語は、映像がそれを示す場所で一度だけ声に出して言われ、どの用語も最初の行には現れません。世界の中の物事が最初に来て、その後に用語が名付けられます。その命名行の外では、文は一つの世界に留まります。花は成長を止めたのであって、「閉じた」わけではありません。あるフィルム全体が、"segment"という言葉を一度も言わずに、街路標識に"segment 7"と表示しました。
5. コードではなく仕組みを教える。 視聴者が検索するであろう真の名前（validDocIds）は表示しますが、機械にラベルを付けるだけの関数名は決して表示しません。

リファレンス内のすべてのルールは、これらの5つのうちの1つを適用したものです。ルールが別のルールと矛盾するように見える場合、または何もケースをカバーしていない場合は、視聴者モデルを実行すると決定します。

注釈は決して一つのインスタンスに関するものではありません。 あなたがフィルムを作っている相手が一つの瞬間を指摘したとき、彼らはモデルが壊れた一つの場所を指摘しています。同じように壊れた他のすべての場所を見つけ、すべてを修正し、その数を報告してください。Kartikの「苦しいビート」は、フィルとクリックやカチカチ音でした。彼の欠落した文字は、固定フレームからタイミングが取られたイベントであり、それがshiftcheck.pyが存在する理由です。彼の「間違ったフレーズ」はすべての絶対的な単語であり、それがscriptcheck.pyがそれらをリストする理由です。

セットアップ

このスキルを使用するには、同じスキルフォルダにcode-filmが隣接してインストールされている必要があります。ビルド、ゲート、キャプチャ、シーム、サウンドチェック、および手書きはすべてそこから取得され、すべてのスクリプトはそこまたは$CODE_FILMでそれを見つけます。

bash assets/setup.shを一度実行してください。code-filmのdoctorをチェックし、次に~/.cache/lesson-film/venvにKokoro、soundfile、faster-whisper、spaCy英語モデルを含むPython 3.12仮想環境を構築し、ffmpegにloudnormがあることを確認します。

良い状態の定義

• 初心者が説明できる。 彼らの2つの文が、インテントカードの要点行と一致し、実際の用語が正しい場所に配置されている。
• 一人の人があなたに説明しているように聞こえる。 各文が次の文に導き、各シーンチェンジがライブの質問を引き継ぐ。映像なしでスクリプトを声に出して読んでください。ラベルのリストのように聞こえるなら、それは完成していません（reference/words.md）。
• 呼吸している。 視聴者は次の変更の前に、それぞれの変更を見る時間がある。Kartikは、毎秒0.36カットの64秒のカットを「ペースが速すぎる」と判断しました。承認されたカットは130秒で毎秒0.16カット、声は通常の速度で実際の息継ぎがあります（reference/pace-and-ending.md）。
• すべての主張が真実であり、チェックされている。 描画を始める前に、主張をfacts.mdにソースに対して書き込みます。映像はまさにその状態を示します。
• 映像が言葉とともに変化する。 それぞれのものは、声がそれを名付ける瞬間に現れます。動きと色は、説明されている部分のみに配置されます（reference/teaching.md）。
• 穏やかに始まり、ゆっくりと終わる。 誰でも理解できる最初の行があり、映像と曲がすでに流れている、質問で終わるコールドオープン、次に約5秒のタイトルスティング。これはKurzgesagtのやり方です。「始まりが唐突に感じる」は、視聴者がまだ出会っていないキャラクターで始まったフィルムに対するKartikのメモでした（reference/pace-and-ending.md）。
• 終わるのであって、止まるのではない。 要約、見返り、冒頭に答える締めのセリフ、ホームコード、そして映像と音声が数秒かけて一緒にフェードアウトする。「終わり方が唐突だ」は二度ともらってはいけないメモです。
• 欠陥がゼロ。 フラッシュなし、ポップなし、クリップなし、ラウドネス-14 LUFS、すべての単語が聞こえる。

これらは判断であり、ルールではありません。カードが理由を述べている場合にのみ、それらを破ってください。

ワークフロー

これをノートにコピーし、各ラインを完了したら報告してください。方法を言わずにラインにチェックを入れることはできません。

[ ] 0 リファレンス  共有された場合のみ。クリップ、静止画、またはHTMLページ。どの形式か、何をするか、どのギャップが埋められるか、何を取り入れ何を残すかを報告する。
[ ] 1 事実      facts.mdをソースに対して作成する。主張とそれぞれがどこでチェックされたかを報告する。
[ ] 2 インテント     assets/intent.mdを<piece>.intent.mdにコピー、要点、感情、質問、推測。報告する。
[ ] 3 ギャラリー    code-filmのreference/gallery.md、最も近い2つか3つのフィルム。何を取り入れ、何をコピーしないかを報告する。
[ ] 4 スケッチ   3つの新しいストーリー、それぞれキット（sketch.py）で描かれた完成形の静止画、1つは住んでみたい世界、例や共有リファレンスから取ったものではない。sketchcheck.pyがBLOCKを報告しないこと、その後シートで判断する。表示する。各ストーリーのライン、3つの判断回答、選択を報告する。
[ ] 5 言葉    スクリプト全体を1つの段落として<piece>.chain.txtに書き、次に「用語」「物」「技術」で行に分割する。段落の前に、各用語の物と、それが持つ各実際の状態に対する世界の動詞を書く。scriptcheck.pyがBLOCKを報告しないこと。そのマップ、一度声に出して読んだスクリプト、すべてのヒンジ、各REVIEWの決定を報告する。
[ ] 6 声     <piece>.lines.json -> voice.py -> heard.py --write。長さ、聞こえた/聞こえなかったすべての単語とその理由を報告する。
[ ] 7 計画    シーン、それぞれを変更する言葉に結び付け、共有する世界の状態。計画を報告する。各用語を示す世界の物と、各実際の状態に対する世界の動詞を含む。
[ ] 8 ビルド     assets/template/からのページ。シーンは最初にドラフトで個別にチェックする。見た後に何を描き直したかを報告する。
[ ] 9 サウンド     assets/score_template.pyからの<piece>.score.py。コード、隙間のメロディ、世界内のサウンドを報告する。
[ ] 10 レンダリング    assets/build.sh。最初はDRAFT=1。数値を報告する。
[ ] 11 検証    以下の3つのレイヤーすべて。それぞれ報告する。
[ ] 12 納品     ビルドごとに新しいファイル、上書きしない。YouTube用のマスター、送信用の30MB未満の小さいプレビュー。

ステップ1から5がレッスンの成否を分けます。特にステップ5：最初に散文としてスクリプトを書き、その後行に分割します。最初に行を切ることは、スクリプトがキャプションのスタックになる方法です。

検証

納品ノートで3つのレイヤーすべてを別々に報告してください。

• 欠陥ブロック。 build.shはscriptcheck.py（すべての用語が言われている、最初の行にない、存在する関連性）とcode-filmのcheck.pyおよびseamcheck.pyを実行し、マスターを-14 LUFSインテグレーテッド、トゥルーピーク-1.5 dBTPにし、YouTubeの仕様にエンコードします（reference/youtube.md）。
• レッスンが測定される。 verify.pyはカードの長さ、ペース、サウンドをチェックします。heard.pyは声を文字起こしし、どの単語が聞こえなかったか、音がキュータイムからどれだけ遅れているかを示します。wordsync.pyは、映像が結び付けられたすべての単語で動きが発生することをチェックします。shiftcheck.pyは、声を2秒後に移動させてフィルムをレンダリングし、変化するシーンをすべて失敗させます。これにより、固定フレームからタイミングが取られたイベントが明らかになります。captions.pyは同じキューから正確なSRTを書き込みます。
• 視聴テストはあなた、次に相手が行う。 初心者として語り直してください。コンタクトシートのすべてのタイルに名前を付けてください。音を消して見てください。映像なしでスクリプトを声に出して読んでください。最後の10秒を単独で判断してください。そして、耳で聞く声など、チェックしなかったことを率直に述べてください。

いつ何を読むか

各ファイルを丸ごと、1回の呼び出しで読んでください。読み取りでトークンが切り詰められたと言われた場合は、そのファイルを単独でもう一度読んでください。code-filmの「いつ何を読むか」は、一括読み取りのコストについて述べています。

• リファレンスが共有された場合、code-filmのreference/references.mdを読んでください。3つの形式すべてをカバーしています。クリップと静止画はffmpegで分解します。HTMLページ（当社または相手のもの）は、code-filmのassets/refpage.mjsを介して処理します。これはページの描画を監視し、パレット、マーク、レイヤー、オーディオキットを報告し、MP4を書き込むため、クリップチェックも実行できます。
• 事実とインテントカードの前に、reference/teaching.mdを読んでください。
• スケッチの前に、このスキルのreference/sketches.mdと、それ自身のreference/traps.mdのStoryセクションを読んでください。次に、code-filmのreference/story.md（「まず形を選べ」と「何が持続するか」）と、code-filmのreference/traps-story.mdを読んでください。
• スクリプトの1行も書く前に、reference/words.mdを読んでください。
• 冒頭またはエンディングを計画するとき、および声の速度、息継ぎ、ホールドを設定するときに、reference/pace-and-ending.mdを読んでください。
• 声を作成または修正するときに、reference/voice.mdを読んでください。
• シーンを計画するとき、ヘルパー間で分割するとき、またはページを構築するときに、reference/film.mdと、2つの映像間の動きを所有するcode-filmのreference/moves.mdを読んでください。
• サウンドを作成するときに、reference/sound.mdと、楽器についてはcode-filmのreference/sound.md、およびreference/traps-sound.mdを読んでください。
• 最初のレンダリングの前と、レンダリングに関するメモの後に、reference/traps.mdを読んでください。
• 公開する前に、reference/youtube.mdを読んでください。
• ルールのソースが必要なとき、または誰かがスキルが何かをする理由を尋ねたときに、reference/research.mdを読んでください：証拠、効果量、リンク。
• 見た目、テイスト、プリント仕上げについて、code-filmのgallery.md、taste.md、press.md、および仕上げを調整する前にtraps-print.mdを読んでください。

ファイル

ファイル	説明
assets/setup.sh	一度だけのセットアップ：音声と聴取のvenv、およびチェック
assets/intent.md	レッスンインテントカード、code-filmのカードに教育用の行を追加
assets/voice.py	Kokoroで<piece>.lines.jsonを読み上げ、ビートグリッドに線を配置し、音声とキューを書き込む
assets/heard.py	Whisperで音声を文字起こし、見つからない単語と遅延を報告、--writeでキューに遅延を保存
assets/saytest.py	Kokoroが間違って発音する単語の別の綴りを試し、Whisperが正しく聞くものを通知
assets/captions.py、assets/wordsync.py	キューからのSRT、および各結び付けられた単語で動きが発生するかのチェック
assets/shiftcheck.py	すべてのシーンが固定フレームではなく音声からタイミングが取られているかのチェック
assets/scriptcheck.py	スクリプトのチェック：用語が言われている、最初の行にない、各用語の物が用語の前に言われている、存在する関連性、絶対的な単語、言われていない画面上の単語、世界と実際のシステムを混在させる文のリスト
assets/sketchcheck.py、assets/barsheet.py	code-filmのスケッチチェック。このスキルの承認されたフレーム、例の町、テンプレートのスタブで実行。また、判断シートを再構築するスクリプト
assets/score_template.py	行ごとのベッド、隙間のメロディ、状態変化時の世界内サウンド、スピーチ下での16dBダッキング、フェードアウトアウトロ
assets/build.sh	ページ、ゲート、パラレルキャプチャ、シーム、スコア、-14 LUFSマスター、エンコード、キャプション、コンタクトシート、すべてのチェック
assets/template/	コピーするページ：assemble.py、film/kit.js（世界を含まないクラフト：インク、ドット、エッジ、ライト、手書き、プリント仕上げ）、film/core.js（音声クロック、レイヤー、カメラ、ダイブ、アイリスムーブ）、film/main.js、film/SCENES.md、1つのスタンドインオブジェクトを構築するサンプルシーン、および3つのストーリー静止画用のsketch.pyとsketches/sketch.js
reference/stills/	承認されたレッスンからのフレーム（キャプション付き）。散文だけでは伝わらない2つのルール用：冒頭とエンディングのビート、および言葉とともに変化する映像。また、自分の3つが存在した後にのみ開かれるスケッチの判断シートsketch-bar.jpgとsent-back.jpg
examples/parcel42-lesson/	承認されたレッスンの全ソース、音声トラック、視聴用フィルムプレビューへのリンク、README、コンタクトシート、サムネイル

パラレルキャプチャはcode-filmにあります（assets/capture-range.mjs、assets/capture-par.sh）。なぜなら、長いフィルムにはそれが必要だからです。

このスキルの変更

意図と判断を述べ、結果を意図と照らし合わせて確認してください。誰かが承認した新しいレッスンは2番目の例となり、このファイルにそれが機能する理由の行が追加されます。学んだ教訓は、それを所有する1つのリファレンスファイルに記録され、他のすべてのファイルはそこを1行で指します。