npm package: @meframe/core
Description: Next generation media processing framework based on WebCodecs
Author: Sheepy
Latest version: 0.4.6

# 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     | 典型项目场景       |

## 快速开始

### 安装

```bash
npm install @meframe/core
```

### 配置 Vite 插件

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

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

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

### 基础使用

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

### 增量更新

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

### 插件使用

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

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

## API 参考

### Meframe

#### 创建实例

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

#### 合成树管理

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

#### 预览控制

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

#### 导出

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

### PreviewHandle

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

### CompositionModel

```typescript
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       │
└─────────────────────────────────────┘
```

## 性能优化

### 内存管理

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

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

### 预渲染策略

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

### 降级处理

```typescript
// 配置质量自适应
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](./docs/MIGRATION.md)

## 相关文档

- [架构总览](./ARCHITECTURE.md) - 架构设计
- [技术实现](./TECHNICAL_IMPLEMENTATION.md) - 详细技术方案
- [API 契约](./API_CONTRACTS.md) - 完整 API 定义
- [实现计划](./IMPLEMENTATION_PLAN.md) - 项目结构和技术架构
- [开发任务](./IMPLEMENTATION_TASKS.md) - 任务列表和进度跟踪
- [DSL Parser](./DSL_PARSER_ARCHITECTURE.md) - DSL 解析包架构

## 开发

### 环境准备

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

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

### v2.1.0 (Q2 2024)

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

### v2.2.0 (Q3 2024)

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

## 许可证

MIT License

## 支持

- 文档：[https://meframe.dev](https://meframe.dev)
- Issues：[GitHub Issues](https://github.com/meframe/core/issues)
- 讨论：[GitHub Discussions](https://github.com/meframe/core/discussions)

## 致谢

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

- [MP4Box.js](https://github.com/gpac/mp4box.js)