changelog-video

Changelog → ブランド動画

入力：changelog の .md（テーマと項目。週刊 HyperFrames ダイジェストのようなもの）。 出力：リンターを通過し、シームゲートがグリーンの HyperFrames プロジェクトを projects/active/weekly-changelog-<range>/ に作成します。指示があった場合のみレンダリングします。

最初に必ず読み込むもの： motion-doctrine（カーソルが登場する場合は cut-the-curve と oversized-cursor も、さらに seam-craft）、および captions-overlay。 このスキルは changelog 固有のパイプラインを提供し、ドクトリンはモーションの原則を提供します。

最優先の原則：リストではなく、視覚化する

すべてのテーマは、変更による体験を実演する実際の UI のアニメーションモック、または忠実な類似物で表現します。テキストの箇条書きは使いません。 スクリプトを書く前に、すべてのテーマと項目を references/visualization-registry.md に照らし合わせます。レジストリが ui-recreate / ui-analog / terminal / checklist のいずれを使うか決定します。テキストのチェックリストは最後の手段とし、視覚化が本当に不可能な項目（信頼性の修正リストなど）に限ります。

パイプライン

0 · このスキルのアセットからプロジェクトを初期化する — 必須

構成 HTML を書く前に、必ず実行してください。これを省略すると、必ずこのスキルのブランドではなく、以前に作成した類似プロジェクトの見た目になります。これは、このスキルのブランドから外れる最も一般的な原因です。 スキルのアセット、フォント、スキャフォールドがスキルそのものです。SKILL.md のプロンプトはルーターにすぎません。

mkdir -p project/assets/fonts
cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/
cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3
ffmpeg -y -stream_loop 15 -i <SKILL_DIR>/assets/bg-pattern.mp4 -t <TOTAL> \
  -vf "scale=1080:1080,fps=30,eq=saturation=0.72,[email protected]:t=fill" \
  -an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-<TOTAL>s.mp4
cp <SKILL_DIR>/examples/master-skeleton.html project/index.html

続いて references/build-spec.md を最初から最後まで読む（流し読みは不可）。ここでは、スキャフォールドからすべてのシーンに引き継がれるブランドトークンを定義しています（TT Norms Pro + ABC Solar Display + TT Norms Mono、クリーム色 #f5f6f4、控えめに使うグリーン #5ef17c、グリーンがかった枠線のガラスカード、キッカー／セクションチップのピル形状、top: 990 に配置する 32px のキャプションレール）。

その後に限り、以下の手順 1〜6 を開始します。手順 1〜4（解析、振り分け、スクリプト、VO）では、スキャフォールドに入れる内容を計画します。手順 5 では、すでにコピー済みの project/index.html 内のプレースホルダー（<RANGE>、<TOTAL>、<CUT_N>、<DUR_N>、シーン本文）を埋めます。スキャフォールドのクローム、フォント、パレット、レイアウトシェルを書き直してはいけません。

以前の動画の index.html に対して cp を使おうとしたり、独自の @font-face 宣言を書こうとしたり、上記のエンコード済み bg-pattern MP4 を使わずに WebGL シェーダーの背景をデザインしようとしていることに気づいたら、作業を止めてください。 現在の index.html を削除し、master-skeleton スキャフォールドを cp するところからやり直します。間違ったスキャフォールドにブランドを後付けするより、正しいスキャフォールド上でシーンの内容を作り直すほうが簡単です。

1 · 解析と編集上のカット

• 週の範囲、主要な統計情報（リリース数、コミット数）、テーマ、項目を抽出します。
• 全体の尺は 45〜60 秒にします。 タイトルは 2 秒以内、アウトロは 3.5 秒以内、4 つのテーマにはそれぞれ約 9〜12 秒を割り当てます。
• 各テーマには、主要なビジュアライゼーションを 1 つ、読み上げる項目を最大 3 つ含めます。それ以外の項目は、アウトロの「完全版ダイジェスト」への誘導にのみ含めます。何を削るかを決めるのが作業の要点です。項目が 30 件ある changelog でも、読み上げる要点は最大 14 件にします。
• テーマはストーリーに沿って並べます。注目の機能 → 製品の UI → パフォーマンス → 信頼性（通常、ダイジェストはすでにこの順番になっています）。

2 · ビジュアライゼーションの振り分け

各テーマについて、references/visualization-registry.md から適切な表示形式を選び、次の形式で 1 行にまとめます。テーマ → 表示形式 → モック内で順に行う 2〜4 個のアクション（それぞれをスクリプトのフレーズに対応させる）。レジストリに適合する表示形式がなく、忠実な類似物もない場合は、チェックリストのシーンにします。誠実に表現できないものを、偽の UI で見せてはいけません。

3 · 2 層構成のスクリプト（読み上げ用と表示用）

references/script-voice.md に従い、スクリプトをトークン単位の行で作成します。会話調にし、すべての技術用語に references/lexicon.json の発音表記 spoken を持たせます。一方、display には標準的な綴りを保持します。キャプションには display を表示し、VO では spoken を読み上げます。辞書にない用語があれば、作業を止めてユーザーに発音を尋ね、それを辞書に追加します。 プロジェクト内に script-tokens.json として保存します。

4 · VO — Annie（HeyGen、固定）

# spoken-layer text only; words JSON = ground-truth timestamps of the SPOKEN text
# Repo-native path: the changelog-video skill runs from the hyperframes repo root,
# so it uses the tracked hyperframes-media TTS helper directly (no `npx hyperframes
# skills` install step). If you've copied the skill into another repo, swap in
# your own path to the media-use / hyperframes-media heygen-tts.mjs.
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
  -o voiceover.mp3 --words vo-words.json \
  --voice 330290724a1b470fb63153f34d4c0183   # Annie — lifelike (do not substitute)

heygen CLI ≥0.3.0 が必要です。認証には heygen auth login --oauth を実行してください。 次に、発話タイムスタンプを表示トークンに対応付けます。

node <SKILL_DIR>/scripts/align-captions.mjs \
  --tokens script-tokens.json --words vo-words.json --out captions.json

captions.json はキャプションレールの入力データです（表示用の綴り、発話タイミング）。 アライナーは MISMATCH 警告を出力します。ビルド前にすべて解消してください （通常は、TTS が複数の単語として読み上げる辞書の綴りが原因です）。音声が基準です。すべてのビート時刻は vo-words.json から取得します。VO を再生成すると、すべてのシームが開き直されます。

単語ごとのタイミングは必須条件です。 手順 5 に進む前に、 vo-words.json が空でなく、単語ごとに start／end を含む words: [...] 配列があることを確認してください。空（0 バイト）または配列がない場合は、音声は返されてもタイムスタンプのペイロードがないという既知の失敗ケースです。タイミングなしで続行しないでください。代替手段として、ローカルの whisper を使い、生成した音声を表示用スクリプトに対して強制アライメントします。

uvx --from openai-whisper whisper voiceover.mp3 \
  --model base.en --language en --word_timestamps True \
  --output_format json --output_dir .
# then run align-captions.mjs with --words voiceover.json (same shape)

Whisper は TTS の読み上げを聞き間違えます（「gee-sap」→「gsap」、「heyjen」→「hey Jen」など）。キャプションでは引き続き script-tokens.json の表示用の綴りを使い、 whisper が提供するのはタイムスタンプのみです。align-captions.mjs が両者を結合します。 この代替手段が、キャプション付きビルドと、キャプションが付かないまま気付かずに出荷されるビルドの違いを生みます。

5 · ビルド

references/build-spec.md に正確に従ってください。ブランドトークンとフォント（<SKILL_DIR>/assets/ に同梱）、アニメーション背景のエンコード、シーンの足場、クローム、キャプションレール、各シーンにつき1回に制限したグリーンの演出を設定します。次に、ドクトリンの順序で進めます。ledger.json（通常のシームはすべて左側をカーブカット）→ seam-stamp → VO の単語に合わせた内部ビート → seam-gate による検証。

キャプションは必須です。 マスタースケルトンには LINES 配列を読み込むキャプションレールの IIFE が含まれています。この配列を空のままにして出荷するのは、スタイル上の選択ではなく不具合です。手順 6 に進む前に、captions.json から値を設定してください。

// paste in place of "const LINES = /* … */ []" in the caption-rail IIFE:
const LINES = /* contents of captions.json */ [
  { id: 0, end: 2.74, w: [["This", 0.0], ["week,", 0.30], …] },
  …
];

align-captions.mjs を省略した場合、または LINES が [] の場合、手順 6 のフレームチェックは失敗します。足場から #cap-line を削除して取り繕わないでください。

6 · ゲート（提示前にすべて合格）

1. node packages/cli/bin/hyperframes.mjs check --caption-zone "x0=0;y0=.90;x1=1;y1=1;severity=error;seek=.02,.06,.10,.14,.18,.22,.26,.30,.34,.38,.42,.46,.50,.54,.58,.62,.66,.70,.74,.78,.82,.86,.90,.94,.98"（または、リポジトリ内の skills/hyperframes-cli/ スキルからインストール済みの hyperframes CLI を使用）を実行します。 エラー 0 件（コントラスト：薄いテキストはアルファ値 ≥ .66、シーンのコンテンツはキャプションレールより上に配置）。npx hyperframes@latest は使わないでください。このスキルが生成する構成契約の正解は、追跡対象となっているリポジトリ内の CLI です。
2. seam-gate.mjs verify — 失敗 0 件。
3. プレビューサーバーを再起動します（バンドルがキャッシュされます）。生の comp ページで __player.seek を使い、3～4 個のビートをスポットチェックします。
4. ユーザーから依頼されない限り、レンダリングしないでください。依頼されたレンダリングの後は、MP4 からフレームを確認します（ffmpeg -ss <t> … -frames:v 1）。キャプションが表示されていること、背景動画が黒くないこと、小さすぎる／フリーズしたフレームがないことを確認してください。
5. キャプション表示ゲート — 失敗は即時不合格です。 VO の発話区間全体に分散させて 3～4 フレームをサンプルします（48 秒の VO なら t=3、t=15、t=30、t=42 など）。各フレームで top: 990 のキャプションレールにテキストが見えることを確認してください。発話区間内のフレームでキャプションが欠けている場合、キャプションなしでビルドが出荷されます。赤信号として扱い、手順 5 の LINES の設定を再確認してください。Jul 13-20 の v4 ビルドで実際に起きたのが、まさにこの問題です。

プロジェクト構成

projects/active/weekly-changelog-<range>/
├── index.html            # single-doc master (scenes as slides, stamped seams)
├── ledger.json           # vector ledger (seam-stamp input)
├── script-tokens.json    # two-layer script (source of truth for VO + captions)
├── vo-spoken.txt         # generated: spoken layer, one line
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3               # copy from <SKILL_DIR>/assets/bgm.mp3 (the house track) unless the user supplies one
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4

アンチパターン

しないこと	代わりに
UI の変更を箇条書きにしたスライド	変更を実演するモックを作成します
表現できない項目の偽の UI	正直なチェックリストのシーン
TTS テキストで「JSON」／「CLI」をそのまま使う	発音形は辞書に登録し、表示は標準表記のままにします
キャプションに発音表記を使う	キャプションには常に表示レイヤーを表示します
不明な用語の発音を推測する	尋ねてから、辞書に追加します
変更履歴の項目をすべて読み上げる	テーマごとに最大3項目とし、残りはダイジェストのリンクに含めます
あらゆる場所に緑のアクセントを使う	シーンごとに緑の演出は1回にします（#5ef17c）
前の動画の index.html をベースにする	ステップ0 — このスキルの examples/master-skeleton.html を project/index.html にコピーします。必ず実施してください
@font-face／WebGL シェーダー／カスタム BGM を手作りする	ステップ0 — このスキルの assets/ をそのままコピーします。このスキルのアセットがブランドそのものです
CloudFront の無効化をせずに納品する	S3 の置き換え後は必ず、ディストリビューション E2BSLVSZ7FG3U0 に対して、対象パスを指定して aws cloudfront create-invalidation を実行します。そうしないと、CDN に古いファイルがキャッシュされたままになります
足場コードの LINES 配列が空のまま公開する	ステップ4で値の入った captions.json を生成し、ステップ5で IIFE に貼り付け、ステップ6のゲート5でレンダリング済みフレームにキャプションが表示されることを確認します。LINES が空 = キャプションなしで公開 = 作業をやり直します
vo-words.json がない場合に、キャプションを省略してそのまま公開する	生成した音声に対して whisper の強制アラインメントを使います。キャプションは必須です