blender-video-editing

ビデオ編集とトラッキング

実行モデルは blender-core にあります。3D ショットとコンポジター（5.0 API）のレンダリングは blender-rendering にあります。

それぞれ1回の呼び出し

scripts/vse_edit.py -- --clips //renders/sh010/ //renders/sh020/ //logo.png --crossfade 12 --title "Project" --audio //music.wav --out //edit.mp4 --render
scripts/vse_edit.py -- --clips a.mp4 b.mp4 c.mp4 --crossfade 0 --fps 24 --out //review/f_#### --render   # hard cuts to PNG

import track_camera; print(track_camera.run(clip="C:/shots/sh010.mp4", focal=35, sensor=36))  # live/MCP only

vse_edit.py

• 専用の Edit シーン（--scene）に構築するため、3D シーンには手を加えません。クリップはチャンネル1/2に交互に配置し、クロスフェード（CROSS）は3、タイトルは4、クリップ音声は6/7（動画には音声ストリップを追加）、音楽は8に配置します（--audio-fade による音量フェードアウトを適用し、編集内容に合わせてトリミングします）。
• クリップには動画、静止画（--still-seconds）、フレームのフォルダー、または #### パターンを指定できます。各クロスフェードは前のクリップと --crossfade フレーム重なるため、カットごとに編集の長さがその分短くなります。再実行すると、前の編集内容が置き換わります。
• ビュー変換を Standard に設定します。映像素材には何も変更を加えずに通す必要があります（実測値：AgX では純粋な赤が 0.86/0.23/0.13 に変わりました）。意図的な色調補正には、代わりにストリップモディファイアーを使用してください。
• 出力：.mp4/.mov/.mkv は H.264（CRF 高、プリセット good）+ AAC 192k ステレオです。それ以外のパスでは PNG フレームが出力されます。5.0 以降では、file_format = "FFMPEG" の前に image_settings.media_type = "VIDEO" を設定する必要があります。ファイルサイズを報告し、テストでは出力をデコードして再確認します（フレーム数、サイズ）。

プロが守る編集ルール

• まずフレームレートを合わせてください（--fps は映像素材／レンダリングのレートに合わせます）。レートが混在すると音声がずれていきます。代わりに再レンダリングするか、リタイミング（SPEED エフェクト）を行ってください。
• 重い映像素材にはプロキシを作成します（strip.use_proxy = True、25/50%、sequencer.rebuild_proxy）。5.2 ではプロキシのみが作成されます（.blen_tc タイムコードファイルは作成されなくなりました）。
• ストリップごとの色：strip.colorspace_settings.name（8ビット動画には sRGB、EXR レンダリングには Linear Rec.709）。専用の編集シーンを使うことで、3D の色設定が編集に影響しません。
• 5.2 API：strips.new_movie(..., stream=N) / new_sound(stream=N) でマルチトラックファイルからストリームを選択します。strip.connections には接続されたストリップが一覧表示されます。新しいエフェクトタイプは COMPOSITOR（ノードツリーエフェクト）です。テキストストリップには、UI に Subtitles / Main Title / Corner Title のプリセットがあります。タイミングには left_handle/right_handle/duration（5.1 の名称）を使用します。ストリップのキーフレームはシーンのアクションに格納されます。

モーショントラッキング（track_camera.py、ライブセッション）

• クリップエディターのオペレーターにはウィンドウが必要なため、最も広いエリアを一時的に借りて実行し、元に戻します。-b ではエラーを発生させます。最初と最後のフレームで特徴点を検出し、両方向にトラッキングして、min_frames より短いトラックを削除します。次に解決を行い（キーフレームを自動設定し、焦点距離が不明な場合に限って調整）、max_error px を超えるトラックを削除して再解決した後、setup_tracking_scene（カメラ + Camera Solver 制約、背景映像素材、フレーム範囲）を実行します。
• 960×540 の合成40フレームのドリー映像での実測値：56トラック、0.19 px の解決誤差、焦点距離 35 mm を正確に維持。品質の目安：0.3 px 未満は非常に良好、0.5 未満は良好、1 px 超は滑っています。
• 焦点距離が分かっている場合は、focal/sensor を指定してください。焦点距離を調整する場合より、ソルバーの安定性が大幅に高まります。焦点距離より先にセンサーを設定してください（焦点距離は px 単位で保存されます）。
• ノーダルパン（カメラのみを回転）：tripod=True を指定します。視差がないと通常の解決は失敗します。
• 解決後にシーンの向きを設定します（UI、クリップエディターのコンテキスト）。床のトラックを3つ選択して clip.set_plane(plane="FLOOR")、トラックを1つ選択して clip.set_origin()、既知の距離だけ離れたトラックを2つ選択して clip.set_scale(distance=…) を実行します。それ以外の場合、スケールと上方向は任意になります。
• その他の用途：スクリーン／看板の置き換え → 平面上の4つ以上のトラックに対して clip.create_plane_track()。手ブレのある映像 → 2D 手ブレ補正（tracking.stabilization.use_2d_stabilization、トラックを追加）。モデリング用のポイント → clip.bundles_to_mesh()。

トラッキングを成功させる撮影／映像素材のヒント

シャッター速度を速くする（モーションブラーを抑える）、実際の視差を作る（パンだけでなくカメラを移動する）、複数の深度にテクスチャのある静止面を配置する、ローリングシャッターによる急なパンを避ける、広角レンズを使う場合は歪み補正用にレンズグリッドを撮影する。

注意点

• bpy.ops.render.render(animation=True) は、scene.render.use_sequencer が有効で、ストリップがレンダリング対象のシーンにある場合にのみ、シーケンサーをレンダリングします。このスクリプトは独自の編集シーンをレンダリングします。
• クリップを削除すると、そのエフェクトストリップも削除されます。ループ内で削除する前に名前を収集してください。
• 画像シーケンスは連続している必要があります。フレームが欠けている場合、黒く表示されます。