EffectCraft モーションキット

EffectCraftで60秒のコーポレートモーショングラフィックスを作成するためのテスト済みワークフローです。デザインされたように見え、同期が取れており、古典的なバグ（シーン間の空フレーム、重複する音声行、装飾で隠されたテキスト、消える数字、リズムから外れた効果音）がないことを保証します。

デザインは、見た目とレイアウトから生まれます。ゼロから作るものではありません。 テスト済みの5つのルックから1つを選び、各シーンを1つのscene()呼び出しとして、コンテンツと単語タイミングを指定して記述します。レイアウトがサイズ、グリッド、色、モーションを処理します。スタイルを発明するエージェントは、暗いグラデーション、グロウブロブ、小さな中央揃えテキストになってしまい、これが生成されたプロモーションが安っぽく見える最大の理由です。

どのエージェントでも使用できます。 すべてシェルから実行されます（effectcraft-cli を scripts/ec.py 経由で）。MCPはオプションです。キットの場所：このファイルを含むフォルダ（$KIT と呼びます）。

このキットの対象外： 棒人間/キャラクターストーリービデオ（「間違った方法 vs 正しい方法」の分割画面）には、代わりに stick-figure-story スキルを使用してください。

黄金律（理由は references/ にあります）

時間は推測ではなくデータから得ます。 シーンプランは timeline.json にあります。シーンスクリプトは SC("s3") と W("s3", "word")（単語が話される絶対時間）を使用します。23.6 のような時間を直接入力しないでください。
構築するすべてのシーンを見てください。 プレビューフレームをレンダリングし（ec.py frames）、PNGを開きます。エラーなしで実行されるコードでも、レンダリングが間違っている可能性があります。
「完了」とはゲートを通過したことを意味します。 timeline.py check で FAIL が0、ec.py qa で FAIL が0、ec.py qa-video で FAIL が0であり、コンタクトシートを確認していること。結果は警告も含めて正直に報告してください。
ルックとレイアウトを使用します（references/looks.md）。2つのルックを比較してから選択してください。少なくとも3分の1のシーンはビジュアル（電話/アイコン/フロー/バー、またはオブジェクトを含むカスタムシーン）でなければなりません。カスタムシーンコードは、どのレイアウトでもカバーできないもの（地図、製品モックアップ）のためのものであり、それでもルックのパレット P(S.bg) とタイプサイズ LOOK.type を使用します。
EffectCraftスクリプトを書く前に references/pitfalls.md を読んでください。シーンをデザインする前に references/motion-design.md、references/looks.md、references/techniques.md（ビートグリッド、ピークアラインされたSFX、連続モーフ、禁止リスト）を読んでください。
ブランドはあなたが編集するものではありません（references/brand.md）。実際のロゴファイルを表示し、ワードマークとしてタイプした名前を決して表示しないでください。タグラインは1文字ずつそのまま書いてください。製品名、ボタンラベル、統計を発明しないでください。timeline.json の "brand" ブロックに入力して、ec.py qa がこれをチェックできるようにしてください。
QAを通過することは、良いデザインと同じではありません。 シーンを書く前に、カラースクリプト、ビジュアル、印象的な瞬間を計画し、レンダリング前にクリエイティブディレクターレビューでフィルムを評価してください（references/design-review.md、references/benchmark_sheet.png と比較）。 7b. 実際の製品UI（SaaS、アプリフィルム）：references/ui-footage.md に従ってください。サンプルデータのみをキャプチャし、1つのパネルにトリミングし、読み取り可能なサイズ（幅55%以上）で表示するか、アニメーションUIとして再構築し、1ショットに1画面、色あせたサムネイルの壁は避け、数字を発明せず、QAゲートが実行されるようにここで構築してください。
ハイエナジー/超動的広告（TikTokスタイル、話されたすべての単語にスラムを合わせる）：落ち着いたレイアウトの代わりに references/high-energy.md と templates/hyper.jsx に従ってください。
計画した内容ではなく、レンダリングが表示する内容を報告してください。 レポートや引き継ぎを書く前に、最終MP4（プレビューではない）から各シーンの中間点と最後の0.5秒のフレームを取得し、すべての主張を確認してください。各行が読むのに十分な長さ画面に表示されているか、描かれたすべてのステップが実際に見えるか、スクリーンショットが読み取れるか、長さがブリーフとファイル名に一致しているか。すべての音声トランスクリプトをスクリプトと照合し、ブランド名を聴いてください。テストでは、エージェントの引き継ぎは4つの図のステップ、3つの約束、「BridgeAxis Technologies」を説明しましたが、フィルムでは最後のステップがカットの0.3秒前、約束は0.5秒間、読めないスクリーンショット、「Bridge Access」という音声が表示されました。timeline.py check と ec.py qa は現在、読めない音声の間違いや min_read 秒未満しか読めないテキストについて警告します。それらの警告を修正し、説明でごまかさないでください。エージェントが利用可能な最高の推論設定で実行してください。ずさんな実行は「低」設定で行われました。

プロジェクトレイアウト

<project>/
  timeline.json        シーンプラン + SFXキュー + 音楽（$KIT/templates/timeline.example.json から開始）
  audio_meta.json      音声ファイル + 単語タイムスタンプ（オーディオステップから）
  soundtrack.wav       timeline.py mix によって生成
  assets/voice|sfx|bgm|icons|fonts
  scripts/lib.jsx      $KIT/templates/lib.jsx のコピー（COMPを設定；ルックが色とフォントを提供）
  scripts/look.jsx     `ec.py look NAME --accent HEX` によって書き込まれる
  scripts/timing.jsx   生成される（timeline.py emit）- 決して編集しない
  scripts/wipes.jsx    生成される（timeline.py emit）- 最後に実行
  scripts/reset.jsx, s1.jsx ... s8.jsx
  qa/                  プレビューとコンタクトシート

すべてのコマンドは <project>/ から実行してください。ec.py はプロジェクトパスとコンポ名を timeline.json から読み取ります。

ワークフロー A：新しい動画

0. ブリーフィング。 構築する前に尋ねること：一致させるブランド/ウェブサイト、雰囲気（派手/落ち着いている/技術的/高級）、長さとアスペクト比、声（性別/トーン）、音楽/SFXの要不要。クリエイティブな方向性を推測することは、最初のカットが却下される最も一般的な理由です。

1. セットアップ

mkdir -p <project>/{scripts,assets/{voice,sfx,bgm,icons},qa} && cd <project>
cp $KIT/templates/lib.jsx $KIT/templates/reset.jsx $KIT/templates/s1.jsx scripts/
cp $KIT/templates/timeline.example.json timeline.json   # プロジェクト/コンポ/出力名を編集
python3 $KIT/scripts/ec.py fonts                         # ルックのフォントをインストール（マシンごとに1回）

scripts/lib.jsx の COMP をタイムラインのコンポ名に設定します。ブランドのアクセントカラー（ロゴ、ウェブサイトCSS、製品）に注意してください。ブランドにウェブサイトがある場合、そのCSSからアクセントとフォントを読み取ってください。ロゴファイルを assets/logo/ に配置し、timeline.json の "brand" ブロックに名前、正確なタグライン、ロゴファイル、承認された製品名やURLを記入します（references/brand.md）。

2. スクリプトと音声。 8行を書きます（フック、問題、ブランド、2〜3のメリット、証明、エンドカード）。60秒で約110〜130の話し言葉が収まります。行ごとに1つのオーディオファイルを生成し、単語タイムスタンプを以下の形式で audio_meta.json に取得します。

{"voices": [{"id": "s1", "path": "assets/voice/s1.wav", "duration_s": 6.45,
             "words": [{"word": "Every", "start": 0.30, "end": 0.59}, ...]}]}

最初に python3 $KIT/scripts/ec.py doctor を実行します。 このマシンが何を持っているか、不足しているものをインストールする方法を一覧表示します。ready と表示されたら、代替案（edge-tts、Whisper、piper、Playwright）を調査またはインストールしないでください。以下のツールがテスト済みのものです。音声がまったくない場合は、単語の代わりに "in+0.5" オフセットを使用してシーンをタイミング調整します。$KIT/demo/ は完全な無音の例です（ec.py demo でレンダリングされます）。

音声（デフォルト）：ローカル Kokoro、女性音声 af_heart。無料、アカウント不要。モデルは ~/.cache/hyperframes/tts/ にキャッシュされます（初回実行時に1回ダウンロード）：
```
export HYPERFRAMES_PYTHON=~/.venvs/kokoro/bin/python   # 必須：kokoro-onnx を持つvenv
npx hyperframes tts "Line one text." -v af_heart -o assets/voice/s1.wav   # 行ごとに1ファイル
```
HYPERFRAMES_PYTHON がないと、「kokoro-onnx パッケージがインストールされていません」というエラーで失敗します。何も pipインストールしないでください：変数を設定してください。
単語タイムスタンプ：npx hyperframes transcribe assets/voice/s1.wav --json。 Parakeet モデルを使用します。初回実行後 ~/.cache/hyperframes/parakeet にキャッシュされます（エンジン auto がそれを選択します）。Parakeet は Kokoro のようなクリーンなTTS音声に適しています。ここでは -e whisper を渡さないでください。hyperframes の Whisper エンジン（whisper.cpp）はセットアップされていません。アクセントのある実際の録音音声の場合、フッテージ編集スキルは代わりに faster-whisper large-v3-turbo（~/.venvs/asr）を使用します。単語とその開始時間と終了時間を audio_meta.json にコピーします。
音楽とSFX：メディア利用オーディオエンジン（node <skills>/media-use/audio/scripts/audio.mjs --request audio_request.json --out audio_meta.json --only bgm,sfx）。HeyGenカタログから説明文で取得します。例："bgm": {"mode": "retrieve", "query": "warm calm piano"}。<skills> は Claude Codeでは ~/.claude/skills、Codex/OpenCode/DeepSeekでは ~/.agents/skills です。
HeyGenテキスト読み上げ（エンジンまたは heygen CLI経由）は代替音声ですが、無料枠がなくなります。その場合はKokoroを使用してください。音楽とSFXの取得も、HEYGEN_API_BASE が設定されていない限り、heygen CLIへのサインインが必要です（heygen auth login --oauth）。これがない場合、sfx は media-use のバンドルライブラリから応答し、ユーザーは独自の音楽ファイルを提供できます。

実際に使用したプロバイダーと音声を書き留めてください。

3. タイムライン

python3 $KIT/scripts/timeline.py beats      # 音楽テンポ、ビート、バーの開始、ドロップ -> beats.json（"music" が必要）
python3 $KIT/scripts/timeline.py suggest    # シーンのイン/アウト + voice_at を提案；beats.json がある場合、シーンはビートで終了
# timeline.json に貼り付け、各シーンの "bg"（light/dark/accent）を設定し、単語に固定されたSFXキューを追加
python3 $KIT/scripts/timeline.py words      # 絶対時間を持つすべての単語
python3 $KIT/scripts/timeline.py check      # FAILが0であること必須
python3 $KIT/scripts/timeline.py emit       # scripts/timing.jsx + scripts/wipes.jsx を書き込む
python3 $KIT/scripts/timeline.py mix        # soundtrack.wav を書き込む（-14 LUFS）

ビートに合わせてカットします。timeline.py snap は、音声がまだ収まる場所で既存のカットをビートに移動します。シーン内では、BEAT(n)、DOWNBEAT(n)、nearBeat(t)、T.drop が音楽に合わせて時間の衝撃とポップを提供します（references/techniques.md）。SFXの "at" は、数値、"beat:12"、"downbeat:3"、"drop"、"s2:late"（s2の音声の単語 "late"；"s2:the#2" = 2番目の "the"）、"wipe:s3"（s3へのトランジション）、"in:s3" または "out:s3" にできます。"offset"、"vol"、"max"（トリム長）、"align": "peak"（音の最も大きな瞬間がアンカーに来るようにする：インパクトとポップに使用）を追加します。

4. 計画を立て、シーンを書きます。 最初に計画を qa/design_review.md に書きます（references/design-review.md、パート1-6）：各シーンに1行のカラースクリプト、各行が何を言っているかを示すビジュアル、各シーンのヒーロー、そして1つの印象的な瞬間。timeline.json の各シーンに背景を設定し（"bg": "light" | "dark" | "accent"）、timeline.py emit を再実行します。各カットが新しい章として読まれるように交互に設定します。1〜2の最も派手な瞬間、通常は感情的なピークに "accent" を使用します。ブランドの公開とエンドカードは、実際のロゴが最もよく読める背景（通常は明るい背景）に配置し、アクセントには配置しないでください。次に scripts/s1.jsx ... sN.jsx を書き、それぞれをレイアウトを使用した scene() 呼び出しにします（仕様：templates/layouts.jsx の上部；ガイド：references/looks.md）：

// scripts/s2.jsx
scene("s2", "list", { label: "問題",
  items: [["到着が遅れる。", "late"], ["税関の驚き。", "customs"], ["何も教えてくれない追跡。", "tracking", "nothing"]],
  punch: ["手遅れ。", "too"] });

*word* は行のアクセント部分を示します。時間は timeline.py words からの単語です（"word"、"word#2"、"word+0.3"、"in+0.2"）。句読点なしで書きます。レイアウトはフレームに収まるようにテキストを拡大または縮小するので、希望するコピーを書き、レイアウトにサイズ設定を任せてください。画面上の行は短く保ってください。それらは見出しであり、ナレーションではありません。どのレイアウトでもカバーできないもの（地図、製品モックアップ）の場合のみ、代わりに $KIT/templates/scene_template.jsx をコピーします。

少なくとも3分の1のシーンをビジュアルにしてください。 背景に単語だけのフィルムは、タイポグラフィがどんなに優れていても、スライドデッキのように読まれます。ビジュアルレイアウトは、音声が話しているオブジェクトを画面に配置します：phone（電話画面に製品：支払いランディング、注文、追跡更新）、icons（ラベル付きの2〜4の描かれたピクトグラム）、flow（話されるにつれて埋まる線で結ばれた停止：顧客→電話→銀行、倉庫→港→ドア）、bars（成長する2〜4のバー：手数料、待ち時間、前後）。音声が主張ではなく、物やプロセスを説明しているシーンを選んでください。

scene("s4", "flow", { label: "仕組み", title: ["*同日*に銀行入金。", "money", "same"],
  nodes: [{ icon: "shop", label: "あなたが販売", at: "sell" }, { icon: "phone", label: "Tapnest", at: "app" },
          { icon: "bank", label: "あなたの口座", at: "account", note: "同日" }] });

アイコンはキットによって描画されます（ファイルなし）：phone card bank cash clock check tick shop bolt chart truck box pin lock user people chat globe send star plane doc。カスタムビジュアルシーンも、その画像/オブジェクトレイヤー名に "VIS" が含まれている場合にカウントされます（例："s5 VIS map"）。ec.py qa は、3分の1未満のシーンがビジュアルである場合に警告します。 layouts.jsx をプロジェクトにコピーしないでください。ec.py はキットからそれをロードし、コピーすると古いバージョンが固定されてしまいます。

5. ルックを選びます（最初に references/looks.md を読んでください）。ブランドに異なる方法で適合する2つのルックを絞り込み、ブランドからアクセントを取得し、自分のシーンでそれらを比較します：

python3 $KIT/scripts/ec.py new
python3 $KIT/scripts/ec.py import soundtrack.wav assets/icons/*.png
python3 $KIT/scripts/ec.py compare editorial swiss --accent FF5B1F   # -> qa/look_compare.png: 開く
python3 $KIT/scripts/ec.py look editorial --accent FF5B1F             # 勝者を適用

6. 構築とプレビュー

python3 $KIT/scripts/ec.py run s1 s2 s3 s4 s5 s6 s7 s8 wipes   # s1 がコンポ+サウンドトラックを作成
python3 $KIT/scripts/ec.py frames 2 4 6.5                      # qa/frames.png を開いて確認

すべてのシーンの2〜3の瞬間をプレビューします。1つのシーンを修正するには、編集して ec.py rebuild sN を実行します（そのシーンのみをクリアし、再構築し、ワイプを再実行します）。すべてを再構築するには（例：ルック変更後）：ec.py run reset s1 ... sN wipes。ルックがトランジションを提供します。それを置き換えるには、「GENERATED」ヘッダー行なしで独自の scripts/wipes.jsx を書きます（emit はそれを残します）。

...[元のテキストが切り詰められています]

akdavid4real/effectcraft-motion

effectcraft-motion とは？

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

ドキュメント

EffectCraft モーションキット

黄金律（理由は references/ にあります）

プロジェクトレイアウト

ワークフロー A：新しい動画

関連スキル

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code