Video Boost(口播強化)
エンジニアリングディレクトリ:リポジトリルート(公開リポジトリ github.com/Minerva67/video-boost;ローカルは ~/CC/knock-video-boost/)。HyperFrames レンダリング + GSAP タイムライン + 自前コンポーネントライブラリ。
サンプル:runs/example/beats.mjs(構造テンプレート)+ references/components.md(各コンポーネントのデータ記述)。判断ルールは全て references/rules.md(負荷タイプ、セクション区切り、バリエーションローテーション、テンプレートの登場順序、小見出し)に記載。外部ドキュメントには依存しません。
鉄則(ユーザーが繰り返し確認済み、違反は差し戻し)
- 追加のみ、変更なし:元動画の映像、カット順、タイムライン、音声、尺は全て不変。CTA も最後の数秒に重ねるだけで、動画は延長しない。
- カードで口述を繰り返さない。各画像はテストを通過すること:「音声と字幕を消した時、この画像は何を追加で伝えている?」答えが「同じ文字」なら削除。字幕が既に喋っている内容をカードに再掲すると三重の重複となる(v4 が却下された理由)。
- 演じられるなら書くな、本物を取れるなら演じるな:口述で実際に存在するニュース/レポート/製品/場所に言及した場合、優先して実際のスクリーンショットや写真を配置(
photoコンポーネントで該当数字をハイライト);「X ツールで Y をやった」という言及には、X の実際のインターフェースと Y の成果物を演出(Claude Code のセッションでコマンドを入力→ツール呼び出し→結果表/レポート)。グレーのプレースホルダーは不可(v5→v6 で指摘)。 - 演出 ≠ 捏造:インターフェースの演出は許可(ウィンドウ角に「演出」と明記)するが、元動画にない主張は追加しない。数字や出典は必ず実際に検索・検証(WebSearch+WebFetch でページ原文を確認;複数の情報源で数値が異なる場合は範囲で記載し全て明示)。見出し例に「いいね数」「再生数」は付けない。
- 顔を隠さない、圧迫しない:人は常に画面下部中央に配置——全画面 / 62%(通常グラフィック)/ 50%(情報量の多いグラフィック、ユーザー 10-02 要望「情報量が多いなら人を小さくして可視化領域を広く」)。ピクチャーインピクチャー(人を 30% に縮小して隅に配置)は却下済み。
- スキン = テーマ(theme)、デフォルトはユーザー自身の Knock〆 デザインシステム B ライン濃度(
brand/themes/knock/);プライベートテーマもあり(brand/themes/<プライベートテーマ>/、ブランド規範 B ラインに従う)。テーマ切り替え:node build.mjs runs/<name> --theme=<name>(出力先public-<theme>/)。Knock 版の詳細:紙白ベース、ドアイエローは小さなブロックのみ、ノックオレンジ ≤5%、1.5px 墨黒アウトライン、影なし;右上に横長ロゴを常時表示。Claude スタイルのスキンは却下済み(「デザインシステムは私のものを使って」)、Knock の三色を画面全体に敷くのも却下済み(「派手すぎて疲れる」)。 - 分割ロジック:6種類の負荷タイプ + 複合タイプ + 隣接セクションは異なるバリエーション + 補足は強化対象外。ルールは
references/rules.md§1–2 に記載(ユーザーの動画強化 PRD V3 及び『可視化選定規範・30テンプレート』から抜粋済み)。低負荷の説得・意見タイプの口述では、大部分の時間は全画面に戻し、4–6個のグラフィックのみを配置する。
パイプライン
./prep.sh <動画ファイル> <name> # 元動画コピー(HDR は自動で avconvert で SDR 変換)、音声抽出、medium モデル beam5 で文字起こし、句読点で再セグメント化
# → runs/<name>/segs_beam.json を読み込み、校正して runs/<name>/script.txt を作成(| = 字幕区切り)
.venv/bin/python align.py runs/<name> <尺> # 校正テキストを ASR のワードレベルタイムにアライン + VAD で時刻補正 → transcript.json / captions.json / voiced.json
.venv/bin/python fix_caps.py runs/<name> <尺> # <1s または >9字/s の字幕画面を自動マージ、再アライン(章/文/ポーズをまたがない)
# → 先に runs/<name>/structure.md(論証構造)→ cut.md(編集台本)→ beats.mjs を記述(runs/example/beats.mjs をコピーして修正)
# 実素材:node grab.mjs <URL> runs/<name>/assets/x.png --find "キーフレーズ";python3 commons.py "<英語キーワード>" runs/<name>/assets
node build.mjs runs/<name>
npx hyperframes lint runs/<name>/public # 0 error が条件(caption の nested 警告は既知)
HYPERFRAMES_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
npx hyperframes render runs/<name>/public --sdr -q draft -o runs/<name>/draft.mp4 # 156s ≈ 100s
./review.sh runs/<name>/draft.mp4 <各セクション末尾のタイムスタンプ…> # コンタクトシートを生成、1枚ずつ確認
# → 編集者レビュー:独立したサブエージェントを起動、コンタクトシート + cut.md のみを渡し、references/editor.md §5 に従い各セクションを「通過 / 差し戻し」判定。差し戻し分を修正後、再レビュー。
# 修正完了後 → -q draft を外して本番版 output.mp4 を生成
./evaluate.sh runs/<name> [--theme <テーマ>] [--platform xhs] # 最終ステップ:Eval(フォントサイズ/セーフエリアの計測 + 23項目の自動チェック)→ runs/<name>/eval.md
# 閾値を満たさなければ納品不可;WARN は1つずつ判断して修正可能なら修正、再実行。通過後 → ~/Desktop/口播強化_<バージョン>_<テーマ>.mp4 にコピー → SendUserFile
各動画は Eval で締めくくる。納品メッセージには必ず記載:閾値通過の有無、自動スコア、残っている WARN とその許容理由。
環境:ffmpeg/ffprobe は ~/.local/bin;whisper モデルは ~/.cache/kvb-models/ggml-medium-q5_0.bin(一度クリアされたことがあるが、prep.sh が自動で再ダウンロード、515MB);レンダリングはシステム Chrome を使用。
script.txt 校正のポイント
- まず prep の2つの出力を確認:①「ASR カバレッジチェック」、欠落した文は1つずつ再文字起こしして台本に補完;②「元動画に焼き込み字幕あり」、検出時はデフォルトで私たちの字幕をオフにする(
rules.md§8 参照)。 - フォーマット:
|は画面区切り。文末は。を記述(区切りのみで表示はされない)。疑問符・感嘆符はそのまま保持。その他の句読点は記述しない。 - 誤字のみ修正、言い回しは変えない。フィラー(えー、うーん)の削除は可、推敲や語句の補完はしない。固有名詞は正式名称で記述(ClockCode→Claude Code、Codeash→Codex)。
- 聞き取りにくい単語:
.venv/bin/python retranscribe.py runs/<name> <開始> <終了> --terms "3–5 個の本セクションの用語"で、通常速度、用語付き、0.8倍速スロー の3パターンで文字起こしを試行。それでも不明な場合は、納品時にタイムスタンプを付けてユーザーに確認を依頼。 - 画面分割:縦画面は ≤10字/画面(ラテン文字は0.5カウント)、意味の切れ目で分割。固有名詞、数字+単位は分割しない。ぶら下がりの「の」「と」「を」で終わらない。速い発話時には fix_caps が文をまたがない範囲でマージ、上限は14字。
テーマ(デザインシステムの切り替え)
コンポーネント内で色をハードコードせず、全てロール(brand/themes/<name>/theme.json)経由で設定:
| ロール | 用途 | Knock | プライベートテーマ |
|---|---|---|---|
| paper / card | キャンバス / カード | 紙白 / 白 | Gray50 / 白 |
| ink · ink70 · ink40 | 本文3段階グレー | 墨黒系 | Gray900/700/500 |
| line · lineSoft | 区切り線 | 石灰 | Gray300/100 |
| mark + markInk | ハイライト塗りつぶし(現在項目、チェックマーク、進捗表示) | ドアイエロー | Tappy Green |
| accent | 1画面に1箇所の強調(終点枠、コマンド記号、キーワード) | ノックオレンジ | Signal Purple |
| frame · stroke · shadow · radius | カードボーダー/シャドウ/角丸 | 1.5px 墨黒アウトライン、シャドウなし、18 | 1px 薄灰アウトライン+極薄シャドウ、16 |
| fontCn / fontEn / fontMono + fonts[] | フォント(ローカル ttf、レンダリングはオフライン) | Outfit | Plus Jakarta Sans / Inter / JetBrains Mono |
| logo · logoPill | 右上ロゴ、カプセル枠に入れるか | 入れる | そのまま配置 |
| caption.style | 字幕:pill カプセルカラオケ / stroke 白文字黒縁 | pill | stroke(プライベートテーマ PRD V3 字幕仕様) |
新規デザインシステムの導入手順:①その規範を読み、B ライン/プロダクト UI 密度に該当する階層を見つける(動画オーバーレイは控えめに、マーケティング A ラインの派手な色ブロックは避ける);②ブランドカラーを mark(広い範囲でハイライトしても目が疲れない色)と accent(1箇所のみに使う色)に割り振る。彩度の高いブランドカラーはベタ塗りではなく mark として使う方が無難;③フォントの OFL 版をテーマディレクトリに配置;④theme.json を作成 → build → Eval + 手動 H4/H6 を実行;⑤白背景、明るい髪などのシーンで字幕の可読性を確認(stroke スタイルは縁取りを太くする)。
beats.mjs の記述:まず判断、次にコンポーネント選択
ステップ0:まず構造を整理し、小見出しを書く
全文を読み、runs/<name>/structure.md を作成:論点、構造タイプ(パス / フレームワーク / 並列 / 問題→解決 / 比較)、各セクションの役割と結論。小見出し = 役割語 · 結論(≤12字)、これらを繋げて読めば論証そのものが分かるようにする。各セクションに独立した名前を付けない(以前2度却下されている)。詳細とサンプルは references/rules.md §4 を参照。
ステップ1:編集台本——まず「編集者はここで何の映像を切るか」を考える(最重要、references/editor.md 参照)
まず runs/<name>/cut.md を書き、次に beats.mjs を記述。各セクションごとに記入:口述の内容 → 機能(説明 / 証明 / 注意のリセット、いずれでもなければグラフィックを追加しない)→ 編集者が切るであろう映像 → 素材レベル → なぜより上位のレベルを使わないのか。
- 素材レベルは上位から検討:①実素材(ニュース/公式サイトのスクリーンショット、実写真、実際のインターフェース、
grab.mjs/commons.pyで取得、photoコンポーネントで配置)→ ②デモ(cc/folio/resume/checktable)→ ③データ可視化 → ④テキストカード。③④を選ぶ場合は具体的な理由を明記。 - 口述で実際に存在するもの(ニュース、レポート、企業、製品、場所、コミュニティ)に言及した場合、まず①を試す。
- 1画面で1つのことだけを扱う。口述の順序に従って1つずつ画面に表示。空白マス、表の一括表示、大きな余白が生じた場合は、分割するか素材を変更する。
- 単なる意見、繋ぎ、感情、口頭でのまとめ → 全画面、グラフィックは追加しない(スロープッシュは可)。全編で4–6個のグラフィックで十分。
ステップ2:コンポーネント選定
素材レベルが決まったら、コンポーネントを選択。レベル③④は内容の形状に応じて references/rules.md §6 の表を参照。コンポーネントの記述方法は references/components.md を参照。
- 全編に「N 点」構造がある場合、進捗表示は build が CH と TRACK から自動生成する。
ccはあらゆる「コマンド → 手順 → 成果物」のソフトウェア操作を演出可能。AI ツールに限定されない。- 口述に「コメント / フォロー / DM」が登場した場合、
ctaを使用。 - ライブラリに適切なコンポーネントがない場合:
components.md末尾の「新コンポーネントリスト」を参照して新規作成。 - 口述にない実データを使用する場合、まず
rules.md§7 の境界を確認。
HyperFrames 公式ディレクトリ(npx hyperframes catalog)には tiktok-follow / yt-comment-card / claude-exchange / chatgpt-exchange / code-typing などの既成ブロックがあるが、これらはプラットフォーム独自の配色や偽アカウント・偽コメント・偽いいねを含む——動作のみ借用し、Knock のスキンに置き換え、偽のソーシャルプルーフは使用しない。新コンポーネントは components.mjs + brand/components.css に記述。登場順序は references/rules.md §2 に従う。記述のリストは references/components.md 末尾の「新コンポーネントリスト」を参照。
フォントサイズ(感覚で決めない)
全てのグラフィックテキストは6段階のみ:hero 140 / display 96 / title 54 / body 36 / small 28 / micro 22、字幕の76は画面上で最も大きな読み文字。1つのグラフィックで最大3段階まで。dense モードではフォントサイズを大きくしない。仕様、業界基準、プラットフォームセーフエリアは references/typography.md を参照。Eval の T1–T5、S1 で実測チェック。
モーショングラフィックス素材ライブラリ(GSAP タイムラインにアタッチでき、フレーム単位で同期できるもののみ)
- GSAP 全プラグイン(2025年以降無料、商用可;既に node_modules にあり、build で自動ロード):
DrawSVG線画アニメーション、MorphSVG形状変形(例:「パッチ」の破片表現)、MotionPathパスに沿ったモーション(例:脱出軌道のescapeコンポーネント)。 - rough.js(MIT):手描き風の囲み。ビートに
annot: [{ sel, kind: 'circle'|'underline'|'box'|'strike', at }]と記述。パスは固定シードで Node 内で生成し、レンダリング毎に同じ結果に。結論を示すためだけに使い、グラフィック毎に最大2箇所。 - HyperFrames 公式コンポーネントディレクトリ(Apache-2.0):動作のみ借用、現在のテーマのスキンに置き換え。
- 使用可能だが制限あり:Lottie の無料アニメーションは商用可だが、元ファイルを再配布不可。ローカルにのみ残し、公開リポジトリには含めない。使用しない:純粋な CSS アニメーションライブラリ(フレーム単位で同期できないため)。
ブランドロゴ / アイコン(本物、手書きは不可)
グラフィック内に製品名/企業名が登場した場合、名前の前に実際のロゴを挿入:テキストに :openai: ChatGPT と記述すると、md() が brand/icons/openai.svg をインライン展開。
- 取得:
./fetch_icons.sh openai gemini google claudecode codex deepmind …(Lobe Icons、MIT;si:xiaohongshuは Simple Icons、CC0 経由)。出典はbrand/icons/SOURCES.txtに記録。 - 全て単色版を使用(テーマの ink 色を継承):カラーロゴ(Gemini のグラデーション、Google の四色)は「強調色は1画面に1箇所」のルールを壊す。
- 名前とロゴは実際の帰属と一致させること(Veo は DeepMind のロゴを使用)。ライブラリにないブランドは文字のみで表示し、似たアイコンで代用しない。
- 参照のみ(誰の製品か)を目的とし、コラボレーションやエンドースメントを暗示しない。
ステップ3:タイミング
全てのタイミングは校正稿から t('…原文…') で取得(秒数を手入力しない)。グラフィック要素はキーワードが発話される瞬間に出現。コマンド系テキストは1文字ずつ表示(dur はその発話の長さにほぼ等しい)。
カメラワークルール(beats.mjs の CAM に記述)
| レイアウト | いつ使う | パラメータ |
|---|---|---|
full 全画面 | 人がコンテンツである場合:フック、意見、繋ぎ、「以前はこうだった」という説明、締め、CTA | s 1 |
split 寄り/スプリット | グラフィックが情報を伝える時のみ。2つのグラフィック間が <4s の場合は全画面に戻らない(拡大縮小の繰り返しを避ける) | s .62 下端揃え |
dense 密集 | 情報量の多いグラフィック(表 ≥8行、リスト ≥6項目、デモセッション/レポート/履歴書の表示)、ビートに dense: true を記述。余ったスペースはフォントサイズ拡大ではなく、below で2段目の可視化に使う | s .50 下端中央揃え、グラフィック領域 760px(rules.md §5参照) |
push スロープッシュ | 重要な判断、定義、エンディングへの振り返り | 1.00→1.06、d 5–9s |
punch ハードカット拡大 | フックのキラーフレーズにのみ。章の切り替え時にハードカットで戻す | s 1.14、d 0。自撮り顔アップの場合はビート内で LAYOUT.punch を1.07 に下げる |
寄り/スプリット(split)は snapBefore() を使用:前方のポーズのみを検索し、人が先に移動し、グラフィックが後から入場することを保証(build は違反するグラフィックに警告を出す、Eval C6 でチェック)。その他の移動は snap() を使用して発話のポーズに吸着させる(voiced.json の隙間;±0.7s で見つからなければ ±1.4s まで緩和;発話が速く完全にポーズがない場合は最も近い字幕区切りにフォールバック)、カメラは単語の途中で動かない。split の着地はグラフィック入場より前であること。
Eval(納品前に必ず実行)
パイプライン最終ステップ ./evaluate.sh runs/<name>(内部でまず node audit.mjs を実行してフォントサイズと位置を実測、次に python3 eval.py を実行)→ eval*.md:閾値 A1–A5(満たさなければ納品不可)+ 自動 B1–B6/C1–C5 + 手動 H1–H6 評価表。基準、閾値、出典、ベースラインスコアは references/eval.md を参照。納品時報告:閾値通過の有無、自動スコア、主要な WARN とそれが許容される判断項目かどうか。
納品前自己チェック(レビュー用コンタクトシートを確認、各セクション末尾の1フレーム+各演出インターフェースの3–4フレーム)
- 字幕を繰り返すカードはないか?あれば削除。
- 文字や要素がはみ出していないか、字幕帯(y 1520–1670)に被っていないか、顔を遮っていないか?
- 演出インターフェース:空のコンテナが内容より先に露出していないか(全体をフェードインすること)。長いコンテンツは自動スクロールしているか?数字に出典はあるか?
- 進捗表示は正しいか(現在地点/完了/振り返り、全てチェックされているか)?
- 尺 = 元動画(ffprobe で確認)。
納品時のコメント:各グラフィックが何秒目にあり、視聴者に何を追加で提供するかを説明。演出と実際の検索結果(出典リンク付き)の区別を明記。ユーザーに確認が必要な不明な単語も記載。
既知の落とし穴
- iPhone/Clips の元動画は HLG HDR の場合が多い:カラータグのみ変更すると肌色が黄色くなるため、
avconvert -p Preset1920x1080を使用(prep.sh で対応済み)。レンダリング時は--sdrを追加。 - Whisper は冒頭の無音部分を0に近づける傾向がある → align.py の VAD 時刻補正で対応。長い区間で句読点がないもの → resegment.py で対応。
class="clip"要素に対して opacity アニメーションを直接適用不可。アウトアニメーションは内側の要素に適用。GSAP タイムラインは paused 状態でwindow.__timelines["main"]にアタッチすること。- Python で components.mjs を編集する際、
'\n'が本当の改行にエスケープされて JS 構文エラーになる →'\\n'を使用。 - GSAP は
left/topをアニメーション不可(lint が gsap_non_transform_motion を報告) → x/y を使用。幅が必要な場合はページスクリプト内で clientWidth を計測。 - テンプレートリテラル
${}は Node 内で評価されるため、document.*を記述しない(出力される JS 文字列に含める必要がある場合を除く)。 - レビューフレームの削除は
rmのワイルドカードを使用しない(セキュリティチェックに引っかかる)。同名ファイルを上書きで作成する。
バージョン履歴(嗜好の変遷、振り返らない)
v1 Knock 三色全画面 + ピクチャーインピクチャー → 却下(派手すぎる、顔を隠す)|v3 Claude スキン → 却下(私のデザインシステムを使って)|v4 PRD 全セクション強化 → 却下(「彼の言葉をまた可視化しているだけ」)|v5 進捗/メカニズム図/演出モックのみ ✓|v6 演出を実際のインターフェース+実際のデータに変更 ✓|v7 ポートフォリオ/履歴書の演出+カメラワークルール追加 ✓(「このバージョンはとても良い」)|10-01 スキル初実行 ai-value + テーマ化(Knock/プライベートテーマ)+ Eval v1|10-02 「内容の形状→コンポーネント」に汎用化後、ブラインドテストの動画が大量の表やテキストカードだらけに → 却下(「可視化が以前より悪くなった」)→ 編集者視点を追加:編集台本 + 素材レベル + 実素材コンポーネント + レビュー