dance-video-to-prompt README

The project's README from github.com/CattleZ/dance-video-to-prompt. As one markdown file: README.md.

dance-video-to-prompt

把 本地短视频（跳舞 / 姿态 / 变装 / 旅行打卡 / 穿搭行走等，优先 ≤10s）反推成可直接用于 AI 视频生成的结构化 Prompt。

仓库：https://github.com/CattleZ/dance-video-to-prompt

能力包含：密帧抽帧、关键帧清晰度检测与邻帧救援、音轨节奏/BPM 分析、画面事实观察、节奏卡点融合、7 段生成提示词。
看图须分析 人物身材特征、穿搭颜色与样式、拍摄场景、拍摄方法 / 运镜 / 关注重点 与面部表情。
动作清单强制含：左右肢、角度/幅度、手型、视线、面部表情（含变化）。

快速开始

# 1. 环境
bash scripts/setup.sh

# 2. 抽帧 + 清晰度 + 节奏（Agent 模式工作包）
bash skills/dance-video-to-prompt/scripts/run_extract.sh /path/to/video.mp4

# 3. 安装 Skill 到本机 Grok / Claude 目录（可选）
bash skills/dance-video-to-prompt/scripts/install.sh

输出目录默认在 output/<视频名>_<时间戳>/（该目录不入库）。

输出模板（固定 7 段）

模块 作用
视觉风格 画质、构图、光影、色调
场景叙述 人物（含身材体型特征）、穿搭（颜色与样式）、气质
拍摄场景 场所、空间关系、背景、地面、陈设、时空与环境光
摄影技术 拍摄方法、运镜、关注重点、机位、焦段、灯光、情绪
动作清单 带时间；强制含左右肢、角度/幅度、手型、视线
对话/文字 对白与字幕
背景声音 BGM 风格、BPM 与卡点关系

两个版本

A. Skill / Agent 版（推荐默认） B. CLI / API 版
谁做「看懂画面」 当前 CLI Agent 的多模态看图 外部视觉模型 HTTP API
是否调 Vision API 否 是
适用 交互式、准确可控、免配 API 批量、无人值守、CI
入口 Skill dance-video-to-prompt 或 extract_frames.sh analyze_api.sh
模型依赖 会话里的 Grok/Claude 等（能 read 图片） VISION_MODEL + 网关 Token

两种版本 共用：

本地视频
   │
   ▼
 scripts/extract_frames.sh     ← 共用，无 API
   │
   ├──────────── Agent/Skill 版 ────────────┐
   │  Agent read_file 看帧                   │
   │  → analysis.json → prompt.md            │
   │                                         │
   └──────────── API 版 ─────────────────────┤
      analyze_api.sh → Vision API 三阶段 ────┘

A. Skill / Agent 版（不调 API）

方式 1：在 Grok/CLI 里用 Skill

触发示例：

Agent 会：

  1. 运行抽帧脚本
  2. 自己看关键帧图片
  3. 写出 analysis.json + prompt.md

Skill 主副本（随仓库复用）：

skills/dance-video-to-prompt/

同步到本机各 Agent（修改 skill 后请再执行）：

bash skills/dance-video-to-prompt/scripts/install.sh

会安装到：

方式 2：手动只抽帧，再让 Agent 继续

bash scripts/setup.sh   # 首次
bash scripts/extract_frames.sh /path/to/dance.mp4
# 或
bash scripts/analyze.sh /path/to/dance.mp4 --mode agent

输出目录内会有：

然后在对话里让 Agent「按 AGENT_INSTRUCTIONS 完成分析」。

B. CLI / API 版（调视觉 API）

# 1. 配置
cp config/settings.example.env config/settings.env
# 填写 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / VISION_MODEL
# VISION_MODEL 必须支持看图

# 2. 一键分析
bash scripts/analyze_api.sh /path/to/dance.mp4

# 更高精度抽帧
bash scripts/analyze_api.sh /path/to/dance.mp4 --interval 0.25

# 跳过校验轮（更快）
bash scripts/analyze_api.sh /path/to/dance.mp4 --no-verify

输出目录

output/<视频名>_<时间戳>/
  frames/
  frames_meta.json
  AGENT_INSTRUCTIONS.md   # 仅 agent 模式
  analysis.json             # 分析完成后
  prompt.md                 # 最终可复制 Prompt
  run_meta.json             # 仅 api 模式

output/ 为运行产物，默认不提交到 Git。

流水线（准确率）

  1. 高密度抽帧（默认 0.33s，可 0.25s）
  2. 清晰度检测 + 邻帧救援
  3. 节奏分析（BPM / 拍点）
  4. 阶段一：事实观察 → JSON（含身材、穿搭、拍摄场景、运镜、表情）
  5. 阶段二：改写 7 段生成 Prompt
  6. 阶段三：对照事实校验

不做关节坐标级动作重建；动作以可生成的时间轴文字为准。

依赖

bash scripts/setup.sh

脚本一览

脚本 作用
scripts/setup.sh 安装依赖
scripts/extract_frames.sh 只抽帧 + Agent 工作包
scripts/check_frame_quality.sh 关键帧清晰度检测与邻帧救援
scripts/analyze_rhythm.sh 音轨节奏 / BPM 分析
scripts/analyze.sh 通用入口（--mode agent|api）
scripts/analyze_api.sh API 全自动
skills/dance-video-to-prompt/scripts/run_extract.sh Skill 入口：抽帧 + 清晰度 + 节奏
skills/dance-video-to-prompt/scripts/install.sh 同步 Skill 到本机 Agent 目录

dance-video-to-prompt (CattleZ/dance-video-to-prompt)

Searching Database…

143 ·GitHub
Dance-video-to-prompt
这是什么？Dance-video-to-prompt 接收一段简短的本地视频(跳舞、摆姿势、换装、旅行打卡、穿搭行走,最好不超过 10 秒),把它逆向解析成结构化提示词,可以直接投喂给 AI 视频生成器。
这是命令行脚本,还是 agent 技能？两者都是:它既以 Agent Skill 的形式发布,可以被 Grok 或 Claude 这类多模态编码代理在聊天会话中直接触发;也作为独立的 CLI/API 管线发布,通过 HTTP 调用外部视觉模型,适合无人值守的批处理或 CI 使用。
怎么让它跑起来？运行 scripts/setup.sh 安装依赖,然后在兼容的代理里触发 dance-video-to-prompt 技能(或运行 scripts/extractframes.sh)走免 API 路径,或者运行 scripts/analyzeapi.sh 走全自动 API 路径。
用它需要外部视觉 API 吗？只有 API 版本需要:该模式需要 VISION_MODEL 和网关令牌,外加 httpx 库;Skill/Agent 版本只依赖你所用的 CLI 代理(Grok、Claude 等)的多模态视觉能力,不需要额外的 API 密钥。
它能重建精确的身体关节运动吗？不能——它有意跳过关节坐标式的运动重建,而是把动作描述为可直接用于生成的时间线文本,涵盖肢体、角度/幅度、手型和视线。
什么样的视频用它效果最好？它专为短视频打造,比如跳舞、摆姿势、换装、旅行打卡和穿搭行走视频,最好在 10 秒以内,因为密集抽帧和节奏分析就是按这个长度调校的。
最终生成的提示词长什么样？它始终遵循固定的 7 段式模板:视觉风格、场景叙事、拍摄地点、镜头/摄影手法、带时间戳的动作列表、对白/字幕,以及包含 BGM 风格和 BPM 的背景音。
哪些代理能运行 Skill 版本？安装脚本会把该技能同步到 .grok/skills/、~/.grok/skills/、~/.agents/skills/ 和 ~/.claude/skills/,所以它适用于 Grok CLI 和基于 Claude 的代理,或任何能读取图像的代理。
产出提示词的管线是怎样的？它先做密集抽帧(默认每 0.33 秒一帧,最密可到 0.25 秒)、结合邻帧补救的清晰度检查、BPM/节拍节奏分析,然后是三阶段撰写:把原始事实观察写成 JSON,改写成 7 段式提示词,最后再做一次事实核查。
What are similar projects?seedance-2.0, VideoAgent, procedural-film, brag, capcut-mate, video-use, seedance2-skill, sprite-gen
Which topics is it in?video-understanding, audio-processing, grok, video-processing, multimodal, video-generation, image-processing, prompt-engineering, skill, video, generative-ai, computer-vision
Creator
CattleZ
Size
0.1 MB
Stars
143
Updated
CommitAug 22
Age
2mo
Commits · 90 Days