vstoos/vlog-film

Vlog film

ユーザーの映像素材フォルダを完成済みYouTube動画に変換し、ユーザーが満足するまでフィードバックに基づいて繰り返し編集を行います。このパイプラインは「Yaris farewell」（24分、ウクライナ語音声、iPhone＋Sonyドラレコ）で構築されました。references/example_yaris.py はその映画の完全なプロジェクトファイルであり、完成した編集がどのようなものかを理解するための最良のガイドです。

開始前の準備

• セットアップ. <skill>/config.json にはマシンのパス（ffmpeg、melt、WhisperXを備えたPython、プレートモデル、音楽フォルダ、エンコーダ、音声言語）が格納されています。これがない場合、またはツール不足でスクリプトが失敗した場合は、python <skill>/setup/setup.py（確認のみ）を実行し、不足しているものをユーザーに表示します。ユーザーの了承を得たら python <skill>/setup/setup.py --install を実行します。以下のすべてのスクリプトは、config.json で指定されたPython（"python"）を使用して実行してください。それはWhisperXとtorchがインストールされている環境だからです。
• ユーザーについて. <skill>/user.md が存在する場合はそれを読んでください。そこにはユーザーが誰か、どの言語で応答するか、ユーザーの恒常的な設定が記載されています。ない場合：ユーザーの言語で応答し、返信は簡潔に、動画の時間はmm:ss形式で、確認が必要な箇所を指定してください。
• 以下のコマンドでは $K は <skill>/scripts を表し、python は設定されたPythonを指します。

プロジェクト構成

映像素材はユーザーが配置した場所にそのまま残ります。最終的なmp4、YouTubeの説明文、サムネイル、字幕もそこに配置されます（ユーザーがそこを確認するためです）。作業ファイルはプロジェクトフォルダ（例：C:/Data/<name>-video/）に配置します：

<name>-video/
  project.py        パス、EDL、HOOK、音楽、フレーミング、make_stills()   （references/project_template.py をコピー）
  transcripts/      transcribe_all.py からの <clip>.json
  film/             レンダリングされたインサート、<clip>_blur.mov、<name>.mlt、<name>.mp4
  film_check/       コンタクトシート、テストwav、確認フレーム（スクラッチ）
  edit_notes.md     ユーザーのレビューノートと各対応内容
  subs/、thumbnail/、route/

ワークフロー

1. 素材の棚卸し

1. python $K/scan_meta.py <footage> film_check/meta.json：すべてのファイルの時刻、長さ、GPSを取得します。時刻順に並べるとこれがストーリーの順序になります。
2. 決定前に確認：python $K/contact_sheet.py <out.png> 6 <clips...> でクリップのコンタクトシート、写真用のタイルシートを生成し、自分で画像を確認します。縦向きクリップ（回転-90/90）、ナンバープレートが映るクリップ、ドラレコファイル、画面録画に注意してください。Teslaドラレコ / 旅行日付のSentryイベント：references/teslacam.md（インシデントの発見、teslacam_grade.py による色補正）。
3. python $K/transcribe_all.py <footage> transcripts：すべてのトーキングクリップのワードタイムスタンプ付きWhisperX書き起こし（再開可能、言語はconfigから）。すべてを読んでください。これらがストーリーの生の素材です。

2. ストーリーとEDL

構築前に、ティーザー、パート、どの写真やマップやスチルがどのトークを説明するかなど、構造を数行でユーザーに提案します。典型的な構成：

• ティーザー (HOOK)：旅全体から選んだ4〜6の短く力強いフレーズ。それぞれが完全な意味を持つもの。
• タイトルカード を道路映像に重ね、その後、4〜10秒の音楽に乗せた道路インサートで区切られたトークブロック。
• トークが何かに言及しているときにインサート：燃料の話が出たときのレシート、点検の話が出たときの点検スタンド、各区間の開始時のルートマップ。
• 音声に重ねる写真（Bロール、スマホのスクリーンショット、話者が話し続けている間のキャプション）：burn_in.py を使ってトーキングクリップに焼き付けます（これはfilmkitの前に行います。filmkitは話している間だけトーキングクリップを表示します）。縦向きの写真（スクリーンショット、縦動画、縦写真）は、話者の顔の空いている側にフルフレーム高さで配置され、顔検出によって顔が表示されたままになります。スマホの時計やボタンは上下を埋めます。横向きの写真はフレーム全体を覆います。
• 道路インサートは、その時点でストーリーに必要なものを表示する必要があります（「停車した」という前のガソリンスタンドへの進入路、空港のシーンの前の空港駐車場など）。単なる高速道路ではなく、適切な瞬間の道路クリップのコンタクトシートを確認してください。
• エンドカード：道路映像に20秒、上部にテキスト、中央はYouTubeエンドスクリーンタイル用に空けておきます。ユーザーが持っている場合はここに紹介リンクを配置します。

references/project_template.py から project.py を作成します。EDLアイテムの種類、キャプション、音楽キー、クリップごとのオプションはそこに文書化されています。トーク範囲は書き起こしのタイムスタンプから取得します。

3. ビルドとレンダリング

python $K/blur_plates.py <footage> <project>/film [--faces] IMG_0089 ...   # ナンバープレート; --faces: 人物も
python $K/burn_in.py film/IMG_0089_blur.mov film/IMG_0089_over.mov spec.json   # 写真を音声に重ねる（必要な場合）
python $K/filmkit.py <project>/project.py                        # インサートをレンダリング、film/<name>.mlt を作成
python $K/render_final.py <project>/film <name> <footage>/<Name>_HLG.mp4   # 長時間: バックグラウンドで実行

重いGPUジョブ（レンダリング、WhisperX、吹き替え）の前に nvidia-smi を実行します。カード番号はセッション間で変わり、ツール間でも異なり、他のジョブがカードを保持している可能性があります（references/lessons.md、「GPUとハードウェアエンコーダ」）。filmkit.py --no-media は .mlt のみを再書き込みします（一瞬で完了）。レンダリングはラウドネス、長さ、コーデック/HDRタグ、およびグリーンフレーム数を出力します。期待値：約 -14 LUFS、Main 10、arib-std-b67、bt2020、グリーンフレーム0。

4. 完了をユーザーに伝える前に検証する

EDLを信頼するのではなく、WhisperXで聞いて確認します。新しくまたは変更されたカットごとに、完成した mp4 から同じ秒数を切り出し、書き起こします（python $K/transcribe_window.py <wav> <offset>）。最初のパスの書き起こしは、特に数字を含むフレーズの終わりを誤ることがよくあります（「не 144, а 147」で「а 147」が欠落するなど）。また、隣接するセクションのラウドネスを測定し（ffmpeg -ss A -t N -i film.mp4 -af ebur128 -f null -）、新しいインサートごとに1フレームを確認します。その他の落とし穴とその修正方法については、references/lessons.md を参照してください。

5. レビューラウンド

ユーザーが視聴し、フィルムの時間指定でノートを送ってきます。各ノートについて：

1. python $K/timeline.py film/<name>.mlt 12:22 でクリップ名とソースの秒数を特定します。
2. ソースを確認します（ウィンドウを書き起こし、ラウドネスを測定し、フレームを確認します）。実際に何があるかを、元の言葉を引用してユーザーに伝えます。ユーザーの記憶が録画と異なる場合があります。
3. EDLを変更し、edit_notes.md に記録します（フィルム時刻、クリップと秒数、言われたこと、変更点）。

ユーザーがまだ視聴している間はノートを収集し、ビルドは行いません。最後に一度ビルドすることで、長いレンダリングを節約できます。ユーザーがビルドを指示したら、一度だけ再ビルドし、ステップ4と同様にすべての変更箇所を検証し、チャプターを更新します。

6. 成果物

references/youtube.md：チャプター付きの説明文（timeline.py）、サムネイル（make_thumb.py）、字幕（make_subs.py を完成動画に適用し、手動修正後、キューごとに翻訳、画面上のテキストは onscreen_subs.py で独自のキューとして翻訳）、YouTube自動吹き替え。ユーザーは python $K/media_server.py --port 8765 <footage> <project>/film で電話からレンダリングを視聴できます（LAN / VPNのみ、読み取り専用、github.com/vstoos/media-server でも利用可能）。

7. 吹き替え音声

ユーザーが読みたくなく聞きたい言語の場合：references/dubbing.md。音声は Higgs TTS 3（2026年11月6日以降デフォルト）で、ユーザーのその言語での保存済み参照音声（C:/Data/voices、- を渡す）を使用します。Higgsトラックを含むすべての動画の説明には「Boson AI's Higgs Audio」のクレジットを記載します。字幕は dub.py gen を経由し、dub_check.py がモデルの不具合をテイクごとに検出し、dub_regen.py が失敗したものを置き換え、dub.py mix がトラックを構築して再生すべき箇所を出力します。発音の修正は say.json で行います。無音映像（ドラレコクリップ）のナレーションは、ウクライナ語で同じルートをたどり、字幕として書き出されます。チェックだけでは吹き替えをクリーンと判断しないでください。ユーザーの耳が最終判断です。

プライバシー

ナンバープレート：ユーザーは通常の交通のナンバープレートをぼかしません（ポーランド。浮遊するボックスが道路映像を台無しにします）。クリップがそのドライバーの可能性のある違反やヒヤリハットを示している場合にのみナンバープレートをぼかします。これにより、動画が個人に対する告訴の材料になることを防ぎます。道路インサートは、プロジェクトの CLIP_SRC を介してそのまま挿入します。スタッフ、通行人、子供の顔をぼかします（blur_plates.py --faces。フレームを確認してください。車の塗装への映り込みが誤検出を引き起こす可能性があります）。ルートマップは公共の場所から開始し、決してユーザーの自宅から開始しないでください。特に子供の顔など、他人の顔をサムネイルに使用しないでください（特に明示的に依頼された場合を除く）。

リファレンスファイル

• references/project_template.py：コピーして使用する注釈付きプロジェクトファイル。EDL構文。
• references/example_yaris.py：完成したYaris動画。すべての機能を使用。
• references/lessons.md：HDR、オーディオ、カット、フレーミングの落とし穴と、実際に機能した修正方法。
• references/teslacam.md：Teslaドラレコ / Sentryクリップ（HW3）：保存されたイベントからインシデントを見つける方法と色補正（scripts/teslacam_grade.py）。
• references/youtube.md：説明文、チャプター、サムネイル、字幕、吹き替え、エンドスクリーン。
• references/dubbing.md：ユーザーの声をクローンした独自のオーディオトラックと自動グリッチチェック。
• references/example_make_route.py：Yaris動画からのアニメーションルートマップ（Sentinel-2タイル + OSRM道路）。新しい旅行のためにその定数（境界、都市、ピン、区間）を適応させます。