チェンジログ → ブランド動画
入力: チェンジログ .md(テーマと項目。毎週のHyperFramesダイジェストのようなもの)
出力: projects/active/weekly-changelog-<range>/ にある、リントチェックが通ったシームゲート対応の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行で次のように記述します: theme → surface → モックが実行する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 テキストのみ。words JSON は SPOKEN テキストのグラウンドトゥルースタイムスタンプです
# リポジトリネイティブのパス: changelog-video スキルは hyperframes リポジトリルートから実行されるため、
# 追跡されている hyperframes-media TTS ヘルパーを直接使用します(`npx hyperframes skills` インストール手順は不要)。
# このスキルを別のリポジトリにコピーした場合は、メディアユース / 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(すべての通常シームはカット・ザ・カーブ LEFT)→ シームスタンプ → VOワード上の内部ビート → シームゲート検証。
キャプションは必須です。 master-skeleton には 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 · ゲート(提示前にすべてグリーンであること)
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投入を再確認してください。これこそが、Jul 13-20 v4ビルドで問題が発生した点です。
プロジェクトレイアウト
projects/active/weekly-changelog-<range>/
├── 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の無効化なしで納品する | 配布 E2BSLVSZ7FG3U0 に対して、S3置換後に正確なパスで aws cloudfront create-invalidation を実行する。そうしないとCDNが古いファイルをキャッシュする |
スキャフォールド内の LINES 配列を空のまま出荷する | ステップ4で captions.json を生成し、ステップ5でIIFEに貼り付け、ステップ6のゲート5でレンダリングフレーム上のキャプションを確認する。空の LINES = キャプションなし出荷 = やり直し |
vo-words.json がないからといってキャプションをスキップしてそのまま出す | 生成されたオーディオに対してwhisperの強制アライメントにフォールバックする。キャプションは必須である |