Skip to content
项目

ZhouXiaolin/opencat has 72 GitHub stars and 12 forks. GitHot measured 0 stars in 24 hours and 0 in 7 days. Last checked 2026-11-16 03:16 UTC. Last push 2026-11-03.

这些数字如何统计

实测星标增长

24小时
0
7天
0
15天
更新延迟
1个月
更新延迟

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Write JSONL/XML. Render video/image. Built for agents.

创作与媒体

README_ZH.md

原文

OpenCat

用 JSX 写视频,Rust 渲染,一行命令出 MP4。

Rust Skia FFmpeg WASM license Stars zread

English · 中文

JSX 定义场景、动画与布局,Skia GPU 加速渲染,FFmpeg 编码输出 MP4 —— 跨机器、跨平台、确定性一致。告别 Chromium 快照、Puppeteer 和笨重的 Web 渲染管线。

写一个视频,就是写一段 JSX(下面是 examples/k3-promo 的场景 A——入口 index.jsx,场景在 scenes/ 目录,即上方示例):

import { gsap } from 'gsap';
import { useGSAP } from 'opencat/runtime';

export const meta = { width: 1920, height: 1080, fps: 30, duration: 16.4667 };

function StageCanvas({ id }) {
  return <canvas id={id} class="absolute inset-0 w-[1920px] h-[1080px]" />;
}

function SceneA() {
  useGSAP((ctx, t) => {
    var T = t;                               // 秒,覆盖整个 16.4667s
    if (T >= 0.75 && T < 4.62) {
      gsap.timeline()
        .set('azoom', { scale: 1.07 }, 0.933)
        .to('azoom', { scale: 0.9417, duration: 3.667, ease: 'none' }, 0.933)
        .fromTo('atitlegrp', { opacity: 0 }, { opacity: 1, duration: 0.2, ease: 'power1.inOut' }, 3.03);
    }
  });
  return (
    <div id="sceneA" class="absolute inset-0 z-[2] opacity-0">
      <div id="azoom" class="absolute inset-0 [transform-origin:50%_50%]">
        <div id="afield" class="absolute inset-0"><StageCanvas id="afield-canvas" /></div>
        <div id="atitlegrp" class="absolute left-[755px] top-[444px] w-[467px] h-[185px] opacity-0">
          <div id="a-sel" class="absolute inset-0 border-[1px] border-white/25"></div>
          <text id="aline1" class="absolute text-[#d8d8da] text-[63.6426px] tracking-[-0.8px] leading-none">Every token</text>
        </div>
      </div>
    </div>
  );
}

export default function K3Promo() {
  return <div id="root" class="relative w-[1920px] h-[1080px] bg-[#010101] overflow-hidden"><SceneA /></div>;
}
cd examples/k3-promo
npm install        # bun install 也可以
npm run build      # vite:打包 JSX、内嵌编译后的 CSS 并渲染 → dist/video.mp4

MP4 已生成。不需要浏览器、不需要截图、不需要任何图形界面(vite 插件通过 opencat 二进制渲染,从 PATH 或 OPENCAT_BIN 解析)。

Why OpenCat

OpenCat Remotion / HyperFrames
渲染方式 Rust 原生 GPU (Skia) Chrome snapshot
渲染速度 10x 基准
部署环境 任意环境 / 纯 CLI 需要 Chromium
动画 真 GSAP——官方 npm 包在引擎内直接运行 直接使用 GSAP / anime.js
浏览器渲染 WASM + CanvasKit 原生
确定性输出 ✅ 跨机器一致 ❌
AI 友好 JSX 声明式 JSX/HTML,较复杂

Remotion 复用了 Web 生态,但 Chrome snapshot 的先天缺陷无法绕过 —— GPU 受限、内存开销大、帧率上不去、部署必须带 Chromium。OpenCat 原生调用 GPU 和 FFmpeg,性能上限不在一个量级。

Capabilities

真 GSAP——官方包,引擎内运行

官方 gsap 3.x 源码在引擎内(V8)跑在确定性 seek 时钟上:tween 就是 g(t),每帧按 t 求值——ticker 永不接触墙钟。非交互的官方插件全部收录(eases 全家、SplitText、MorphSVG、DrawSVG、MotionPath、ScrambleText、Physics2D/PhysicsProps、Flip、CustomEase 等);滚动/指针类插件按设计排除——输入事件不可能写成 t 的纯函数。

import { gsap } from 'gsap';
import { SplitText } from 'gsap/SplitText';

// 声明式 timeline —— examples/k3-promo 场景 A(scenes/scene-a.jsx)。
// tween 目标是节点 id;每帧按 t 对 timeline 求值。
gsap.timeline()
  .set('azoom', { scale: 1.07 }, 0.933)
  .to('azoom', { scale: 0.9417, duration: 3.667, ease: 'none' }, 0.933)
  .to(['afield', 'afieldp'], { opacity: 0.35, duration: 0.4333, ease: 'power1.inOut' }, 1.9667)
  .fromTo('apwrap', { opacity: 0 }, { opacity: 1, duration: 0.2, ease: 'power1.inOut' }, 3.03);

// 官方 SplitText(gsap 自带那个包):拆出来的 wrapper 是真节点
var chars = new SplitText(document.getElementById('otxt'), { type: 'chars' }).chars;
var tl = gsap.timeline();
chars.forEach(function (p, i) {
  tl.fromTo(p, { opacity: 0, x: (i - 6.5) * 21 },
    { opacity: 1, x: 0, duration: 0.43, ease: 'power2.out' }, 7.5663);
});

多场景 + 转场

<tl id="main-tl">
  <Scene1 />                                             {/* duration="4" 写在它的根节点上 */}
  <transition from="scene1" to="scene2" effect="fade" duration="0.6" />
  <Scene2 />                                             {/* duration="4" 写在它的根节点上 */}
</tl>

每个场景是一个组件,duration 写在它的根节点上。场景内的钩子自动绑到该场景的时钟,所以场景可见时 ctx.current.time 从 0 开始 —— 不用手抄起点,转场也不会让它偏移。

内置 fade / slide / wipe / clock_wipe / iris / light_leak,支持自定义 GLSL 着色器。

组件 —— 可复用的构件

任何 JSX 函数都是组件。k3-promo 把公共构件从节点树中提出来(scenes/shared.jsx)—— 用 props 取代旧的模板参数:

function StageCanvas({ id }) {
  return <canvas id={id} class="absolute inset-0 w-[1920px] h-[1080px]" />;
}
function Cdot({ id, s, c }) {
  return <div id={id} class={'absolute w-[' + s + '] h-[' + s + '] bg-[' + c + ']'} />;
}

// 调用点只传差异参数
<StageCanvas id="afield-canvas" />
<Cdot id="a-tl" s="13px" c="#d8d8da" />

组件通过嵌套组合,props.children 从调用点注入内容:

function Card({ bg, title, children }) {
  return <div class={'w-[400px] rounded-xl p-6 ' + bg}>
    <text class="text-[20px] font-bold">{title}</text>
    {children}
  </div>;
}
<Card bg="bg-white" title="Hello">
  <text class="text-gray-500">卡片内容。</text>
</Card>

浏览器内 WASM 渲染

import { initWasm, preloadAssets, getRendererOrThrow, exportMp4 } from 'opencat-web';

await initWasm();
const catalog = await preloadAssets(jsxContent);
const renderer = getRendererOrThrow();
renderer.build_frame(jsxContent, frameNumber, canvas, catalog);
await exportMp4({ /* ... */ });

纯 WASM + CanvasKit,无需服务器。

Canvas 绘制 + SKSL 效果

每个 <canvas> 节点都是真画布:官方 CanvasKit API 面(CK.MakeCanvasSurface、Paint、RuntimeEffect 等)直接画进合成,节点的 CSS 盒、变换与效果仍叠加在其上。引擎接受官方 CanvasKit 签名并降为绘制指令流——原生侧由 Rust 渲染器重放,浏览器侧由真 canvaskit.wasm 重放。逐像素自定义效果一律手写 SKSL,走 CK.RuntimeEffect.Make——这是唯一的效果通路,与浏览器跑的同源:

// examples/inspector-launch —— SKSL 半调背景
var fx = CK.RuntimeEffect.Make(SKSL_SOURCE);           // 编译一次,缓存复用
var paint = new CK.Paint();
paint.setStyle(CK.PaintStyle.Fill);
paint.setShader(fx.makeShader([ax, ay, bx, by, blend, phase]));  // uniforms
canvas.drawRect([0, 0, 1920, 1080], paint);

canvas 子树——布局、图片、文本、视频——经 surface 管线(canvas target → surface → picture)合成进场景;像素缓冲永不跨 JS 桥。参考:examples/inspector-launch/inspector-launch.jsx、examples/hyperframes-launch;指南:skills/opencat-creator/references/canvaskit.md。

更多能力

  • 3D 场景:import * as THREE from 'three'——官方包原样执行,WebGLRenderer 输出被捕获进场景图,由 Rust 原生渲染(浏览器侧用真 three 重放)。支持 GLTF/GLB(GLTFLoader)、贴图、自定义着色器
  • 标准 CSS 布局:class="flex items-center justify-center gap-4" 由 tailwindcss 编译成纯 CSS 后交给内置 CSS 引擎(选择器匹配、层叠、var/calc/color-mix);style 属性支持完整声明
  • 音频混音:多轨道,场景级挂载,自动混音输出
  • 字幕引擎:SRT 解析,跨场景持久化显示
  • SVG:文件(src)与内联 markup(inline)双通道,按节点盒子缩放
  • 确定性渲染:value = f(time),跨机器一致

Quick start

# 渲染 MP4(上方示例)——打包 + 内嵌 CSS + 渲染一条命令完成
cd examples/k3-promo && npm install && npm run build    # → dist/video.mp4

# 桌面播放器实时预览(macOS / Windows / Linux)
cargo run --release --bin opencat -- view path/to/input.jsx

CLI 形态是 opencat render <input> / opencat view <input>;老的裸调用 opencat input.jsx 仍然可用。渲染 dist 构建产物时传 --base-dir(相对资源路径默认按输入文件所在目录解析)。

Web (WASM):cd crates/opencat-web/web && npm run build,浏览器需要 Cross-Origin-Isolated 环境。

Engine / Web 像素对齐(k3diff 像素指标)

硬像素指标(mae/maxd/p8,非 SSIM),裁决工具是 tools/k3diff.py:两边各自出 MP4 后逐帧比对。原生侧用 opencat render;web 侧由 crates/opencat-web-oracle(ChromeDriver headless 驱动 wasm facade + CanvasKit 渲染 harness 页)出分段的 H.264 MP4,再与原生渲染或原始参考视频一起喂给 k3diff。除样片组合外,还有一份着色器效果注册表(docs/shaders-align,200+ 预设)逐预设钉住 engine↔web↔compute 的像素一致性。

# 1) 构建 web facade(wasm + JS + web-demuxer.wasm → dist/)
cd crates/opencat-web/web && npm run build && cd -

# 2) oracle 组合依赖的媒体(会请求 http://127.0.0.1:8080/...)
#    将 mp4/png/mp3 目录用静态服务挂到 :8080
Architecture
JSX ──→ Taffy 布局 ──→ Skia 渲染 ──→ 编码 → MP4
              ↑
         V8 动画脚本

双管道: Rust (GPU) + FFmpeg → MP4 | WASM + CanvasKit (WebGL) → Canvas / MP4

增量渲染: Resolve → Layout → Display,Merkle Tree 跳过不变子树 + Scene Snapshot 零计算复用。

opencat
├── crates/
│   ├── opencat-core/        # JSX 运行时 (V8)、布局 (Taffy)、文字 (cosmic-text)、CSS 引擎
│   ├── opencat-engine/      # Skia 渲染、three 光栅化、FFmpeg 编码、V8 宿主
│   ├── opencat-web/         # WASM:浏览器端渲染 + MP4 导出
│   ├── opencat-web-oracle/  # headless web 渲染器——对齐 oracle
│   ├── opencat/             # CLI:render / view
│   └── faac/                # AAC 编码绑定
├── packages/create-opencat/ # vite 工程模板
├── web/                     # Web 视频编辑器
└── examples/                # 示例工程

编译指南

前置依赖

  • Rust 工具链(edition 2024)。通过 rustup 安装:

    rustup install nightly  # edition 2024 需要 nightly(截至 2025 年初)
    
  • FFmpeg 开发库(用于 MP4 编码)。ffmpeg-next 通过 pkg-config 自动查找 FFmpeg。

    Linux(Ubuntu / Debian)
    sudo apt install \
      libavcodec-dev libavformat-dev libavutil-dev \
      libavfilter-dev libswscale-dev
    

    最低版本要求:FFmpeg 6.x。验证:

    ffmpeg -version
    

    当前环境已验证:FFmpeg 7.1.1,dev 包已全部安装。

    macOS
    brew install ffmpeg
    

    Homebrew 安装后需要用 FFMPEG_DIR 指定 ffmpeg 的 lib 路径:

    # Apple Silicon(M1/M2/M3/M4)
    export FFMPEG_DIR=/opt/homebrew
    
    # Intel Mac
    export FFMPEG_DIR=/usr/local
    

    如果 pkg-config 不能自动找到 ffmpeg lib,可以用 FFMPEG_DIR 来指定路径。建议写入 shell 配置(~/.zshrc / ~/.bashrc)持久化。

    验证:

    ls $FFMPEG_DIR/lib/libavcodec.*
    
    Windows

    从 gyan.dev 下载 FFmpeg dev 包,或 vcpkg install ffmpeg。然后设置:

    $env:FFMPEG_DIR = "C:\path\to\ffmpeg"
    
  • OpenGL / EGL 开发库(Linux,Skia GPU 渲染需要):

    sudo apt install libegl-dev libgles-dev libgl1-mesa-dev libx11-dev
    

    macOS 使用系统 SDK 自带的 Metal,无需额外安装。Windows 通过系统驱动提供 OpenGL。

  • Fontconfig 开发库(Linux):

    sudo apt install libfontconfig-dev
    

Windows:两个必需的链接器标志

预编译的 Skia 与 V8 二进制使用了互不兼容的 C 运行库,因此在 Windows 上直接 cargo build 会链接失败。两个修正都写进 ~/.cargo/config.toml(或仓库内的 .cargo/config.toml):

[target.x86_64-pc-windows-msvc]
rustflags = [
  "-C", "link-arg=/STACK:16777216",
  "-C", "link-arg=/FORCE:MULTIPLE",
]

/STACK:16777216 —— ffmpeg-sys-next 的构建脚本用 bindgen 解析 FFmpeg 全套头文件,递归深度超过 Windows 主线程默认的 1 MiB 栈(PE 头里的 SizeOfStackReserve)。不加这个,构建脚本会以 STATUS_STACK_OVERFLOW(退出码 0xc00000fd)崩溃。

/FORCE:MULTIPLE —— rusty_v8.lib 自带 /DEFAULTLIB:libcmt.lib 指令(静态 CRT);skia.lib 自带 /DEFAULTLIB:msvcrt.lib + msvcprt.lib(动态 CRT)。两条指令都写死在预编译二进制里,Cargo 特性与环境变量都改不掉。两个库各自定义了 std::terminate,链接因此报 LNK2005 / LNK1169。这个标志让链接器任选一份实现,而不是报错退出。

已知风险: 同一个可执行文件里混用了两套 STL 实现。常规渲染与 JS try/catch 已验证可用,但 C++ 异常在 Skia 与 V8 两侧之间传递的行为未定义。若遇到无法解释的崩溃,先怀疑这个标志。干净的解法是用动态 CRT 从源码构建 V8(EXTRA_GN_ARGS="is_component_build=true"),耗时数小时,目前尚未接入。

Skia

Skia 通过 skia-safe 引入,并启用了 binary-cache 特性。构建时 skia-bindings 会自动下载预编译的 Skia 二进制文件,无需本地编译或手动下载静态包。

  • Linux:gl 后端(OpenGL)
  • macOS:metal 后端(Metal)
  • 额外:skottie 支持 Lottie 动画

预编译二进制文件首次构建后会缓存到 ~/.cargo/skia-binaries/。

如果下载失败(如代理环境),可设置 HTTP_PROXY / HTTPS_PROXY,或手动将二进制文件放到构建脚本提示的路径。

构建命令

CLI(MP4 渲染):

cargo build --release --bin opencat

二进制文件在 target/release/opencat。渲染视频:

opencat render examples/k3-promo/dist/index.bundle.jsx

桌面预览播放器(macOS / Windows):

cargo run --release --bin opencat -- view path/to/input.jsx

Web(WASM):

cd crates/opencat-web && npm run build

需要 wasm-pack 和 Cross-Origin-Isolated 浏览器环境才能运行。

验证

确认构建正确地链接了 FFmpeg 和 Skia:

cargo run --bin opencat -- --version

标准配置下无需设置 ffmpegDir 或 SKIA_BINARIES_URL 等环境变量——一切通过 pkg-config 和 binary-cache 自动完成。如果使用了非标准路径安装 FFmpeg,在构建前设置 FFMPEG_DIR 即可。

Who is it for

  • AI 视频管线:模型输出 JSX,引擎渲染视频,接入成本最低
  • Web 应用:浏览器内集成视频渲染 / 编辑,无需服务器
  • 程序化动画:确定性 GPU 加速渲染,跨机器输出一致
  • 批量生产:组件化视频,换 props = 换一个视频

Reference

Community

Star History

License

MIT License