Fkbuilder

fkbuilder Skill

fkbuilder - Node.js 程序化视频创作库，通过代码 API 创建视频。

1. 快速开始

安装

npm install fkbuilder

代码渲染

import { VideoBuilder } from 'fkbuilder';

const builder = new VideoBuilder({
  width: 1280,
  height: 720,
  fps: 30,
});

const track = builder.createTrack({ zIndex: 1 });

const scene = track.createScene({ duration: 3, startTime: 0 });
scene.addBackground({ color: '#0f0f23' });
scene.addText({
  text: 'Hello World',
  x: '50%', y: '50%',
  fontSize: 72, fontFamily: 'Arial',
  color: '#ffffff', textAlign: 'center', textBaseline: 'middle',
  duration: 3,
});

const outputPath = './output/video.mp4';
await builder.render(outputPath);

2. VideoBuilder 主类

构造函数

const builder = new VideoBuilder({
  width: 1920,      // 视频宽度，默认 1920
  height: 1080,     // 视频高度，默认 1080
  fps: 30,          // 帧率，默认 30
});

核心方法

render 选项

await builder.render(outputPath, {
  parallel: false,    // 是否并行渲染，默认 true
  usePipe: true,      // 使用管道模式（不保存中间帧），默认 true
});

3. Track 轨道

创建轨道

const track = builder.createTrack({
  zIndex: 1,          // 层级顺序，数字越大越上层
  name: 'main',       // 轨道名称（可选）
});

轨道方法

4. Scene 场景

创建场景

const scene = track.createScene({
  duration: 3,           // 持续时间（秒）
  startTime: 0,          // 开始时间（秒），可选
});

场景方法

背景配置

scene.addBackground({ color: '#0f0f23' });
// 或
scene.addBackground({ image: './bg.png' });

5. 元素通用属性

所有元素都支持以下属性：

坐标系统

• 原点在画布左上角 (0, 0)
• 使用 "50%" 可以相对于画布中心定位
• anchor 影响旋转和缩放的中心点

6. 文本元素 (Text)

scene.addText({
  text: 'FOLIKO',
  x: '50%', y: '40%',
  fontSize: 120,
  fontFamily: 'Arial Black',
  fontWeight: 'bold',
  fontStyle: 'normal',
  color: '#ffffff',
  textAlign: 'center',      // left/center/right
  textBaseline: 'middle',   // top/middle/bottom
  lineHeight: 1.2,
  duration: 3,
  startTime: 0,
  animations: ['zoomIn'],

  // 文字阴影
  textShadow: true,
  textShadowColor: '#6366f1',
  textShadowBlur: 30,
  textShadowOffsetX: 2,
  textShadowOffsetY: 2,

  // 文字描边
  stroke: true,
  strokeColor: '#000000',
  strokeWidth: 2,

  // 渐变
  gradient: true,
  gradientColors: ['#FF6B6B', '#4ECDC4'],
  gradientDirection: 'horizontal',

  // 拆分动画
  split: 'letter',        // letter/word/line
  splitDelay: 0.1,
  splitDuration: 0.3,
});

7. 矩形元素 (Rect)

scene.addRect({
  x: '50%', y: '50%',
  width: 600,
  height: 60,
  bgcolor: '#1e1b4b',
  borderRadius: 10,
  borderWidth: 2,
  borderColor: '#22c55e',
  shadowBlur: 25,
  shadowColor: '#6366f1',
  shadowOffsetX: 0,
  shadowOffsetY: 0,
  opacity: 0.9,
  rotation: 0,
  anchor: [0.5, 0.5],
  duration: 3,
  startTime: 0,
  animations: ['fadeIn'],
});

8. 圆形元素 (Circle)

scene.addCircle({
  x: '50%', y: '50%',
  radius: 100,
  color: '#ffffff',
  fill: true,
  borderWidth: 2,
  borderColor: '#8b5cf6',
  opacity: 0.8,
  rotation: 0,
  anchor: [0.5, 0.5],
  duration: 3,
  startTime: 0,
  animations: ['zoomIn'],
});

9. 图片元素 (Image)

scene.addImage({
  src: './assets/logo.png',
  x: '50%', y: '50%',
  width: 200,
  height: 200,
  fit: 'cover',         // cover/contain/fill/none
  borderRadius: 0,
  flipX: false,
  flipY: false,
  brightness: 1,        // 0-2
  contrast: 1,          // 0-2
  saturation: 1,        // 0-2
  duration: 3,
  startTime: 0,
  animations: ['fadeIn'],
});

10. 视频元素 (Video)

scene.addVideo({
  src: './assets/clip.mp4',
  x: 0, y: 0,
  width: 1920,
  height: 1080,
  cutFrom: 0,           // 裁剪起始（秒）
  cutTo: undefined,     // 裁剪结束（秒）
  speedFactor: 1,       // 播放速度
  loop: false,
  mute: true,
  volume: 1,
  duration: 10,
  startTime: 0,
});

11. SVG 元素

scene.addSVG({
  src: './assets/icon.svg',
  x: '50%', y: '50%',
  width: 100,
  height: 100,
  fit: 'contain',
  preserveAspectRatio: true,
  enableSVGAnimations: true,
  duration: 3,
  startTime: 0,
  animations: ['zoomIn'],
});

12. HTML 元素 (HTMLElement)

使用 Takumi 渲染任意 HTML/CSS 为视频元素，特别适合使用 CSS @keyframes 动画。

安装依赖

npm install @takumi-rs/core @takumi-rs/helpers

基础用法

scene.addHtml({
  x: 0, y: 0, width: 1280, height: 720, anchor: [0, 0],
  html: `
    <div style="width:100%;height:100%;display:flex;align-items:center;justify-content:center;background:#1e1b4b;">
      <h1 style="color:white;font-size:64px;">Hello World</h1>
    </div>
  `,
  duration: 5,
});

CSS @keyframes 动画

通过 timeMs 自动注入，CSS 动画与视频时间轴同步：

scene.addHtml({
  x: 0, y: 0, width: 1280, height: 720, anchor: [0, 0],
  html: `
    <style>
      @keyframes spin { to { transform: rotate(360deg); } }
      @keyframes pulse {
        0%, 100% { transform: scale(1); opacity: 1; }
        50% { transform: scale(1.1); opacity: 0.8; }
      }
      .spinner {
        width: 120px; height: 120px;
        border: 8px solid rgba(255,255,255,0.1);
        border-top-color: #a78bfa;
        border-radius: 50%;
        animation: spin 1s linear infinite;
      }
      .title {
        font-family: system-ui;
        color: white;
        font-size: 64px;
        animation: pulse 2s ease-in-out infinite;
      }
    </style>
    <div style="width:100%;height:100%;display:flex;flex-direction:column;align-items:center;justify-content:center;">
      <div class="spinner"></div>
      <div class="title">Loading</div>
    </div>
  `,
  duration: 5,
});

中文字体支持（默认开启）

HTMLElement 默认开启中文字体支持，无需手动指定 fonts：

• Windows: 微软雅黑 (Microsoft YaHei)、黑体 (SimHei)、宋体 (SimSun)
• macOS: 苹方 (PingFang SC)、华文黑体 (STHeiti)、宋体 (Songti SC)
• Linux: 文泉驿微米黑、文泉驿正黑、Noto Sans CJK SC

// ✅ 直接使用，默认就有中文支持
scene.addHtml({
  html: `<div style="font-size:48px;">你好世界</div>`,
  duration: 4,
  // 无需指定 fonts
});

// ✅ 自定义 fonts 覆盖默认
scene.addHtml({
  html: `<div style="font-family:'Microsoft YaHei';font-size:48px;">中文标题</div>`,
  duration: 4,
  fonts: [
    { path: 'C:/Windows/Fonts/msyh.ttc', family: 'Microsoft YaHei' },
    { path: 'C:/Windows/Fonts/simhei.ttf', family: 'SimHei' },
  ],
});

多场景示例

每个 Scene 必须在不同的 track 上：

// Scene 1: 0-4 秒（loading 动画）
builder.createTrack()
  .createScene({ duration: 4 })
    .addBackground({ color: '#1e1b4b' })
    .addHtml({ x: 0, y: 0, width: 1280, height: 720, anchor: [0, 0],
      html: loadingHtml, duration: 4 });

// Scene 2: 4-8 秒（CSS @keyframes 动画）
builder.createTrack()         // ⚠️ 必须用新 track
  .createScene({ duration: 4, startTime: 4 })
    .addBackground({ color: '#0c0a09' })
    .addHtml({ x: 0, y: 0, width: 1280, height: 720, anchor: [0, 0],
      html: keyframeHtml, duration: 4,
      fonts: [{ path: 'C:/Windows/Fonts/msyh.ttc', family: 'Microsoft YaHei' }] });

await builder.render('output/html-keyframes.mp4', { parallel: true });

配置选项

字体配置

// URL 方式
fonts: ['https://fonts.googleapis.com/css2?family=Roboto']

// 系统字体路径
fonts: [{ path: 'C:/Windows/Fonts/msyh.ttc', family: 'Microsoft YaHei' }]

// Buffer 方式
fonts: [{ data: fontBuffer }]

与 FKbuilder 动画结合

scene.addHtml({
  html: '<div style="color:white;font-size:48px;">Welcome</div>',
  duration: 5,
  animations: [
    { type: 'transform', from: { opacity: 0, x: -100 }, to: { opacity: 1, x: 0 }, duration: 1, easing: 'easeOut' },
    'fadeIn',
  ],
});

单独渲染帧（导出函数）

import { renderHtmlFrame } from 'fkbuilder';

const rgba = await renderHtmlFrame({
  html: '<div style="color:red;">Test</div>',
  width: 1280,
  height: 720,
  timeMs: 0,
});
// rgba: width * height * 4 的 Buffer（RGBA 格式）

集成 Tailwind CSS

# 1. 安装 Tailwind v4
npm install -D tailwindcss @tailwindcss/cli

# 2. 创建 tailwind-input.css
# @import "tailwindcss";
# @theme {
#   --color-brand: #FF6B6B;
# }

# 3. 编译
npx tailwindcss build -i tailwind-input.css -o output/tailwind/tailwind.css --minify

import fs from 'fs-extra';

const tailwindCss = fs.readFileSync('output/tailwind/tailwind.css', 'utf8');

scene.addHtml({
  x: 0, y: 0, width: 1280, height: 720, anchor: [0, 0],
  html: `
    <style>${tailwindCss}</style>
    <style>
      @keyframes float {
        0%, 100% { transform: translateY(0); }
        50% { transform: translateY(-20px); }
      }
      .float { animation: float 3s ease-in-out infinite; }
    </style>
    <div class="min-h-screen bg-gradient-to-br from-purple-600 to-blue-500 flex items-center justify-center">
      <h1 class="text-7xl font-bold text-white float">FKbuilder + Tailwind</h1>
    </div>
  `,
  duration: 5,
});

✅ 完全离线，所有 utility 类生效，自定义 @keyframes 正常。

CDN 方式（更快但功能受限）：

html: `<script src="https://cdn.tailwindcss.com"></script>
<div class="bg-gradient-to-br from-purple-600 to-blue-500 ...">`

⚠️ Takumi 不执行 <script>，hover 等 JS 事件不生效，但 CSS 样式和动画正常。

完整示例：examples/html-element-with-tailwind.js

注意事项

1. 锚点 (anchor) 设置

anchor 控制元素"哪个角"对齐到 (x, y)：

• anchor: [0, 0] → 元素左上角对齐 (x, y)
• anchor: [0.5, 0.5] → 元素中心点对齐 (x, y)
• anchor: [1, 1] → 元素右下角对齐 (x, y)

全屏 HTML 必须用 anchor: [0, 0] + x: 0, y: 0：

// ✅ 正确：全屏 HTML 左上角对齐画布左上角
.addHtml({
  x: 0, y: 0, width: 1280, height: 720, anchor: [0, 0],
  html: '...',
})

// ❌ 错误：anchor 默认值 [0.5, 0.5] + x: 0, y: 0
// 会导致元素偏移 (-640, -360)，元素一半在画布外看不见！
.addHtml({
  x: 0, y: 0, width: 1280, height: 720,
  // anchor 默认为 [0.5, 0.5]，元素中心对齐到 (0, 0)
  // 元素最终位置: x = 0 - 1280*0.5 = -640 (超出画布)
  html: '...',
})

居中显示元素的两种方式：

// 方式 1: anchor [0, 0] + x/y 指向画布中心
.addHtml({ x: 640, y: 360, width: 200, height: 100, anchor: [0, 0], html: '...' })

// 方式 2: anchor [0.5, 0.5] + x/y 指向元素中心（即画布中心 640, 360）
.addHtml({ x: 640, y: 360, width: 200, height: 100, anchor: [0.5, 0.5], html: '...' })

2. 其它注意事项

1. 必须用不同 track：多个 HTML 场景必须各自 createTrack()，否则会被合并到同一图层导致时间累加错误
2. Worker 模式：parallel: true 时正常工作，Takumi 在每个 Worker 中独立初始化
3. 中文字体默认支持：HTMLElement 自动加载系统常见中文字体，无需手动指定 fonts
4. 字体名称匹配：自定义 fonts 时，CSS 中 font-family 必须和 fonts 数组中的 family 名称一致
5. 不要多次调用 build()：builder.build() 后又调用 builder.render() 会触发重复构建
6. 完整示例：examples/html-element-basic.js、examples/html-element-keyframes.js、examples/html-element-with-font.js、examples/html-element-with-tailwind.js

13. 音频元素 (Audio)

scene.addAudio({
  src: './assets/music.mp3',
  volume: 0.8,
  fadeIn: 2,            // 淡入时长（秒）
  fadeOut: 2,           // 淡出时长（秒）
  cutFrom: 0,
  cutTo: undefined,
  loop: false,
  startTime: 0,
  duration: 30,
});

14. 歌词字幕 (LRC)

从 LRC 文件加载歌词字幕，支持多时间标签格式 [03:06.90][02:33.64]歌词内容。

// 方式1：从 LRC 文件加载（推荐）
scene.addLRC('./assets/lyrics.lrc', {
  x: '50%', y: '85%',
  fontSize: 48,
  fontFamily: 'Microsoft YaHei',
  textColor: '#ffffff',
  textAlign: 'center',
  split: 'line',
  splitDuration: 0.3,
});

// 方式2：使用 addSubtitles 加载 LRC
scene.addSubtitles({
  src: './assets/lyrics.lrc',
  x: '50%', y: '85%',
  fontSize: 48,
  fontFamily: 'Microsoft YaHei',
  textColor: '#ffffff',
  textAlign: 'center',
});

LRC 字幕选项

15. 示波器元素 (Oscilloscope)

音频可视化波形显示，支持多种样式。

scene.addOscilloscope({
  audioPath: './assets/music.mp3',  // 音频文件路径
  x: '50%', y: '50%',
  width: 400,
  height: 200,
  waveColor: '#00ff00',           // 波形颜色
  backgroundColor: 'rgba(0, 0, 0, 0.3)', // 背景颜色
  lineWidth: 2,                   // 线条宽度
  smoothing: 0.3,                  // 平滑度 (0-1)
  mirror: true,                    // 是否镜像显示
  style: 'line',                  // 样式类型
  sensitivity: 1.0,                // 灵敏度
  cutFrom: 0,                      // 裁剪起始（秒）
  cutTo: undefined,                // 裁剪结束（秒）
  windowSize: 0.1,                 // 显示窗口大小（秒）
  scrollSpeed: 1.0,                // 滚动速度
  duration: 30,                    // 持续时间
  startTime: 0,
});

示波器样式

16. 字幕元素 (Subtitles)

scene.addSubtitles({
  text: 'Hello World',           // 直接文本内容
  x: '50%', y: '85%',
  fontSize: 72,
  fontFamily: 'PatuaOne',
  textColor: '#ffffff',
  position: 'center',
  textAlign: 'center',
  split: 'letter',
  splitDelay: 0.1,
  splitDuration: 0.3,
  maxLength: 20,
  duration: 5,
  startTime: 0,
});

17. 预设动画

使用字符串数组形式：

animations: ['zoomIn']
animations: ['fadeInUp']
animations: ['bigIn', 'bigOut']  // 多个动画组合

淡入/淡出

缩放

旋转

滑动

弹跳

其他

18. 转场效果 (Transition)

基本用法

// 不指定 startTime，系统自动推断转场位置
track.addTransition({ name: 'CrossZoom', duration: 0.5 });
track.addTransition({ name: 'Dreamy', duration: 0.5 });
track.addTransition({ name: 'fade', duration: 0.5 });

// 指定 startTime（可选）
track.addTransition({ name: 'CrossZoom', duration: 0.5, startTime: 2.5 });

转场行为要点

重要：转场在 GL 层面预渲染 fromFrame 和 toFrame，然后混合。

• fromScene 元素的 endTime 会被调整为 transitionStartTime（转场开始时间）
• toScene 的 startTime 会被覆盖为 transitionEndTime（转场结束时间）
• 转场期间（transitionStartTime ~ transitionEndTime），两个场景元素都不在主时间轴显示，由预渲染帧负责视觉混合

预渲染帧时间点：

• fromFrame 在 transitionStartTime - 0.001s 渲染（确保 fromScene 元素仍可见）
• toFrame 在 transitionEndTime 渲染（此时 toScene 元素已可见）

转场位置计算

当不指定 startTime 时：

• 转场居中在两个场景的交界处
• transitionStartTime = sceneEndTime - duration/2
• transitionEndTime = sceneEndTime + duration/2

例如：场景1 (0-3s) + 转场 (0.5s) + 场景2 (3-6s)

• 转场1: 2.75-3.25s
• 场景1 元素 endTime = 2.75
• 场景2 元素 startTime = 3.25

可用转场

19. onFrame 回调

scene.addCircle({
  x: '50%', y: '50%',
  radius: 100,
  duration: 5,
  onFrame: (el, ev, item) => {
    // el: 元素实例
    // ev: 事件对象 { time, delta, count }
    // item: Paper.js 渲染项

    // 旋转
    item.rotation = ev.time * 30;

    // 脉冲缩放
    const scale = 1 + Math.sin(ev.time * 4) * 0.1;
    item.scaleX = scale;
    item.scaleY = scale;

    // 闪烁
    item.opacity = 0.3 + Math.sin(ev.time * 5) * 0.4;
  },
});

20. 重要细节

0. 多次调用 builder.build() 会导致时间累加错误

builder.build() 会修改原始元素的 startTime 和 endTime 属性。如果先调用 build() 查看结构，再调用 builder.render()（内部又会调用 build()），元素时间会重复累加。

修复：Track.build 内部使用 _absoluteTimeSet 标记防止重复处理，但最佳实践是：直接调用 builder.render()，不要额外手动调用 builder.build()。

// ❌ 错误：先 build 再 render，会导致时间累加
const vm = builder.build();   // 第一次 build
await builder.render(path);    // 第二次 build（render 内部调用）

// ✅ 正确：直接 render
await builder.render(path);

1. 元素可见性判断

元素使用 < 而非 <= 判断结束：

isActiveAtTime(time) {
  return this.visible && time >= this.startTime && time < this.endTime;
}

这意味着元素在 endTime 时刻不再可见。

2. 元素时间系统

• scene.startTime: 场景开始时间（绝对时间）
• element.startTime: 元素相对于场景的开始时间
• element.duration: 元素的持续时间
• element.endTime: 元素的结束时间 = sceneStartTime + elementStartTime + duration

3. 元素时间不能超过场景时间

重要：元素的 endTime 不能超过场景的结束时间。超过的部分会被自动截断，并输出警告。

// 错误示例：元素的 endTime 超过了场景的结束时间
const scene = track.createScene({ duration: 3, startTime: 0 });
scene.addText({
  text: 'Hello',
  duration: 5,  // 错误！元素持续时间超过场景时间
});

// 正确示例：元素的 endTime 应在场景范围内
const scene = track.createScene({ duration: 3, startTime: 0 });
scene.addText({
  text: 'Hello',
  duration: 3,  // 正确：元素持续时间等于场景时间
});

转场时，系统以转场调整后的场景结束时间为准：

• 转场会缩短 fromScene 的 duration，使其在 transitionStartTime 结束
• 因此 fromScene 元素的 endTime 不能超过 transitionStartTime

4. 百分比坐标

坐标支持 "50%" 形式，表示画布中心：

x: '50%', y: '50%'  // 画布中心
x: '0%', y: '0%'    // 左上角
x: '100%', y: '100%' // 右下角

5. Scene.startTime 的影响

• 如果不设置 scene.startTime，系统会基于前一个场景的结束时间自动推断
• 当添加转场时，toScene.startTime 会被强制覆盖为 transitionEndTime

6. 音频需要特殊处理

音频元素通常应该添加到独立的音频轨道，或者在场景外添加：

// 方式1：全局音频
composition.addAudio({ src: './music.mp3', startTime: 0, volume: 0.5 });

// 方式2：通过 builder 的 audioTracks
builder.audioTracks = [{ src: './music.mp3', startTime: 0, volume: 0.5 }];

7. SVG 异步加载

SVG 元素需要异步加载，如果渲染时 SVG 还未加载完成，会导致问题。使用 initialize() 预加载：

await builder.initialize();  // 预加载所有资源
await builder.render(outputPath);

8. 字体注册

如果使用自定义字体，需要先注册：

import { registerFont } from 'fkbuilder';
registerFont('./fonts/CustomFont.ttf', 'CustomFont');

21. 完整示例

促销视频

import { VideoBuilder } from 'fkbuilder';
import path from 'path';

async function createPromoVideo() {
  const builder = new VideoBuilder({
    width: 1280,
    height: 720,
    fps: 30,
  });

  const track = builder.createTrack({ zIndex: 1 });

  // 场景 1: 标题 (0s - 3s)
  const scene1 = track.createScene({ duration: 3, startTime: 0 });
  scene1.addBackground({ color: '#0f0f23' });
  scene1.addText({
    text: 'FOLIKO',
    x: '50%', y: '40%',
    fontSize: 120, fontFamily: 'Arial Black', fontWeight: 'bold',
    color: '#ffffff', textAlign: 'center', textBaseline: 'middle',
    duration: 3,
    animations: ['zoomIn'],
    textShadow: true, textShadowColor: '#6366f1', textShadowBlur: 30,
  });

  // 场景 2: 特性展示 (3s - 6s)
  const scene2 = track.createScene({ duration: 3, startTime: 3 });
  scene2.addBackground({ color: '#1a1a2e' });
  scene2.addText({
    text: '40+ 插件',
    x: '50%', y: '30%',
    fontSize: 48, fontFamily: 'Arial', fontWeight: 'bold',
    color: '#8b5cf6', textAlign: 'center',
    duration: 3, animations: ['fadeInUp'],
  });

  // 转场（不指定 startTime，系统自动推断）
  track.addTransition({ name: 'CrossZoom', duration: 0.5 });
  track.addTransition({ name: 'Dreamy', duration: 0.5 });

  const outputPath = './output/promo.mp4';
  const result = await builder.render(outputPath, {
    parallel: false,
    usePipe: true,
  });

  console.log(`渲染完成: ${result}`);
}

createPromoVideo().catch(console.error);

22. 目录结构

project/
├── output/
│   └── video.mp4
├── examples/
│   └── render-video.mjs
└── assets/
    ├── music.mp3
    ├── image.png
    └── icon.svg