pr-explainer-film
デフォルトでは無音の、5つのパートからなる約30秒の動画。その構成こそが重要です。視聴者は「差分は読めない」と感じた後、平易な言葉で答えを得て、証拠を見て、何を入力すべきかを知ります。
| 時間 | パート | 目的 |
|---|---|---|
| 0-2秒 | フック | 変更の規模を伝える("15ファイルが変更されました") |
| 2-8秒 | 差分ブラー | 実際の差分が高速スクロール;カウンターが増加 |
| 8-13秒 | 平易な言葉 | 1文のヘッドラインと3つの短いポイント |
| 13-23秒 | 4つのビート | 各機能を1つずつ、実際のコード行と共に表示 |
| 23-30秒 | クロージング | インストールコマンドがタイプされ、続けてURLを表示 |
入力
構築を始める前にこれらを収集します。不足しているものだけを尋ねてください。
- 変更ソース: GitHubのPRまたはリリース(
gh pr diff,gh pr view --json title,body,files)、またはローカルのワーキングツリー(git diffと追跡されていないファイル)。読み取り専用です。リポジトリを変更しないでください。 - オーディエンス: 差分を読まない人(顧客、チームメイト、フォロワー)。これによって要約やビートの語彙が決まります。
- CTA: 正確なインストールコマンドとURL。そのまま使用します。製品に標準的なコマンドが一つある場合は、そのコマンドのみを表示し、他のツール名は表示しません。
- ブランド: パレット、ロゴ(自身のファイル)、フォント。テンプレートのデフォルトはニュートラルでダークです。
ワークフロー
- 変更を読む。 追加/削除数と実際の差分ハンクを含むファイルリストを取得します。非エンジニアが理解できる一文で変更を記述します。それができないなら、まだ変更を理解していない証拠です。
- コンテンツを選ぶ(
references/content-rules.mdを参照):フック番号、ブラー用の5〜8個の差分ハンク、3つの要約ポイント、正確に4つの機能ビート、CTA。 - スキャフォールド。
npx --yes hyperframes init <dir> --non-interactive --example=blankを実行し、生成されたファイルをtemplate/index.htmlとtemplate/film.config.jsで上書きします。ロゴがあればassets/logo.pngに配置します。 film.config.jsを記述する。 すべての文言、スニペット、数値はここに記述します。index.htmlは、:root内のブランド変数、タイミング、またはレイアウトを変更する場合にのみ編集します。- 検証する:
npx --yes hyperframes lintを実行し、次にnpx --yes hyperframes checkを実行します。すべてのエラーを修正します。既知の許容可能な警告:nested_structure_needs_subcomposition(ブランド変更を容易にするため、意図的にファイルを1つにしています)。 - 確認する。
npx --yes hyperframes snapshot --at 1,4,6,8.3,11,14,17,19.5,22,26,29を実行し、snapshots/contact-sheet-*.jpgを開きます。以下のリストと照合し、問題がなくなるまで修正と再スナップショットを繰り返します。 - レンダリングする。
npx --yes hyperframes render --quality high --workers 2 --output final.mp4を実行します。ffprobeで1920x1080、H.264、28〜34秒であることを確認します。 - 再度確認する MP4から抽出した4〜6フレーム(
ffmpeg -ss T -i final.mp4 -frames:v 1 f.png)を確認します(スナップショットだけではありません)。
フォーマットを機能させるためのルール
- 差分は実際のものでなければならない。 実際の差分から実際のコード行をコピーします。コードやカウントをでっち上げないでください。
git diff --shortstatと新しいファイルのwc -lからカウントを計算します。 - 意図的に読めなくする。 スクロールは加速(
power2.in)し、ぼかしがかかります。人が読めるように速度を落とさないでください。「読むには多すぎる」というカードがその代償を支払います。 - 言葉の後に証拠。 要約はどの機能ビートよりも先に表示されます。各ビートのタイトルは2〜4語のメリットです。説明は1文で専門用語はありません。スニペットは1〜5行の実際のコードで、主要な行が強調表示されています。
- 正確に4つのビート、各ビートは1つのアイデア、それぞれ約2.6秒です。テキストを縮小するよりも、弱いビートを削除します。
- 画面の切り替え。 差分とビートはダーク、要約は一つのライトシーン。背景の変化は「今はシンプルです」という合図です。
- コマンドで締めくくる。 実際のコマンドを一文字ずつタイプし、続けてURLを表示します。第2のCTAはありません。
- コピーの衛生。 競合他社や無関係なツールに言及しているコードコメントは、スニペットに到達する前に削除します。CTA以外のCLIは絶対に表示しないでください。
- アセットは自身のものを。 自身のロゴ、マシンに既にあるフォントを使用し、ストックやサードパーティのメディアは使用しないでください。音楽はオプションです。使用する場合は、商用利用が許可されているトラックのみを使用し(
media-useで解決)、動画は無音でも完全に読み取れるようにしてください。 - 決定性。 コンポジション内で
Math.random、Date.now、ネットワークコールを使用しないでください。アニメーションテキストとカウンターはトゥイーンの進行値から駆動し、シークが正確になるようにします。
フレームチェックリスト(ステップ6と8)
- フック番号と文言が実際の変更と一致している。
- 差分ウィンドウがそのフレーム内に収まっている。ファイルヘッダーと緑/赤の行が静止時は判読可能で、移動時はぼやけている。
- カウンターが真の数値で終了している。
- 要約スライドがフェードアウトする前に3つのポイントすべてを表示している。
- すべてのビートにタイトル、文、スニペットが一緒に表示され、何も切れていない。
- 最終フレームに完全なコマンドとURLが正確に表示されている。
成果物
final.mp4 とプロジェクトフォルダ(index.html、film.config.js、assets/、meta.json)を引き渡します。パス、再生時間、許容された検証警告を報告します。フォルダは同じコマンドで再レンダリングできます。次のリリースのためにブランド変更や再利用をするには、film.config.js のみを編集します。
サイズと文言の制限については references/content-rules.md を参照してください。