Communitygithub.com

4waiz/kanban-motion

コード駆動のモーショングラフィックス動画の作成・編集:プロジェクト、ウェブサイト、スクリプトからローンチ動画、解説動画、プロモ動画を生成。生成または録音したナレーション、BGM、効果音を単語単位で同期。Motion as Code キット(ナレーション同期プレート、プレビュー、静止画、レンダリング、効果音ミックス)またはバンドルされたスターターキットに対応。

kanban-motion とは?

このスキルは、コードベースのモーショングラフィックス動画を制作・編集するための統合ワークフローを提供します。TypeScript/JavaScript で記述された各シーン(プレート)は時間の純粋関数として描画され、生成または録音されたナレーションの単語レベルのタイミングと完全に同期します。高品質な出力(1920x1080, 60fps)を実現し、Claude Code、Cursor、Codex などの AI エージェントプラットフォームとシームレスに連携します。このワークフローは2層構造になっています。第一層は Motion as Code キット(既存プロジェクト向け、three.js + headless Chrome + ffmpeg 使用)、第二層は Kanban Motion 拡張(スターターキット、ナレーション生成、単語整列、ローンチ動画計画、BGM、無料効果音ライブラリ、配信機能を含む)です。ユーザーが既存のキットを持っている場合はそれを使い、そうでなければスターターキットを使います。効果音のミックスはコードで管理され、レンダリング前に静止画で確認し、本番レンダリング前にユーザーの許可を求めるルールが徹底されています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/4waiz/kanban-motion/tree/HEAD/skills/kanban-motion

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

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

ドキュメント

Kanban Motion

Kanban Studios 作。コードとして記述されたモーショングラフィックスを、音声にロックします。このスキルには2つの層があります。

  1. Motion as Code(以下、変更なし):Motion as Code キットの完全なワークフロー。
  2. Kanban Motion 追加機能(その後に続きます):外部プロジェクトを必要としないスターターキット、ナレーション生成と単語整列、ローンチ動画計画(調査、計画、トーン、クリエイティブの原則)、オリジナル BGM、CC0 サウンドライブラリとミキサー、配信(ポスターフレームと共有用コピー)。

ユーザーがキットを持っているか、編集している場合はキットを使用します。それ以外の場合はスターターキットを使用します。両方に同じルールが適用されます:プレートは時間の純粋関数であり、レンダリング前に静止画を確認し、完全なレンダリングの前に許可を求めます。

Motion as Code

コードからモーショングラフィックスを作成し、ナレーションにロックするワークフロー。After Effects は不要です。各シーン(「プレート」)は TypeScript ファイルで、すべてのフレームを時間の純粋関数として描画します。ナレーションの単語レベルのタイミングが、各プレートのアニメーションタイミングを指示します。ブラウザプレビューとエクスポートされた MP4 は同一です。

出力:1920x1080, 60 fps。スタック:TypeScript + three.js、bun + Vite、headless Chrome + ffmpeg。

キットの場所

プロジェクトフォルダは、ユーザーの Documents フォルダ(Windows PC では C:\Users\awaiz\OneDrive\Documents\Motion_as_kit)にある Motion_as_kit です。アクセスできない場合や移動した場合は、ユーザーに場所を尋ねてください。フォルダ構造はそのまま維持してください。スクリプトは相対パスを使用します。

セッションで最初の変更を行う前に、README.md、app/src/timeline.ts、app/src/engine/scene.ts を読んでください。

必要条件(ユーザーのマシン上)

  • bun (bun.sh):パッケージのインストールとスクリプトの実行
  • Google Chrome:レンダラーがヘッドレスで駆動します(BROWSER_CHANNEL を設定、例:msedge、で別のブラウザを使用)
  • libx264 対応の ffmpeg
  • Python + uv:新しいナレーションの再整列または SFX ミックスの再構築にのみ使用。python -m uv で実行

app/node_modules は同梱されていません。最初に app/ 内で bun install を実行してください。

レイアウト

パス役割
audio/voiceover.mp3ナレーション
audio/sfx/28 個の効果音(name_1.mp3、name_2.mp3 は別テイク)
data/lyrics.json単語レベルのタイミング。analysis/align_vo.py(CTC 強制アラインメント、wav2vec2 ONNX)で作成
data/audio.json音声ラウドネスエンベロープ、単語開始点、名目上のビートグリッド。analysis/audio_vo.py で作成
analysis/sfx_mix.pyキューシート(約500キュー)と SFX ミキサー
app/src/engine/pdoom-video エンジン。編集禁止。
app/src/scenes/_vo.ts共有ツールキット:2D カメラ、プロッターペン、ワールド空間のカラオケ単語、方眼紙
app/src/scenes/*.tsプレート
app/src/timeline.ts各プレートの再生タイミング。カットは各行の直前の一時停止に配置
app/scripts/render.tsオフラインレンダラー:ヘッドレス Chrome → 生フレーム → ffmpeg
out/レンダリング出力

同梱デモには9つのプレートがあります:hook、model、prompt、crazy、code、frames、pipeline、edits、verdict(合計 92.6 秒;verdict はフレーム 0 にループバック)。

ルール

  • プレート内のすべては時間の決定論的関数でなければなりません。シードなしの Math.random()、実時間、シークでリセットされない状態は禁止。
  • app/src/engine/ を編集しないでください。
  • ユーザーに事前に尋ねずに完全なレンダリングを実行しないでください。決して 4K レンダリングを実行しないでください。作業確認には静止画を使用してください。
  • 各変更を行う前に、1~2文で説明してください。
  • LICENSE.pdoom-engine をプロジェクトと共に保持してください(エンジンとビジュアルスタイルは mexicat による pdoom-video、MIT ライセンス)。

ワークフロー

1. プレビュー(高速ループ)

cd app
bun install      # 初回のみ
bunx vite        # http://localhost:5173

編集はホットリロードされます。キー:space 再生/一時停止、left/right 1 秒シーク(shift で 5 秒)、, . 1 フレーム進む/戻る、[ ] 前/次のプレート、l プレートをループ、h UI 非表示。URL に ?t=35 を追加すると 35 秒から開始します。

2. 編集時の静止画確認

cd app
bun scripts/render.ts stills --t 12.5,40.2 --only code --out ../out/wip

単一フレームをレンダリングします(ここでは code プレートの 12.5 秒と 40.2 秒)。静止画を確認し、完全なレンダリングを提案する前にユーザーに表示してください。

3. 動画のレンダリング(事前に確認)

cd app
bun run render

以下と同等:bun scripts/render.ts video --samples auto --min-samples 4 --max-samples 12 --shutter 0.5 --crf 17 --out ../out/motion-as-code.mp4。

  • --samples 4:約 4 倍高速なドラフト。速い動きは段階的なコピーとして表示されます
  • --samples auto:動きが速い場所でより多くのサブフレーム(デフォルト)
  • --scale 2:4K(3840x2160)

4. 効果音

再レンダリングは不要:ミックスを再構築し、映像をコピーしてオーディオを追加します。プロジェクトルートから実行。

python -m uv run --no-project --with numpy python analysis/sfx_mix.py
cd out
ffmpeg -i motion-as-code.mp4 -i mix.wav -map 0:v -map 1:a -c:v copy -c:a aac -b:a 320k -shortest motion-as-code_sfx.mp4

効果音はナレーション下で最大 7 dB 抑えられます。ミックスは -14 LUFS にノーマライズされます。効果音のラウドネスを変更するには、キューシート内の db 値を編集します。タイミングを変更するには、時間式を編集します。

5. ナレーションの差し替え

  1. audio/voiceover.mp3 を置き換えます。
  2. analysis/align_vo.py の SCRIPT(および数字や頭字語の SPOKEN)を編集します。
  3. プロジェクトルートから再実行:
python -m uv run --no-project --with onnxruntime --with numpy python analysis/align_vo.py
python -m uv run --no-project --with numpy python analysis/audio_vo.py

プレートは単語を内容で見つけるため(lineOf、wordOf)、同じスクリプトであればすべてのアニメーションが自動的に再タイミングされます。文言が変更された場合は、timeline.ts の cut(...) 呼び出し内のアンカーフレーズを更新し、変更されたものをユーザーに伝えてください。

プレートの作成または変更

プレートは Scene(app/src/engine/scene.ts)を拡張するクラスであり、ファイルのデフォルトエクスポートです。エンジンはフレームごとに render(f, out) を1回呼び出します。引数は次の通りです:

  • f.t 曲の時間、f.lt プレート開始からの経過時間、f.p プレートの進行度 0 から 1
  • f.a その瞬間のオーディオ特徴(音声エンベロープ、ヒットパルス)
  • f.seeked スクラブ後に true。ステートフルなプレートはこれでリセットする必要があります

プレートを追加するには:app/src/scenes/yourplate.ts を作成し、timeline.ts に E('yourplate', 'yourplate', start, end) の行を1つ追加します。開始時間はスクリプトから取得されます:cut('This is Claude') は、その行の最初の単語の 0.18 秒前にカットします。timeline.ts のファイル名は app/src/scenes/ 内のファイルと一致している必要があります。

prompt プレートは app/src/scenes/prompt-data.ts からトークン分解を読み取ります。

新しいプレートを作成する前に、既存のプレートと _vo.ts を学習し、新しいヘルパーを発明するのではなく、ツールキットとパレット(ink、bone、signal orange)を再利用してください。

トラブルシューティング

問題解決策
localhost:5173 で空白ページapp/ で bun install を実行。vite ターミナルのエラーを確認
プレビューで音が出ないspace キーを押す。ブラウザはインタラクションまでオーディオをブロックします。タブがミュートされていないか確認
レンダラーが Chrome を見つけられないChrome をインストールするか、BROWSER_CHANNEL を設定(例:msedge)
ffmpeg が見つからない / libx264 がない完全な ffmpeg ビルドをインストール。新しいターミナルで ffmpeg -version を確認
レンダリングが非常に遅いドラフトには --samples 4。still コマンドで単一プレートをレンダリング
新しいナレーション後にアニメーションがずれる両方の分析スクリプトを再実行。文言が変わった場合は cut(...) フレーズを更新
シーンモジュールが見つからないtimeline.ts のファイル名が app/src/scenes/ 内のファイルと一致している必要がある

Kanban Motion 追加機能

以下はすべて上記の Motion as Code ワークフローに追加されるものであり、置き換えるものではありません。<skill-dir> はこの SKILL.md を含むフォルダです(Claude Code はこれを「このスキルのベースディレクトリ」と表示します)。インストールパスを推測しないでください。

パスの選択

状況実行すること
ユーザーが Motion_as_kit を持っているか、その中のプレート編集、レンダリング、ナレーション差し替えを依頼した場合上記の Motion as Code に従います。ナレーション生成、BGM、ローンチ計画、配信といった追加機能が役立つ場合に使用します。
プロジェクト、ウェブサイト、スクリプト、アイデアからの新しい動画で、キットがない場合以下の スターターキット とローンチワークフローを使用します。
「ローンチ動画を作って」「これを動画にして」「プロモ」など利用可能なキットで ローンチワークフロー(調査、計画、構築、配信)を実行します。

出力はカレントディレクトリの kanban-motion-output/ に、またはそのフォルダが存在する場合はタイムスタンプ付きの kanban-motion-output-YYYY-MM-DD-HHmmss/ に出力されます。内部には:reel/(プレート)、out/(レンダリング、ミックス、静止画)、work/(ダウンロード、スクラッチ)、および plan.md、script.txt、share-copy.txt。

スターターキット

同じアイデアの小型で依存関係のないバージョン:ブラウザ内のプレーンな ES モジュール、ヘッドレス Chrome でキャプチャされたフレーム、ffmpeg でエンコード。必要条件:Node 18+、Chrome または Edge、libx264 対応の ffmpeg、および(オーディオスクリプト用の)uv。マシンごとに1回:npm install --prefix <skill-dir>/scripts。

<skill-dir>/template/ を kanban-motion-output/reel/ にコピーします。最初の変更の前に、reel.js、engine.js、および1つのプレートを読んでください。

パス役割
reel.jsタイムライン:プレートごとに E(plate({...}), start, end)。カットは cut('phrase') で音声から取得
engine.jsプレビュー、シーク、レンダリングフック。編集禁止。
motion.jsツールキット:range、ease、閉形式 spring、シード付き rng/hash、typed、および音声同期 lineOf、wordOf、wordsIn、cut
plates/*.jspaper(音声に合わせて呼吸する方眼紙背景)、say(話されると同時に着地するキネティックワード)、code(タイピングエディター)、shot(ウィンドウ内の実際のスクリーンショット)、outro(名前、ペンの下線、タグライン、URL)。ローンチ動画用:bg(ドリフトするグラデーション)、photo(プッシュ付きのフルサイズ画像、オプションで2番目の画像へのスキャンライン「ターン」)、screen(カメラキーとトラッキングコールアウト付きの実際のUI)、typewrite(文字ごとの見出し)、stats(カウントアップ数字)、steps(音声でライトアップするパイプライン)、cap(話されている行のキャプション)、logo(タグライン、バッジ、URL、クレジット付きロゴ公開)。シネマティックシーケンス用:space(モーフィングするワイヤーフレームソリッド、透視格子、3Dキネティックタイプで構成される3Dシーンを通るシームレスなカメラ移動)
style.cssパレットとタイプトークン(ink、bone、signal orange)。プロジェクトの正確な色とフォントに差し替えます。
audio/、data/、cues.jsonナレーションと音楽。words.json、lines.json、audio.json。サウンドキューシート。テンプレートには3つすべての実動デモが同梱されているため、プレビューとレンダリングはすぐに機能します。画像は assets/ に配置します。

プレートは { name, setup(root), draw(f) } です。draw は f.t(グローバル時間)、f.lt(プレート開始からの時間)、f.p(プレートの進行度 0 から 1)、f.dur、f.env(音声ラウドネス 0 から 1)、f.fps を受け取ります。すべてのビジュアルプロパティは f のみから設定する必要があります:Math.random() は使用不可(代わりに rng(seed) を使用)、実時間も、シークでリセットされない状態も禁止です。E(...) でプレートに tail: 0.4 を指定すると、トランジションのために次のプレートと重ねることができます。

node <skill-dir>/scripts/render.mjs preview --dir reel                         # http://127.0.0.1:5173、キットと同じキー
node <skill-dir>/scripts/render.mjs stills --dir reel --plates --out out/wip   # プレートごとに定常フレーム + カットイン直前のフレーム
node <skill-dir>/scripts/render.mjs stills --dir reel --t 2.4,6.1 --only say --out out/wip
node <skill-dir>/scripts/render.mjs video --dir reel --samples 4 --audio out/mix.wav --out out/reel.mp4   # 最初に確認

レンダリングフラグはキットを反映:--samples(モーションブラーのサブフレーム数、ドラフトは 4、最終版は 8 から 12)、--shutter 0.5、--scale 2(4K、最初に確認)、--crf 17、--from/--to、--fps。Chrome がない場合は BROWSER_CHANNEL=msedge または BROWSER_PATH=... を使用。reel.js で width/height を変更することで、縦型(1080x1920)と正方形(1080x1080)も動作します。その場合はすべてのプレートのレイアウトを静止画で再確認してください。

実際の使用例はリポジトリの examples/ フォルダにあります(5つの実プロジェクト:ナレーション付き横長、ビートカット縦型、ナレーション付き正方形説明動画、2つの3Dシネマティックシーケンス)。新しいリールを作成する前に、リクエストに最も近いものを読んでください。実際のUIを「ものを見せる」素材としてキャプチャします:

  • ライブサイト: ヘッドレス Chrome のスクリーンショットを 2 倍で使用。
  • ユーザーが所有するアプリ: localhost で実行し、アプリのデモまたは「入力」サインインがあればそれを使用。

次に、各スクリーンショットのグリッドコピーから読み取った 0..1 の割合でカメラとコールアウトを設定します。

ナレーション

ユーザーがナレーションやボイスオーバーを要求した場合、または --voice を渡した場合に追加します。詳細は references/voiceover.md にあります。

  1. script.txt を書く:ビートごとに1行。行がカットになります。空白行はより長いポーズを追加します。[pause 0.8] は正確なポーズを追加します。[at 6.0] は次の行を正確な時間に開始し、既存の編集に音声を合わせます。数字や頭字語は話される通りに書きます。ナレーションはビジュアルをそのまま読み上げるのではなく、補足するものにし、シーンのペースに合わせ、会話調で、製品に固有のものにします。1秒あたり約2.5語を目安にします。
  2. 生成する ローカルで動作するオープンウェイト音声モデル Kokoro を使用します。モデルは一度ダウンロードされます(約340 MB)。
    uv run <skill-dir>/scripts/voiceover.py script.txt -o reel/audio/voiceover.wav --lines reel/data/lines.json --voice af_heart
    
    おすすめの音声:af_heart、af_bella、am_michael、am_fenrir、bf_emma、bm_george(--voice af_heart:0.6,af_bella:0.4 でブレンド。--speed で速度調整)。--engine system はダウンロードなしで OS の音声を使用します。ユーザーが自分の声を録音した場合は、reel/audio/voiceover.wav に配置し、この手順をスキップします。
  3. 整列する 単語レベルのタイミングを取得します。faster-whisper の単語タイミングがスクリプトの単語にスナップされ、ステップ2の行境界が正確に固定されます:
    uv run <skill-dir>/scripts/align.py reel/audio/voiceover.wav --script script.txt --lines reel/data/lines.json -o reel/data/words.json
    
    これにより words.json と audio.json(f.env の背後にある音声エンベロープ)が書き込まれます。
  4. プレートを同期する:cut('Every frame') はその行の 0.18 秒前にプレートを開始します。lineOf、wor

…

[翻訳のため一部省略]

関連スキル