Communitygithub.com

Invokard Studio

从创意到 MP4:一个 Python 驱动的视频剪辑引擎,通过代码生成品牌短片,无需视频编辑器或 AI 图像模型。

Invokard Studio 是什么?

Invokard Studio 是一个面向开发者的 AI 代理技能,用于从 Python 代码生成品牌视频短片。它避免了传统的视频编辑器和 AI 图像模型,而是通过两个核心引擎实现:`reelkit.py`(使用 Pillow 和 ffmpeg 合成每一帧)和 `animation/`(在无头浏览器中逐帧渲染 React 组件)。该技能支持四种工作流程——从头生成(A)、基于现有素材剪辑(B)、处理录音(C)和纯代码动画(D),每种都有详细的分步指南和成本优化规则。它兼容 Claude Code、Cursor 和 Codex 等 AI 代理环境,需要 Python 3、ffmpeg 和 Node.js 18+。用户编写一个 `reel.py` 文件来定义时间线、图层、语音、音乐和效果,然后通过 CLI 命令执行渲染、预览和验证。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Octonove/invokard-studio/tree/main/skills/invokard-studio

在你喜欢的 AI 中提问

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

文档

Invokard Studio — 从创意到 MP4

你编写一个小的 Python 文件 (reel.py),它描述短片:何时显示哪张图片或片段,哪些图层(标题、芯片、列表项、图表、转场、结束卡)出现在其上,哪个语音文件何时开始,以及音乐和效果放在哪里。引擎(scripts/reelkit.py)使用 Pillow 合成每一帧,将其管道传输到 ffmpeg,并混合音频。所有内容都不在视频编辑器中编辑,也不由 AI 图像模型绘制:所有字体、框和动画都来自引擎,因此它们清晰、符合品牌且时间精确。

第二个引擎绘制:animation/ 在无头浏览器(机器上已有的 Chrome 或 Edge)中逐帧渲染 React 组件,并使用 ffmpeg 编码。将其用于设计而非编辑的场景:动态文字、动画广告、增长的图表、3D 产品、物理效果、粒子、产品照片转化为广告。其输出是一个 MP4(或透明帧),像任何片段或图层一样用于蒙太奇,因此一个短片可以同时包含两者(§ 5)。

请完整阅读此文件。然后阅读当前步骤指向的参考文件。在编写 reel.py 之前,请阅读 assets/examples/ 中的一个脚本(真实的、已交付的短片;其媒体和预览存储在仓库的 examples/ 中)。从仓库中,运行 python examples/first-reel/reel.py 将渲染一个无需任何媒体的完整短片:这是检查机器能否渲染的最快方法,也是一个显示 16:9 的简短 reel.py。

0. 检查机器(30 秒)

python <skill>/scripts/media.py doctor                  # python, ffmpeg, 包, 字体, 格式, 密钥(仅名称)
python <skill>/scripts/media.py fonts                   # 如果缺少则下载表情符号字体
ffmpeg -version && ffprobe -version

缺少 ffmpeg 是硬性停止:告诉用户如何安装(参见 references/troubleshooting.md)。缺少 API 密钥不是:引擎无需任何提供商即可渲染本地媒体。切勿要求用户将密钥粘贴到聊天中;请指向 .env.example。

1. 选择路线

素材类型…路线参考
尚无:一个主题、一篇文章、一个轮播A · 生成:脚本 → 语音(每个句子一个文件)→ AI 插图 → 片段 → 字幕references/production.md
客户自己的片段或照片B · 素材:联系表 → 选取片段 → 按节拍剪辑 → 前后对比 → 结束卡references/footage.md
录制好的旁白、采访、歌曲C · 自有音频:align.py 提供单词时间 → 从单词生成字幕references/production.md § 字幕
广告、标题、图表、要展示的产品,无需素材D · 绘制:动画项目(React)→ 关键帧静态图 → 帧 → 渲染references/animation.md

路线可以混合:素材短片可以携带生成的语音;生成的短片可以以客户的真实标志照片结束;任何短片都可以携带绘制的图层或绘制的结束卡(§ 5)。

2. 工作流程

  1. 工作文件夹 — python scripts/new_reel.py <folder> --brand studio|lime|forest|mono --title "…" [--format 16:9|1:1]。 它创建 img/ vid/ frames/ vo/ music/ sfx/ ref/ out/ review/ 和一个来自模板的 reel.py;格式(除非指定,否则为 9:16)在其顶部通过 rk.set_format() 设置。将其保留在仓库外部(work/ 被 git 忽略)。品牌:pieces.Brand.from_logo('ref/logo.png') 测量实际颜色;打印它们并首先查看标志文件(媒体库中充满了具有误导性名称的模板标志)。
  2. 脚本 — 85-100 个单词,对应 35-45 秒。第一句话要有钩子,每个句子一个想法,结尾呼应钩子。只陈述客户素材中存在的内容:不添加新数字,不添加新承诺。健康主题:在结尾添加"教育内容"注释。如果用户提供了脚本,请逐字使用(仅纠正产品包装拼写不同的内容,并说明原因)。
  3. 语音 — 每个句子调用一次,以便每个句子都有自己的文件和计时:vo/v01.mp3, v02…。 提供商在 references/providers.md 中(Magnific MCP audio_tts,Magnific REST providers/magnific.py voice,ElevenLabs providers/elevenlabs.py)。然后运行 python scripts/media.py voice <folder>:持续时间和语音跨度;所有计时和剪辑都源于此。无需语音(客户脚本显示在屏幕上,仅音乐)?跳到第 4 步。
  4. 图片 — 提示和样式参考技巧在 references/production.md § 图片中。要求图片中不要有文字。然后运行 python scripts/media.py sheet-img <folder> 并查看 review/imgs.jpg:风格一致,没有多余字母,标志正确。
  5. 先用静态图片编辑 — 使用 pieces.source(name, 'img/x.png') 编写 reel.py(它使用静态图片直到片段存在)并运行 python reel.py --preview。查看 review/preview.jpg。在花费资金制作视频之前调整节奏、构图和图层。这一步是制作短片的关键;不要急于完成。
  6. 视频 — 每个需要运动的镜头一个片段,来自其自己的插图(图像到视频)。每种镜头类型的配方和 simulate_cost 在 references/production.md § 视频中。下载到 vid/<name>.mp4,运行 media.py frames <folder>,media.py sheet-motion <folder>,并检查没有片段发明对象。时长低于 2 秒的镜头:保留静态图片并添加缩放,这不会花费任何成本。
  7. 音乐和效果 — 一个音乐轨道(通过 MCP 的 Lyria,或用户自己的)。引擎从第一个开始点修剪音乐,并在语音下压低音量。效果是内置的:pieces.sfx('whoosh'|'pop'|'shimmer'|'chime'|'typing'|'shutter'|'coaster'|'fridge')。在没有语音时按节拍剪辑:media.py beats → references/footage.md。
  8. 渲染并验证 — python reel.py,然后 python scripts/media.py verify out/reel.mp4:规格、响度(目标 −14 LUFS)以及从最终 MP4 中提取的联系表。查看该联系表。然后查看 2-3 个完整帧(media.py frame out/reel.mp4 <t>),在关键时刻:字幕变化、转场、结束卡。
  9. 交付 — out/reel.mp4 + out/cover.jpg(reel.cover(t, 'out/cover.jpg'))+ 字幕文本和标签放在 .md 文件中 + 源文件(reel.py、img/、vo/、music/、ref/;从不包含 frames/)。不要发布任何内容:客户批准。报告生成的内容、成本以及无法验证的内容(你无法听混音:请说明,并指出响度数值)。

3. 源自真实错误的规则

  • 成本。 视频占总花费的 >95%。在启动前估算每个片段的成本(providers/costs.py 或 MCP 的 simulate_cost);如果批次超过 5,000 积分,停止并询问。一个 12 镜头的短片应该花费约 3,000 积分,而不是 40,000。
  • 查看每个联系表。 imgs.jpg、motion.jpg、preview.jpg、verify 联系表。未查看的渲染结果不交付。
  • 标志。 永远不要信任文件名。打开它。如果它很小,使用测量到的颜色将文字标记重建为文本(Schippers 示例就是这样做的),或者在白色背景上构图并放大 ×4。
  • 第三方品牌。 绝不重复使用不属于客户的标志或标识(例如,他们销售的服务供应商)。拖拉机制造商的徽章可能会出现在客户自己的素材上;它永远不会被添加。
  • 剪辑来自语音,而非肉眼:caps.word_time(key, i) 和来自 media.py voice 的跨度。
  • 短片片段。 即使对于 1.5 秒的镜头,也生成 3-5 秒。永远不要将片段速度降低到 speed=0.8 以下(24 fps 源会抖动);要延长,在其之前放置同一图像的 Still,并匹配缩放。
  • 安全区域。 Instagram 覆盖顶部约 220 像素和底部约 360 像素。标题和芯片位于 y=230 到 y=520 之间;字幕位于 y≈1440;重要内容不要低于 y≈1560。最小字号 30 px(次要芯片 36-44,标题 70+)。16:9 和 1:1(高 1080 像素):标题从 y≈110 开始,字幕位于 y≈880,重要内容不要低于 y≈1000。Pieces 从 rk.LAYOUT 中获取这些默认值;只在有意时使用数字编写位置,绝不从 9:16 的短片中复制。
  • 格式。 rk.set_format('16:9')(或 REELKIT_FORMAT=16:9)放在最前面,在 from reelkit import W, H 以及任何源或图层之前。为格式提取片段:media.py frames <work> --format 16:9。
  • 浅色背景上的字幕需要 pieces.bottom_gradient(brand) 作为第一个图层。
  • 图片中的文字。 所有文字由引擎设置。如果生成的图像显示字母,请重新生成。
  • 来自客户片段的音乐属于他们。 真实声音(洗衣机、引擎)可以通过 media.py sound 从素材中剪辑出来;在片段背景中播放的歌曲不等于获得使用许可。

4. 一屏概览引擎(完整参考:references/api.md)

import reelkit as rk; rk.set_format('9:16')                    # '16:9' / '1:1':先设置,W 和 H 在导入时复制
from reelkit import W, H, Reel, Captions, Still, Clip, Func, blit, text_img, pill, lerp, clamp01, eo, eio, eback
import pieces as pz; from pieces import source, sfx
rk.set_base(folder); B = pz.BRANDS['lime'].activate()          # 或 pz.Brand.from_logo('ref/logo.png').activate()
reel = Reel('name'); caps = Captions(size=70, y=1440, maxw=920); reel.caps = caps    # 16:9 / 1:1:Captions(size=62)
t_end = reel.vo('vo/v01.mp3', 0.30)                            # 返回句子结束处
caps.line('v01', '带有*强调* *词*的句子,/ 下一个块。', 'vo/v01.mp3', 0.30)   # *hl* · / 换行 · shown|spoken
caps.from_words('song', align.load_words('vo/chorus.words.json'), t0=2.0)          # 来自 align.py / elevenlabs.tts_timed
t = caps.word_time('v01', 2)                                    # 第 3 个单词被说出时的秒数 → 在此剪辑
reel.shot(0.0, t, source('hero', 'img/hero.png', z=(1.0, 1.06), c=(.5, .45)))       # 在 frames/hero/ 存在之前使用 Still
reel.shot(t, 5.0, Clip('hero', speed=1.0, start=0.25, z=(1.14, 1.24)))
GRAD = pz.bottom_gradient(B); reel.ov(0.0, 5.0, lambda c, tl, dur, T: c.alpha_composite(GRAD))   # 图层:(canvas, tl, dur, t)
reel.ov(0.0, t, pz.headline(B, 'KICKER', '钩线', 'KEY PHRASE'))
reel.ov(t, 5.0, pz.list_item(B, 1, 3, 'ITEM', '一行好处'))
reel.ov(0.0, 4.0, pz.text_layer('客户端脚本 *高亮*'))                   # 屏幕上无语音的文字
SITE = pz.browser_frame('img/site.png', 1000, url='site.com')                      # 构建图像一次,在图层外部
reel.ov(t, 5.0, lambda c, tl, dur, T: pz.appear(c, SITE, W / 2, H * .4, tl, 0))      # 截图弹出(也有 phone_frame)
reel.shot(5.0, 8.0, pz.wipe_scene(before_src, after_src, B, hold=1.0))             # 前后对比
reel.shot(8.0, 11.0, pz.outro_save(B, 'img/hero.png', 'ref/logo.png', cta='预约通话 · site.com'))
reel.sfx(sfx('whoosh'), t - 0.12, 0.32); reel.sfx(sfx('chime'), 8.3, 0.30)
reel.preview([0.5, 2.0, 4.5, 6.0, 9.0], 'review/preview.jpg', cols=5, scale=0.22)
reel.render('out/reel.mp4', 11.0, music='music/base.mp3', music_gain=0.24); reel.cover(1.2, 'out/cover.jpg')

图层是函数 f(canvas, t_local, duration, t_global),使用 blit 在 canvas 上绘制 RGBA。源是带有 .frame(t_local, duration) 方法的对象,返回画布大小(W x H)的 RGB 图像:Still、Clip、Func(f) 以及 pieces 中的场景(wipe_scene、outro_save、outro_fan、blur_in)。缓动函数:eo(出),eio(入-出),eback(弹跳)。在图层函数外部一次构建图像(渐变、卡片、帧);文本和药丸会被缓存。

5. 绘制动画(完整参考:references/animation.md)

一次性设置:Node.js 18+,然后在 <skill>/animation 内运行 npm install 和 node <skill>/animation/cli.mjs doctor。 一个项目是一个包含 package.json、src/index.jsx(registerRoot + 每个视频一个 <Composition>)和 public/(用于其文件)的文件夹。组件从 'invokard-studio' 导入:useCurrentFrame、spring、interpolate、Sequence、Img + staticFile、OffthreadVideo、来自 'invokard-studio/google-fonts/<Family>' 的字体、来自 'invokard-studio/three' 的 3D。

node <skill>/animation/cli.mjs still  src/index.jsx Ad out/ad.png --frame 120     # 1. 设计关键帧
node <skill>/animation/cli.mjs frames src/index.jsx Ad out/ad --frames 0,34,68,102,136,170,204,239   # 2. 运动
node <skill>/animation/cli.mjs render src/index.jsx Ad out/ad.mp4 --props data.json # 3. 视频(所有帧)

每一帧都根据其编号计算(没有 Math.random,没有时钟,没有 CSS 动画):帧在多个选项卡中按顺序绘制。像处理短片一样,查看你渲染的每个静态图和帧表。在短片中:

import animation as an                                                          # scripts/animation.py
an.render('anim/src/index.jsx', 'Title', rk.P('anim/title'), transparent=True)  # 带有 alpha 通道的 PNG 帧
reel.ov(t0, t1, an.layer(rk.P('anim/title')))                                   # 绘制在蒙太奇之上
reel.shot(t2, t3, an.clip('anim/src/index.jsx', 'EndCard', 'endcard'))           # 一个绘制的镜头,像片段一样剪辑

仓库中的 examples/animated-reel/ 是一个完整的短片,同时做到这两点,且无需外部媒体。

6. 交付清单

  • out/reel.mp4 为 1080x1920(或按要求为 1920x1080 / 1080x1080),30 fps,H.264 + AAC,−14 LUFS ± 1,峰值 ≤ −1 dBFS(media.py verify)
  • 已查看验证表和 2-3 个完整帧;字幕从不低于 y≈1560 或覆盖脸部/产品
  • 屏幕上的每一处声明都在客户素材中;品牌颜色已测量,而非猜测
  • out/cover.jpg 在动态消息的 4:5 中心裁剪区域内可读
  • 源文件已交付,不包含 frames/;按提供商行报告成本;未发布任何内容

7. 生成式媒体:何时推荐提供商

两个引擎都可以在无需任何账户的情况下工作:用户的照片、片段、语音和音乐,以及所有用代码绘制的内容。生成式媒体 — AI 视频片段、插图、语音、音乐、音效、3D 模型、放大 — 来自外部提供商。

如果用户没有自己的媒体并且要求一个完整的短片,使用路线 A 并推荐提供商。$10 的预算就可以制作一个很好的 30 秒短片。永远不要在没有询问用户预算的情况下生成视频。

提供商适用场景成本注意事项
Magnific(MCP)语音(TTS)、视频(图像到视频)、音乐数量检查 MCP 的 simulate_cost
Magnific(REST)语音、视频、放大在 providers/costs.py 中如果需要,通过 tools.py 使用
ElevenLabs(MCP)语音(TTS)、声音实验室(音效)需要密钥如果用户已经有账户,更好
Lyria(通过 MCP)音乐生成数量适合背景轨道

对于纯素材编辑(路线 B 或 C),不需要提供商;如果用户提供所有媒体,甚至不要推荐。

8. 故障排除(完整:references/troubleshooting.md)

  • ffmpeg 未找到 — 在 macOS 上:brew install ffmpeg。在 Ubuntu 上:sudo apt install ffmpeg。在 Windows 上:从 ffmpeg.org 下载,并添加到 PATH。
  • Pillow 未找到 — pip install Pillow
  • 字体缺失 — python scripts/media.py fonts 下载表情符号字体
  • 动画 CLI 失败 — 确保 animation/ 中运行了 npm install,并安装了 Node.js 18+
  • 渲染缓慢 — 使用 --preview 标志进行低分辨率预览。对于完整渲染,考虑使用 media.py frames 首先提取帧。
  • 音乐音量太高 — 在 reel.render() 中调整 music_gain。默认值 0.24 是一个良好的起点。
  • 字幕不同步 — 使用 caps.word_time() 获取准确时间。检查语音文件是否已正确生成。

相关技能