mcpField
V
video-motion-previs

video-motion-previs

github.com/akillness创意与媒体5352 次安装4 天前更新
代码仓库

关于 video-motion-previs

video-motion-previs 是用于操作 Motion Previs Studio v4 的技能，面向参考视频分析和制作包生成流程。它通过命令行控制正在运行的应用，并提供分阶段操作及结果校验；分析和导出仍由应用负责。

主要功能

  1. 01导入本地视频或 URL
  2. 02设置片段范围与分析模式
  3. 03启动分析并等待完成
  4. 04导出并检查制作包
  5. 05检查应用连接与状态

适用场景

  1. 01分析一段参考视频
  2. 02按指定时间范围处理镜头
  3. 03检查导出包中的文件和质量报告

MCP 相关

技能可直接使用命令行操作 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、界面状态、分析和导出。CLI 是控制界面，并非分析引擎的替代品。

说明

1. 安装前检查

在此技能目录中：

node scripts/video-motion-previs.mjs check

JSON 结果会区分：

  • macOS 上 /Applications 或 ~/Applications 中的打包安装；
  • 来自 MOTION_PREVIS_SOURCE 或常见本地路径的源代码检出；
  • 具有正常运行的 protocol-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 macOS：**使用 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

切勿在报告或已提交的文件中打印或保存 bearer 令牌。

示例

4. 通过 CLI 操作单个镜头

如果各阶段之间需要人工审核，请使用明确的命令：

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。

如果使用 MCP 客户端而非直接通过 CLI 控制，请将其指向上游的零依赖桥接程序：

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。
  • **导出提示没有已完成的分析：**使用 wait 轮询，直到状态为 done；状态为 running 或 error 时不要导出。
  • **姿势效果不佳：**缩短片段范围、提高主体的可见度、在诊断过程中降低采样成本，并检查质量／姿势诊断信息。
  • **相机解算跟随主体移动：**比较 camera_only 和 full_scene；解算器使用主体遮罩后的背景光流。
  • **深度不可用：**使用支持的 CPU／WASM 回退方案，或在导出时不包含该可选层。
  • **Blockout 不可用：**启动 Blockout，并打开其目标项目，然后再运行 send-to-blockout。

参考资料

此工作流已对照上游 v4.1.0 的提交 95e7d0ff1d4cc546f7eb09a74ccbd084988a19bc 进行检查。验证范围包括 README.md、package.json、install.sh、mcp/README.md、mcp/motion-previs-mcp.mjs、electron/control.cjs 和 src/control/handler.ts。重新分发应用时，请保留上游的 LICENSE、NOTICE 和第三方署名信息。

评论

支持 Markdown