JSPM

  • Created
  • Published
  • Downloads 592
  • Score
    100M100P100Q98660F
  • License MIT

Next generation media processing framework based on WebCodecs

Package Exports

  • @meframe/core
  • @meframe/core/cache
  • @meframe/core/model
  • @meframe/core/node
  • @meframe/core/plugins
  • @meframe/core/vite-plugin
  • @meframe/core/workers

Readme

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

相关文档

开发

环境准备

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 运行测试
npm test

# 构建
npm run build

项目结构

packages/core/
├── 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)

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

v2.1.0 (Q2 2024)

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

v2.2.0 (Q3 2024)

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

许可证

MIT License

支持

致谢

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