mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00

Files

T

Miguel Ángel ceb54811c6 fix(runtime): preload media on init to prevent broken first-play audio (#234 )

## Summary
- Audio (and video) sounds broken/choppy on first play in the studio preview, but works fine on second play
- Root cause: `<audio>` elements default to `preload="metadata"`, which only fetches enough data to determine duration — not enough for smooth playback. When `el.play()` fires, the browser hasn't buffered the audio data yet
- The runtime now eagerly sets `preload="auto"` and calls `load()` during init, ensuring media is fully buffered before the user clicks play
- `syncRuntimeMedia` now defers `play()` on unbuffered media by registering a `canplay` listener, instead of silently swallowing the failure

## Testing
Verified with agent-browser against a 26s narration composition (soulscape-film):

```
# After fix — audio element state at init:
preload: "auto"
readyState: 4 (HAVE_ENOUGH_DATA)
buffered: 26.07s (entire file)
duration: 26.07s
```

Audio is fully buffered before any play attempt, so first-play works identically to subsequent plays.

## Files changed
- `packages/core/src/runtime/init.ts` — set `preload="auto"` + `load()` in `bindMediaMetadataListeners`
- `packages/core/src/runtime/media.ts` — defer `play()` on unbuffered media via `canplay` listener
- `packages/core/src/runtime/media.test.ts` — updated test + added unbuffered media test case

2026-04-10 00:05:32 +02:00

adapters

fix(studio,runtime,engine,compiler): 8 bug fixes — audio, render, timeline, Lottie, thumbnails, video render (#133 )

2026-03-30 23:58:08 +02:00

analytics.test.ts

initial code (#2 )

2026-03-21 22:43:56 -07:00

analytics.ts

initial code (#2 )

2026-03-21 22:43:56 -07:00

bridge.test.ts

style: apply oxfmt baseline formatting across all source files (#25 )

2026-03-23 17:15:14 -07:00

bridge.ts

initial code (#2 )

2026-03-21 22:43:56 -07:00

captionOverrides.ts

feat(skills): add marker-highlight skill for animated text highlighting (#190 )

2026-04-02 13:48:24 -07:00

compositionLoader.test.ts

feat(core): support inline template compositions (#146 )

2026-03-31 03:46:23 +02:00

compositionLoader.ts

fix(core): load head styles/scripts from non-template sub-compositions (#219 )

2026-04-07 17:17:25 +02:00

entry.ts

feat(core): add fitTextFontSize utility for pixel-accurate text measurement (#152 )

2026-03-30 20:14:13 -07:00

init.ts

fix(runtime): preload media on init to prevent broken first-play audio (#234 )

2026-04-10 00:05:32 +02:00

media.test.ts

fix(runtime): preload media on init to prevent broken first-play audio (#234 )

2026-04-10 00:05:32 +02:00

media.ts

fix(runtime): preload media on init to prevent broken first-play audio (#234 )

2026-04-10 00:05:32 +02:00

picker.test.ts

style: apply oxfmt baseline formatting across all source files (#25 )

2026-03-23 17:15:14 -07:00

picker.ts

style: apply oxfmt baseline formatting across all source files (#25 )

2026-03-23 17:15:14 -07:00

player.test.ts

style: apply oxfmt baseline formatting across all source files (#25 )

2026-03-23 17:15:14 -07:00

player.ts

style: apply oxfmt baseline formatting across all source files (#25 )

2026-03-23 17:15:14 -07:00

README.md

fix(ci): update publish workflow to use bun install (#36 )

2026-03-24 08:46:58 -07:00

startResolver.test.ts

style: apply oxfmt baseline formatting across all source files (#25 )

2026-03-23 17:15:14 -07:00

startResolver.ts

fix: composition issues in runtime code + producer parity

2026-03-23 23:56:42 -04:00

state.test.ts

initial code (#2 )

2026-03-21 22:43:56 -07:00

state.ts

initial code (#2 )

2026-03-21 22:43:56 -07:00

timeline.test.ts

fix(core): filter decorative elements from timeline clip collection (#92 )

2026-03-27 18:31:46 +01:00

timeline.ts

fix(core): filter decorative elements from timeline clip collection (#92 )

2026-03-27 18:31:46 +01:00

types.ts

style: apply oxfmt baseline formatting across all source files (#25 )

2026-03-23 17:15:14 -07:00

window.d.ts

initial code (#2 )

2026-03-21 22:43:56 -07:00

README.md

Hyperframe Runtime Engine

This folder owns the runtime that powers preview and producer parity.

Current Direction

Runtime source of truth is converging on hyperframe.ts.
Build produces:
- dist/hyperframe.runtime.iife.js (browser bootstrap)
- dist/hyperframe.runtime.mjs (tooling/tests)
- dist/hyperframe.manifest.json (version + sha256 + artifact map)
FE owns iframe runtime injection.
BE persists raw generated HTML without injecting runtime scripts.
Producer validates pinned runtime checksum from manifest before render.

Runtime Contract (Stable Surface)

Globals:

window.__player
window.__playerReady
window.__renderReady
window.__timelines
window.__clipManifest

postMessage:

parent -> runtime control:
- source: "hf-parent"
- type: "control"
- actions: play, pause, seek, set-muted, set-playback-rate, enable-pick-mode, disable-pick-mode
runtime -> parent events:
- source: "hf-preview"
- type: "state" and type: "timeline"

Determinism baseline:

renderSeek is the producer-canonical seek path.
30fps quantization and readiness gates are correctness requirements.

Build

bun run --filter @hyperframes/core build:hyperframes-runtime

Security Expectations

Runtime bootstrap URL must be version-pinned and host-allowlisted.
Iframe bridge payloads must be schema-validated.
Unsafe URL schemes (javascript: and unapproved data:) are rejected.
Fail closed if runtime bootstrap/handshake is not healthy.

Product Editing Model

Primary mode: prompt + element picking.
Secondary mode: manual precision controls.
Avoid timeline-first manual workflows as default product path.