@meframe/core

MEFrame Core

新一代高性能浏览器端视频合成引擎

概述

MEFrame Core 是完全重新设计的视频处理引擎，基于 WebCodecs API 和 Worker 并行架构，提供毫秒级响应的视频编辑和秒级导出能力。

核心特性

• 六阶段处理模型 - Load → Demux → Decode → Compose → Encode → Mux/Export
• Worker 并行架构 - 充分利用多核 CPU，各阶段独立并行处理
• 双层缓存系统 - L1 VRAM + L2 IndexedDB，智能缓存管理
• 流式处理 - 边加载边处理，优化首帧时间
• 增量更新 - 基于 Patch 的细粒度更新，最小化重渲染

性能指标

指标	目标值	说明
首帧渲染	< 100ms	从加载到显示第一帧
Seek 响应	< 50ms	缓存命中情况下
播放帧率	> 29.97 fps	1080p 多轨合成
导出速度	> 2x 实时	1080p H.264 编码
内存占用	< 500MB	典型项目场景

快速开始

安装

npm install @meframe/core

配置 Vite 插件

// vite.config.ts
import { defineConfig } from 'vite';
import { meframePlugin } from '@meframe/core/vite-plugin';

export default defineConfig({
  plugins: [
    meframePlugin(), // 必需：复制 worker 文件到输出目录
  ],
});

为什么需要插件？ Worker 文件在 node_modules 中，生产环境需要复制到输出目录才能访问。插件会自动处理这个过程。

基础使用

import { Meframe } from '@meframe/core';
import { parseDSL } from '@meframe/dsl-parser'; // 可选：DSL 解析

// 1. 创建实例
const core = await Meframe.create();

// 2. 设置合成树（两种方式）

// 方式一：直接使用标准模型格式
// CompositionModel 是引擎的标准输入模型，定义了明确的数据契约
const compositionTree = {
  version: '1.0',
  fps: 30,
  durationUs: 10_000_000, // 10 seconds
  root: {
    type: 'group',
    id: 'root',
    startUs: 0,
    durationUs: 10_000_000,
    children: [
      {
        type: 'video',
        id: 'video-1',
        src: 'https://example.com/video.mp4',
        startUs: 0,
        durationUs: 5_000_000,
      },
      {
        type: 'caption',
        id: 'caption-1',
        text: 'Hello World',
        startUs: 1_000_000,
        durationUs: 3_000_000,
        style: {
          fontSize: 48,
          color: '#ffffff',
        },
      },
    ],
  },
};

await core.setCompositionTree(compositionTree);

// 方式二：使用 DSL Parser（业务 DSL → CompositionModel）
const dsl = await fetch('/project.json').then((r) => r.json());
const model = parseDSL(dsl); // 转换为标准格式
await core.setCompositionTree(model);

// 3. 开始预览
const preview = core.startPreview();
preview.play();

// 4. 导出视频
const blob = await core.export({
  preset: 'high',
  container: 'mp4',
});

增量更新

// 应用局部更新
await core.applyPatch({
  version: '1.0',
  operations: [
    {
      type: 'update',
      nodeId: 'caption-1',
      updates: {
        text: 'Updated Text',
      },
    },
  ],
});

插件使用

import { PerfMonitorPlugin } from '@meframe/core/plugins';

const core = await Meframe.create({
  canvas,
  workerBaseUrl: '/workers/',
  plugins: [
    new PerfMonitorPlugin({
      overlay: true,
      sampleRate: 60,
    }),
  ],
});

API 参考

Meframe

创建实例

static async create(config: CoreConfig): Promise<Meframe>

合成树管理

async setCompositionTree(model: CompositionModel): Promise<void>
async applyPatch(patch: CompositionPatch): Promise<void>

预览控制

startPreview(options?: PreviewOptions): PreviewHandle

导出

async export(options: ExportOptions): Promise<Blob>

PreviewHandle

interface PreviewHandle {
  play(): void;
  pause(): void;
  seek(timeUs: number): void;
  setRate(rate: number): void;
  getCurrentTime(): number;
  on(event: string, handler: Function): void;
}

CompositionModel

interface CompositionModel {
  version: '1.0';
  fps: 24 | 25 | 30 | 60;
  durationUs: number;
  root: GroupNode;
  renderConfig?: {
    width: number;
    height: number;
    background?: string;
  };
}

架构设计

系统架构图

┌─────────────────────────────────────────────────────────┐
│                      Main Thread                         │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Meframe │  │ Orchestrator │  │ CacheManager │  │
│  └─────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────┬───────────────────────────────┘
                          │ MessageChannel
┌─────────────────────────┴───────────────────────────────┐
│                      Worker Threads                      │
│  ┌────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │DecodeWorker│  │ComposeWorker│  │EncodeWorker   │  │
│  └────────────┘  └─────────────┘  └────────────────┘  │
│                  ┌─────────────┐                        │
│                  │  MuxWorker  │                        │
│                  └─────────────┘                        │
└──────────────────────────────────────────────────────────┘

数据流

Input Stream
    ↓
[ResourceLoader] → ReadableStream
    ↓
[DecodeWorker] → VideoFrame/AudioData
    ↓
[ComposeWorker] → Composed VideoFrame
    ↓
[EncodeWorker] → EncodedChunk
    ↓
[MuxWorker] → MP4/WebM Blob
    ↓
Output File

缓存架构

┌─────────────────────────────────────┐
│         Cache Manager               │
├─────────────────────────────────────┤
│  L1: VRAM (VideoFrame)             │
│  - LRU eviction                     │
│  - ~90 frames @ 1080p              │
├─────────────────────────────────────┤
│  L2: IndexedDB (EncodedChunk)      │
│  - Compressed storage               │
│  - Persistent across sessions       │
└─────────────────────────────────────┘

性能优化

内存管理

// 显式释放资源
videoFrame.close();

// 配置缓存限制
const core = await Meframe.create({
  cache: {
    l1: { maxMemoryMB: 200 },
    l2: { maxSizeMB: 1000 },
  },
});

预渲染策略

// 配置预渲染窗口
core.setPreRenderWindow({
  forward: 10_000_000, // 10s ahead
  backward: 2_000_000, // 2s behind
});

降级处理

// 配置质量自适应
core.setAdaptiveQuality({
  enabled: true,
  targetFPS: 30,
  minQuality: 'low',
  maxQuality: 'high',
});

浏览器兼容性

浏览器	最低版本	说明
Chrome	94+	完整支持
Edge	94+	完整支持
Safari	16.4+	需要开启实验性功能
Firefox	-	暂不支持 WebCodecs

迁移指南

从 v1 迁移

主要变化：

• 时间单位 - 所有时间值改为微秒（microseconds）
• 八阶段 → 六阶段 - 简化的处理模型
• 新的数据结构 - CompositionModel 替代 Storyboard
• Worker 架构 - 所有重计算移至 Worker

详细迁移步骤请参考 MIGRATION.md

相关文档

• 架构总览 - 架构设计
• 技术实现 - 详细技术方案
• API 契约 - 完整 API 定义
• 实现计划 - 项目结构和技术架构
• 开发任务 - 任务列表和进度跟踪
• DSL Parser - DSL 解析包架构

开发

环境准备

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 运行测试
npm test

# 构建
npm run build

项目结构

packages/core-next/
├── src/           # 源代码
├── tests/         # 测试文件
├── examples/      # 示例代码
├── docs/          # 文档
└── benchmarks/    # 性能测试

贡献指南

• Fork 项目
• 创建特性分支 (git checkout -b feature/amazing)
• 提交更改 (git commit -m 'Add amazing feature')
• 推送分支 (git push origin feature/amazing)
• 创建 Pull Request

路线图

v2.0.0 (Current)

• 基础架构设计
• Worker 架构实现
• 双层缓存系统
• 插件系统
• 性能优化

v2.1.0 (Q2 2024)

• WebGPU 渲染加速
• 实时协作支持
• AI 辅助编辑

v2.2.0 (Q3 2024)

• 3D 素材支持
• 高级特效系统
• 云端渲染集成

许可证

MIT License

支持

• 文档：https://meframe.dev
• Issues：GitHub Issues
• 讨论：GitHub Discussions

致谢

感谢所有贡献者和以下开源项目：

• WebCodecs API
• MP4Box.js
• Web Workers