LawrenceHua/ai-ugc-video-pipeline

ai-ugc-video-pipeline は何をしますか？

AIプレゼンターによる短尺マーケティング動画（トーキングヘッド＋実際の商品映像＋キャプション）には、ffprobeやタイムラインをシークするスクリプトでは検出できず、最終ファイルを実機で再生して初めて判明する特有の障害モードがあります。このパイプラインは、それらを納品前に捕捉するゲート方式を採用しており、さらに、一度把握しても再導入しやすい2つの音声バグに対する対策も含んでいます。

使用すべき場面

• 短尺（縦型、9:16）のAIプレゼンターを使った商品・マーケティング動画を制作する場合。
• 既存の動画を再編集または反復改良する場合。
• AI生成のトーキングヘッド映像＋実際の画面キャプチャ＋ffmpegによる生成キャプションを組み立てるパイプライン全体。

非妥協的なフェーズ順序 — 各フェーズが次のフェーズをゲートする

1. PREP（準備：これが完了するまで一切コストをかけない） 現在のプレゼンター・音声生成のモデル情勢を調査する（これらのAPIの料金とエンドポイントは毎月変動するため、実際のプロバイダドキュメントで事前に確認すること）。スクリプトのバリアントをいくつか書き、テキスト判定AIに1つ選ばせ、使用する人物の顔・音声のリファレンス素材（使用する本人の同意を実際に文書化したもの）を準備し、合成する実際の商品映像を撮影し、評価基準とハードな予算上限を設定してから、1セントも使わない。
2. CALIBRATE（キャリブレーション） フルレングスで生成する前に、まず短くて安価なクリップを1つ生成し、フレーミングと本人確認の受容性を検証する。フレーミングが悪い場合は、モデルの選択を変えるのではなく、モデルに与えている参照画像を修正する。
3. GENERATE（生成） 最小限かつ意図的なテイクのみとする。あるモデルが不調であるという証拠が得られた場合にのみ、プロバイダ間／モデル間のA/Bテストを行う — リクエストを散弾的に送らない。スコアが横ばいになったら生成を停止し、有料の反復回数に上限を設ける（例：スコアが上昇傾向でない限り、2回で停止）。
4. ASSEMBLE（組み立て） 最終的な結合にはffmpegのconcatフィルター（デマルチプレクサではない）を使用する（理由は下記の音声バグの項を参照）。リビルドごとに新しいファイル名を付ける — 決して上書き保存せず、常に最後の正常バージョンとの差分を取れるようにする。
5. VERIFY（検証） メディア検証ゲート（後述）と、すべてのスクリプト・キャプション・コピーアセットに対するテキスト/誠実性の事前チェックを実行する。いずれかのゲートに不合格の場合は納品しない。
6. DELIVER（納品） 短い評価・メモ付きのドキュメントとともに、ファイルを人間の最終承認に回す。どのプラットフォームへの投稿も常に人間によるゲート判断 — 自動投稿は絶対に行わない。プレゼンターが現実的な合成類似像である場合は、動画内で別途開示を意図的に行っていても、プラットフォームのAIコンテンツ開示トグルを使用する。

対策しないとサイレントに出荷される2つの音声バグ

1. セグメントの音声トラックがビデオトラックより短い（ナレーションがビデオクリップの途中で終わってしまう）。ストリームコピーでの連結では、音声タイムラインがずれ、最終ファイルの途中で実質的に早く終了してしまう。修正方法： すべてのセグメントの音声をビデオの長さに合わせてパディングし、連結前にすべてのセグメントのサンプルレートとチャンネル数を統一する。
2. パディングしても、連結デマルチプレクサでは音声長の丸めにより微小な（約0.1秒）パケットタイミングのギャップが残ることがある。ffmpegや文字起こしツールのようにストレートにデコードするツールではこれらのギャップを問題なく再生し、何も検出しない。しかし、一部の実プレーヤーでは最初のギャップで音声が完全に停止するため、自動チェックを「通過」したファイルが実際の視聴者には壊れた状態になることがある。修正方法： 最終的な組み立ては、連続的でギャップのないタイムラインに強制的に音声リサンプリングを行うシングルパスのconcatフィルター（デマルチプレクサではない）で行う。

両方を捕捉するプローブ： 最終ファイルの音声パケットタイムスタンプをスキャンし、50ミリ秒を超えるギャップがないか確認する。メディアの検証は、実際のプレーヤーが消費する方法 — 連続デコードと全ファイルの文字起こし — で行い、タイムスタンプにシークしてサンプリングする方法は避ける。後者は捕捉すべきギャップを正確にすり抜けて自動再同期してしまう可能性があるため。

判定AIプロトコル — LLM判定AIはメディアに対して幻覚を起こすため、相互検証を行う

• 固定された適度な圧縮プロキシに対してスコアリングする（過度な圧縮はアーティファクトを誇張し、コンテンツではなくフォーマットに対してスコアを歪める）。
• 判定AIによる音声に関する主張はすべて、決定論的プローブ（文字起こし＋上記のパケットギャップスキャン）で相互検証してから行動に移す。 「グリッチ」と呼ぶ判定は、正しい場合もあれば、間違った理由で正しい場合もある — 雰囲気で信じたり却下したりせず、先に決定論的チェックを実行し、その上で判断する。
• A/B比較の場合：同じ音声トラック、固定された評価基準、一貫した順序で行い、厳密な構造化出力を強制する — 自由形式の判定意見は行動に移しにくく、理屈をつけて軽視しやすい。
• 判定AIは厳しめに出ると想定する。エビデンス（すべての決定論的ゲートが緑＋実際の人間の承認）に基づいて出荷し、判定AIの判定だけで出荷しない。

誠実性と安全性のゲート — これらを雰囲気チェックではなくコードとしてエンコードする

出荷前に、すべてのスクリプト・キャプション・コピーアセットに対して自動事前チェックを実行する：

• 製品の機能や結果に関する捏造された主張がないこと。
• 誰かの顔や音声の無断使用がないこと — 実際の人物の肖像を生成する前に、実際の同意を取得し文書化し、かつ生成プロバイダの本人確認ベース生成に関する利用規約を確認すること。
• 実際のユーザー体験として提示されているが、実際には生成・シミュレートされたものである主張がないこと。
• 公開すべきでないブランド名や製品名が、スクリプト、キャプション、投稿用メモに含まれていないこと。
• 投稿自体は常に別の人間によるゲート判断 — パイプラインの役割は「レビュー準備完了」で終了し、「公開済み」ではない。

予算規律

PREPで設定したハードな上限に対して、見積もり対実績のランニング台帳を維持し、スコアが横ばいになったら生成を停止する — 収穫逓減を過ぎても「あと1テイク」と続けてコストをかけない。事前に予算を組み、エビデンスに基づいて停止することが、このパイプラインの費用対効果を維持する鍵である。

使用方法

インストール： 個人使用の場合はこのフォルダを ~/.claude/skills/ai-ugc-video-pipeline/ に、プロジェクトリポジトリ内の場合は .claude/skills/ai-ugc-video-pipeline/ にコピーする。プレゼンター・音声生成プロバイダや画面キャプチャツールは各自で組み込む — このスキルはゲート手法と実戦で得た障害モードの修正であり、特定ベンダーとの統合ではない。

呼び出し方：

30秒の商品デモ動画について、ai-ugc-video-pipelineのPREPフェーズを案内してください — 生成前にスクリプトバリアントと予算台帳を作成するのを手伝ってください。

組み立てた動画の音声が、一部のプレーヤーでは途中で途切れるが、ffplayでは正常に再生されます。ai-ugc-video-pipelineの音声バグのセクションを使って診断と修正を行ってください。