Communitygithub.com

Craft Music Video(FilmCraft + EffectCraft)

エージェントがミュージックビデオを企画、制作、または編集する方法を示します。具体的な出力は、エージェントがショットごとに説明できる動画です。この手順は、Craft Music Video(FilmCraft + EffectCraft)を通して進みます。新しいアサインメントでこの技術が必要になったときに使用します。

Craft Music Video(FilmCraft + EffectCraft) とは?

このスキルは、AIエージェントがミュージックビデオを制作するための完全なワークフローを提供します。**EffectCraft**(2Dシーン、モーショングラフィックス、VFX、独立したアルファチャンネル付き歌詞レイヤーの作成)と**FilmCraft**(マルチトラック編集、リズム同期、オーディオミックス/マスタリング、カラーグレーディング、歌詞あり/なしの二重書き出し)を組み合わせます。2Dアニメーションの共通ルールは、別のスキル[craft-2d-animation]に従います。MCPサーバー`effectcraft`と`filmcraft`の存在確認、Flatpak環境でのファイルシステムアクセス設定、GUIとヘッドレスモードの競合回避などの前提条件を最初にチェックします。次に、オーディオ解析(44.1kHz、`audio_cues.py`)、編集可能な`lyrics_timing.json`による歌詞タイミングの管理、EffectCraftでのシーンと歌詞レイヤーの作成(ProRes 4444 RGBA)、FilmCraftでのアセンブルと二重書き出し(歌詞あり/なし)を実行します。最終監査では、音声ありとなしの両方で確認し、`uncertain`フラグが付いたタイミングポイントを明示します。このワークフローは、Craft Videoスイートの一部として、T3 Code環境で利用可能な共有ツール(`audio_cues.py`、`lyrics_overlay.py`、`assemble_filmcraft.py`、`render_ec_batch.sh`)に依存しています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NelaBDV/craft-video-kit/tree/HEAD/skills/craft-music-video

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Craft Music Video(FilmCraft + EffectCraft) は何をしますか?

オーディオトラックに同期したミュージックビデオを、EffectCraft(2Dシーン、モーショングラフィックス、VFX、独立したアルファチャンネル付き歌詞レイヤー)とFilmCraft(メイン編集、マルチトラック、リズム同期、オーディオミックス/マスタリング、グローバルカラーグレーディング、歌詞あり/なしの二重書き出し)を組み合わせて生成するための再利用可能なワークフローです。

共通の2Dアニメーション手法(フレーミング、アンティシペーションを伴うポーズ変更、キャラクター/カメラアンカー、EffectCraftのペアレンティングの落とし穴、重ね順とテキストの可読性)については、craft-2d-animation に従ってください。

MCPの完全なリファレンス、検証済みエンジンコマンド、Flatpak設定については、references/mcp-and-commands.md を参照してください。


0. MCPとサンドボックスの前提条件(開始前に確認すること)

  1. 現在のセッションでeffectcraftおよびfilmcraft MCPサーバーが公開されていることを確認します(または、適切にCLI effectcraft-cli / filmcraft-cli に切り替えます)。
    • サーバーがない場合は、呼び出しを自作せず、正確な設定(Flatpak Linux ai.storyteller.filmcraft / ai.storyteller.effectcraft、ネイティブバイナリ、ヘッドレスモードまたはブリッジモード)について references/mcp-and-commands.md を参照してください。
  2. Flatpak(Linux)の注意:デフォルトでは、ai.storyteller.effectcraft は xdg-documents、xdg-pictures、xdg-videos にのみアクセスできます。プロジェクトが別の場所にある場合(例:~/.t3/projects/...)、--filesystem=<プロジェクトルート> を渡すか、オーバーライドを設定します: flatpak override --user --filesystem=home ai.storyteller.effectcraft
  3. 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.audioToKeyframesmarkers.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)。
  • EffectCraft からの不透明なビジュアルシーン(V1):
    • format: "prores"、proresProfile: "hq"、channels: "rgb"、audio: "off"。
  • FilmCraft からの最終納品:
    • Web/配信:format: "h264"(.mp4、プリセット "High Quality 1080p HD")。
    • マスターアーカイブ:format: "prores"。

解像度、フレームレート(FPS)、カラースペースの整合

  1. 最初に EffectCraft(comp.new)と FilmCraft(file.newSequence)で共有する一意の組み合わせ (width, height, fps) を固定します。例:1920×1080、30 または 24 fps。
  2. フレーム単位でセクションを揃える:各セクションの境界をフレームの整数値(f0 / fps .. f1 / fps)で計算し、セクションの合計がオーディオトラックの実際の長さを正確にカバーし、ずれやギャップが生じないようにします。
  3. カラースペース:両方のソフトウェアでSDRの workingSpace: "rec709" を使用します(EffectCraftの file.projectSettings、FilmCraftの sequence.colorSettings)。HDR/Logの場合は autoToneMap: true。
  4. 時間変換:EffectCraftは秒(f64)で動作します。FilmCraftはティック(254016000000 ティック = 1 秒)を使用し、timeline.place では frame / seconds も受け入れます。

3. 主要な音楽的手法(聴覚によるタイミング、編集可能なタイミング、独立した歌詞とインストゥルメンタル)

A. 聴覚によるタイミングとマスターオーディオの正確な終了点の測定

  1. 常に audio_cues.py analyze を使用して、44.1 kHz(hop = 441 = 正確に10,000 ms)でオリジナルトラックを測定します。22.05 kHzの丸められたステップは使用しないでください。3分間で数百ミリ秒のずれが生じます。
  2. MP3/WAVで正確な終了点を確認してから編集を確定します:最後の強いアクセント、最後のドラム/楽器のヒット(例:ブラックカット)、最終的な残響が実際にフェードアウトするまでの実際の終了点を特定します。
  3. 実際にトラックをセクションごとに聴く:曲を重複するセクションに分割し(例: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)と二重書き出し(マスター/クリーン)

  1. 恒久的な黒帯はなし:craft-2d-animation §5 に従い、各フレーズをショットの空きスペースに配置します。ソフトなドロップシャドウ、セーフマージン、および display_end_ms がセクションカットをまたぐ場合の自動継続(isContIn / isContOut)を適用します。
  2. 専用の透明トラック:歌詞を別のコンポジション L01..Lnn(純粋にインストゥルメンタルなセクションは省略)で生成し、ProRes 4444 RGBA でレンダリングし、FilmCraft の V2 に配置します。
  3. V1 のシーン内テキストは保持:看板、画面、コピー、ボードなどは V01..Vnn シーンに残します。
  4. 厳密に同一の二重書き出し:歌詞ありバージョン(V2 有効)を書き出し、その後 V2 を無効にして(timeline.setTrack {"track": "V2", "enabled": false})、編集とオーディオが100%同一のクリーンバージョンを書き出し、最後に .fcproj を保存する前に V2 を再度有効にします。

D. インストゥルメンタル部分での視覚的なアクション(汎用的なオーディオ波形カーブは禁止)

  1. 汎用的な視覚的な安易な手法は禁止:イントロ、ソロ、インタールードでのオーディオ波形、オシロスコープのジグザグ、装飾的な浮遊円は使用しません。
  2. 耳で選んだアクセントに合わせた描画アクションを振り付ける:ドアがバタンと閉まる、一連の天井照明が1つずつ点灯する、リフに合わせて背景が段ボール/紙の3Dに展開する、オブジェクトがスライドする、またはキャラクターがアンティシペーションとホールドを伴ってポーズを変える。
  3. アクセントの間のショットを保持する:2つのビートの間に明確で安定した画像を残し、アクションが読み取れるようにします。
  4. 共通の2Dルールを適用:バラエティに富んだフレーミング(ワイド / OTS / プロフィール / クローズアップ)、完全なシルエット、変換前の中立アンカー階層(craft-2d-animation 参照)。

4. ステップバイステップのワークフロー

ステップ 1 — 聴覚によるオーディオ解析とタイミングスケルトン

  1. 44.1 kHz で audio_cues.py analyze を使用してマスターを分析し、正確な長さ、10 ms のトランジェント、トラックエンドの詳細を取得します。
  2. audio_cues.py slice でリスニングクリップを抽出し、それらを聴いて正確な BPM、フレームに揃えられたセクション境界、フレーズ、エコー、最終カットを確定します。
  3. audio/lyrics_timing.json を初期化して入力し、疑わしい基準点に "uncertain": true + "review_note" をマークし、JSON を検証します(lyrics_overlay.py --validate)。

ステップ 2 — ショット分割 / 簡易ストーリーボード(大規模レンダリングの前)

  1. 簡易編集プラン(時間 / セクション / 場所とフレーミング / 描画されたビジュアルアクション / 歌詞の処理)を作成します。
  2. 分割(およびインストゥルメンタルパッセージのアクセント選択)をユーザーに提示してから、完全なレンダリングを開始します。

ステップ 3 — EffectCraft でのシーン(V01..Vnn)と歌詞(L01..Lnn)の作成

  1. craft-2d-animation のアンカー、ニュートラルペアレンティング、重ね順のルールに従って 2D シーン(V01..Vnn)を構築します(ec_runtime.py を使用)。
  2. audio/lyrics_timing.json から lyrics_overlay.py を使用して、透明な歌詞コンポジション(L01..Lnn、インストゥルメンタルは除く)を直接生成します。
  3. クイックチェック用に PNG キャプチャ(render-frame --max-side 960) をキーショットで取得し(歌詞には --transparent)、ビデオレンダリングの前にオーバーラップやアンカーのずれをすぐに修正します。
  4. 短い MP4 プレビューを音声付きで(例:サビ 1 つ + ソロ 1 つ):これらの 1~2 セクションのみをレンダリングし、マスターオーディオの正確なクリップとマルチプレックスし、それらを見て聴くことで、必要に応じてエコーのエントリー、ショット間の最後の単語の保持、ソロの可読性を調整します。
  5. 低消費電力の完全レンダリングを ./renders_vfx/ に render_ec_batch.sh を使用して行います(一度に 1 レンダリングずつ順次、V* は ProRes HQ RGB、L* は ProRes 4444 RGBA、ffprobe による自動再開)。
  6. projects/<clip>.ecproj を保存します。

ステップ 4 — FilmCraft でのアセンブルと二重書き出し

  1. 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)
  2. シーケンスを確認します(inspect sequence)+ いくつかのフレームを V1+V2 と V1 単体でレンダリングし、アルファの抜きとクリーンバージョンでのダイジェティックテキストの存在を確認します。
  3. 歌詞ありバージョン(*_lyrics.mp4)を書き出し、V2 を無効にし、クリーンバージョン(*_clean.mp4)を書き出し、その後 V2 を再度有効にして projects/<clip>.fcproj を保存します。

ステップ 5 — 最終必須監査(音声あり + 音声なし)

  1. 音声ありで *_lyrics.mp4 の書き出しを確認:フレーズの終わり、サビのカット、エコーの入り、正確なブラックカット、オリジナルオーディオトラックの適切な終了をチェックします。
  2. 音声なし(ミュート) でインストゥルメンタルパッセージ(ソロ、インタールード)を *_clean.mp4 から確認:キャラクターの意図と視覚的な進行が音声なしで100%理解可能であり、残存するオーディオ波形カーブがなく、シーン内テキストがそのままであることを確認します。
  3. 納品物を提示し、lyrics_timing.json で "uncertain": true とマークされた基準点を明示的にリストアップします。

5. T3 コード共有ツールと依存関係

再利用可能なツールは ~/.t3/shared/craft-video/ にあります:

ツールパスミュージックビデオでの用途
44.1 kHz オーディオ解析&スライス~/.t3/shared/craft-video/audio_cues.pyanalyze で正確な長さ、トランジェント、エンドの詳細を取得。slice で重複するクリップを抽出して聴覚確認。
歌詞オーバーレイ生成~/.t3/shared/craft-video/lyrics_overlay.pyaudio/lyrics_timing.json から EffectCraft コンポジション L* を生成。--validate でタイミングファイルを検証、--preview で PNG キャプチャ。
FilmCraft アセンブル~/.t3/shared/craft-video/assemble_filmcraft.pyMCP 呼び出しを使用して .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-animationEffectCraft の下にあるすべての2Dシーン作成の親ルール。アンカー、ポーズ、ペアレンティング、テキスト可読性。
craft-film-editingFilmCraft 内でのトランジション、タイミング、トリミング、エフェクト、一般的な編集に関するもの。
craft-motion-designEffectCraft のキネティックタイポグラフィ、グラフィックモーション、より複雑なコンポジション。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル