変更履歴 → ブランド化動画
入力: 変更履歴マークダウン（テーマと項目を含む、例: 週次のHyperFramesダイジェスト）
出力: projects/active/weekly-changelog-<範囲>/ に保存される、lintが通った、シームゲート・グリーンなHyperFramesプロジェクト。レンダリングは要求された場合のみ行います。
最初に必ずロードすること（交渉不可）: motion-doctrine（＋カーソルが表示される場合は cut-the-curve、oversized-cursor、seam-craft）と captions-overlay。このスキルは変更履歴固有のパイプラインを提供し、ドクトリンがモーションの法則を提供します。
基本原則: リスト表示ではなく、視覚化せよ
すべてのテーマは、変更内容を体現する実際の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項目ある変更履歴でも、読み上げられるビートは14以下になります。
- テーマをストーリーで並べます: 目玉機能 → プロダクトサーフェス → パフォーマンス → 信頼性（通常、ダイジェストは既にこの順序です）。
2 · 視覚化のルーティング
各テーマについて、references/visualization-registry.md からサーフェスを選択し、1行を書きます: テーマ → サーフェス → モックが実行する2〜4の順次アクション（各アクションはスクリプトのフレーズに紐づく）。レジストリのサーフェスが適合せず、忠実な類似物も存在しない場合は、チェックリストシーンにします。正直に表現できないもののために偽のUIを発明してはいけません。
3 · 2レイヤースクリプト（読み上げ用 vs 表示用）
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バイト）または配列がない場合（TTSプロバイダーがオーディオを返したがタイムスタンプペイロードを返さなかった既知の障害モード）、それなしで進めないでください。フォールバック: 生成されたオーディオをローカルの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（すべての通常シームは左にカーブをカット）→ シームスタンプ → VO単語の内部ビート → シームゲート検証。
キャプションは必須です。 master-skeletonには、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 · ゲート（提示前にすべてグリーン）
bun run --cwd packages/cli hyperframes check（またはリポジトリローカルのskills/hyperframes-cli/スキルからインストールされたhyperframesCLI）— エラー0（コントラスト: 薄いテキスト ≥ .66 アルファ）。npx hyperframes@latestに頼らないでください。追跡されたリポジトリローカルCLIが、このスキルが生成するコンポジションコントラクトの真実の情報源です。seam-gate.mjs verify— 0 失敗。- プレビューサーバーを再起動します（バンドルをキャッシュします）。
__player.seekを使用して、未加工のコンポページで3〜4ビートをスポットチェックします。 - ユーザーが要求しない限り、レンダリングしないでください。要求されたレンダリング後、MP4からフレームを検証します（
ffmpeg -ss <t> … -frames:v 1）。キャプションが存在すること、背景ビデオが黒でないこと、小さな/フリーズしたフレームがないことを確認します。 - キャプション存在ゲート — ハードフェイル。 VOの読み上げウィンドウ全体にわたって3〜4フレームをサンプリングし（例: 48秒のVOの場合
t=3、t=15、t=30、t=42）、top: 990のキャプションレールが各フレームに表示可能なテキストをレンダリングしていることを確認します。読み上げインターバル内のフレームでキャプションが欠落している場合、ビルドはキャプションなしで出荷されます。赤信号として扱い、手順5のLINES設定を再確認してください。これこそが、7月13〜20日のv4ビルドで問題が発生した箇所です。
プロジェクトレイアウト
projects/active/weekly-changelog-<範囲>/
├── index.html # 単一ドキュメントマスター（スライドとしてのシーン、スタンプされたシーム）
├── ledger.json # ベクターレジャー（シームスタンプ入力）
├── script-tokens.json # 2レイヤースクリプト（VO + キャプションの真実の情報源）
├── vo-spoken.txt # 生成: 読み上げレイヤー、1行
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3 # <SKILL_DIR>/assets/bgm.mp3 からのコピー（ハウストラック）。ただし、ユーザーが提供する場合はそちらを使用
└── 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強制整列にフォールバックする。キャプションは必須 |