mcpField
V
video-motion-previs

video-motion-previs

github.com/akillnessクリエイティブ・メディア5352 回インストール4 日前に更新
リポジトリ

video-motion-previs について

video-motion-previs は Motion Previs Studio v4 を操作するスキルで、参考動画の分析や制作パックの作成に使います。CLI から起動中のアプリを制御し、段階的な処理と出力確認を行います。分析とエクスポートはアプリが担います。

主な機能

  1. 01ローカル動画または URL の読み込み
  2. 02範囲と分析モードの設定
  3. 03分析の実行と完了待ち
  4. 04制作パックのエクスポートと確認
  5. 05アプリの接続と状態の確認

活用シーン

  1. 01参考動画の分析
  2. 02指定した時間範囲でのショット処理
  3. 03出力ファイルと品質レポートの確認

MCP 対応

CLI で Motion Previs Studio を操作でき、上流の MCP bridge の設定方法も示します。bridge はポートとトークンを自動検出しますが、アプリの起動が必要です。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/akillness/jeo-skills --skill video-motion-previs

インストール後、Claude Code で/video-motion-previsを入力して読み込まれたか確認します。

同梱ファイルscripts/video-motion-previs.mjs

詳細

ビデオモーションのプリビズ

軽量な video-motion-previs ラッパーを使用して、実際の Motion Previs Studio v4 コントロール API を操作します。ラッパーは、アプリのローカルホスト限定でトークン保護されたディスカバリー記述子を読み込み、上流の MCP ブリッジと同じ許可リスト登録済みアクションを呼び出します。

このスキルを使用する場合

このスキルは、参照動画の分析や Motion Previs Studio の制作パックに使用します。Blender のシーンスクリプト作成のみの場合は Blender スキルに、ComfyUI グラフの作成には AI 動画／ComfyUI スキルに、ウェブアニメーションのパフォーマンス最適化には optimize-web-animations に、一般的な動画編集には video-production に振り分けてください。

これは完全なヘッドレスレンダラーではありません。実行中の Electron アプリが MediaPipe、ffmpeg、UI の状態、分析、エクスポートを管理します。CLI は操作インターフェイスであり、分析エンジンの代替ではありません。

手順

1. インストール前に確認する

このスキルのディレクトリから実行します。

node scripts/video-motion-previs.mjs check

JSON の結果では、次の項目を判別できます。

  • macOS の /Applications または ~/Applications にあるパッケージ版インストール
  • MOTION_PREVIS_SOURCE または一般的なローカルパスからのソースチェックアウト
  • プロトコル v1 のコントロールサーバーが正常に稼働している実行中のアプリ
  • Node／プラットフォームとの互換性の問題や古いディスカバリーファイル

正常に動作している既存のアプリは、通常、再インストールしないでください。Motion Previs Studio が生成する MediaPipe／モデル／ランタイムのアセットは比較的大きいため、インストールは冪等に保ってください。

2. 必要な場合にのみインストールする

node scripts/video-motion-previs.mjs install

インストールの方針：

  • macOS Apple Silicon： 調査済みの公式上流インストーラーと、最新の arm64 リリースを使用します。利用可能なソースチェックアウトをパッケージ版アプリに置き換える場合にのみ、--packaged を渡してください。
  • Windows 11 x64： CLI は公式の最新リリース版インストーラーの URL を表示します。上流の NSIS インストーラーは署名されておらず、対話型のため、インストールはユーザーに表示されます。
  • Linux または Intel 搭載 Mac： install --source [DIR] を使用してソースをクローンし、npm ci を実行して、SHA-256 で検証された固定バージョンのランタイムアセットを準備します。Linux では、上流のドキュメントに記載されているとおり、ffmpeg／ffprobe のランタイム上書き設定または PATH の明示的な指定も必要です。

上流のインストーラーは、既存の Motion Previs Studio v4.app を削除して置き換えるため、ユーザーの意図を確認せずに強制実行しないでください。

ターミナル全体から使用する場合は、ラッパー自体を PATH にインストールします。

node scripts/video-motion-previs.mjs link
video-motion-previs check

3. 起動して接続を確認する

video-motion-previs launch
video-motion-previs state
video-motion-previs screenshot /tmp/motion-previs.png

launch は、正常に動作しているアプリがあればそれを再利用し、利用可能な場合はパッケージ版アプリを開き、そうでなければ準備済みのソースチェックアウトを起動します。モーション関連のコマンドでは、常に最初に state を実行します。読み込まれたメディア、範囲、モード、分析状態、設定、最後のバンドル、Blockout の利用可否を確認できます。

記述子が存在してもヘルスチェックに失敗する場合は、アプリを終了して再起動してください。通常、記述子は次の場所にあります。

  • macOS／Linux：~/.config/motion-previs/control.json
  • Windows：%APPDATA%\Motion Previs Studio\v4\control.json
  • 上書き設定：MOTION_PREVIS_CONFIG_DIR または MPS_CONFIG_DIR

ベアラートークンをレポートやコミット対象ファイルに出力または保存しないでください。

例

4. CLI から 1 ショットを操作する

各段階の間に人間による確認が必要な場合は、個別のコマンドを使用します。

video-motion-previs import-file "/absolute/path/to/shot.mp4"
video-motion-previs set-range 0 3
video-motion-previs set-mode camera_only
video-motion-previs set-settings '{"sampleFps":6,"resolution":"720p"}'
video-motion-previs analyze
video-motion-previs wait --timeout 900
video-motion-previs export
video-motion-previs list-bundle

すべての入力が承認済みの場合は、範囲を限定したワークフローを使用します。

video-motion-previs workflow "/absolute/path/to/shot.mp4" \
  --start 0 --end 3 --mode camera_only --sample-fps 6 --timeout 900

ローカルパスの代わりに URL を使用できます。Motion Previs Studio は、互換性のあるウェブ動画のダウンロードを yt-dlp に委任します。

video-motion-previs workflow "https://example.com/reference-video" \
  --start 2 --end 7 --mode actor_motion

有効なモードは camera_only、actor_motion、object_motion、full_scene です。上流で受け付けられる設定は、sampleFps、maxPeople、smoothing、detectionConfidence、trackingConfidence、および resolution（auto または 720p）です。時刻の単位は秒です。

5. 高度な自動化の場合にのみ生のアクションを使用する

video-motion-previs call get_state '{}'
video-motion-previs call send_to_blockout '{"which":"openpose"}'

上流の v4.1 コントロールインターフェイスには、次の 11 個の許可リスト登録済みアクションがあります。

get_state、import_file、import_url、set_range、set_mode、set_settings、run_analysis、export_pack、list_bundle、send_to_blockout、screenshot

CLI による直接操作ではなく MCP クライアントを使用する場合は、上流の依存関係ゼロのブリッジを指定します。

claude mcp add motion-previs -- node "/ABSOLUTE/PATH/motion-previs-studio/mcp/motion-previs-mcp.mjs"

引き続きアプリを実行しておく必要があります。ブリッジはポートとトークンを自動的に検出します。

ベストプラクティス

6. 成功を前提とせず、出力を検証する

export の後、返されたバンドルパスと list-bundle の成功の両方を必須とします。選択したコントロールとローカルモデルの利用可否に応じて、パックには reference.mp4、深度／エッジ／線画／モーション／ポーズ動画、openpose_keypoints.json、camera_motion.json、Blender インポートスクリプト、comfyui_manifest.json、プロンプト／ショットバイブルファイル、品質レポート、bundle_manifest.json が含まれる場合があります。

検証ゲート：

  1. エクスポート前に、state で analysis.status: "done" が報告されていること。
  2. export が bundlePath と zipPath を返すこと。
  3. list-bundle の内容が要求したコントロールと一致すること。オプションのレイヤーは常に含まれるとは限りません。
  4. 下流の生成を行う前に、bundle_manifest.json と quality_report.json を確認すること。
  5. 長いクリップを処理する前に、3～5 秒の短い範囲でテストすること。

トラブルシューティング

  • アプリが実行されていない場合： launch を実行し、state を待ってから再試行してください。
  • ディスクリプターが古い場合： パッケージ版とソース版の両方を完全に終了し、古い control.json だけを削除してから再起動してください。
  • メディアが読み込まれていない場合： 分析の前に import-file または import-url を実行してください。
  • エクスポート時に分析が完了していないと表示される場合： ステータスが done になるまで wait でポーリングしてください。running 中や error の後にエクスポートしないでください。
  • ポーズの品質が低い場合： 範囲を短くし、被写体が見えやすい状態にして、診断時はサンプリングコストを下げ、品質／ポーズの診断情報を確認してください。
  • カメラの推定が被写体を追ってしまう場合： camera_only と full_scene を比較してください。ソルバーは被写体をマスクした背景のオプティカルフローを使用します。
  • 深度を利用できない場合： 対応する CPU/WASM フォールバックを使用するか、そのオプションレイヤーを含めずにエクスポートしてください。
  • ブロックアウトを利用できない場合： Blockout を起動し、send-to-blockout の前に移行先プロジェクトを開いてください。

参考資料

このワークフローは、コミット 95e7d0ff1d4cc546f7eb09a74ccbd084988a19bc の上流 v4.1.0 に照らして確認されています。検証した対象は README.md、package.json、install.sh、mcp/README.md、mcp/motion-previs-mcp.mjs、electron/control.cjs、src/control/handler.ts です。アプリを再配布する際は、上流の LICENSE、NOTICE、およびサードパーティの帰属表示を保持してください。

コメント

Markdown 対応