HyperFrames Studio 约定
Studio 会为每个顶层元素绘制一条时间线行。遵循以下规则的项目打开后会呈现简短、可读的时间线;不符合规则的项目则会显示成用户无法编辑的、一堆未标记的行。这些是关于构建内容的约定。关于如何修改剪辑,请遵循 /hyperframes-core 中的 references/creator-editing-recipes.md,切勿发明同一编辑操作的不同形式。
1. 每个场景都是一个子合成
根合成仅包含定时的主机、媒体和音频。任何具有嵌套结构的场景(包含子元素的 div、带副标题的标题、图表)都应作为单独的文件,通过 data-composition-src 加载,并参考 references/sub-compositions.md 中的接线方式。
留在根合成内部的嵌套标记不会成为独立的行,而是隐藏在一个不透明的行中,无法逐部分修剪或移动。
编写时假设有一种结构检查器会拒绝任何违反约定的情况。
2. 一条字幕轨道
- 所有字幕都位于同一条轨道上:一个子合成主机(一个
data-track-index),标记为data-track-kind="captions",它按顺序承载所有字幕组。 - 绝不为每个字幕组设置一行,也绝不将字幕与其他类型的元素混在同一条轨道上。
- 单词时间规则不变:请参见
/embedded-captions和caption_*检查规则。
3. 每种元素类型占一条轨道
按类型分组,以便每条行都是用户可以选择、静音或成组拖动的单一实体。
| 类型 | data-track-kind |
|---|---|
| 基础视频 / A 卷 | video(来自标签) |
| 场景、叠加、图形 | graphics |
| 字幕 | captions |
| 音频(旁白、音乐、音效) | audio(来自标签) |
将 data-track-kind 放在子合成主机上。视频和音频类型来自标签,因此 <video> 和 <audio> 无需添加额外属性。为每种类型分配一个 data-track-index;该数字仅用于显示,不会改变渲染的层级顺序。使用 CSS 进行层叠控制。
4. 安全区域
任何标尺或安全框叠加都位于预览面板中,绝不在合成内部,因此不要向 HTML 中添加引导元素。
两种画面比例(宽屏和竖屏)使用相同的两个安全框,即 Premiere 的默认设置。预览开关会在每条边的中点绘制一个刻度标记来显示它们。来源:packages/studio/src/utils/previewSafeMargins.ts 中的 ACTION_SAFE_PERCENT 和 TITLE_SAFE_PERCENT。
| 框 | 占画幅比例 | 每条边内缩距离 |
|---|---|---|
| 动作安全框 | 90% | 5% |
| 标题安全框 | 80% | 10% |
- 安全边距:所有可见内容保持在动作安全框(90%)内,字幕和关键内容保持在标题安全框(80%)内。
- 双栏和 50/50 布局中,每半部分的内容保持在标题安全框内。
检查你的工作
运行 hyperframes lint 并修复所有发现的问题。然后在 Studio 中打开项目,检查时间线是否显示基础行、每个场景主机对应的行、一个字幕行以及音频行。