mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
Miguel Ángel
2cf3558f8e
## Summary - hide the leading trim handle for timeline clips that cannot offset their own content - keep leading trim available for media clips backed by playback offset metadata or source duration - map visual row priority like a normal timeline editor: top timeline rows render above lower rows ## Why This Is Needed Generic GSAP/DOM timeline clips do not have a playback-offset model like media clips do. That means a left trim affordance on those clips is misleading today: - users reasonably expect front trim to remove the beginning of the animation - the current model can only shorten the clip window, not start the motion halfway through Instead of exposing a control that implies unsupported behavior, this PR keeps true front trim only on clips that can actually offset their content. The PR also fixes the stacking convention so the timeline matches normal editor expectations: - visually higher track row = higher render priority - visually lower track row = lower render priority ## Current Flow By Element Type ### Generic motion / DOM clips Examples: `section`, `div`, `aside`, GSAP-driven cards and overlays. Current supported flow: - drag the whole clip horizontally to change `data-start` - right-trim to shorten the end of the clip window - move between tracks to change `data-track-index` Not supported yet: - true front trim that removes the beginning of the animation itself Behavior after this PR: - no interactive left trim handle is shown - right trim still works - horizontal move still works ### Media clips Examples: `video` / `audio` clips, or wrappers carrying `data-media-start` / `data-playback-start`. Current supported flow: - drag the whole clip horizontally to change `data-start` - left trim advances clip start and playback offset together - right trim shortens `data-duration` Behavior after this PR: - both left and right trim handles remain available - left trim persists `data-start` plus `data-media-start` / `data-playback-start` - right trim persists `data-duration` ## Z-Index Rule This PR now follows the normal timeline-editor convention: - top visual row on the timeline = highest `z-index` - lower visual rows = lower `z-index` Concretely, because Studio renders tracks in ascending numeric order from top to bottom, lower numeric track values now map to higher `z-index` values. ## Validation ### Automated - `bun test packages/studio/src/player/components/timelineEditing.test.ts packages/studio/src/player/components/Timeline.test.ts packages/studio/src/player/store/playerStore.test.ts packages/studio/src/utils/sourcePatcher.test.ts` - `bun run --filter @hyperframes/studio typecheck` ### Browser verification Verified with `agent-browser` on `timeline-edit-playground`: - generic motion clips no longer expose an interactive left trim handle - media clips still expose both trim handles - left trim on `media-card` persisted `data-start` and `data-media-start` - right trim on `media-card` persisted `data-duration` only - moving `title-card` from the bottom row to the top row persisted the highest `z-index` for the top-row clips - recordings: - `/tmp/trim-fix-artifacts/trim-flow.webm` - `/tmp/trim-fix-artifacts/z-index-flow.webm`
111 lines
4.3 KiB
Plaintext
111 lines
4.3 KiB
Plaintext
---
|
|
title: Timeline Editing
|
|
description: "What you can edit in the Studio timeline today, how those edits map back to HTML, and the current limitations."
|
|
---
|
|
|
|
The Studio timeline lets you edit the parts of a HyperFrames composition that can be persisted cleanly back into source HTML.
|
|
|
|
It is not a separate project format or hidden binary state. Every supported timeline action updates the same `data-*` attributes and inline styles that your composition already uses.
|
|
|
|
## What the Timeline Can Do
|
|
|
|
- **Move clips in time** — drag a clip horizontally to update `data-start`
|
|
- **Move clips between rows** — drag a clip vertically to update `data-track-index`
|
|
- **Change visual stacking** — top timeline rows render above lower rows, and that ordering is persisted back into inline `z-index`
|
|
- **Trim the end of a clip** — drag the right handle to reduce `data-duration`
|
|
- **Trim the start of media clips** — drag the left handle on clips backed by media offsets to advance the clip start and playback offset together
|
|
|
|
## How Timeline Edits Map To Source
|
|
|
|
The timeline works directly against your HTML:
|
|
|
|
- horizontal move updates `data-start`
|
|
- vertical move updates `data-track-index`
|
|
- right trim updates `data-duration`
|
|
- media left trim updates `data-start` and `data-media-start` or `data-playback-start`
|
|
- changing row order also updates inline `z-index` so the preview matches the timeline
|
|
|
|
This means timeline editing stays inspectable and versionable. If you open the file after a move or trim, you can see the exact attributes that changed.
|
|
|
|
## Current Editing Model By Clip Type
|
|
|
|
### Generic motion / DOM clips
|
|
|
|
Examples:
|
|
- `div`
|
|
- `section`
|
|
- `aside`
|
|
- GSAP-driven cards, overlays, and text blocks
|
|
|
|
Supported:
|
|
- move the clip later or earlier on the timeline
|
|
- move the clip to another row
|
|
- trim the end of the clip
|
|
|
|
Not supported yet:
|
|
- true front trim that removes the beginning of the animation itself
|
|
|
|
### Media clips
|
|
|
|
Examples:
|
|
- `video`
|
|
- `audio`
|
|
- wrappers backed by `data-media-start` / `data-playback-start`
|
|
|
|
Supported:
|
|
- move the clip later or earlier on the timeline
|
|
- move the clip to another row
|
|
- trim the end of the clip
|
|
- trim the start of the media content itself
|
|
|
|
## Why Start Trim Is Media-Only
|
|
|
|
Media clips have a real content-offset model:
|
|
|
|
- `data-media-start`
|
|
- `data-playback-start`
|
|
|
|
Those attributes let the Studio say:
|
|
|
|
> Start this clip later on the timeline, and also start reading the media later inside the source.
|
|
|
|
Generic motion clips do not have an equivalent playback-offset model yet. For a GSAP-driven `section` or `div`, the Studio can:
|
|
|
|
- move the whole clip later by changing `data-start`
|
|
- shorten its visible window by changing `data-duration`
|
|
|
|
But it cannot yet say:
|
|
|
|
> Start this animation halfway through its timeline.
|
|
|
|
That is why generic motion clips do **not** show an interactive left trim handle. The control is hidden instead of implying behavior the runtime cannot currently represent truthfully.
|
|
|
|
<Note>
|
|
A useful mental model is: **move** changes when a clip starts, **right trim** changes when it ends, and **left trim** only appears when the clip can actually skip the beginning of its own content.
|
|
</Note>
|
|
|
|
## Stacking Rule
|
|
|
|
The Studio follows the normal timeline-editor convention:
|
|
|
|
- the visually top row renders on top
|
|
- lower rows render underneath
|
|
|
|
If you want captions, lower-thirds, or overlays to sit above other content, place them on a visually higher timeline row.
|
|
|
|
## Current Limitations
|
|
|
|
- **No true front trim for generic motion clips yet.**
|
|
You can move those clips later in time, but you cannot start their internal animation phase partway through.
|
|
- **Layering is still driven by row order plus persisted inline `z-index`.**
|
|
If a clip already has custom CSS stacking rules outside the Studio flow, keep that in mind when editing manually.
|
|
- **Timeline editing is intentionally scoped.**
|
|
The Studio currently focuses on move and trim behavior. It does not yet expose full split, slip, slide, ripple, or roll editing semantics.
|
|
|
|
## Best Practices
|
|
|
|
- Use **move** when you want an element to start later but still play its full animation.
|
|
- Use **right trim** when you want the element to end sooner.
|
|
- Use **media left trim** when you want to remove the beginning of a video or audio clip.
|
|
- Put overlays and captions on visually higher rows so they render above base footage.
|