@channek/project-format

Channek 工程文件（.channek）的格式脊柱：类型 + 有理时间 + 编辑操作 + 读写校验迁移。 零运行时依赖。

npm i @channek/project-format

它解决什么

一份时间轴工程要被多方读写——界面、引擎、AI、导出——只要各自平行定义一份 clip / track / 时间结构，它们就会慢慢漂开，而漂开的症状是「导出与预览对不上」这种最难查的 bug。 这个包是那份唯一定义。

import { parseProject, serializeProject, validateProject } from '@channek/project-format';

const project = parseProject(await readFile('demo.channek', 'utf8'));
const issues = validateProject(project);   // 空数组 = 合法
await writeFile('demo.channek', serializeProject(project));

时间一律是有理数，不是浮点秒

import type { RationalTime } from '@channek/project-format';

const t: RationalTime = { value: 1001, rate: 30000 };   // 恰好 1 帧 @ 29.97fps

浮点秒在 29.97 这类非整数帧率下会累积漂移，剪 20 分钟的片子足以让末尾差出一帧；而「差一帧」 在时间轴上就是黑场或错帧。工程文件里不出现浮点秒，也不出现裸帧号——裸帧号换个帧率就失真。 time.js 里有配套的 TimeRange 与换算工具。

改文档只有一条路：编辑操作

不要直接 mutate 解析出来的对象。所有改动都表达成 EditOperation 打进 reducer—— 每次编辑因此天然可撤销、可预览、可审计，人手拖拽与 AI 工具调用走的是同一条路。

版本迁移

import { upgradeProject, downgradeProject } from '@channek/project-format';

旧版本文件读进来先 upgradeProject 升到当前 schema。parseProject 会替你做这件事； 单独导出它是为了让你能在迁移前后做对比。

稳定性

0.x 阶段 API 可能有破坏性变更，升级前看 CHANGELOG。破坏性变更只在次版本号上发生 （0.1.x → 0.2.0），补丁号恒向后兼容。

许可

Apache-2.0。本许可只覆盖这个包——Channek 应用本体、引擎与编辑模型不在其列。