Communitygithub.com

JularDepick/Agent-Video-Driver

使用脚本化工具链,从零开始驱动一条可交付的音视频成片,无需任何视频生成模型。覆盖结构化提示词搭建、内容核查与文案编排、分镜设计、逐拍卡点、程序化画面渲染、程序化配乐合成、FFmpeg 编码封装,以及在无视觉能力下通过字符图和客观指标完成验收。适用于科普讲解片、产品宣传片、数据动画、片头片尾等需要自主生成视频的任务。

O que é Agent-Video-Driver?

此技能适用于在 AI Agent(如 Claude Code 或 Cursor)环境下自主制作完整的音视频成品。它定义了一套完整的、可编程的工作流:从环境检测、代价报告(Token 消耗、渲染时间、磁盘占用等)和用户确认开始,经过文案编排、分镜设计、程序化画面渲染(基于 Python+Pillow)、程序化配乐合成(默认管弦乐或可选电子配乐),最终使用 FFmpeg 编码封装。重要的是,它完全不依赖任何第三方素材库或剪辑软件,所有画面和音乐都由代码实时生成。该技能还内置了严格的内容底线(事实可溯源、素材许可合规、不生成真人脸)和工程铁律(如先做配乐再做画面、所有动画按拍为单位而非秒数)。交付前通过字符图审阅、客观指标(如 PSNR、响度、卡点)和全绿验收标准确保质量。对开发者而言,它提供了一种可重复、可控、可审计的方式,让 AI Agent 能独立处理视频制作任务,非常适合需要精确控制风格和内容的自动化视频生产场景。

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JularDepick/Agent-Video-Driver.SKILL/tree/HEAD/skills/agent-video-driver

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Agent-Video-Driver faz?

不依赖任何素材库与剪辑软件,画面和音乐都由代码算出来,再用 FFmpeg 封装成片。 本技能只规定方法与纪律,不固定风格,风格库见 references/styles.md。

一,两道确认门(都不可跳过)

门一:启动确认门

接到视频任务后,先向用户报告代价并取得明确同意,再开始任何渲染:

必须告知的代价典型量级
Token 消耗单条 30s 片约 5 到 10 万 output token,90s 以上分段片更高,长会话缓存命中也会累计到百万级
中间帧图片30s@30fps 约 900 张 PNG,1080p 下约 200MB,90s 以上约 3000 张
渲染耗时1080p@30fps 约 0.08 到 0.12 秒每帧,单进程 3000 帧约 5 分钟
机器占用全量渲染与最终合成都会长时间吃满 CPU,开发机上会明显卡顿,按限额跑可以缓解
会话占用一个会话只做一个视频任务,中途插入别的任务会污染上下文并拖慢每一步

同时确认四件事:时长与分辨率、确认模式(逐步确认或一次确认)、是否需要作者署名(默认不加)、交付文件命名。 逐步确认适合事实与审美需要用户发言权的题材,一次确认适合判据客观的题材;两种模式下"先出开头 10 秒"这个节点都不省略。 用户未确认前只做环境探测与分镜草案,不渲染。

门二:合成确认门(每次跑重活之前单独确认)

门一的同意不覆盖这一步。全量渲染与最终合成是仅有的两个把 CPU 长时间吃满的动作,各自之前都要再确认一次:

  1. 先探测本机资源,拿到限额建议与风险提示
python scripts/resources.py --for render --frames <帧数>
python scripts/resources.py --for encode --frames <帧数>
  1. 把核数、当前负载、可用内存、目标盘剩余空间、建议的线程数与编码预设、以及是否建议拦截,一并报告给用户
  2. 用户明确同意后才动手;未同意时只跑探测,不做任何编码或全量渲染
  3. 动手时一律按探测给出的限额执行,不按满核跑

scripts/assemble.ps1 把这道门做进了脚本本身:不带 -ConfirmAssembly 时只打印确认门并退出,退出码 3 表示"正在等待用户二次确认"。 -ProbeOnly 只探测不编码。探测判定空间不足或负载过高时,脚本会拒绝开工,要强行开工必须显式加 -Force。

二,八阶段流程

0 探测环境 -> 1 简报与提示词 -> 2 内容与文案 -> 3 风格与分镜
  -> 4 配乐先行 -> 5 分段渲染 -> 6 编码封装 -> 7 客观验收

细节与每阶段的产出物见 references/workflow.md。 每阶段结束都要落一个可检查的产物,不要一口气写完再跑。 阶段 1 到 3 的提示词按 references/prompt-scaffolding.md 的七模块填,填完与产出一起给用户看。 阶段 5 与阶段 6 开工前各走一次合成确认门(见第一节的门二)。

三,目录与文件规范

<工作目录>/
├── .skill/<技能名>/        # 技能本体,一个技能一个目录 bundle
├── prompts/                # brief.md 与各阶段提示词
├── script.md               # 屏文案表,timing.py 的输入
├── storyboard.md           # 分镜表与启动确认门
├── credits.md              # 外部素材的署名与许可
├── temp/                   # 一切中间产物,帧序列、plan.json、试渲染、校验图
├── <产物目录>/             # 只放最终交付文件与可直接复用的源脚本
└── audio/                  # 配乐 WAV(可并入产物目录)
  • 中间帧必须落在 temp/ 下,交付前清理,不要把 3000 张 PNG 留在根目录
  • 相对路径优先,脚本内不要写死绝对路径
  • 一个视频一个命名前缀,帧目录与成片名对应,避免多任务互相覆盖
  • 更多约定见 references/conventions.md

四,风格不固定,但配乐默认走管弦乐

本技能给的是引擎,不是模板。开片前先选风格,再选配色与音色,最后才写分镜。 references/styles.md 提供八种可直接套用的风格,含配色十六进制、字体、运动语法、配乐音色与适配题材:

深空霓虹 / 冷调纪录片 / 温暖纸感 / 极简白场 / 复古终端 / 学术图表 / 手绘涂鸦 / 电影胶片。

配乐默认用 scripts/orchestra.py 的管弦乐音色库。理由是它同时满足两条硬要求:

  • 不刺耳:音色靠谐波堆叠而非宽带噪声,实测刺耳区(2 到 6kHz)占比 1.2%,谱心 418Hz
  • 不单调:十段式配器表加动机变奏加力度弧线,实测每 10 秒 RMS 起伏 2.80 倍

需要更轻更现代的听感时才换 scripts/music.py 的键盘与电子音色。 无论用哪套,都不许出现这三种情况:全片一套配置跑到底,高频占比过半,或持续声部盖住拍点。

五,脚本清单

脚本作用
scripts/check_env.py探测 ffmpeg,Python 库,字体,磁盘,沙箱限制,渲染路线可用性
scripts/resources.py重活前的资源探测与限额建议:核数,负载,内存,磁盘,建议线程数与编码预设
scripts/check_text.py字形体检:位图比对找出会变豆腐块的字符
scripts/beats.py从音频反推 BPM,拍点,小节线,逐小节响度变化
scripts/timing.py把屏文案表排到拍网格,产出 plan.json 与分镜用的时间表
scripts/canvas.py画面引擎:超采样画布,缓动,发光,文字,通用 UI 组件,渲染驱动
scripts/dsp.py共享 DSP 基元:滤波,混响,总线压缩,暖调母带,写 WAV
scripts/orchestra.py管弦乐配乐引擎(默认推荐)
scripts/music.py键盘与电子配乐引擎(备选)
scripts/sfx.py音效轨混音:按 cue 表把用户自备音效混成一条轨
scripts/check_audio.py配乐客观检查:卡点,频段,脉冲,单调性一次跑完
scripts/preview.py无视觉能力下的画面验收:把帧降采样成彩色字符图,支持前后帧对比
scripts/qa.py按 plan.json 逐屏抽帧,锚点前后帧对比,拼总览图
scripts/tokens.py统计本会话 token 与成本,供片尾字幕使用
scripts/assemble.ps1编码,混音,响度归一,质检
templates/scene_module.py场景模块骨架:逐拍触发,分段调度,区间渲染 CLI
templates/storyboard.md分镜表与确认门模板
templates/brief.md简报模板,全片唯一的一份背景
templates/stage-prompt.md阶段提示词模板,七模块
templates/screen-script.md屏文案表模板,timing.py 的输入

画面默认走 Python + Pillow 逐帧渲染。浏览器渲染路线在受限沙箱下不可用,原因与规避见 references/pitfalls.md。

六,内容底线(Must hold,四条不可协商)

  1. 事实有出处:每个年份,人名,数字,引语都要能追到可靠来源,并在工作目录里记下链接;追不到的直接删掉,估算要标注,二手说法要写清是谁的说法
  2. 素材可用:引入外部图,字体,音效,现成配乐时逐项核实许可,署名写进 credits.md;未采用的候选素材也要列出并写明原因
  3. 不画真人脸:不用 AI 生成真人的脸;用了 AI 生成的画面要按平台要求勾选"AI 生成内容"标注
  4. 画面只依赖时间:所有随机性必须定种子,同一帧每次渲出来必须一样

判定规则,汇报格式与发布前清单见 references/content-and-rights.md。

七,十四条工程铁律(都是踩过的坑)

  1. 先做配乐再做画面,画面切点必须等于配乐切点,不要反过来迁就画面
  2. 所有入场动画以拍为单位写死,禁止用秒数近似,卡点差一帧观众就能看出来
  3. 单位坐标与像素坐标必须显式分开,混用会让整场戏塌到左上角
  4. 段落调度用区间映射,写完必须打印每段的起止帧核对,差一段整片错位
  5. 帧序列不要写进根目录,也不要留在磁盘上过夜,交付前删干净
  6. 分区间并行渲染要开独立进程各写各的,不要用共享队列,沙箱会拦命名管道
  7. 混音先看频段占比,高频占比过半就是刺耳,低频占比过半就是浑浊
  8. 总线压缩的时间常数不能短于 0.3 秒,否则压缩器会把拍点本身压平
  9. 任何时长不小于小节且每小节都出现的声部都会变成声墙,掩掉拍点
  10. 文本要过三层编码关;画面引擎已按字做字形回退,但回退链也覆盖不到的字符仍会静默画成豆腐块,所以每段渲染完必须看字形审计报告,缺字形就改写法或换字体
  11. 编码后必须量 PSNR,低于 45dB 说明码率给少了
  12. 无视觉能力时不要凭想象交付,用字符图逐帧核对构图再用客观指标兜底
  13. 会话里只做一条片,第二条另开会话,否则缓存与上下文都会失控
  14. 全量渲染与最终合成前先探测资源并按限额跑,不按满核跑,且这两步各自要用户再确认一次

完整坑表与复现条件见 references/pitfalls.md,文本编码见 references/text-and-encoding.md。

八,验收标准(交付前必须全绿)

项判据
时长精确到帧,30s 片必须 30.000s
卡点逐帧差分峰值落在小节线正负 1 帧内,且锚点屏的前后帧差异峰值落在切点帧
响度集成响度 -16 到 -14 LUFS,真峰值不高于 -1.0 dBFS
画质编码后与源帧 PSNR 高于 45dB
构图每个段落至少抽 2 帧做字符图核对,每屏至少 1 帧进总览图
体积1080p 每 30s 控制在 15MB 以内(CRF 18 到 20)
字形渲染期审计报告里没有"回退链也找不到字形"的项
内容上屏每一行文字都能在已核实的内容里找到出处

方法见 references/verification.md。

九,署名策略

  • 视频产物默认不加作者信息,由工作流在启动确认门里问一次,用户要才加
  • 若用户要求署名,只在片尾卡出现,并同时给出可替换的常量位置
  • 本技能作者 JularDepick,版本见 frontmatter 的 metadata

十,参考文档索引(按推荐阅读顺序)

顺序文档内容什么时候读
1references/workflow.md八阶段流程,每阶段产出物,分段经验值接到任务后第一份
2references/prompt-scaffolding.md简报与阶段提示词的七模块,角色分工,子代理交接开工写提示词时
3references/narrative.md开场语法,单屏字数与阅读速度,叙事线索与节奏写文案时
4references/content-and-rights.md事实来源判定,素材许可,署名,发布前清单查资料与配图时
5references/styles.md八种风格与配乐对应,选风格的四条判断法定风格时
6references/beat-sync.md三层对齐,段内事件写法,卡点验证写分镜之前
7references/audio-engine.md两套配乐引擎,音色库,编排骨架,客观判据做配乐时
8references/visual-engine.md画面引擎 API,通用组件,图形配方,性能写场景时
9references/text-and-encoding.md三层编码关与字形体检写任何上屏文本前
10references/verification.md各类验收手段与交付自检清单交付前
11references/pitfalls.md踩坑的现象,原因与规避出问题或复盘时
12references/conventions.md目录,命名,代码,文档,协作规范建项目结构时

排序只由本表承担,文件名不带序号。 新增参考文档时在表里插一行即可,不需要重命名任何既有文件。 新增脚本放进 scripts/,新增骨架放进 templates/,并在本表与脚本清单里各加一行。

Habilidades Relacionadas