@meframe/core

# 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_VNEXT.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-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](https://meframe.dev) - Issues：[GitHub Issues](https://github.com/meframe/core-next/issues) - 讨论：[GitHub Discussions](https://github.com/meframe/core-next/discussions) ## 致谢感谢所有贡献者和以下开源项目： - [WebCodecs API](https://www.w3.org/TR/webcodecs/) - [MP4Box.js](https://github.com/gpac/mp4box.js) - [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)