指标	目标值	说明
首帧渲染	< 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

开发

环境准备

# 安装依赖
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)

v2.1.0 (Q2 2024)

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

v2.2.0 (Q3 2024)

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

许可证

MIT License

支持

致谢

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

Keywords

FAQs

What is @meframe/core?

Is @meframe/core popular?

Is @meframe/core well maintained?

Package last updated on 11 Jan 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@meframe/core

MEFrame Core

概述

核心特性

性能指标