Invokard Studio Local — 从用户素材到 MP4
你编写一个小的 Python 文件 (reel.py),描述整个短视频:哪个照片或剪辑何时出现在屏幕上,哪些图层(标题、标签、列表项、图表、擦除、片尾卡)叠加在上面,哪个语音文件何时开始,以及音乐和效果放在哪里。引擎 (scripts/reelkit.py) 用 Pillow 合成每一帧,通过管道发送给 ffmpeg 并混合音频。无需在视频编辑器中编辑:所有文字、框体和动画均由引擎生成,因此清晰、符合品牌且时间精确。
第二个引擎负责绘制:animation/ 在机器上已有的 Chrome 或 Edge(无头模式)中逐帧渲染 React 组件,并用 ffmpeg 编码。用于设计而非拍摄的内容:动态文字、动画广告、生长的图表、3D 产品、物理、粒子、产品照片转为广告。其输出为 MP4(或透明帧),蒙太奇可像使用任何剪辑或图层一样使用它们,因此一个短视频可以同时包含两者(§ 5)。
所有操作均在此计算机上运行。该技能在工作期间从不上传、下载或调用服务:字体已捆绑,音效已捆绑,媒体文件来自用户。通读此文件,然后阅读当前步骤指向的参考文档。插件文件夹中的 examples/first-reel/reel.py 和 examples/animated-reel/reel.py 渲染了完整的短视频,完全无需外部媒体:这是检查机器能否渲染的最快方法。
0. 检查机器(30 秒)
python <skill>/scripts/media.py doctor # python, ffmpeg, 包, 字体, 格式
ffmpeg -version && ffprobe -version
缺少 ffmpeg 是硬性停止条件:告诉用户如何安装(references/troubleshooting.md)。缺少 Pillow 或 numpy:python -m pip install Pillow numpy(它会从 PyPI 下载一次;运行前请告知用户)。
1. 选择路线
| 素材类型… | 路线 | 参考文档 |
|---|---|---|
| 用户自己的剪辑或照片 | A · 镜头:联系表 → 挑选片段 → 卡点剪辑 → 前后对比 → 片尾卡 | references/footage.md |
| 用户可以录制的脚本 | B · 配音:用户每句录制一个文件 → 逐字字幕 → 卡词剪辑 | references/production.md |
| 广告、标题、图表、产品展示,没有镜头素材 | C · 绘制:动画项目(React)→ 关键帧静态图 → 帧 → 渲染 | references/animation.md |
| 只有文本和音乐 | D · 屏幕文本:将客户的脚本作为动画文本置于绘制或照片背景上,卡点剪辑 | references/production.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()设置。品牌:pieces.Brand.from_logo('ref/logo.png')测量真实颜色;先打印它们并查看 logo 文件(文件夹中可能包含误导性的文件名)。 - 脚本 — 85-100 词,时长 35-45 秒。第一句吸引注意,每句一个想法,结尾呼应开头。只声称用户素材中实际存在的内容:没有新数据,没有新承诺。如果用户已给出脚本,则逐字使用。
- 语音 — 用户录制,每句一个文件(
vo/v01.m4a, v02…;mp3、wav 和 m4a 均可):手机语音备忘录就足够。如何请求以及尚未录制时该做什么,详见references/production.md§ 语音。然后运行python scripts/media.py voice <folder>:获取时长和有声段落;所有时间和剪辑都基于此。没有语音(纯屏幕文字,仅音乐)?跳到第 4 步。 - 图片和剪辑 — 用户照片放在
img/,剪辑放在vid/。运行python scripts/media.py sheet-img <folder>和sheet-footage在联系表中显示它们:在选择之前务必查看。绘制的背景、卡片和图表来自 pieces 或动画引擎。 - 先用静态图编辑 — 使用
pieces.source(name, 'img/x.png')编写reel.py,然后运行python reel.py --preview。查看review/preview.jpg。在渲染之前调整节奏、构图和图层。这一步是制作短视频的关键,不要仓促。 - 剪辑 — 运行
media.py extract将短视频使用的真实镜头片段剪切到frames/<name>/;media.py frames转换整个剪辑。检查运动表(media.py sheet-motion <folder>)。 - 音乐和效果 — 用户自己的曲目放在
music/(用户拥有版权的曲目),或者没有。引擎从第一个起音处开始修剪,并在语音下方将其调低。效果已捆绑: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. 源自真实错误的规则
- 查看每个联系表。
imgs.jpg、motion.jpg、preview.jpg、verify表。未经查看的渲染不得交付。 - Logo。 永远不要相信文件名。打开它。如果它很小,用测量到的颜色将文字标记重建为文本。
- 第三方品牌。 永远不要添加不属于用户的 Logo 或身份(例如用户销售产品的制造商)。品牌可能出现,因为它存在于用户自己的镜头中;但绝不会被添加。
- 剪辑来自语音,而非肉眼:使用
caps.word_time(key, i)和media.py voice生成的跨度。 - 短剪辑。 永远不要将剪辑速度降低到
speed=0.8以下(24fps 源素材会出现抖动);如需延长,在同一剪辑的某帧前放置一个匹配缩放的Still。 - 安全区。 Instagram 覆盖顶部约 220 像素和底部约 360 像素。标题和标签位于 y=230 到 y=520 之间;字幕位于 y≈1440;重要内容不要低于 y≈1560。最小字号 30 像素(次级标签 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.m4a', 0.30) # 返回句子结束的位置
caps.line('v01', 'Sentence with *key* *words*, / next block.', 'vo/v01.m4a', 0.30) # *hl* · / 断句 · 显示|朗读
t = caps.word_time('v01', 2) # 第 3 个词被朗读的时刻 → 在此处剪辑
reel.shot(0.0, t, source('hero', 'img/hero.jpg', z=(1.0, 1.06), c=(.5, .45)))
reel.shot(t, 5.0, Clip('hero', speed=1.0, start=0.25, z=(1.14, 1.24))) # frames/hero/ 来自 media.py extract
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', 'Hook line', 'KEY PHRASE'))
reel.ov(t, 5.0, pz.list_item(B, 1, 3, 'ITEM', 'One-line benefit'))
reel.ov(0.0, 4.0, pz.text_layer('Client script *highlighted*')) # 无配音的屏幕文本
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.jpg', 'ref/logo.png', cta='Book a call · 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 在画布上绘制 RGBA。源是返回画布大小(W x H)的 RGB 图像的对象:Still、Clip、Func(f) 以及 pieces 中的场景(wipe_scene、outro_save、outro_fan、blur_in)。缓动函数:eo(out)、eio(in-out)、eback(弹跳)。在图层函数外部一次性构建图像(渐变、卡片、帧);文本和标签会被缓存。
5. 绘制动画(完整参考:references/animation.md)
一次性设置:Node.js 18+,然后在 <skill>/animation 内运行 npm install(它会从 npm 下载引擎的包一次;运行前告知用户),再运行 node <skill>/animation/cli.mjs doctor。项目是一个包含 package.json、src/index.jsx(registerRoot + 每个视频一个 <Composition>)和 public/(用于文件)的文件夹。组件从 'invokard-studio' 导入:useCurrentFrame、spring、interpolate、Sequence、Img + staticFile、OffthreadVideo,3D 来自 'invokard-studio/three',字体来自 'invokard-studio/google-fonts/<Family>' — 仅限十五个捆绑的字体族:Inter, Outfit, Figtree, Poppins, Montserrat, Space Grotesk, Barlow, Barlow Condensed, Oswald, Anton, Bebas Neue, Playfair Display, Fraunces, Shrikhand, Caveat。其他字体:用户将其文件放在 public/ 中,并用 @font-face 声明。
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在 feed 的 4:5 中心裁剪区域内可读 - 源文件已交付,不含
frames/;未发布任何内容
7. 此构建不做的事情
它不使用 AI 生成图像、视频剪辑、语音、音乐或 3D 模型,也不调用任何在线服务。当请求需要其中一项时,请在计划中明确说明:现在可以使用用户自己的照片、剪辑和录音来制作视频,也可以使用绘制动画(标题、图表、3D 产品、由形状构成的插图),或使用用户从任何地方带来的文件。不要推荐特定产品或服务。
参考文档
references/production.md— 用户的语音、字幕、安全区、音频、品牌。references/footage.md— 基于用户剪辑的短视频:联系表、提取、节拍网格、音乐拼接、擦除、片尾卡。references/animation.md— 动画引擎:项目、命令、API、捆绑字体、蒙太奇+动画、故障排除。references/api.md—reelkit.py、pieces.py和media.py的每个函数及其参数,以及每种格式的默认位置。references/troubleshooting.md— ffmpeg、字体、Windows 控制台、长时间渲染。