Troubleshooting

Solve common Studio, project, media, animation, preview, and rendering problems.

Start with the symptom you can see. Keep the exact error and note whether the problem happens in Studio, validation, or only in the final render.

Start here

1. Check the machine

   npx hyperframes doctor
   

   This checks the runtime, browser, FFmpeg, and other local requirements.

2. Check the project

   npx hyperframes lint
   npx hyperframes check
   
3. Inspect the visible result

   Open Studio or capture important frames:

   npx hyperframes snapshot --at 0,3,8
   
4. Give the agent useful context

   Copy the complete error and add what you did, what you expected, and what must not change.

Studio problems

Studio does not open

Run npx hyperframes preview from the project folder and keep that terminal running.

If it still fails:

1. read the terminal error;
2. run npx hyperframes doctor;
3. try another port with npx hyperframes preview --port 4567;
4. restart the preview process.

The preview is not updating

Confirm that you are editing a file inside the open project. Save the file, wait for refresh, and inspect the preview terminal for errors.

If needed, reload Studio or restart npx hyperframes preview.

I cannot select or edit an element

Pause on a frame where the element is visible, then select it from Layers.

The element may belong to a group or nested composition, sit outside the frame, or use source that Studio cannot edit safely. Open the nested composition, use the inspector, or copy context to your agent.

A move became animation

Auto-keyframing was probably enabled. Undo the edit, turn off the auto-keyframe control, and apply the layout change again.

A timeline edit landed at the wrong time

Undo, zoom in, and place the playhead more precisely. Check whether snapping moved the boundary to a nearby clip or beat.

Continue to Studio troubleshooting for selection, editing, timeline, and save recovery.

Project and environment problems

”No composition found”

The project needs an index.html containing a valid composition root with data-composition-id, width, and height.

Create a new project:

npx hyperframes init my-video

Or compare the current source with Compositions.

”FFmpeg not found”

FFmpeg is required for local video encoding.

macOS

brew install ffmpeg

Verify with ffmpeg -version, then rerun npx hyperframes doctor.

Docker render will not start

Run docker info.

Confirm Docker is installed, its daemon is running, your user has permission, and the first image download can reach the registry.

Media problems

Video is black in preview but renders

The browser may not decode the source codec even though FFmpeg can.

HyperFrames normally creates and uses a compatible preview proxy. If the frame remains black:

1. confirm automatic proxying is not disabled;
2. run npx hyperframes doctor;
3. run npx hyperframes lint --verbose to identify affected files;
4. confirm the source file exists and can be read.

Video, image, or audio is missing

Prefer a local project asset. Confirm its path, filename capitalization, and whether it was moved or renamed.

Remote media can fail because of permissions, expiring URLs, or cross-origin restrictions.

Preview stutters

Common causes:

• very large source images;
• several large backdrop-filter blurs;
• expensive shadows or filters on animated elements;
• too many large overlapping layers.

Check whether the slowdown occurs in one scene. Resize oversized media and simplify the expensive element before reducing the whole project’s quality.

Animation and composition mistakes

These problems often appear in agent-written or manually edited source.

A video freezes while its box animates

Do not animate width, height, top, or left directly on a <video> element.

Put the video inside a wrapper and animate the wrapper:

<div id="video-wrapper">
  <video src="./assets/video.mp4" style="width:100%;height:100%"></video>
</div>

tl.to("#video-wrapper", { width: 500, height: 280, x: 1200 }, 2);

Media plays out of sync

Do not call play(), pause(), or set currentTime from composition scripts.

HyperFrames owns media playback. Use timing and media attributes to describe when the file should play.

The composition ends too early

Check the resolved composition duration:

npx hyperframes compositions

A short animation timeline can make a project end before the underlying media. Extend the authored root duration or timeline using the correct pattern for that composition.

A timed element is always visible

Timed visible elements need class="clip" as well as their timing attributes.

<h1 class="clip" data-start="2" data-duration="5" data-track-index="0">
  Hello
</h1>

npx hyperframes lint normally catches this.

Animation is static

Check that the animation is paused and registered using the exact composition ID.

const timeline = gsap.timeline({ paused: true });
window.__timelines = window.__timelines || {};
window.__timelines["my-video"] = timeline;

my-video must match data-composition-id="my-video".

Changing root duration from a variable does nothing

The root render length is determined before composition scripts run. Author or generate the intended root data-duration directly.

Clip durations can still vary. See Variables for what may be changed safely.

Render problems

The render looks different from preview

Check fonts, remote media, browser-specific effects, and the actual exported file.

Use Docker when you need a pinned rendering environment:

npx hyperframes render --docker --output output.mp4

The render is slow

During iteration:

• use draft quality;
• render a shorter range or inspect snapshots;
• resize large source media;
• simplify expensive filters;
• avoid increasing resolution or frame rate before needed.

Run npx hyperframes benchmark when tuning worker settings.

Expected HDR but received SDR

HDR needs a supported output and correct source color metadata. MP4 is the normal HDR output path; WebM and MOV may fall back to SDR.

Use --hdr only when the whole source and delivery workflow is intended for HDR. Read HDR rendering before delivery.

Still stuck?

Run:

npx hyperframes info

Then search GitHub issues or open a report with:

• the exact error;
• steps to reproduce;
• HyperFrames version and operating system;
• whether the issue occurs in preview, checks, or render;
• a small shareable project when possible.

Do not include secrets, private media, or access tokens.