@meframe/core 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1] - 2025-10-08
+
+### Added
+
+- Initial release of @meframe/core
+- Six-stage processing pipeline: Load → Demux → Decode → Compose → Encode → Mux/Export
+- Worker-based parallel architecture
+- Dual-layer cache system (L1 VRAM + L2 IndexedDB)
+- Streaming processing support
+- Incremental update via patch system
+- Plugin system foundation
+- Basic composition model support
+- Preview and export capabilities
+
+### Features
+
+- WebCodecs-based video/audio processing
+- Multi-track composition
+- Real-time preview with playback control
+- Video export to MP4/WebM
+- Performance monitoring plugin
+- Resource loading and management
+- Cache-aware rendering
+
+### Documentation
+
+- Architecture overview
+- API reference
+- Quick start guide
+- Migration guide from v1
+
+[Unreleased]: https://github.com/one2x-ai/meframe/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/one2x-ai/meframe/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Sheepy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,396 @@
+# 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
+```
+
+### 基础使用
+
+```typescript
+import { Meframe } from '@meframe/core';
+import { parseDSL } from '@meframe/dsl-parser'; // 可选：DSL 解析
+
+// 1. 创建实例
+const core = await Meframe.create({
+  canvas: document.getElementById('preview'),
+  workerBaseUrl: '/workers/',
+});
+
+// 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)

package/dist/Meframe.d.ts

@@ -0,0 +1,82 @@
+import { MeframeConfig, ResolvedConfig, MeframeState, ExportOptions } from './types';
+import { CompositionModelData, CompositionPatch, TimeUs } from './model/types';
+import { PreviewHandle } from './controllers/types';
+import { CompositionModel } from './model/CompositionModel';
+import { PluginManager } from './plugins/PluginManager';
+import { EventBus } from './event/EventBus';
+import { EventPayloadMap } from './event/events';
+
+export declare class Meframe {
+    /** Current state - managed internally via setState() */
+    state: MeframeState;
+    /** Configuration - immutable after construction */
+    readonly config: ResolvedConfig;
+    /** Composition model - managed via setCompositionTree() */
+    model: CompositionModel | null;
+    /** Plugin manager for extensions */
+    readonly pluginManager: PluginManager;
+    /** Event bus for subscribing to Meframe events */
+    readonly events: Pick<EventBus<EventPayloadMap>, 'on' | 'off' | 'once'>;
+    private orchestrator;
+    private eventBus;
+    private playbackController;
+    private preRenderService;
+    private canvas?;
+    private constructor();
+    /**
+     * Create a new Meframe instance
+     */
+    static create(config?: MeframeConfig): Promise<Meframe>;
+    /**
+     * Initialize the core engine
+     */
+    private initialize;
+    /**
+     * Set the composition model
+     */
+    setCompositionModel(model: CompositionModel | CompositionModelData): Promise<void>;
+    /**
+     * Apply a patch to the composition model
+     */
+    applyPatch(patch: CompositionPatch): Promise<void>;
+    /**
+     * Start preview and return a handle for control
+     */
+    startPreview(options?: {
+        canvas?: HTMLCanvasElement | OffscreenCanvas;
+        startUs?: TimeUs;
+    }): PreviewHandle;
+    /**
+     * Export the composition
+     */
+    export(options: ExportOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Run the export pipeline
+     */
+    private runExportPipeline;
+    /**
+     * Export to buffer (convenience method)
+     */
+    exportToBuffer(options: ExportOptions): Promise<ArrayBuffer>;
+    /**
+     * Get current playback time
+     */
+    getCurrentTime(): number;
+    /**
+     * Clean up and destroy the instance
+     */
+    dispose(): Promise<void>;
+    /**
+     * Set internal state
+     */
+    private setState;
+    /**
+     * Ensure the instance is not destroyed
+     */
+    private ensureNotDestroyed;
+    /**
+     * Ensure the instance is ready
+     */
+    private ensureReady;
+}
+//# sourceMappingURL=Meframe.d.ts.map

package/dist/Meframe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Meframe.d.ts","sourceRoot":"","sources":["../src/Meframe.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAM5D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGpE,qBAAa,OAAO;IAClB,wDAAwD;IACxD,KAAK,EAAE,YAAY,CAAU;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2DAA2D;IAC3D,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IACtC,oCAAoC;IACpC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC;IAExE,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,kBAAkB,CAAmC;IAC7D,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,MAAM,CAAC,CAAsC;IAErD,OAAO;IAeP;;OAEG;WACU,MAAM,CAAC,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAQjE;;OAEG;YACW,UAAU;IAyBxB;;OAEG;IACG,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBxF;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxD;;OAEG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE;QACrB,MAAM,CAAC,EAAE,iBAAiB,GAAG,eAAe,CAAC;QAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,aAAa;IA+BjB;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IA+EzE;;OAEG;YACW,iBAAiB;IA8C/B;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC;IA0BlE;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB9B;;OAEG;IACH,OAAO,CAAC,QAAQ;IAYhB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;OAEG;IACH,OAAO,CAAC,WAAW;CAWpB"}