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)

video-understanding
Searching Database…

143 ·GitHub
Dance-video-to-prompt
What is this?Dance-video-to-prompt takes a short local video (dancing, posing, outfit changes, travel check-ins, walking in an outfit, ideally 10 seconds or less) and reverse-engineers it into a structured prompt you can feed straight into an AI video generator.
Is this a CLI script or an agent skill?Both: it ships as an Agent Skill that a multimodal coding agent like Grok or Claude can trigger directly inside a chat session, and as a standalone CLI/API pipeline that calls an external vision model over HTTP for unattended batch or CI use.
How do I get it running?Run scripts/setup.sh to install the dependencies, then either trigger the dance-video-to-prompt skill inside a compatible agent (or run scripts/extractframes.sh) for the no-API path, or run scripts/analyzeapi.sh for the fully automated API path.
Do I need an external vision API to use it?Only for the API version: that mode needs a VISION_MODEL and a gateway token plus the httpx library; the Skill/Agent version just relies on the multimodal vision of whatever CLI agent (Grok, Claude, etc.) you're running it in, with no extra API key.
Does it reconstruct precise body-joint motion?No — it deliberately skips joint-coordinate motion reconstruction and instead describes actions as generation-ready timeline text covering limbs, angle/amplitude, hand shapes and gaze.
What kind of videos does it work best on?It's built for short clips like dancing, posing, outfit changes, travel check-ins and outfit-walking videos, ideally 10 seconds or shorter, since the dense frame extraction and rhythm analysis are tuned for that length.
What does the final generated prompt look like?It always follows a fixed 7-section template: visual style, scene narrative, shooting location, camera/photography technique, a timestamped action list, dialogue/subtitles, and background sound including BGM style and BPM.
Which agents can run the Skill version?The install script syncs the skill into .grok/skills/, ~/.grok/skills/, ~/.agents/skills/ and ~/.claude/skills/, so it works with Grok CLI and Claude-based agents, or any agent capable of reading images.
What's the pipeline that produces the prompt?It runs dense frame extraction (every 0.33s by default, down to 0.25s), sharpness checking with neighbor-frame rescue, BPM/beat rhythm analysis, then a three-stage write-up: raw fact observation into JSON, rewriting into the 7-section prompt, and a final fact-check pass.
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