Troubleshooting

"No composition found"

Your directory needs an index.html with a valid composition. The root element must have a data-composition-id attribute.Fix: Run npx hyperframes init to create a composition from an example, or verify your index.html has the correct structure:

index.html

<div id="root" data-composition-id="my-video"
     data-width="1920" data-height="1080">
  <!-- elements here -->
</div>

"FFmpeg not found"

Local rendering requires FFmpeg installed on your system. Install it for your platform:

brew install ffmpeg

sudo apt install ffmpeg

# Download from https://ffmpeg.org/download.html
# Add the bin directory to your PATH

ffmpeg -version

After installing, run npx hyperframes doctor to verify the CLI can find it.

If you cannot install FFmpeg, use Docker mode instead — it bundles FFmpeg inside the container: npx hyperframes render --docker --output output.mp4

Lint errors

Run npx hyperframes lint to check for common structural issues (see CLI: lint):

Error	Meaning
Missing `data-composition-id`	Root element needs this attribute. See Compositions.
Missing `class="clip"`	Timed visible elements need this class. See Data Attributes.
Overlapping timelines	Clips on the same `data-track-index` cannot overlap in time.
Unmuted video elements	Video elements should be `muted` unless `data-has-audio="true"` is set.
Deprecated attribute names	`data-layer` and `data-end` have been replaced. Check the HTML Schema Reference.

Preview not updating

Make sure you are editing the index.html in the project directory. The preview server watches for file changes and auto-reloads.If changes still do not appear:

Check the terminal for errors from the preview server
Stop and restart npx hyperframes preview
Hard-refresh the browser: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
Clear the browser cache if CSS changes are not reflected

Preview stutters or plays at a low frame rate

Symptom: Preview playback is jerky or skips frames, but the rendered mp4 looks fine.Cause: Individual frames are taking longer than 16-33ms to paint. Render hides this (it captures frames one at a time), preview does not.Common culprits, most to least frequent:

Stacked backdrop-filter: blur() layers, especially at radii above 32px
Source images at very high resolution (above 4K) displayed in small regions
filter: blur() or filter: drop-shadow() on large elements
Many elements with box-shadow or text-shadow that also animate

First thing to check: does the stutter happen only during specific scenes, or throughout? Scene-specific stutter usually points at an element, often a blur overlay, that becomes visible in that scene.How to diagnose: open Chrome DevTools, switch to the Performance tab, record a few seconds of playback, and look for long tasks labeled “Composite Layers” or “Paint”. See Performance: Measuring a slow composition for the full walkthrough.Temporary workaround: render to mp4 and watch the output. Render is accurate regardless of per-frame cost.

Terminal

npx hyperframes render --quality draft --output preview.mp4

See Performance for the full guide on expensive CSS patterns and how to fix them.

Render looks different from preview

Use --docker mode for deterministic output. Local renders may differ due to:

Font availability — different fonts on different platforms cause text reflow
Chrome version — local Chromium vs. Docker’s pinned version can render slightly differently
System-specific rendering — GPU compositing, subpixel antialiasing, etc.

Terminal

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

See Rendering: When to Use Each Mode for guidance on choosing between local and Docker rendering.

Docker mode fails to start

Verify Docker is installed and the daemon is running:

Terminal

docker info

Common issues:

Docker not running: Start Docker Desktop or the Docker daemon
Permission denied: Add your user to the docker group (sudo usermod -aG docker $USER) and restart your shell
Image pull fails: Check your internet connection; the first render downloads the Hyperframes Docker image

Render is slow

Try these optimizations:

Use --quality draft during development for faster encoding
Run npx hyperframes benchmark to find the optimal worker count for your system
Local Chrome/WebGL GPU capture is enabled automatically; compare with --no-browser-gpu if troubleshooting
Use --gpu for hardware-accelerated encoding (local mode only)
Reduce --fps to 24 if 30fps is not needed
Check that your composition does not have unnecessary elements or overly complex animations

See Rendering: Options for all available flags.

Video asset plays black in preview but renders fine (HEVC/H.265)

Rendering decodes video assets with FFmpeg, so HEVC (H.265) inputs render correctly on every platform. Live preview is different: preview, play, Studio, and published player pages play the file in your browser, and not every browser decodes HEVC (Chrome 107+, Edge, and Safari do on most modern hardware; Firefox does not).If an HEVC asset shows a black or frozen frame in preview:

Confirm the render itself is fine: npx hyperframes render output will contain the video.
For authoring, generate an H.264 proxy (ffmpeg -i asset.mp4 -c:v libx264 -crf 18 proxy.mp4) and point the composition at it while you iterate.
Swap the HEVC original back before the final render, or keep the proxy; both render correctly.

npx hyperframes lint flags HEVC assets with an info-level hevc_preview_codec note. See Rendering: Input Video Codecs.

Common Mistakes

Coding pitfalls that break compositions

Rendering

Rendering modes, options, and tips

CLI Reference

Full list of CLI commands

Contributing

Report bugs and contribute fixes

System Diagnostics

Still Stuck?

Next Steps

Common Mistakes

Rendering

CLI Reference

Contributing

​System Diagnostics

​Still Stuck?

​Next Steps

Common Mistakes

Rendering

CLI Reference

Contributing

System Diagnostics

Still Stuck?

Next Steps