功能导览与项目目录

一条完整用户路径

阶段	UI 操作	状态或产物	主要实现
导入	点测试素材或“选择 MP4”	Project Asset + 运行时 source	Media Worker + Mediabunny
代理	导入后自动开始，可取消	OPFS `proxy.mp4`、WebP、`waveform.f32`	Proxy Worker + WASM
编辑	添加片段、裁剪、分割、标题、滤镜	revision 递增的纯 JSON	Command Bus + Redux
预览	播放、逐帧、拖动 Seek	Worker 解码帧、PixiJS Scene Graph	RxJS + ECS
导出	点“开始导出”	OPFS H.264/AAC MP4 + 下载 URL	Export Worker
调试	切换日志/JSON/能力/同步	JSONL、队列、资源、漂移指标	observability

正式编辑器支持设置工程总时长和时间线缩放。总时长会保存到 Project，并且不能短于最长内容；缩放只改变像素密度和横向滚动，不改变工程时间。视频轨、音频轨和文字轨都按 track.order 显示和重排；视频/文字低 order 先画，高 order 后画，音频轨按工程时间混合，静音轨不参与播放或导出。添加素材默认落在当前播放头，也可以选择追加到当前目标轨尾。片段可在同类型轨道间拖动，跨类型拖动会被拒绝；删除含内容轨道需要确认，确认后级联删除该轨道内容。旧工程保留默认 video-track、audio-track、text-track，继续作为 V1/A1/T1 使用。文字轨可继续新增为 T2/T3；“添加标题”写入当前目标文字轨，标题属性面板可编辑显示时间、字号、文字颜色、描边、背景透明度和字体。系统字体枚举不可用或未授权时，仍可使用常用字体预设或手动字体名，预览和导出消费同一组 TextItem 字段以保持时间范围和样式一致。运行时结构、导出合成和导入边界见多轨道编辑。当前仍不包含多人协作、云上传、AI、复杂转场、专业调色或 FFmpeg 全格式兜底。

需要引入 HTML 动画、Three.js / WebGPU 或独立包装层时，参见 HyperFrames：素材、二次编辑与透明包装轨道。该专题区分上游已有能力与本编辑器的待接入方案；当前尚未集成 HyperFrames 工程导入或透明导出。

页面入口

/：编辑器。
/mobx.html：不写正式工程的 MobX 对照实验。
/preview.html：独立预览实验。
/sync-debug.html：音频主时钟和 SAB 环形缓冲调试。
http://localhost:5174：本 VitePress 站点。

目录与依赖方向

text

apps/
  editor/             React UI、Redux、Worker 入口、E2E
  docs/               本中文 VitePress 站点
packages/
  domain/             Project schema、校验、Command、Undo/Redo
  observability/      日志 schema、sink、requestId
  media-wasm/         Rust crate、wasm-bindgen、TS 包装
  media-runtime/      Worker 协议、RxJS、探测、代理、OPFS、同步
  preview-runtime/    ECS adapter、systems、PixiJS、解码客户端
test_assets/          三份只读 MP4
scripts/              verify 与文档校验

依赖从应用指向包：editor -> preview-runtime -> media-runtime，领域与日志包不依赖 UI； Redux 不保存 Worker、File、ArrayBuffer、VideoFrame、Pixi 对象。

复现与预期输出

bash

pnpm dev:editor

依次点击 test_1.mp4、“添加到时间线”、“添加标题”、“开始导出”。

text

UI: Project Assets 0 -> 1；REV 持续递增
UI: PROXY PIPELINE RUNNING -> READY（或主动 CANCELLED）
UI: Project JSON 中只有 JSON 值，不出现 File/ArrayBuffer/VideoFrame
Console: [IMPORT] -> [COMMAND] -> [ECS]/[RENDER] -> [EXPORT]
CLI: Vite 输出 Local: http://localhost:5173/

源码证据

页面装配和数据所有权：apps/editor/src/App.tsx
workspace 脚本与包边界：package.json
编辑器依赖版本：apps/editor/package.json
核心用户路径测试：apps/editor/e2e/task12-core.spec.ts

从总体架构与线程开始按层阅读。媒体基础概念可先看 MP4 文件格式详解和帧编码格式 RGB / YUV / YCbCr，预览取帧细节可看预览 Worker 解码链路。

功能导览与项目目录 ​

一条完整用户路径 ​

页面入口 ​

目录与依赖方向 ​

复现与预期输出 ​