Craft Music Video(FilmCraft + EffectCraft) は何をしますか?
オーディオトラックに同期したミュージックビデオを、EffectCraft(2Dシーン、モーショングラフィックス、VFX、独立したアルファチャンネル付き歌詞レイヤー)とFilmCraft(メイン編集、マルチトラック、リズム同期、オーディオミックス/マスタリング、グローバルカラーグレーディング、歌詞あり/なしの二重書き出し)を組み合わせて生成するための再利用可能なワークフローです。
共通の2Dアニメーション手法(フレーミング、アンティシペーションを伴うポーズ変更、キャラクター/カメラアンカー、EffectCraftのペアレンティングの落とし穴、重ね順とテキストの可読性)については、craft-2d-animation に従ってください。
MCPの完全なリファレンス、検証済みエンジンコマンド、Flatpak設定については、references/mcp-and-commands.md を参照してください。
0. MCPとサンドボックスの前提条件(開始前に確認すること)
- 現在のセッションで
effectcraftおよびfilmcraftMCPサーバーが公開されていることを確認します(または、適切にCLIeffectcraft-cli/filmcraft-cliに切り替えます)。- サーバーがない場合は、呼び出しを自作せず、正確な設定(Flatpak Linux
ai.storyteller.filmcraft/ai.storyteller.effectcraft、ネイティブバイナリ、ヘッドレスモードまたはブリッジモード)について references/mcp-and-commands.md を参照してください。
- サーバーがない場合は、呼び出しを自作せず、正確な設定(Flatpak Linux
- Flatpak(Linux)の注意:デフォルトでは、
ai.storyteller.effectcraftはxdg-documents、xdg-pictures、xdg-videosにのみアクセスできます。プロジェクトが別の場所にある場合(例:~/.t3/projects/...)、--filesystem=<プロジェクトルート>を渡すか、オーバーライドを設定します:flatpak override --user --filesystem=home ai.storyteller.effectcraft - GUIとヘッドレスの競合:同じ
.ecprojまたは.fcprojファイルを、グラフィカルアプリケーションとMCP/CLIヘッドレスモードで同時に開かないでください。開いているウィンドウを制御するには--bridgeを使用します。
1. 役割分担:EffectCraft vs FilmCraft
| 領域 | EffectCraft (.ecproj) | FilmCraft (.fcproj) |
|---|---|---|
| 主な用途 | アニメーション2Dシーン(V01..Vnn)、独立した透明レイヤー上の歌詞(L01..Lnn)、キネティックタイトル、パーティクル、2D/3Dコンポジット | マルチトラックメイン編集(V1シーン + V2歌詞RGBA + A1マスターオーディオ)、フレーム単位の同期、トランジション、グローバルカラーグレーディング、二重書き出し(歌詞あり + クリーン) |
| 作成 | comp.new、layer.newText、layer.newShape、layer.newSolid、layer.newAdjustment、add_effect、JSXスクリプト(ec_runtime.py) | file.newSequence、timeline.place、timeline.setTrack、timeline.razor、timeline.trim、timeline.move、clip.speedDuration |
| 音楽同期 | audio/lyrics_timing.json からの正確な基準点 + 聴覚による確認。オプションで、測定されたリアクティブエフェクトが必要な場合のみ keys.audioToKeyframes | markers.add を各セクション、最後のアクセント、ブラックカットに配置。フレーム単位の正確な合わせ込み(frame: f0) |
| スタイリング&カラー | レイヤースタイル、マスク、ベジェ、グロー、ドロップシャドウ、プリコンポーズ(layer.precompose) | Lumetri Color(lumetri.applyPreset、lumetri.setLook、lumetri.applyMatch)、sequence.colorSettings、sequence.applyVideoTransition |
| オーディオ | 中間レンダリングではオーディオをエクスポートしない(--audio off) | オリジナルマスターオーディオトラックを A1 に配置(デフォルトで 0.0 dB に設定され、元のマスターを保持。essentialSound.* または sequence.normalizeMixTrack は要求があった場合のみ使用) |
2. ファイル交換パイプラインと技術的な一貫性
プロジェクトフォルダの命名規則
<project_root>/
├── audio/ # マスターオーディオトラック (WAV/FLAC/MP3) + lyrics_timing.json(編集可能な単一ソース)
├── footage/ # ビデオリュッシュ、写真、ロゴなど
├── renders_vfx/ # EffectCraft中間レンダリング:V01..Vnn.mov (RGB) + L01..Lnn.mov (RGBA)
├── previews/ # PNGキャプチャ (render-frame) + プレビュー用の短いMP4(サビ、ソロなど、音声付き)
├── projects/ # .ecproj および .fcproj ファイル
├── scripts/ # クリップ固有のジェネレーター(T3 Codeの共有ツールが重要)
└── exports/ # 最終納品物 1080p:*_lyrics.mp4 および *_clean.mp4
互換性のある交換フォーマット
- EffectCraft → FilmCraft への歌詞&オーバーレイ(透明度あり、
V2):- 推奨(単一ファイル):QuickTime Apple ProRes 4444(
.mov)、format: "prores"、proresProfile: "4444"、channels: "rgba"、audio: "off"。 - ロスレス代替:PNG または OpenEXR シーケンス(
channels: "rgba")、FilmCraft にimage_sequence: trueでインポート。 - アルファ禁止:
H264、Hevc、Av1はアルファチャンネルを処理しません(alpha: false)。
- 推奨(単一ファイル):QuickTime Apple ProRes 4444(
- EffectCraft からの不透明なビジュアルシーン(
V1):format: "prores"、proresProfile: "hq"、channels: "rgb"、audio: "off"。
- FilmCraft からの最終納品:
- Web/配信:
format: "h264"(.mp4、プリセット"High Quality 1080p HD")。 - マスターアーカイブ:
format: "prores"。
- Web/配信:
解像度、フレームレート(FPS)、カラースペースの整合
- 最初に EffectCraft(
comp.new)と FilmCraft(file.newSequence)で共有する一意の組み合わせ(width, height, fps)を固定します。例:1920×1080、30または24fps。 - フレーム単位でセクションを揃える:各セクションの境界をフレームの整数値(
f0 / fps .. f1 / fps)で計算し、セクションの合計がオーディオトラックの実際の長さを正確にカバーし、ずれやギャップが生じないようにします。 - カラースペース:両方のソフトウェアでSDRの
workingSpace: "rec709"を使用します(EffectCraftのfile.projectSettings、FilmCraftのsequence.colorSettings)。HDR/Logの場合はautoToneMap: true。 - 時間変換:EffectCraftは秒(
f64)で動作します。FilmCraftはティック(254016000000ティック =1秒)を使用し、timeline.placeではframe/secondsも受け入れます。
3. 主要な音楽的手法(聴覚によるタイミング、編集可能なタイミング、独立した歌詞とインストゥルメンタル)
A. 聴覚によるタイミングとマスターオーディオの正確な終了点の測定
- 常に
audio_cues.py analyzeを使用して、44.1 kHz(hop = 441= 正確に10,000 ms)でオリジナルトラックを測定します。22.05 kHzの丸められたステップは使用しないでください。3分間で数百ミリ秒のずれが生じます。 - MP3/WAVで正確な終了点を確認してから編集を確定します:最後の強いアクセント、最後のドラム/楽器のヒット(例:ブラックカット)、最終的な残響が実際にフェードアウトするまでの実際の終了点を特定します。
- 実際にトラックをセクションごとに聴く:曲を重複するセクションに分割し(例:18秒、2秒のオーバーラップ)、トランジション、サビ、コーラス、フレーズの終わり付近の短いクリップを抽出します(
audio_cues.py slice)。これらを聴いて、正確なBPMと各ボーカルエントリーを実際の耳で確定します。
B. 編集可能な単一タイミングファイル(audio/lyrics_timing.json)と不確かな基準点
すべての歌詞タイミングを、手動で編集可能な単一のJSONファイル(audio/lyrics_timing.json)に集中させ、EffectCraftジェネレーターがこれを読み取ります:
meta:オーディオファイル、オーディオ/ビデオの長さ(ms)、fps、bpm、first_drum_hit_ms、last_accent_ms、black_cut_ms。sections:フレームに揃えられた境界start_ms/end_ms。phrases:start_ms、end_ms、およびdisplay_end_ms(必要に応じて+250~+600 ms延長し、次のショットやセクションが変わっても最後の単語が読み取れるようにします)。type: "lead"はメインボーカル、type: "echo"は別エントリーとして、コーラス、レスポンス、アドリブに使用します。words(単語/グループへの分割)は、アニメーションや視覚的なアクセントが必要な場合のみ含めます。それ以外の場合は、フレーズ全体を適切に表示します。- あいまいな基準点(コーラス、エコー、重なったボーカライズ、短い叫び声)には
"uncertain": true+"review_note": "..."を付け、ユーザーがコードに触れずに簡単に手動で調整できるようにします。
C. 独立したレイヤーの歌詞(V2 RGBA)と二重書き出し(マスター/クリーン)
- 恒久的な黒帯はなし:craft-2d-animation §5 に従い、各フレーズをショットの空きスペースに配置します。ソフトなドロップシャドウ、セーフマージン、および
display_end_msがセクションカットをまたぐ場合の自動継続(isContIn/isContOut)を適用します。 - 専用の透明トラック:歌詞を別のコンポジション
L01..Lnn(純粋にインストゥルメンタルなセクションは省略)で生成し、ProRes 4444 RGBA でレンダリングし、FilmCraft のV2に配置します。 V1のシーン内テキストは保持:看板、画面、コピー、ボードなどはV01..Vnnシーンに残します。- 厳密に同一の二重書き出し:歌詞ありバージョン(
V2有効)を書き出し、その後V2を無効にして(timeline.setTrack {"track": "V2", "enabled": false})、編集とオーディオが100%同一のクリーンバージョンを書き出し、最後に.fcprojを保存する前にV2を再度有効にします。
D. インストゥルメンタル部分での視覚的なアクション(汎用的なオーディオ波形カーブは禁止)
- 汎用的な視覚的な安易な手法は禁止:イントロ、ソロ、インタールードでのオーディオ波形、オシロスコープのジグザグ、装飾的な浮遊円は使用しません。
- 耳で選んだアクセントに合わせた描画アクションを振り付ける:ドアがバタンと閉まる、一連の天井照明が1つずつ点灯する、リフに合わせて背景が段ボール/紙の3Dに展開する、オブジェクトがスライドする、またはキャラクターがアンティシペーションとホールドを伴ってポーズを変える。
- アクセントの間のショットを保持する:2つのビートの間に明確で安定した画像を残し、アクションが読み取れるようにします。
- 共通の2Dルールを適用:バラエティに富んだフレーミング(ワイド / OTS / プロフィール / クローズアップ)、完全なシルエット、変換前の中立アンカー階層(craft-2d-animation 参照)。
4. ステップバイステップのワークフロー
ステップ 1 — 聴覚によるオーディオ解析とタイミングスケルトン
- 44.1 kHz で
audio_cues.py analyzeを使用してマスターを分析し、正確な長さ、10 ms のトランジェント、トラックエンドの詳細を取得します。 audio_cues.py sliceでリスニングクリップを抽出し、それらを聴いて正確な BPM、フレームに揃えられたセクション境界、フレーズ、エコー、最終カットを確定します。audio/lyrics_timing.jsonを初期化して入力し、疑わしい基準点に"uncertain": true+"review_note"をマークし、JSON を検証します(lyrics_overlay.py --validate)。
ステップ 2 — ショット分割 / 簡易ストーリーボード(大規模レンダリングの前)
- 簡易編集プラン(時間 / セクション / 場所とフレーミング / 描画されたビジュアルアクション / 歌詞の処理)を作成します。
- 分割(およびインストゥルメンタルパッセージのアクセント選択)をユーザーに提示してから、完全なレンダリングを開始します。
ステップ 3 — EffectCraft でのシーン(V01..Vnn)と歌詞(L01..Lnn)の作成
- craft-2d-animation のアンカー、ニュートラルペアレンティング、重ね順のルールに従って 2D シーン(
V01..Vnn)を構築します(ec_runtime.pyを使用)。 audio/lyrics_timing.jsonからlyrics_overlay.pyを使用して、透明な歌詞コンポジション(L01..Lnn、インストゥルメンタルは除く)を直接生成します。- クイックチェック用に PNG キャプチャ(
render-frame --max-side 960) をキーショットで取得し(歌詞には--transparent)、ビデオレンダリングの前にオーバーラップやアンカーのずれをすぐに修正します。 - 短い MP4 プレビューを音声付きで(例:サビ 1 つ + ソロ 1 つ):これらの 1~2 セクションのみをレンダリングし、マスターオーディオの正確なクリップとマルチプレックスし、それらを見て聴くことで、必要に応じてエコーのエントリー、ショット間の最後の単語の保持、ソロの可読性を調整します。
- 低消費電力の完全レンダリングを
./renders_vfx/にrender_ec_batch.shを使用して行います(一度に 1 レンダリングずつ順次、V*は ProRes HQ RGB、L*は ProRes 4444 RGBA、ffprobeによる自動再開)。 projects/<clip>.ecprojを保存します。
ステップ 4 — FilmCraft でのアセンブルと二重書き出し
assemble_filmcraft.pyを使用して(または MCP 経由でfile.newProject、file.newSequence、media_import、timeline.place、markers.add)、Rec.709 シーケンスをアセンブルします:A1:オリジナルマスターオーディオそのまま(volumeDb: 0.0)V1:V01..Vnn.movを正確なフレーム位置(frame: f0)に配置V2:L01..Lnn.mov(ProRes 4444 RGBA)を同じ正確なフレーム位置に配置(audio: false)
- シーケンスを確認します(
inspect sequence)+ いくつかのフレームをV1+V2とV1単体でレンダリングし、アルファの抜きとクリーンバージョンでのダイジェティックテキストの存在を確認します。 - 歌詞ありバージョン(
*_lyrics.mp4)を書き出し、V2を無効にし、クリーンバージョン(*_clean.mp4)を書き出し、その後V2を再度有効にしてprojects/<clip>.fcprojを保存します。
ステップ 5 — 最終必須監査(音声あり + 音声なし)
- 音声ありで
*_lyrics.mp4の書き出しを確認:フレーズの終わり、サビのカット、エコーの入り、正確なブラックカット、オリジナルオーディオトラックの適切な終了をチェックします。 - 音声なし(ミュート) でインストゥルメンタルパッセージ(ソロ、インタールード)を
*_clean.mp4から確認:キャラクターの意図と視覚的な進行が音声なしで100%理解可能であり、残存するオーディオ波形カーブがなく、シーン内テキストがそのままであることを確認します。 - 納品物を提示し、
lyrics_timing.jsonで"uncertain": trueとマークされた基準点を明示的にリストアップします。
5. T3 コード共有ツールと依存関係
再利用可能なツールは ~/.t3/shared/craft-video/ にあります:
| ツール | パス | ミュージックビデオでの用途 |
|---|---|---|
| 44.1 kHz オーディオ解析&スライス | ~/.t3/shared/craft-video/audio_cues.py | analyze で正確な長さ、トランジェント、エンドの詳細を取得。slice で重複するクリップを抽出して聴覚確認。 |
| 歌詞オーバーレイ生成 | ~/.t3/shared/craft-video/lyrics_overlay.py | audio/lyrics_timing.json から EffectCraft コンポジション L* を生成。--validate でタイミングファイルを検証、--preview で PNG キャプチャ。 |
| FilmCraft アセンブル | ~/.t3/shared/craft-video/assemble_filmcraft.py | MCP 呼び出しを使用して .fcproj とシーケンス全体を生成:A1、V1、V2、マーカー。 |
| EffectCraft バッチレンダリング | ~/.t3/shared/craft-video/render_ec_batch.sh | 低消費電力で順次レンダリング。PrORES RGB / RGBA、ffprobe による自動再開。 |
T3 コード共有ツールの使用:
from t3.shared import craft_videoで~/.t3/shared/が$PYTHONPATHにあることを前提とします。そうでない場合は、sys.pathを手動で追加します。
6. よくある落とし穴と診断
| 症状 | 原因 | 解決策 |
|---|---|---|
| 書き出しファイルに透明な領域が黒く表示される | コーデックがアルファをサポートしていない | H264、Hevc、Av1 に書き出さない。ProRes 4444 または PNG シーケンスを使用。 |
| 歌詞が2つのショットの間で消える | display_end_ms が設定されていない、または短すぎる | すべてのフレーズに display_end_ms を設定し、必要に応じて +250 ~ +600 ms 延長。 |
| クリーンバージョンにシーン内テキストがない | テキストが誤って L* にある | ダイジェティックテキストを V* シーン内に維持する。L* にはオーバーレイテキストのみ。 |
| オーディオが3分後に200 ms ずれる | 22.05 kHz で解析した | hop = 441(44.1 kHz)で audio_cues.py analyze を再実行。 |
7. 関連クラフト
| クラフト | 関係 |
|---|---|
| craft-2d-animation | EffectCraft の下にあるすべての2Dシーン作成の親ルール。アンカー、ポーズ、ペアレンティング、テキスト可読性。 |
| craft-film-editing | FilmCraft 内でのトランジション、タイミング、トリミング、エフェクト、一般的な編集に関するもの。 |
| craft-motion-design | EffectCraft のキネティックタイポグラフィ、グラフィックモーション、より複雑なコンポジション。 |