Back to Details

hyperframes-studio

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HyperFrames Studio conventions

HyperFrames Studio 规范

Studio draws one timeline row per top-level element. A project that follows the rules below opens as a short, readable timeline; one that does not opens as a wall of unlabeled rows the user cannot edit. These are conventions for what to build. For how to change a clip, follow 
/hyperframes-core
references/creator-editing-recipes.md
and never invent a different form of the same edit.
Studio 会为每个顶层元素绘制一行时间线。符合以下规则的项目打开后是简短、可读的时间线；不符合的项目打开后会是一堆用户无法编辑的无标签行。这些是关于要构建内容的约定。关于如何修改剪辑，请遵循 
/hyperframes-core
的 
references/creator-editing-recipes.md
，且永远不要自行发明同一种编辑的不同形式。

1. Every scene is a sub-composition

1. 每个场景都是一个子合成

The root composition holds only timed hosts, media and audio. Any scene with nested structure (a div containing children, a title with a subtitle, a chart) is its own file loaded with 
data-composition-src
, wiring in 
references/sub-compositions.md
.
Nested markup left inside the root does not become a row of its own. It hides inside one opaque row that cannot be trimmed or moved part by part.
Author as if a structure lint rejects any violation.
根合成只包含定时宿主、媒体和音频。任何具有嵌套结构的场景（包含子元素的 div、带副标题的标题、图表）都应有自己的文件，通过 
data-composition-src
加载，具体接入方式见 
references/sub-compositions.md
。
留在根合成中的嵌套标记不会成为独立的一行。它会隐藏在一个不透明的行中，无法逐部分修剪或移动。
创建内容时要假设存在一个结构 lint，会拒绝任何违规。

2. One caption track

2. 一条字幕轨

  • All captions live on one track: a single sub-composition host (one 
    data-track-index
    ) marked 
    data-track-kind="captions"
    that carries every caption group in order.
  • Never one row per caption group, and never captions mixed onto a track with another kind.
  • Word-timing rules are unchanged: see 
    /embedded-captions
    and the 
    caption_*
    lint rules.
  • 所有字幕都位于一条轨道上：一个子合成宿主（一个 
    data-track-index
    ），标记为 
    data-track-kind="captions"
    ，按顺序承载所有字幕组。
  • 绝不要让每个字幕组各占一行，也绝不要把字幕与另一种类型混在同一条轨道上。
  • 逐词计时规则保持不变：见 
    /embedded-captions
    和 
    caption_*
    lint 规则。

3. One element kind per track

3. 每条轨道一种元素类型

Group by kind so each row is one thing the user can select, mute or drag as a set.
Kind
data-track-kind
Base video / A-roll
video
(from the tag)
Scenes, overlays, graphics
graphics
Captions
captions
Audio (voiceover, music, sound effects)
audio
(from the tag)
Put 
data-track-kind
on sub-composition hosts. Video and audio kinds come from the tag, so 
<video>
and 
<audio>
need no attribute. Give each kind its own 
data-track-index
; the number is display only; it never changes what renders on top. Use CSS for layering.
按类型分组，使每一行都是用户可以作为一组选择、静音或拖动的单一事物。
类型
data-track-kind
基础视频 / A-roll
video
（来自标签）
场景、叠加、图形
graphics
字幕
captions
音频（旁白、音乐、音效）
audio
（来自标签）
将 
data-track-kind
放在子合成宿主上。视频和音频类型来自标签本身，因此 
<video>
和 
<audio>
不需要该属性。给每种类型分配各自的 
data-track-index
；该数字仅用于显示，它永远不会改变什么内容渲染在最上面。使用 CSS 来分层。

4. Safe zones

4. 安全区

Any ruler or safe-box overlay lives in the preview pane, never inside the composition, so do not add guide elements to the HTML. Both framings (wide and vertical) use the same two safe boxes, Premiere's defaults. The preview toggle draws them with a tick at the midpoint of every edge. Source: 
ACTION_SAFE_PERCENT
and 
TITLE_SAFE_PERCENT
in 
packages/studio/src/utils/previewSafeMargins.ts
.
BoxShare of the frameInset on every edge
Action-safe90%5%
Title-safe80%10%
  • Safe margins: everything visible stays inside the action-safe box (90%), and captions and key content stay inside the title-safe box (80%).
  • Two-up and 50/50 layouts keep each half's content inside the title-safe box.
任何标尺或安全框叠加层都只存在于预览窗格中，绝不放在合成内部，因此不要向 HTML 添加引导元素。 宽幅和竖幅两种构图都使用相同的两个安全框，即 Premiere 的默认值。预览切换开关会在每条边的中点绘制一个刻度来显示它们。来源：
packages/studio/src/utils/previewSafeMargins.ts
中的 
ACTION_SAFE_PERCENT
和 
TITLE_SAFE_PERCENT
。
框占画面比例每条边内缩
动作安全区90%5%
标题安全区80%10%
  • 安全边距：所有可见内容保持在动作安全框（90%）内，字幕和关键内容保持在标题安全框（80%）内。
  • 双栏和 50/50 布局让每一半的内容保持在标题安全框内。

Checking your work

检查你的工作

Run 
hyperframes lint
and fix every finding. Then open the project in Studio and check that the timeline shows a base row, one row per scene host, one caption row and the audio rows.
运行 
hyperframes lint
并修复所有发现的问题。然后在 Studio 中打开项目，检查时间线是否显示基础行、每个场景宿主一行、一行字幕行和音频行。