video-edit

Video Edit — キャプション付きショーケースパイプライン

HyperFrames を基盤とする、エンドツーエンドのキャプション付き動画エディターです。ユーザーから動画を受け取り、文字起こし → レビュー → レンダリングを実行します。長時間のレンダリングの前には、必ず文字起こしの承認を待ちます。

YUV.AI ピラミッドにおけるこのスキルの位置づけ

video-edit は、yuv-design-system、yuv-decks、yuv-viral-video、parallax-landing-page、video-to-landing-page と並ぶ、YUV.AI スキルピラミッドの中間層にあります。最上位のオーケストレーター yuv-pilot は、字幕付きのショーケース、チュートリアル、またはトーキングヘッド動画の編集をユーザーが希望した場合、ここに処理を振り分けます。

これは、yuv-viral-video と同じ系統の、より汎用的な動画スキルです。違いは次のとおりです。

• yuv-viral-video — YUV.AI 独自の意見を反映したバイラルショート動画パイプライン（MrBeast 風のテンポ、独自の編集スタイル）
• video-edit — 文字起こしのレビュー後にレンダリングする汎用キャプション付きエディター（ヘブライ語、英語、その他の Whisper 対応言語）

YUV.AI ブランドのキャプション付き動画を作成する場合は、このスキルと yuv-design-system を組み合わせてください（書体やパレットの選択には Neon モードを使用します）。汎用、またはサードパーティ向けのキャプション付き動画には、このスキル単体で対応できます。

起動するタイミング

• 動画ファイルのパス（mp4/mov/mkv）が提示され、「編集」「キャプションを付ける」「字幕を追加する」「リール／プロモを作る」「同じようにしてほしい」といった依頼がある場合
• 「キャプションを修正して／ヘブライ語のスペルミスを直して」— 既存のプロジェクトのレビュー手順から再開する場合
• キャプション付きチュートリアル／トーキングヘッド／プロモの作成全般

保存先

デフォルト： ~/Documents/yuv-projects/videos/<slug>/ — レンダリング結果を見つけやすいよう、キャプション付き動画プロジェクトは必ずここに保存します。<slug> はトピックまたはソースファイル名に基づく短い名前です。

mkdir -p ~/Documents/yuv-projects/videos
cd ~/Documents/yuv-projects/videos
# Initialize the project here.

最終レンダリング結果は ~/Documents/yuv-projects/videos/<slug>/renders/<name>_FINAL.mp4 に保存されます。レンダリング完了時に、動画の保存場所をユーザーに伝えてください。

---

ワークフロー（12 ステップ）

1. ソースを調査する — ffprobe で解像度、fps、長さ、音声を確認します。

2. プロジェクトを作成する — cd ~/Documents/yuv-projects/videos && npx hyperframes init <slug> --video <path> --non-interactive を実行します。コピーされた動画の名前を source.mp4 に変更します。

3. 音声を抽出する — ffmpeg -i source.mp4 -vn -ac 1 -ar 16000 audio.wav を実行します。

4. 文字起こしする — references/transcribe.py をプロジェクトにコピーします。デフォルトのモデルは large-v3（ヘブライ語に最適）です。Windows では CUDA が失敗することがよくあります（cuDNN が見つからないため）。その場合、スクリプトは CPU の int8 にフォールバックします。ヘブライ語では language="he"、英語では language="en" を指定し、それ以外の場合は自動検出します。

5. 既知の誤りを修正する — references/corrections-hebrew.md の内容をプロジェクトルートの corrections.json にコピーします（キー = 誤ったトークン、値 = 正しいトークン）。

6. 🛑 停止 — レビューサーバーを起動し、ウェブアプリでユーザーの承認を待ちます。 まず既知の誤りを修正します。references/make_review.py をプロジェクトにコピーし、 python make_review.py を実行します。corrections.json の内容が transcript.json に適用されます。

   次に、レビューサーバーをバックグラウンドタスクとして起動します（ユーザーがブラウザーで 「Approve & Render」をクリックするまで処理をブロックします）。

   python "$HOME/.claude/skills/video-edit/references/serve_review.py" .
   # On Windows: python "C:\Users\<you>\.claude\skills\video-edit\references\serve_review.py" .
   

   サーバーは REVIEW_URL=http://localhost:PORT/ のような行を出力します。バックグラウンドタスクの出力から （または標準出力を読み取って）この URL を取得し、ユーザーに次のように伝えます。

   👉 こちらで文字起こしを確認してください：http://localhost:PORT/ Approve & Render をクリックすると、自動的に処理を続行します。

   エージェントは「続行」というメッセージを待つ必要はありません。ユーザーがボタンをクリックすると、 サーバーはプロジェクトディレクトリに transcript_review.txt を書き込み、終了コード 0 で終了します。 エージェントにバックグラウンドタスクの通知が届き、パイプラインはステップ 8 から再開します。

   ブラウザーもサーバーも使えない場合の代替手順：エディターを静的ファイルとして開きます （start "" "$HOME/.claude/skills/video-edit/transcript-editor/index.html"）。 ユーザーにプロジェクトフォルダーを選択してもらい、編集後、transcript_review.txt をプロジェクトに保存して、 「続行」と返信するよう依頼します。エディターはどちらのモードにも対応しています。

7. （任意）背景を削除する — 下記のステップ 7 を参照してください。ユーザーの レビュー中に並行して実行できます。

8. 承認後、python references/apply_review.py を実行します。編集した行を再トークン化し、単語ごとのタイミングを transcript.json に再配分するため、字幕の同期が保たれます。

9. （任意）背景の除去 — トーキングヘッドのセグメントで被写体の背後にテキストを表示する必要がある場合は、そのセグメントを outro.mp4（または intro.mp4）として書き出し、npx hyperframes remove-background <clip>.mp4 -o <name>_subject.webm --quality best を実行します。ほとんどの環境ではCPUのみを使用し、約15秒の1440pクリップで約3〜8分かかります。

10. ソースを高密度キーフレームで再エンコード — マルチワーカーでのレンダリングでは、キーフレームがまばらだとシーク時にフリーズします。必ず以下を実行します。

    ffmpeg -y -i source.mp4 -c:v libx264 -preset medium -crf 18 -r 30 -g 30 -keyint_min 30 -sc_threshold 0 -pix_fmt yuv420p -movflags +faststart -c:a copy footage.mp4
    

11. （編集済みの）トランスクリプトを再読み込みし、references/gen_body.py で本文のサブコンポジションを生成します。ジェネレーターは、エディトリアルとマトリックスがリキッドグラスのピル内で交互に表示される compositions/components/caption-body.html 全体を出力します。左下寄りの中央に配置されるため、右下のWebカメラPiPを避けられます。

12. references/host-template.html を使ってホストの index.html を設定します。レイヤーの順序（z-index。トラックインデックスではありません）：

    • z0：映像 .cam-bg
    • z1：リキッドブロブの背景（compositions/liquid-blobs.html、mix-blend-mode: screen、全尺）
    • z2：被写体の背後に配置する視差字幕（背景除去を使用した場合のイントロおよび／またはアウトロ）
    • z3：被写体の切り抜き .cam-out / .cam-sub（対応する data-media-start を設定）
    • z6：本文字幕
    • z46：プログレスバー＋フラッシュ＋リキッドモーフワイプ

13. Lint — npx hyperframes lint を実行します。エラーが0件である必要があります。よくある修正方法：ワイプ要素でのGSAPとCSSのtransformの競合（xPercent/yPercent を使うか、CSSのtransformを削除する）、同じプロパティに対するトゥイーンの重複（overwrite: "auto" を追加する）。

14. レンダリング — npx hyperframes render --quality standard --fps 30 --output renders/<name>_FINAL.mp4 を実行します。納品にはstandardが適しています。high ではレンダリング時間が約2倍になります。完了を報告する前に、タイムライン全体から6〜8フレームを抜き取り確認します。

TikTok / Reels / Shorts 向けの縦型（9:16）出力

ユーザーが（16:9のソースから）縦型／ポートレート／TikTok／Reels／9:16の出力を求めた場合：

1. プロジェクトを同階層のフォルダーに複製します：cp -r project/ project-vertical/。
2. index.html を references/host-template-vertical.html に置き換えます（1080×1920のキャンバス、リキッドブロブを配置したぼかし背景、中央に横向きの16:9映像、下部に字幕）。
3. gen_body.py を references/gen_body_vertical.py に置き換えます（中央配置のピル、大きめのフォント、狭い最大幅）。その後、再実行して compositions/components/caption-body.html を出力します。
4. 被写体の背後に配置する切り抜きと視差のサブコンポジションを削除します（切り抜きは16:9向けに配置されており、v1では再配置する価値がありません）。代わりに、縦型コンポジションでは、雰囲気を演出するためにぼかしたソースの背景とブロブを使います。
5. data-duration を実際の動画の長さに更新します。index.html のブランドチップのテキストも更新します（デフォルトは YUV.AI）。
6. Lintとレンダリングを実行します。同じコマンドを使用します。出力は 1080×1920 です。そのままTikTok / IG Reels / YT Shortsに投稿できます。

16:9と9:16の両方を一度に納品するには、2つのレンダリングコマンドを（別々のプロジェクトで）実行します。transcript_review.txt の承認は両方に適用されます。同じ字幕で、コンポジションが2種類になります。

重要なルール

• 文字起こしの明示的な承認がないまま、最終版を絶対にレンダリングしないでください。 レビューの手順こそが、このプロセスの要点です。
• ヘブライ語の場合：large-v3 + language="he" + direction: rtl + Rubik（編集上の二段階のウェイトによる強調には 700 + 900）。
• キャプションのピルには、必ず不透明な暗色の背景を付けてください。明るいアプリ UI 上では、背景のない明るい色のテキストは見えなくなります。
• キャプションのピルは水平方向の中央に配置します。ただし、映像の右下にウェブカメラの PiP がある場合は、中央の x 座標を左にずらしてください（例：left: 720px）。
• 被写体の背後に配置する切り抜きクリップには、data-start と一致する（またはクリップを抽出した場合はソースからのオフセットと一致する）data-media-start を必ず設定してください。設定しないと、切り抜きはフレーム 0 から再生され、同期がずれます。
• remove-background の webm は元の RGB を保持し、アルファマスクのみを書き込みます。ffprobe では yuv420p と報告され、「アルファなし」のように見えます。TAG:ALPHA_MODE=1 を確認するか、単色の背景に合成してください。
• テキストが焼き込まれたアウトロ／エンドカードには、キャプションを重ねないでください。テキストが重なってしまいます。

ファイルの参照先

ファイル	用途
transcript-editor/index.html	インタラクティブなブラウザーエディター — 動画プレビュー、RTL 編集、辞書の適用、オプションの WebLLM AI 提案機能を備え、transcript_review.txt を保存します
references/setup.md	Node／Python／FFmpeg／faster-whisper の前提条件とインストールコマンド
references/transcribe.py	CPU フォールバックと単語のタイムスタンプに対応した faster-whisper による文字起こし
references/serve_review.py	ローカルレビューサーバー — エディターを自動で読み込み、ユーザーが「Approve & Render」をクリックするまで待機してから、transcript_review.txt を書き込み、終了します（エージェントに通知します）
references/make_review.py	修正を適用し、transcript_review.txt を出力します（ファイルモードのフォールバック）
references/apply_review.py	編集済みのレビューファイルを解析し、単語のタイミングを再配分して、transcript.json を更新します
references/gen_body.py	キャプション本文ジェネレーター（リキッドグラスのピルを使った編集版＋マトリックス版）
references/host-template.html	リキッドエフェクトとトランジションワイプを備えた 16:9 のホスト構成
references/host-template-vertical.html	9:16 のホスト（1080×1920）— TikTok／Reels／Shorts 向けレイアウト：ぼかした背景、中央に配置した 16:9 の映像ストリップ、その下のキャプション、右上のブランドチップ
references/gen_body_vertical.py	縦型向けに調整されたキャプション本文ジェネレーター（中央揃えのピル、大きめのフォント、狭めの最大幅）
references/liquid-blobs.html	全尺にわたって漂うブロブレイヤー
references/caption-parallax-outro.html	被写体の背後に配置するキャプションテンプレート（英語。他の言語では複製して使用）
references/corrections-hebrew.md	ヘブライ語で Whisper が誤認識しやすい既知の表現
references/transcript-review-workflow.md	一時停止／承認の手順の詳細