Kanban Motion
Kanban Studios 作。コードとして記述されたモーショングラフィックスを、音声にロックします。このスキルには2つの層があります。
- Motion as Code(以下、変更なし):Motion as Code キットの完全なワークフロー。
- 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. ナレーションの差し替え
audio/voiceover.mp3を置き換えます。analysis/align_vo.pyのSCRIPT(および数字や頭字語のSPOKEN)を編集します。- プロジェクトルートから再実行:
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 から 1f.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/*.js | paper(音声に合わせて呼吸する方眼紙背景)、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 にあります。
script.txtを書く:ビートごとに1行。行がカットになります。空白行はより長いポーズを追加します。[pause 0.8]は正確なポーズを追加します。[at 6.0]は次の行を正確な時間に開始し、既存の編集に音声を合わせます。数字や頭字語は話される通りに書きます。ナレーションはビジュアルをそのまま読み上げるのではなく、補足するものにし、シーンのペースに合わせ、会話調で、製品に固有のものにします。1秒あたり約2.5語を目安にします。- 生成する ローカルで動作するオープンウェイト音声モデル Kokoro を使用します。モデルは一度ダウンロードされます(約340 MB)。
おすすめの音声:uv run <skill-dir>/scripts/voiceover.py script.txt -o reel/audio/voiceover.wav --lines reel/data/lines.json --voice af_heartaf_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に配置し、この手順をスキップします。 - 整列する 単語レベルのタイミングを取得します。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.jsonwords.jsonとaudio.json(f.envの背後にある音声エンベロープ)が書き込まれます。 - プレートを同期する:
cut('Every frame')はその行の 0.18 秒前にプレートを開始します。lineOf、wor
…
[翻訳のため一部省略]