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