akomlik/assemble-timeline

Atomic MCP タイムラインアセンブリ＆検証 (/assemble-timeline)

オプション A: FilmCraft MCP 実行 (filmcraft MCP サーバー — FilmCraft v0.17.0+ 必須)

1. 環境とブリッジの確認

1. 最初に python3 ./.agents/skills/assemble-timeline/scripts/check_filmcraft_env.py を実行し、FilmCraft が v0.17.0 以上であること、filmcraft-cli と FilmCraft.app が自動同期されていること、新しく追加された MCP コマンドを 00_Archive_Indexes/filmcraft_capabilities.json にリストアップします。
2. FilmCraft がブリッジモードで起動しており、キャッシュが ~/Movies/Cache_And_Previews にルーティングされていることを確認します：

   mkdir -p ~/Movies/Cache_And_Previews && cd ~/Movies/Cache_And_Previews
   open -a FilmCraft --args --control 9876
   

2. ライブビジュアルアセンブリモード（デフォルト・推奨）

開いている FilmCraft GUI でタイムラインがリアルタイムで組み立てられていく様子を確認できます。ソケット実行時間は合計 1.5 秒未満（ローカルブリッジ上の呼び出しは各 20 ms 未満）で、瞬時に視覚検証が可能です：

1. 0秒地点にブランクキャンバスを開く： command_run ({"id": "file.open", "params": {"path": "<fcproj_path>"}}) または sequence.new を使用して、すぐにクリーンな .fcproj シェルを作成し FilmCraft で開きます。ユーザーは 0 秒地点に空の 4K シーケンスが表示されるのを見ます。
2. ストリーミングメディア取り込み： 選択されたすべてのビデオカット、写真、アーカイブ素材、および選択された 03_Audio_Library/01_Curated_BGM/ トラック（A2）の絶対ファイルパスを指定して media_import を呼び出します。
3. シーンごとのライブストリーム： 承認された Cut Table の各シーンが処理されるにつれて、command_batch 呼び出しを 9876 ブリッジ経由でライブストリームします：
   • playhead.set: 再生ヘッドをシーン開始タイムコードに移動。
   • source.overwrite / timeline.insertClip: ビジュアルクリップを V1（またはオーバーレイ/PIP の場合は V2）に配置し、同期オーディオを A1 に配置。
   • motion.apply: 静止画に Ken Burns EaseIn/EaseOut スケール＆パンキーフレームを注入（100% → 108%、または 4:3 写真の場合は 134% → 142% でピラーボックスを防止）。
   • audio.append: 1.5 秒のフェードインと盛り上がりを伴う A2 背景音楽をドロップ。
   • voiceover.insert: 各音声キューが合成され次第、A4 ナレーションセグメントをライブタイムラインにドロップ。
4. 放送品質の仕上げ：
   • 同一言語ライブダイアログ尊重ルール： 言語 L の A4 ナレーションを、同じ言語 L で話されている A1 ライブカメラダイアログの上に決して配置しない（EN ナレーションはライブ EN ダイアログを尊重、RU ナレーションはライブ RU ダイアログを尊重、UA ナレーションはライブ UA ダイアログを尊重）。A4 ナレーションが外国語のカメラダイアログを含むクリップを翻訳する場合（edition_lang != clip_dialog_lang）、アクティブなナレーションキュー中は A1 を -12 dB ダックする。
   • 自然な 1.00x 話速、1:1 V1 == A1 リップシンク＆オープニング音楽イントロルール： ライブカメラスピーチ (A1) または合成ナレーション (A4) に atempo > 1.0 や内部ポーズ除去 (stop_periods=-1) を決して適用しない。話しているビジュアルカット (V1) は常に完全な 1.00x の話された文 (src_in, dur) に合わせてサイズ調整し、V1 と A1 がフレーム＆サンプル同期（atrim=start=...:end=...,asetpts=PTS-STARTPTS でスライスし、amix 後に dynaudnorm=f=150:g=7:p=0.90 を一度適用）で 1:1 にロックされ、無関係なシーンに溢れ出さないようにする。すべてのタイムラインおよびレンダリングされた .mp4 は、最初のナレーションキューが始まる前に必ず 1.5s–2.0s の音楽イントロで開始する。
   • RMS校正済み音楽ダッキング（音声下で平均 -28.5 dB）： ffmpeg volumedetect を使用して各 A2 音楽トラックの mean_volume を測定し（compute_bgm_ducked_gain_db）、gain_db = -28.5 - raw_mean_db を設定。これにより、ダックされた BGM はホットマスタリングされたアップビートトラックでも、正規化された -16.0 dB 平均のナレーションおよびライブダイアログより 12.5 dB 静かな -28.5 dB 平均 で再生される。
   • A4 ナレーションと A1 ダイアログを Dialogue としてタグ付けし（clarity.eqPreset: "Balanced Voice"）、essentialSound.generateDucking（reduceDb: -6.0, fadeS: 0.45）を A2 音楽に実行。
   • 最後のビジュアルクリップにネイティブの 1.5 秒～ 2.0 秒の dip_to_black トランジションを適用。
   • 必須の同期アウトロオーディオフェード： マスターオーディオ出力（[fullout]）と A2 の音楽は、同期した 2.0s–2.5s の半サイン波フェードアウト（afade=t=out:st=<TOTAL_DUR - FADE_DUR>:d=<FADE_DUR>:curve=hsin）を実行し、すべてのオーディオ（音楽、カメラノイズ、SFX テール）が最終フレームまたはそれ以前に完全な無音（-infinity dB）に達するようにする。.fcproj では、トラック A2 は EndAtCut オーディオフェードトランジション（from: Some(clip.id), to: None, align: "EndAtCut"）を必ず保持する。サウンドが突然途切れてはならない。
   • マルチ言語字幕トラックを caption_tracks (C1) に書き込み、enabled: false を設定（burnCaptions: false デフォルト）。

3. ヘッドレスバッチフォールバック (assemble_engine.py)

FilmCraft GUI が動作していないかブリッジモードがオフラインの場合、自動的に assemble_engine.py を介して .fcproj を 1 秒未満でアセンブルし、filmcraft-cli で 4K マスター MP4 をレンダリングします。

• リポジトリ衛生ルール： .agents/skills/assemble-timeline/scripts/ は、ユニバーサルでプロジェクトに依存しないエンジン（assemble_engine.py, gpx_widgets.py, generate_voiceover.py, check_filmcraft_env.py）のみを厳密に保持すること。特定のプロジェクト用のカスタムまたはプロジェクト固有のアセンブリスクリプトを作成する場合は、常にそのプロジェクトの git 無視カタログフォルダ（04_Project_Catalog/YEAR/<project_name>/）内に保存し、決して .agents/skills/ 内には保存しない。

4. ビジュアル検証とマスターレンダリング

1. 3つのタイムスタンプ（Act 1 イントロ、中間、エピローグ）で render_frame を呼び出し、フレーミングを確認。
2. マスター 4K MP4 を ~/Movies/Exports/YEAR/<project_name>.mp4 にレンダリング。
3. 多言語版が要求された場合（option_b）、_UA.mp4 および _RU.mp4 のローカライズステムでリマックス。

オプション B: DaVinci Resolve Studio MCP 実行 (davinci-resolve)

1. 新しいタイムラインを作成（1920x1080 または 3840x2160、29.97 fps、DaVinci YRGB Color Managed Rec.709）。
2. 選択したメディアを media_pool 経由で Selects ビンにインポートし、timeline_edit でクリップを V1/V2/A1 に、音楽を A2 に追加。transitions で Cross Dissolve トランジションを適用。keyframes で Ken Burns ズームキーフレームを設定。audio / inspector でオーディオダッキングを設定。
3. export_still を3つのタイムスタンプで呼び出し、カットを視覚検証。.drp/.drt バックアップを 04_Project_Catalog/YEAR/<project_name>/ にエクスポート。render を介して最終 .mp4 レンダリングを ~/Movies/Exports/YEAR/ にキューイング。