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 迁移

主要变化：

1. 时间单位 - 所有时间值改为微秒（microseconds）
2. 八阶段 → 六阶段 - 简化的处理模型
3. 新的数据结构 - CompositionModel 替代 Storyboard
4. 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/    # 性能测试

贡献指南

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

路线图

v2.0.0 (Current)

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

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