Communitygithub.com

custom-animated-video

将脚本、配音和任意 style_bible.json 转化为逐帧动画 MP4,支持口型同步、锥形描边赛璐珞艺术、边缘光、布料物理、视差镜头运动、风格化字幕以及自动闪避的 -14 LUFS 混音。

custom-animated-video 是什么?

该技能是一个完整的动画视频制作编排器,可将用户的脚本、配音和风格圣经自动化转化为逐帧动画 MP4 文件。它由编排器智能体主导,按顺序调用多个专门的子智能体(如 cav-ingest、cav-director、cav-artist 等),每个子智能体负责流水线中的一个特定阶段:从音频分析、故事板生成、场景绘制(使用 HTML5 Canvas)、音效合成、音频混音到最终渲染和 QA。所有渲染均在本地通过 Playwright、FFmpeg 和 numpy/scipy 完成,不依赖任何云端视频 API。该技能高度参数化,所有风格变量均来自用户提供的 style_bible.json,核心代码内不包含任何硬编码风格。它支持 16:9 和 9:16 画幅,包含自动口型同步(基于 faster-whisper)、锥形描边赛璐珞艺术、边缘光、布料物理模拟、视差镜头运动、风格化字幕以及完整的 Foley/环境音效制作。输出音轨自动闪避并符合 -14 LUFS 标准。该技能的主要用例包括:动画旁白/解说、动画短片、解说视频、YouTube Shorts,或用户要求“以我的风格”制作视频的场合。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/aryanmali/custom-animated-video/tree/main

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

custom-animated-video: orchestrator

SKILL_DIR = 存储此文件的文件夹。你是一个编排器:你需要保持用户的意图,将每个阶段委托给专门的子智能体,并亲自运行审核关卡。切勿将任何风格硬编码到核心中;每个风格值都来自用户的 style_bible.json。

标志含义
--scriptscript.txt / script.md (实际说出的文字)
--audiovoiceover.wav / .mp3
--stylestyle_bible.json (任何形状;会被自动标准化)
--bgm可选音乐文件 (否则使用素材库,再否则使用程序化调式环境音)
--aspect16:9 (1920×1080, 默认) 或 9:16 (1080×1920)
--subtitlestrue / false
--out输出 .mp4 文件 (其文件夹即为 WORK,除非指定了 --workdir)

流水线 (均由 scripts/build_video.py 驱动): normalize_style → analyze_audio → storyboard.json → scene_drawers.js → sfx_synth → mix_audio → render_frames (分镜头→片段,删除帧) → concat + mux → QA 帧 → 自动清理 → 审核关卡.

智能体及路由

阶段子智能体模型 · 精力任务
1 输入cav-ingesthaiku · low运行时检查,--stage analyze,写入 WORK/director_brief.json
2 导演cav-directorsonnet · mediumstoryboard.json (7 条导演规则);仅按镜头更新
3 绘制cav-artist (cav-artist-fast 在快速/经济模式下)opus · high (sonnet · high)scene_drawers.js (6 条艺术规则) + 预览验证;针对性修复
4 构建cav-builderhaiku · low完整构建 / --only / --apply-review / --ship,音频遥测
5 QAcav-qa-criticsonnet · medium检查 WORK/qa/ 目录,返回 `STATUS: PASS

仅在用户明确要求快速/经济/廉价/草稿模式时使用快速模式。切勿在未告知的情况下降低艺术家智能体的模型级别。

编排规则

  • 单一任务、无状态的子智能体。 提示词缓存约 5 分钟后过期,而用户审核关卡可能耗时更长,因此切勿在审核关卡之间保持子智能体存活,也切勿向已完成的子智能体发送 SendMessage。为每个任务创建一个全新的子智能体,并附上明确的绝对路径和简洁的结构化简报 (见下文)。独立的工作可以在一条消息中并行完成。
  • 简报格式 (每次委派):SKILL_DIR、WORK、确切的 --script/--audio/--style/--aspect/--subtitles/--bgm/--out 值、任务、要读取的输入文件、要写入的文件以及所需回复的格式。
  • 保持自己的上下文精简: 阅读子智能体的摘要,而不是原始文件。切勿 Read audio_timeline.json (包含巨大的逐帧数组)。应使用 WORK/director_brief.json。
  • 如果 cav-* 子智能体类型在当前会话中尚不可用 (在会话中途注册的智能体可能需要重启后才能列出),请保持模型路由:调用 Agent(subagent_type="general-purpose", model=<m>),其中 model = haiku (用于 cav-ingest/cav-builder)、sonnet (用于 cav-director/cav-artist-fast/cav-qa-critic)、opus (用于 cav-artist),并告诉它先读取 $SKILL_DIR/agents/<agent-name>.md 并将其作为指令执行,然后给出常规简报。
  • 确保用户已提供脚本、配音和风格圣经;仅对缺失的内容提问 (AskUserQuestion)。

阶段 0 · 注册子智能体和运行时

AGENTS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents" && mkdir -p "$AGENTS_DIR" && for f in "$SKILL_DIR"/agents/cav-*.md; do cmp -s "$f" "$AGENTS_DIR/$(basename "$f")" || cp "$f" "$AGENTS_DIR/"; done

(可在 macOS 和 Linux 上移植执行。build_video.py 也会在每次运行时保持同步;上面的命令保证了首次执行时的正确性。) 私有运行时 ($SKILL_DIR/.runtime/: venv、Whisper 模型、浏览器、ffmpeg 等) 由 cav-ingest 通过 build_video.py --check 引导启动 (约 1–3 分钟,需要互联网;绝不接触其他环境)。决定 WORK 目录为 dirname(--out) 并 mkdir -p 创建。

阶段 1 · 输入 → cav-ingest

委托。期望返回 STATUS: ok|needs_user 和 WORK/director_brief.json。

  • alignment_coverage < 0.6 → 脚本与录音不匹配:停止并询问用户 (修复脚本 / 确认 / 提供新的录音)。仅拼写差异可以接受。
  • 缺少必需的情绪/调色板条目 → 询问是否将其添加到圣经或接受默认值。
  • 否则继续;在面向用户的下一条消息中显示警告。

阶段 2 · 导演 → cav-director

输入:WORK/director_brief.json,WORK/storyboard.draft.json,references/storyboard_schema.json。输出 WORK/storyboard.json。对回复进行完整性检查 (镜头拼接,在暂停中点剪切,1.5–6 秒的镜头,摄影机多样性,音效存在)。不满意 → 再次调用全新的 cav-director 并附上具体修正。

阶段 3 · 绘制 → cav-artist (或 cav-artist-fast)

输入:WORK/storyboard.json、WORK/style.normalized.json、用户的圣经以及原始 CLI 参数 (用于预览渲染)。输出 WORK/scene_drawers.js,并通过 --frames 预览验证 (零个 [场景 / 图层 / 帧] 错误)。艺术家的职责仅限于艺术;所需的故事板更改会报告给你,以便转发给 cav-director。

阶段 4 · 构建 → cav-builder

完整构建至 --out (它会传递 --no-review;审核关卡由你负责)。期望返回 BUILD: ok,闪避在目标 ±1 dB 范围内,约 −14 LUFS,以及 WORK/qa/ 帧。如果 failed,将指定的 [场景 / 图层 / 帧] 错误路由给 cav-artist (或时间错误给 cav-director),然后使用 --only 重新构建。

阶段 5 · QA → cav-qa-critic

在用户看到任何内容之前始终运行。如果 STATUS: FAIL:

  1. 包含 target_file: scene_drawers.js 的问题 → 新的 cav-artist (修复模式,简报中包含问题列表)。 包含 storyboard.json 的问题 → 新的 cav-director (针对性更新),如果场景键发生变化,则接着调用 cav-artist。
  2. cav-builder 使用 --only <受影响镜头ID>。
  3. 对新的帧运行新的 cav-qa-critic。 最多 2 次自动修复循环;然后告知用户仍然失败的问题,并让他们决定 (继续到审核关卡或指导修复)。

阶段 6 · 审核关卡 (你,在主会话中;绝不跳过,绝不替用户决定)

python3 "$SKILL_DIR/scripts/review.py" --questions --storyboard WORK/storyboard.json --video project/final_video.mp4

使用 AskUserQuestion 提问,最多三次快速调用 (告知用户视频路径和 QA 确认的信息):

  1. 第1轮 · "发布它还是修改它?"
  2. 如果 修改它,第2轮 在一次调用中完成:哪些部分? (视觉效果 / 摄影与剪辑 / 字幕 / 音效,多选) 和 哪些时刻? (整个视频或特定镜头,多选)。
  3. 对每个选定的部分,在一轮调用中提出 第3轮 问题 (多选;"其他" = 自由文本): 视觉效果 → 角色 · 背景 · 颜色与照明 · 动态;摄影 → 更紧 · 更宽 · 更平稳 · 剪辑时机/转场; 字幕 → 关闭 · 放大 · 缩小 · 移至顶部;音效 → 音乐更安静/更响亮 · 音效更安静/更响亮。

将答案写入 WORK/review.json:

{"decision": "change", "parts": ["visuals", "sound"], "shots": ["s2 3.5-5.6s"],
 "visuals": ["Character", "Motion"], "sound": ["Music quieter"],
 "notes": {"visuals": "face looks too long", "sound": "use ~/music/sitar.mp3"}}

然后:

  • 参数化更改 (构图更紧/更宽/更平稳,字幕关闭/调整大小/位置,音乐/音效 ±3 dB) → cav-builder 使用 --apply-review WORK/review.json。它仅重新构建受影响的资源 (音效 → 音频 + 重新封装;摄影 → 对应镜头;字幕 → 所有镜头)。
  • 艺术/剪辑问题 (视觉效果,剪辑时机,自由文本注释) → --apply-review 还会写入 WORK/review_plan.json 并打印确切的 --only 命令。将 仅受影响的镜头 委托给全新的 cav-director (剪辑时机/摄影节奏) 和/或 cav-artist (视觉效果),提供 review_plan.json 和注释 → cav-builder --only <镜头> → cav-qa-critic 检查更改后的镜头 → 返回到第 1 轮。

循环直到 发布它。storyboard.prev.json 保存更改前的故事板,以便用户在需要时撤销。

阶段 7 · 交付 → cav-builder

在 发布它 时,委托 --ship (如果用户即将制作另一个视频,则使用 --keep-deps;仅当被要求时才使用 --purge-recipe)。它仅保留最终视频 (加上用户的输入和几 KB 大小的 storyboard.json / scene_drawers.js 文件),并删除所有生成的文件以及 $SKILL_DIR/.runtime/ 目录。告知用户:视频路径、其规格行 (分辨率/帧率/时长) 以及释放的磁盘空间。系统工具 (python3, ffmpeg, Chrome) 不会被触碰。


子智能体必须保证的特性 (详细信息见其文件)

导演: 镜头平铺;在暂停中点剪切;1.5–6 秒;多样化的预设;在每个暂停处标记 beat;每个镜头一种情绪;在暂停处转场;在口型同步镜头上标记 speaker;帧精确的 sfx_events (脚步声根据 walk_cycle.frames_per_step,±1.5 dB 交替;swell 峰值在剪辑处的 t_sec + duration_sec;ambience −24…−28 dB;bgm.gain_db −18…−21)。 艺术: 仅使用调色板颜色,无十六进制,无 #000,使用 shadowOf 阴影,一个主光源 F.mood.key_dir_deg,五个视差层 + _lights,≥ 400 像素边距,有根基的建筑,celShade + drawTaperedStroke(…, 1.6) + 一个基于数组的 applyRimLight,IK 固定脚部,布料链,口型同步嘴部,CAV.withBoil 在角色/FX 上使用二帧动画 (tc),确定性随机数生成器。 音频: 优先使用音效素材,然后是程序化生成;使用 sidechaincompress 进行闪避,±1 dB 相对于 audio_palette.duck_db (15),暂停处 +3 dB 增强,两次通过 loudnorm 达到 −14 LUFS / −1.5 dBTP;混音后删除分轨音频。 构建: 每镜头片段 (x264 crf 16) 并立即删除帧;build_state.json 的哈希使重新运行成为增量;--only s2,s3,audio 限制重新运行;任何镜头如果剪辑点移动,以及任何重新渲染镜头的交叉渐变后续镜头,都将重新渲染。标志:--preview --workers N --force --frames a,b,c --apply-review --ship --keep-deps --purge-recipe --stage analyze --check --auto。 艺术 API:references/art_reference.md · 模式:references/storyboard_schema.json、references/style_schema.json。

故障排除

  • alignment_coverage 低 → 脚本和录音不匹配;修复 script.txt。
  • scene_drawers.js does not define scene(s) → 故事板的 scene 键必须与 registerScenes 的键匹配。
  • 闪避与目标相差甚远 → 呼吸声/音乐泄漏;传递 --duck-db 或提高 bgm.gain_db。
  • 空白/黑色帧 → 某个图层抛出错误;读取 [场景 / 图层 / 帧] 错误。渲染缓慢 → 使用 --workers N、--preview。
  • 运行时损坏/过期 → 删除 $SKILL_DIR/.runtime/ 并运行 --check。离线 → 设置 CAV_RUNTIME;没有 Whisper 模型时,对齐器会回退到仅基于能量的分段。
  • 新子智能体在当前会话中未列出 → 它们已在磁盘上注册;启动新的 Claude Code 会话或使用上面描述的 general-purpose 回退方案 (使用匹配的 model) 。

相关技能