mcpField
A
aip-composition

aip-composition

github.com/opus-pro创意与媒体7127 次安装4 天前更新
代码仓库

关于 aip-composition

aip-composition 是 AI Producer 视频项目中 HTML 合成内容的制作技能,供构建可编辑的动态图形与视觉片段。它遵循编辑器和导出器共同识别的结构,并将可编辑内容与代码绘制图层区分开。

主要功能

  1. 01以 HTML 定义视频合成
  2. 02通过 GSAP 时间线驱动动画
  3. 03支持 DOM 与画布图层混合
  4. 04配置说话人片段和视觉片段
  5. 05遵循编辑器可识别的合成结构

适用场景

  1. 01制作视频标题卡与动态图形
  2. 02叠加可编辑的文字和标签
  3. 03在合成中加入画布绘制的 3D 内容

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/opus-pro/ai-producer-plugin --skill aip-composition

安装后在 Claude Code 中输入/aip-composition确认已加载。

包含的文件

除 SKILL.md 外,安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
code-drawn.md
motion-recipes.md
pip-transition.md
text-treatments.md

详细介绍

面向 AI Producer 项目的 HyperFrames

版权归 HeyGen, Inc. 所有,© 2026。修改部分版权归 OpusClip 所有,© 2026。OpusClip 为 AIP 修改;请参阅来源归属、许可证和变更。

HTML 就是视频:一个合成内容是带有 data-* 时间属性的 HTML 元素,以及一个由播放器驱动的暂停状态 GSAP 时间线。AI Producer 的编辑器使用自己的播放器播放你的 HTML,导出时则使用 AI Producer 自己固定版本的 HyperFrames 进行渲染;它们是两个程序,有各自独立的播放和编辑约定。本页只定义这两者读取的接口,仅此而已。绘制什么、如何动起来、字幕放在哪里,以及某个瞬间呈现什么样子,都由你决定。

AI Producer 接受的内容

  • 项目位于 render-engine/ 下:index.html、compositions/*.html,以及 public/ 下的资源。AI Producer 会将 public/source.mp4(录制内容)和 public/source.mp3(其音频)放入项目,并将 GSAP 放在 public/vendor/gsap.min.js;请从该路径加载 GSAP。正如主技能所述,你在这台电脑上检查的页面会从本项目获取该文件。
  • 可接受的文件和上传限制见 AI Producer 工作区格式。系统会拒绝项目外的脚本,因此合成内容的逻辑必须内联。
  • 根据绘制内容拆分每个瞬间。文本、标签、卡片、计数器,以及用户可能想要重新输入或调整样式的任何内容,都应作为由 GSAP 动画控制的 DOM 元素,并使用 CSS 3D(perspective、3D 旋转、translateZ 堆叠)赋予实际景深,而不是平铺显示。3D 对象或空间、由着色器驱动的表面,或对 DOM 来说过于密集的数据,应根据代码绘制图层中的要求,通过脚本绘制到 <canvas> 上;3D 场景使用 Three.js。提交检查会拒绝自行运行时钟的 canvas,或在其窗口之外持有 WebGL 上下文的 canvas。一个瞬间可以混合使用两者,例如在 canvas 场景上叠加 DOM 标签。编辑器将 canvas 视为单个叶节点,因此用户无法选择或调整其绘制内容的样式;请将用户可能想要编辑的内容保留在 DOM 中。
  • 用户的图像会暂存到 public/images/<name>,用户的视频片段会暂存到 public/videos/<stem>.mp4;其中 <name> 是将文件名缩减为 ASCII 字母、数字、-、_ 和 . 后的结果(空格会变成 -,其他字符会被删除),因为其他字符会改变浏览器请求的 URL。交接检查会确认合成内容通过 src 或 href 引用的每个文件都位于目录树中;以其他方式引用的文件(data-pip-src、CSS url(...))不会被检查到,因此请在同一批次上传中暂存该文件和合成内容,并在提交后通过列表确认文件已存在。

编辑器如何识别 index.html 中的内容

  • 根元素:<div id="stage" data-composition-id="finecut-root" data-start="0" data-duration="<total s>" data-width="W" data-height="H">。请将此根元素直接放在文档的 body 中,而不是放在 <template> 内。此 id 固定不变:编辑器会通过 window.__timelines["finecut-root"] 定位根时间线,因此根转场应放在该时间线上;根元素会在任何合成内容注册之前创建注册表:
<script>
  window.__timelines = window.__timelines || {};
  const rootTl = gsap.timeline({ paused: true });
  ...root tweens (never a speaker zoom or filter; see below)...
  window.__timelines["finecut-root"] = rootTl;
</script>
  • 说话人:<video id="speaker" class="clip" src="public/source.mp4" muted playsinline data-volume="0"> 和 <audio id="speaker-audio" class="clip" src="public/source.mp3" data-volume="1">。媒体 ID 必须唯一。说话人视频没有声音;源音频是可听到的主声轨。通用的额外 <audio class="clip"> 标签不是 AI Producer 音效轨道:AI Producer 音频轨道需要其编辑文档和派生的 track-audio 元素。剪切后,在同一对文件上使用 N 组视频/音频配对。每个元素都带有 class="clip speaker-clip"、preload="none"、唯一的 id,以及 data-start、data-duration、data-media-start 和 data-track-index。播放器会加载当前配对并预热下一组配对;提前预加载会对同一源重复发起请求。每组配对共享其 data-hf-id 和时间信息;每组配对应使用不同的 data-hf-id。第一组配对保留 speaker 和 speaker-audio。每条说话人轨道上的 DOM 顺序就是输出顺序,因此应按播放顺序写入片段,并使用连续的输出起始时间。EditingScript AV 轨道必须包含相同的片段 ID 和源/输出时间;发布前,workspace helper 会同步该轨道和字幕时间。
  • 一个视觉片段:每个片段对应一个 <div class="visual-host clip" data-composition-id="<id>" data-title="<short name>" data-composition-src="compositions/<file>.html" data-start data-duration data-track-index data-width data-height>。这个 host div 就是编辑器显示并允许用户移动的片段;直接写入根节点的内容不算片段。片段是画面上独立的一层:其 composition 绘制的内容看不到下方的画面,因此像 mix-blend-mode 这类与片段下方内容结合的效果,应设置在 index.html 中的 host div 上,这样它会在编辑器和导出内容中作用于整个片段。data-title 用几个词命名效果(例如 Commute title card);编辑器时间线会用它标注片段,若缺少此属性,则显示 composition ID。它不会改变渲染结果或导出内容。在字幕由服务生成的项目中,host 可以携带其时间窗口的字幕策略:data-hide-captions="false" 会让当前字幕在片段期间继续显示(缺少该属性或设为 "true" 时会隐藏字幕,这是默认行为);data-caption-position="<integer percent of frame height>" 会移动该时间窗口内字幕栏的锚点;data-caption-ink="#<six hex digits>" 会将片段期间字幕文字设为指定颜色,适用于 composition 绘制了浅色背景的情况。编辑器、服务的编辑路径和导出流程都会根据这些属性重新生成该字幕层的时间窗口,因此移动或删除片段时,其策略也会随之调整。自行编写的字幕片段会忽略这些属性:每条字幕都在自己的 composition 中设置位置和颜色。
  • 字幕:字幕片段是普通视觉片段,ID 为 captions-<n>,每段语音对应一个片段,每条字幕都是其 composition 中的静态文本;其时间、外观和挂载方式由 dynamic caption skill 管理。narrator-captions、compositions/narrator_captions.html 和 compositions/transcript-src.json 是服务的字幕层:编辑器和导出流程会按该 ID 查找它,并从一个内联的 const WORDS = [...]; 数组读取文字;如果提交的文件声明了该 ID 却没有这个数组,提交会被拒绝,而且只有服务可以写入这些内容。切勿编写该层或复用其 ID。已有该字幕层的项目应保持其挂载状态;不要在其 host 或 index.html 中的 .caption-band 上添加偏移,否则会移动整个全画布字幕栏,并使所有字幕文字移出屏幕。没有字幕的编辑不需要这些文件。
  • 属于可编辑视觉片段的说话人座位或 PIP 应放在该片段内部:<div class="speaker-pip-frame" data-aip-editable="speaker-pip-frame"><video id="<unique>" data-pip-src="public/source.mp4" data-start="<the host's data-start>" data-duration="<the host's data-duration>" data-media-start="<source seconds at that start>" muted playsinline data-volume="0"></video></div>,不带 src。在根节点的说话人画面上方绘制不透明的片段底色;如果画面应从全屏移动到座位中,则在子级时间线上为该 frame 添加动画。时间表的唯一例外是:此视频的 data-start 应使用 host 的全局起始时间,而不是 0,因为导出时会在已剪切的项目中将其媒体偏移设置为该值,以此重新锚定视频;编辑器则会通过剪切本身进行映射。将画面和内容放在同一个 host 下,可确保时间线移动或删除操作同时作用于两者。对于服务通过 frame_speaker 处理的说话人抠像(public/speaker_<slug>.webm,即按其时间窗口剪切的透明通道视频),连接方式相同,使用 data-media-start="0",并在上方叠加同一时间窗口、几何参数相同的 public/source.mp4 画面;何时显示、显示在哪里由 framing skill 管理。
  • 录制内容以外的画面(用户剪辑或素材剪辑):无论是 PIP 还是分屏,默认都在 index.html 中将根节点视频剪辑放在独立轨道上:<video id="<unique>" class="clip" data-track-index="<n>" src="public/videos/<stem>.mp4" data-start data-duration data-media-start muted playsinline data-volume="0">,并在上方绘制用于构成该画面的片段(如遮罩、边框或标题)。另一种嵌套方案是在片段的 composition 内使用相同标签:<video id="<unique>" class="clip" src="public/videos/<stem>.mp4" data-start="<the host's data-start>" data-duration data-media-start muted playsinline data-volume="0">,像 PIP 一样按 host 的时钟计时。根节点剪辑可由用户在时间线上移动;嵌套剪辑则随其片段一起移动。
  • 说话人缩放或颜色滤镜:使用不带 composition 文件的空 host。缩放效果使用 <div class="visual-host clip" data-composition-id="<id>" data-aip-effect="zoom" data-no-timeline data-start data-duration data-src-anchor data-track-index="20" data-hide-captions="false" data-effect-scale="<above 1, at most 3>" data-effect-origin="<x% y%>" data-effect-in="<s>" data-effect-out="<s>"></div>;滤镜效果则在 data-track-index="21" 上使用 data-aip-effect="filter",并以 data-effect-filter="<grayscale, sepia, saturate, contrast, brightness, invert, hue-rotate, or blur functions>" 替代缩放和原点属性。效果会在 host 的时间窗口内用 data-effect-in 秒渐入,保持不变,再用 data-effect-out 秒渐出;窗口之外,说话人保持原始状态。data-src-anchor 是 data-start 对应的源视频秒数(即覆盖该时间点的说话人剪辑的 data-media-start 加上该时间点在剪辑中的偏移),因此剪切会让效果随其覆盖的文字移动。两个缩放效果或两个滤镜效果不能重叠;缩放可以与滤镜或视觉片段重叠。在根脚本之后加载引擎:<script src="public/vendor/speaker-effects.js"></script>;服务会在首次加载该文件的提交中写入此文件,因此不要上传它。编辑器会在时间线上列出每个 host,并允许用户移动、修剪、删除和调整效果。若在根时间线上对说话人使用 scale 或 filter 补间动画,编辑器将无法看到,因此缩放或滤镜绝不能以这种方式编写。
  • 超出缩放或滤镜范围的摄像机效果(冲击抖动、白色闪光、甩镜、推镜、手持漂移):使用运动 host:<div class="visual-host clip" data-composition-id="<id>" data-aip-effect="motion" data-no-timeline data-start data-duration data-src-anchor data-track-index="<900 to 907>" data-hide-captions="false" data-effect-motion="<name>" data-effect-params='{"<param>":<number>}'></div>,并在 index.html 中添加一个内联 <script data-aip-motion="<name>">,将 window.__aipMotions["<name>"] = { label, params: { <param>: { min, max, default, label, unit } }, frame(t, d, p, rand) } 赋值给它。frame 会返回 x 和 y(像素)、scale(1 至 3)、rotate(度)以及 overlay: { color: "#rrggbb", opacity }(覆盖所有内容,包括字幕的全画面颜色)中的任意值;这些值只能根据函数参数计算:t 是 host 内的秒数,d 是其时长,p 是参数值,rand(i) 是每个 host 固定的相位。脚本中任何位置都不得读取 Math.random、Date、performance、crypto、Intl 或计时器,也不得设置其他名称对应的条目:否则服务会拒绝,因为预览、导出和每个渲染窗口都会绘制出不同的帧。时间上重叠的运动应放在不同轨道上,并叠加生效;偏移总量不得超过 160 px,旋转总量不得超过 8 度。服务会适当缩放画面以覆盖边缘,若 2x 缩放仍无法覆盖,则会减弱运动效果。所有用户应能调整的值都必须声明为参数(最多 8 个;每个参数名使用不超过 16 个字符的 lower camel case;值的范围在 +/-1,000,000 内);编辑器会将每个参数显示为一个字段。完整定义示例见:motion recipes。
  • 用户需要将某个元素作为一个对象移动和调整样式时,应添加 data-aip-editable="<token>",其中 token 必须是该元素自身的某个类名;编辑器还会将 .list-item、.glass-card、.media-card、.speaker-pip-frame 和 .item-bar 视为此类对象。片段内的其他内容只能作为文本或图像叶节点访问。 不要将由视觉片段拥有的席位或画中画实现为根发言者上的绝对时间几何补间。移动或删除宿主不会改写任意根时间线补间,因此该形状会留在原来的时间。根发言者几何仅用于不由可独立编辑的视觉片段拥有的镜头处理,绝不能用于其缩放、滤镜或逐帧镜头移动:发言者缩放或颜色滤镜属于效果宿主,抖动、闪光、鞭甩或推镜属于运动宿主。可选的 画中画示例 展示了由效果拥有的全帧/画中画转场。

子合成文件

<template>
  <div data-composition-id="<id>" data-width="W" data-height="H">
    ...content, with its <style> and <script> inside the template...
    <script>
      const root = document.querySelector('[data-composition-id="<id>"]');
      const tl = gsap.timeline({ paused: true });
      ...tweens on root.querySelector(...) targets...
      window.__timelines["<id>"] = tl;
    </script>
  </div>
</template>

内部 div 的 data-composition-id 与宿主的值相同。严格按照代码片段所示绑定根元素,使用 [data-composition-id="<id>"],且选择器中不能有其他内容;所有元素都通过该根元素上的后代查询获取。导出挂载时会从内部 div 移除 data-composition-id 和其他 data-* 属性,因此导出时只有宿主携带该 id:如果选择器还要求同一元素具有类、id、属性,或包含 :not(.visual-host),或者使用 :scope > 子元素选择器,那么导出时将无法匹配任何内容,脚本会在注册前抛出异常,导出也会拒绝该片段。该宿主就是代码片段在导出时绑定的 root,而根规则 [data-composition-id="<id>"] { ... } 仅为其中模板自身的根元素设置样式,因此不要从 root 读取样式,也不要读取写在模板根元素上的属性:在根规则中声明的自定义属性从 root 读取时会得到 ""(经 parseFloat 转换后为 NaN,基于它计算出的值也会被丢弃),而这些属性并不在宿主上。应从根元素内部的元素读取这类值,因为自定义属性会继承;或者将其保留为脚本常量。将样式和元素查询限定在合成内容内,以便多个片段可以共存于同一文档中。保持合成根元素处于可见的基础姿态;为内部包装元素或其子元素添加动画,而不是合成根元素或宿主。编辑器只挂载 <template> 内的内容,导出则挂载模板本身:写在 </template> 后的 <script> 在两者中都不属于该片段,因此不要在 </template> 后写任何内容;该文件不需要自己的挂载脚本。时间线时间 0 对应宿主的 data-start,播放器会定位时间线,而不是播放它。在 DOM 存在后,同步创建并注册已暂停的时间线。影响渲染的关键变更应放在该时间线上,而不是计时器、requestAnimationFrame 循环、播放回调或 CSS 动画中。不要调用 tl.play(),也不要自行启动媒体播放;时钟由播放器控制。动画重复次数应有限,并使用带种子的随机数,以确保定位到任意时间时都能得到确定状态。连续移动应使用覆盖整个时段的补间,绝不能用一连串 tl.set 步骤,因为每个姿态都会保持数帧,然后突然跳变;叠加在其上的抖动应使用独立通道,例如在 x 和 y 经过补间时,对 xPercent 和 yPercent 添加抖动。对 filter 的补间会替换元素的整个滤镜,因此,如果元素的外观来自 filter: url(#...),应将该滤镜保留在内部元素上,并在其包装元素上执行补间。宿主属性负责时长和活动窗口;不要添加空补间来设置时长,也不要手动将子时间线嵌入根时间线。

时间属性

属性适用于值
data-start每个片段秒数,相对于父合成(合成内的 PIP 或素材片段:宿主的全局起始时间,见上文)
data-duration每个片段秒数,片段自身的时长
data-track-index每个片段整数;同一轨道上的片段不能重叠
data-media-start视频和音频在源文件中的偏移量,单位为秒
data-volume已注册媒体播放增益,范围为 0 到 1;不会将任意音频纳入 AI Producer 混音
data-width、data-height合成画布尺寸,单位为 px

预览验收

AI Producer 技能负责交付和停止检查的条件。请将此约定与创作方向分开。成功的本地动画样片或已接受的上传内容,并不能证明 AI Producer 编辑器或导出流程正确。

评论

支持 Markdown