* perf(studio): reuse filmstrip frames when a zoom changes a strip's width A zoom that changed a strip's frame count decoded the whole strip again on the main thread, and showed the clip's single poster frame until it landed. Frames are now sampled at each slice's left edge, so a strip twice as long holds every frame of the shorter one; decoded frames are shared per source and time, so zooming out decodes nothing and zooming in decodes only the new half. The strip on screen stays until the new width is ready. * perf(studio): redraw only the waveforms on or near the screen after a zoom A zoom resizes every mounted clip, and every mounted waveform redrew in that same frame, on screen or not. A waveform now draws only while it is on or near the screen (one shared observer, a screen of margin each side) and draws when it comes near if a zoom changed it meanwhile. * perf(studio): never start a beat-analysis stage while the timeline zooms Analyzing a long music track runs for over a second on the main thread, and when it started late it landed inside a zoom. The analysis now awaits an optional pause before each long stage; Studio's waits for the timeline to rest and the browser to go idle. Results are unchanged. The tempo detector's stage is one call, so a zoom that starts inside it still waits for it. * fix(studio): reuse a filmstrip frame only where its own strip would show it A shared frame was keyed by the time a strip asked for, not the time it was decoded at, so a coarse strip's keyframe-early frame could land in a finer strip and run its frames backwards. A frame now carries its decoded time and is reused only when the strip would have accepted that keyframe itself. The frame-count ladder now tops out at a power of two (32), so its top step shares frames with the one below instead of none. * feat(studio): show the clip's last frame at the end of every filmstrip Left-edge sampling never showed a clip's final slice, so an end card or a fade-out was missing from its strip. Each strip now also decodes the clip's last frame (at its own time, never an earlier keyframe), shared across zoom steps like the others, and the last tile shows it. The strip on screen is now held per clip and range, not per props: a clip crossing between on and off screen keeps it, and a clip narrowed to one frame lets it go, so widening again never re-decodes a dropped width. * docs(studio): keep the filmstrip files at or under main's comment share The comment ratchet allows no file a higher share of comment lines than on main; the added explanations move to the PR description. * fix(studio): keep a held filmstrip leased so a full cache cannot evict it mid-zoom The hold leased the strip on screen only once a new width was requested, so for one commit it had no lease; with the cache over budget it was evicted, the poster showed, and the old width decoded again. The strip on screen is now leased for as long as it is the clip's, and shown only while held. A frame that fails to decode takes the frame before it, so every slot keeps its time and the last tile still shows the end. * refactor(studio): one owner for which clip a held filmstrip belongs to The hold checked the clip twice, in its lease and again before showing it; the lease alone decides now, and the cross-clip test pins it. A test now also pins that a filled frame is not charged to the cache. * fix(core): hold the tempo detector until idle after a slow import * fix(studio): scope shared video frames to timeline sessions * chore(core): keep beat analysis comments within the ratchet
@hyperframes/core
Types, parsers, generators, compiler, linter, runtime, and frame adapters for the Hyperframes video framework.
Install
npm install @hyperframes/core
Most users don't need to install core directly — the CLI, producer, and studio packages depend on it internally.
What's inside
| Module | Description |
|---|---|
| Types | TimelineElement, CompositionSpec, Asset, canvas dimensions, defaults |
| Parsers | parseHtml — extract timeline elements from HTML; parseGsapScript — parse GSAP animations |
| Generators | generateHyperframesHtml — produce valid Hyperframes HTML from a composition spec |
| Compiler | compileTimingAttrs — resolve data-start / data-duration into absolute times |
| Linter | lintHyperframeHtml — validate Hyperframes HTML (missing attributes, overlapping tracks, etc.) |
| Runtime | IIFE script injected into the browser — manages seek, media playback, and the window.__hf protocol |
| Frame Adapters | Pluggable animation drivers (GSAP, Lottie, CSS, or custom) |
Generated composition trust
Composition generators require trusted authors for code-bearing inputs. styles and
generateHyperframesStyles preserve authored CSS, which can load external resources.
animations may contain __raw: values that are emitted as JavaScript;
includeScripts: true includes executable timeline code. serializeGsapAnimations
also accepts raw preamble, postamble, and a code-bearing timelineVar. Never fill
these inputs with untrusted data. Attribute encoding and closing-tag containment
are not a sandbox; render untrusted compositions in an appropriately isolated
execution environment and never serve them on a privileged origin.
Text content retains the supported inline-formatting sanitizer contract. The clip parser intentionally flattens inner formatting to text, so parse/generate is not a lossless replacement for editing the source HTML.
Frame Adapters
A frame adapter tells the engine how to seek your animation to a specific frame:
import { createGSAPFrameAdapter } from "@hyperframes/core";
const adapter = createGSAPFrameAdapter({
getTimeline: () => gsap.timeline(),
compositionId: "my-video",
});
Implement FrameAdapter for custom animation runtimes:
import type { FrameAdapter } from "@hyperframes/core";
const myAdapter: FrameAdapter = {
id: "my-adapter",
getDurationFrames: () => 300,
seekFrame: (frame) => {
/* seek your animation */
},
};
Parsing and generating HTML
import { parseHtml, generateHyperframesHtml } from "@hyperframes/core";
const { elements, metadata } = parseHtml(htmlString);
const html = generateHyperframesHtml(spec);
Linting
import { lintHyperframeHtml } from "@hyperframes/core/lint";
const result = lintHyperframeHtml(htmlString);
// result.findings: { severity, message, elementId }[]
Documentation
Full documentation: hyperframes.heygen.com/packages/core
Related packages
@hyperframes/engine— rendering engine that drives the browser@hyperframes/producer— full render pipeline (capture + encode)hyperframes— CLI