Skip to content

Commit 22da764

Browse files
committed
feat: add safe-frame crop packs
Named data-safe-frames windows crop the encoded master via --crop-pack. Studio overlays and the player safe-frame attribute preview those windows. No Co-authored-by: trailers.
1 parent dc9fb67 commit 22da764

71 files changed

Lines changed: 2653 additions & 92 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎bun.lock‎

Lines changed: 14 additions & 13 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/concepts/data-attributes.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,45 @@ Media can also declare a source offset, playback rate, and volume. A nested
6565
composition adds a source path and its own fixed timeline window. These are
6666
exact contracts rather than new timing models.
6767

68+
## Safe-frame crop windows
69+
70+
A landscape (or any) master can declare named crop windows on the composition
71+
root. Rendering `--crop-pack` then writes extra files by **cropping the already-encoded
72+
master** — one capture, several output files. Type that sits outside a window is
73+
cut off. The layout does not reflow.
74+
75+
```html
76+
<div
77+
id="root"
78+
data-composition-id="launch"
79+
data-start="0"
80+
data-duration="30"
81+
data-width="1920"
82+
data-height="1080"
83+
data-safe-frames='[
84+
{"id":"vertical","ratio":"9:16","x":0.3416666666666667,"y":0,"width":0.31666666666666665,"height":1},
85+
{"id":"square","ratio":"1:1","x":0.21875,"y":0,"width":0.5625,"height":1}
86+
]'
87+
>
88+
<h1 id="headline" class="clip" data-start="0" data-duration="4" data-safe-critical>Launch day</h1>
89+
</div>
90+
```
91+
92+
`id` is the output suffix (`launch.vertical.mp4`) and the Studio label. `ratio`
93+
is `16:9`, `9:16`, or `1:1` and validates the rect; it does not invent one.
94+
`x`, `y`, `width`, and `height` are fractions of the authored frame (origin
95+
top-left), each in `[0, 1]`, with `x + width ≤ 1` and `y + height ≤ 1`. Pixel
96+
sizes snap by at most one pixel so a 9:16 window on 1920×1080 that rounds
97+
through 607.5 still matches the named ratio.
98+
99+
`data-safe-critical` on a visual element means its border box must stay inside
100+
every named window while it is visible. `data-safe-critical="vertical"`
101+
(comma-separated ids) limits that requirement. Static `lint` checks ids and
102+
rects; `hyperframes check` samples painted boxes.
103+
104+
A composition with no `data-safe-frames` is unchanged. See
105+
[Render from the command line](/guides/rendering#crop-packs) for `--crop-pack`.
106+
68107
Use the [HTML schema reference](/reference/html-schema) for every supported
69108
attribute and element-specific rule. Use [Compositions](/concepts/compositions)
70109
to decide when a scene should become a separate composition.

‎docs/guides/4k-rendering.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,13 @@ For a fully sharp 4K result, use 4K source media and size canvas/WebGL buffers f
5252

5353
HyperFrames checks these conditions before opening the browser. Render at the composition's native size and resize separately when a combination is unsupported.
5454

55+
`--crop-pack` is a different path. It does not reshape the capture viewport and
56+
it is not `--resolution`. The master is captured at the authored size (or the
57+
`--resolution` supersample, if you asked for one), then ffmpeg crops sibling
58+
files from that encoded master. A 9:16 crop of a 1920×1080 composition is still
59+
a crop of 1080p pixels, not a portrait capture and not a 4K re-render. See
60+
[Crop packs](/guides/rendering#crop-packs).
61+
5562
## Verify the file
5663

5764
```bash

‎docs/guides/rendering.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,53 @@ ffmpeg -i out.mp4 -map_metadata -1 -c copy clean.mp4
181181
C2PA.
182182
</Note>
183183

184+
## Crop packs
185+
186+
A composition that declares `data-safe-frames` on the root can emit extra
187+
deliverables from **one** capture. `--crop-pack` runs after the master is encoded
188+
and writes sibling files with ffmpeg crop + scale. It is not a second capture
189+
and not an aspect-ratio override on the capture viewport. Type outside a window
190+
is cut off; the layout does not reflow.
191+
192+
```bash
193+
npx hyperframes render --output renders/launch.mp4 --crop-pack all
194+
npx hyperframes render --output renders/launch.mp4 --crop-pack vertical,square
195+
```
196+
197+
That writes the master unchanged, then one sibling per requested id:
198+
199+
- `renders/launch.mp4` (master)
200+
- `renders/launch.vertical.mp4`
201+
- `renders/launch.square.mp4`
202+
203+
Default output size is the largest integer size that fits the named ratio and
204+
does not upscale either dimension past the cropped source. A 608×1080 9:16 crop
205+
from a 1920×1080 master stays 608×1080.
206+
207+
`all` means every authored id, in array order. An unknown id exits non-zero
208+
**before** capture. `--crop-pack` without authored frames is an error.
209+
210+
GIF and PNG-sequence ignore the flag (warning, master still written). MP4, MOV,
211+
and WebM are supported. HDR masters keep the same encode family; if crop+scale
212+
would break HDR, that member hard-errors by id instead of writing SDR.
213+
214+
Project config may set a default. CLI flags win over `hyperframes.json`.
215+
216+
```json
217+
{
218+
"render": {
219+
"cropPack": ["vertical", "square"]
220+
}
221+
}
222+
```
223+
224+
Lambda, Cloud Run, and `hyperframes cloud render` reject `--crop-pack` with an
225+
explicit error. Crop packs are a local post-encode step until a follow-up ships
226+
sibling uploads.
227+
228+
Mark copy that must survive every requested window with `data-safe-critical`,
229+
then run `hyperframes check`. See [Data attributes](/concepts/data-attributes#safe-frame-crop-windows).
230+
184231
## If rendering fails
185232

186233
Run:

‎docs/reference/html-schema.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ timeline registry key.
8181
| `data-width` and `data-height` | Yes | Authored frame dimensions in pixels |
8282
| `data-duration` | Usually | Total render duration in seconds |
8383
| `data-no-timeline` | Only for a timeline-free composition | Tells the runtime not to wait for a timeline |
84+
| `data-safe-frames` | No | JSON array of named crop windows on this root. Each object is `{ id, ratio, x, y, width, height }`. `id` is `[a-z][a-z0-9-]{0,31}` and unique. `ratio` is `16:9`, `9:16`, or `1:1`. Fractions are of the authored frame, origin top-left, each in `[0, 1]`, with `x + width ≤ 1` and `y + height ≤ 1`. Pixel size must match the named ratio within one pixel after snap. Used by `--crop-pack`, Studio overlays, the player `safe-frame` attribute, and `data-safe-critical` checks. Cropping the encoded master does not reflow layout. |
8485

8586
An explicit root `data-duration` is the render length. The compiler reads it
8687
before composition scripts run, so a script or variable override cannot change
@@ -99,6 +100,7 @@ unbounded animation, and timeline-free compositions need an explicit duration.
99100
| `data-duration` | Yes for DOM, image, and nested-composition clips | Visible slot length in seconds |
100101
| `data-track-index` | No | Studio timeline lane, display only. The render never reads it and it does not prevent overlap |
101102
| `class="clip"` | Recommended for authored timed DOM and image elements | Layout and tooling convention. Visibility is keyed off `data-start`, but the shared `.clip` rule supplies the full-frame box |
103+
| `data-safe-critical` | No | Boolean, or a comma-separated list of `data-safe-frames` ids. The element's border box must stay inside every required crop window while it is visible. Static lint checks unknown ids; `hyperframes check` samples overflow (`safe_critical_overflow`). Cropping is not reflow — keep critical copy inside the windows you intend to deliver. |
102104

103105
`data-track-index` does not control paint order. Use CSS `z-index` for
104106
front-to-back layering. Two clips on the same track may overlap in time; the

‎docs/schema/hyperframes.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,21 @@
5757
"pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
5858
"description": "Owning authoring-workflow skill slug (e.g. product-launch-video). Set by `hyperframes init --skill` or seeded from the first `hyperframes render --skill`; every render of this project is then attributed to it on anonymous telemetry, without re-passing the flag."
5959
},
60+
"render": {
61+
"type": "object",
62+
"description": "Default local render options. CLI flags win when both are set.",
63+
"additionalProperties": false,
64+
"properties": {
65+
"cropPack": {
66+
"type": "array",
67+
"description": "Default --crop-pack ids (or the token \"all\") when the CLI flag is omitted. Extra deliverables are ffmpeg crops of the encoded master, not a second capture.",
68+
"items": {
69+
"type": "string",
70+
"minLength": 1
71+
}
72+
}
73+
}
74+
},
6075
"registryItems": {
6176
"type": "array",
6277
"description": "Catalog items installed by `hyperframes add`, in install order. Installed files are plain composition HTML with no provenance marker, so this is the only record that a file came from the registry; a render reads it back to report which catalog items the finished video actually used. Append-only, deduped by name.",

‎packages/cli/src/commands/cloud/render.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,6 +197,11 @@ export default defineCommand({
197197
type: "string",
198198
description: "Optional Idempotency-Key for safe retries (1-255 chars from [A-Za-z0-9_:.-])",
199199
},
200+
"crop-pack": {
201+
type: "string",
202+
description:
203+
"Not supported on cloud render. Crop packs are a local post-encode ffmpeg crop of the assembled master.",
204+
},
200205
},
201206
// fallow-ignore-next-line complexity
202207
async run({ args }) {
@@ -214,6 +219,15 @@ export default defineCommand({
214219
const maxWaitMs = parseMaxWaitMs(args["max-wait"]);
215220
validateIdempotencyKey(args["idempotency-key"]);
216221

222+
if (args["crop-pack"]) {
223+
errorBox(
224+
"Unsupported flag",
225+
"--crop-pack is not supported on cloud render.",
226+
"Crop packs are a local post-encode ffmpeg crop of the assembled master. Render locally with `hyperframes render --crop-pack`.",
227+
);
228+
failCommand();
229+
}
230+
217231
// Project resolution runs BEFORE variables resolution so a user
218232
// passing conflicting inputs (`dir + --asset-id`) sees the
219233
// structural error before any variable parsing errors.

‎packages/cli/src/commands/cloudrun.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,11 @@ export default defineCommand({
224224
description: "Poll cadence in ms when --wait is set (default: 5000)",
225225
},
226226
json: { type: "boolean", description: "Emit machine-readable JSON" },
227+
"crop-pack": {
228+
type: "string",
229+
description:
230+
"Not supported on Cloud Run. Crop packs are a local post-encode ffmpeg crop of the assembled master.",
231+
},
227232
},
228233
// fallow-ignore-next-line complexity
229234
async run({ args }) {
@@ -232,6 +237,12 @@ export default defineCommand({
232237
console.log(HELP);
233238
return;
234239
}
240+
if (args["crop-pack"]) {
241+
console.error(
242+
"[cloudrun] --crop-pack is not supported on Cloud Run. Crop packs are a local post-encode ffmpeg crop of the assembled master. Render locally with `hyperframes render --crop-pack`.",
243+
);
244+
failCommand();
245+
}
235246
const verbsNeedingAdapter = new Set([
236247
"deploy",
237248
"sites",

‎packages/cli/src/commands/lambda.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,11 @@ export default defineCommand({
189189

190190
// shared
191191
json: { type: "boolean", description: "Emit machine-readable JSON" },
192+
"crop-pack": {
193+
type: "string",
194+
description:
195+
"Not supported on Lambda. Crop packs are a local post-encode ffmpeg crop of the assembled master.",
196+
},
192197
},
193198
async run({ args }) {
194199
const subcommand = args.subcommand;
@@ -197,6 +202,13 @@ export default defineCommand({
197202
return;
198203
}
199204

205+
if (args["crop-pack"]) {
206+
console.error(
207+
"[lambda] --crop-pack is not supported on Lambda. Crop packs are a local post-encode ffmpeg crop of the assembled master. Render locally with `hyperframes render --crop-pack`.",
208+
);
209+
failCommand();
210+
}
211+
200212
const stackName =
201213
(args["stack-name"] as string | undefined) ??
202214
// Lazy-imported so the dispatcher doesn't pull state.ts (and its

0 commit comments

Comments
 (0)