変更ログ → ブランド動画
入力: 変更ログ .md（テーマと項目、例：毎週のHyperFramesダイジェスト）
出力: 構文チェック済み、シームゲートグリーンのHyperFramesプロジェクトを
projects/active/weekly-changelog-<range>/ に生成します。レンダリングは要求された場合のみ行います。
最初に必ずロードすること（譲れません）: 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 を削除し、マスタースケルトンのスキャフォールドの 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、固定）
# 読み上げレイヤーのテキストのみ。単語JSON = 読み上げテキストのグラウンドトゥルースタイムスタンプ
# リポジトリネイティブパス: changelog-videoスキルは hyperframes リポジトリルートから実行されるため、
# 追跡された hyperframes-media TTS ヘルパーを直接使用します（`npx hyperframes
# skills` インストール手順は不要）。このスキルを別のリポジトリにコピーした場合は、
# 自身の 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 — リアルな声（代替禁止）
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 .
# その後、align-captions.mjs を --words voiceover.json（同じ形式）で実行
WhisperはTTSレンダリングを聞き間違えることがあります（"gee-sap" → "gsap"、"heyjen" → "hey Jen" など）— キャプションは依然として script-tokens.json の DISPLAY スペルを使用します。whisperはタイムスタンプのみを提供します。align-captions.mjs が結合を処理します。この代替案は、キャプション付きビルドと、静かにキャプションなしで出荷することの違いを生みます。
5 · ビルド
references/build-spec.md に正確に従います: ブランドトークン + フォント（<SKILL_DIR>/assets/ にバンドル）、アニメーション背景エンコード、シーンスキャフォールド、クローム、キャプションレール、シーンごとに1つの限定使用グリーン瞬間。次に、ドクトリンの順序: ledger.json（すべての通常シームは cut-the-curve LEFT） → seam-stamp → VO単語上の内部ビート → seam-gate 検証。
キャプションは必須です。 マスタースケルトンには、LINES 配列を読み取るキャプションレール IIFE が同梱されています。その配列を空のままにすることは、出荷バグであり、スタイルの選択ではありません。手順6に進む前に、captions.json からそれを入力してください:
// キャプションレール IIFE 内の "const LINES = /* … */ []" をこれで置き換えます:
const LINES = /* captions.json の内容 */ [
{ id: 0, end: 2.74, w: [["This", 0.0], ["week,", 0.30], …] },
…
];
align-captions.mjs がスキップされた場合、または LINES が [] の場合、手順6のフレームチェックは失敗します。スキャフォールドから #cap-line を削除してごまかさないでください。
6 · ゲート（提示前にすべてグリーン）
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/スキルからインストールされたhyperframesCLI）— 0エラー（コントラスト: 薄暗いテキスト ≥ .66 alpha; シーンコンテンツはキャプションレールの上に留まる）。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入力を再確認してください。これこそが、Jul 13-20 v4ビルドで問題が発生した点です。
プロジェクトレイアウト
projects/active/weekly-changelog-<range>/
├── index.html # 単一ドキュメントマスター（スライドとしてのシーン、スタンプされたシーム）
├── ledger.json # ベクトル元帳（seam-stamp入力）
├── 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強制アライメントにフォールバックする。キャプションは必須である |