MEFrame Core

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

概述

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

$3

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

$3

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

快速开始

$3

``bash
npm install @meframe/core
`

$3

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

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

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

$3

`typescript
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',
});
`

$3

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

$3

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

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

API 参考

$3

#### 创建实例

`typescript
static async create(config: CoreConfig): Promise
`

#### 合成树管理

`typescript
async setCompositionTree(model: CompositionModel): Promise
async applyPatch(patch: CompositionPatch): Promise
`

#### 预览控制

`typescript
startPreview(options?: PreviewOptions): PreviewHandle
`

#### 导出

`typescript
async export(options: ExportOptions): Promise
`

$3

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

$3

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

架构设计

$3

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

$3

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

$3

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

性能优化

$3

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

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

$3

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

$3

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

浏览器兼容性

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

迁移指南

$3

主要变化：

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

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

相关文档

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

开发

$3

`bash


安装依赖

npm install

启动开发服务器

npm run dev

运行测试

npm test

构建

npm run build
`

$3

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

$3

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

路线图

$3

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

$3

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

$3

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

许可证

MIT License

支持

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

致谢

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

- MP4Box.js