Skip to main content
If your issue is about a specific coding mistake (animations not working, video cutting off early), see Common Mistakes first. This page covers environment, tooling, and rendering issues.
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 a template, or verify your index.html has the correct structure:
index.html
<div id="root" data-composition-id="my-video"
     data-start="0" data-width="1920" data-height="1080">
  <!-- elements here -->
</div>
Local rendering requires FFmpeg installed on your system. Install it for your platform:
brew install ffmpeg
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 -o output.mp4
Run npx hyperframes lint to check for common structural issues (see CLI: lint):
ErrorMeaning
Missing data-composition-idRoot element needs this attribute. See Compositions.
Missing class="clip"Timed visible elements need this class. See Data Attributes.
Overlapping timelinesClips on the same data-track-index cannot overlap in time.
Unmuted video elementsVideo elements should be muted unless data-has-audio="true" is set.
Deprecated attribute namesdata-layer and data-end have been replaced. Check the HTML Schema Reference.
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:
  1. Check the terminal for errors from the dev server
  2. Stop and restart npx hyperframes dev
  3. Hard-refresh the browser: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
  4. Clear the browser cache if CSS changes are not reflected
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 -o output.mp4
See Rendering: When to Use Each Mode for guidance on choosing between local and Docker rendering.
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
Try these optimizations:
  1. Use --quality draft during development for faster encoding
  2. Run npx hyperframes benchmark to find the optimal worker count for your system
  3. Use --gpu for hardware-accelerated encoding (local mode only)
  4. Reduce --fps to 24 if 30fps is not needed
  5. Check that your composition does not have unnecessary elements or overly complex animations
See Rendering: Options for all available flags.

​
System Diagnostics

Run npx hyperframes doctor to check your environment:
Terminal
npx hyperframes doctor
This checks for Node.js version, FFmpeg availability, Docker status, and other requirements. If doctor reports issues, address them before rendering.

​
Still Stuck?

If none of the above resolves your issue:
  1. Run npx hyperframes info to gather system and project details
  2. Check GitHub Issues for similar reports
  3. Open a new issue with the output of npx hyperframes info and steps to reproduce

​
Next Steps

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