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 секунд или меньше) и методом обратной разработки превращает его в структурированный промпт, который можно сразу скормить ИИ-генератору видео.
Это CLI-скрипт или агентный скилл?И то и другое: он поставляется и как Agent Skill, который мультимодальный кодинг-агент вроде Grok или Claude может вызвать прямо в чат-сессии, и как автономный CLI/API-конвейер, который обращается к внешней vision-модели по HTTP для незанятых человеком пакетных задач или CI.
Как его запустить?Выполните scripts/setup.sh для установки зависимостей, затем либо вызовите скилл dance-video-to-prompt внутри совместимого агента (или запустите scripts/extractframes.sh) — это путь без API, — либо запустите scripts/analyzeapi.sh для полностью автоматического пути через API.
Нужен ли внешний vision 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, prompt-engineering, image-processing, skill, video, generative-ai, computer-vision
Creator
CattleZ
Size
0.1 MB
Stars
143
Updated
CommitAug 22
Age
2mo
Commits · 90 Days