mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-06 02:41:48 +00:00
50aabb9eb2
Adds an optional creative skill that integrates HyperFrames, an HTML-based video rendering framework, as a sibling to manim-video. Complements manim's math-focused animation with motion-graphics, captioned narration, audio-reactive visuals, shader transitions, and website-to-video production. Scope: - optional-skills/creative/hyperframes/SKILL.md — entry point - references/composition.md — data-attr schema, timeline contract - references/cli.md — every npx hyperframes command - references/gsap.md — GSAP core API for compositions - references/website-to-video.md — 7-step capture-to-video workflow - references/troubleshooting.md — OpenClaw / Chromium 147 fix - scripts/setup.sh — idempotent one-time setup OpenClaw / Chromium 147 fix (hyperframes#294): Pinning hyperframes@>=0.4.2 (commit 4c72ba4 ships the HeadlessExperimental.beginFrame auto-detect + screenshot fallback). setup.sh pre-caches chrome-headless-shell so the fast BeginFrame path is preferred over system Chrome. The PRODUCER_FORCE_SCREENSHOT=true escape hatch is documented in troubleshooting.md and in SKILL.md Pitfalls. Placed under optional-skills/ (not bundled) per CONTRIBUTING.md guidance for heavyweight deps: requires Node.js >= 22, FFmpeg, and ~300 MB chrome-headless-shell download.
137 lines
5.3 KiB
Markdown
137 lines
5.3 KiB
Markdown
# Troubleshooting
|
|
|
|
## `HeadlessExperimental.beginFrame' wasn't found` (first thing to check)
|
|
|
|
**Symptom:** `npx hyperframes render` fails with:
|
|
|
|
```
|
|
✗ Render failed
|
|
Protocol error (HeadlessExperimental.beginFrame):
|
|
'HeadlessExperimental.beginFrame' wasn't found
|
|
```
|
|
|
|
**Cause:** Chromium 147+ removed the `HeadlessExperimental.beginFrame` CDP command. This affected sandbox environments (e.g., OpenClaw, some containerized agent hosts) that ship modern Chromium as the system browser. See [hyperframes#294](https://github.com/heygen-com/hyperframes/issues/294).
|
|
|
|
**Fix (permanent — preferred):** upgrade.
|
|
|
|
```bash
|
|
npx hyperframes upgrade -y
|
|
# or
|
|
npm install -g hyperframes@latest
|
|
```
|
|
|
|
`hyperframes >= 0.4.2` auto-detects whether the resolved browser supports `beginFrame` (checks for `chrome-headless-shell` in the binary path) and falls back to screenshot capture mode when it doesn't. Commit [`4c72ba4`](https://github.com/heygen-com/hyperframes/commit/4c72ba4a36ec2bd6733f7b9cb2a9e63f9fb234b9) (March 2026) shipped this auto-detect.
|
|
|
|
**Fix (escape hatch — if you can't upgrade):**
|
|
|
|
```bash
|
|
export PRODUCER_FORCE_SCREENSHOT=true
|
|
npx hyperframes render
|
|
```
|
|
|
|
This forces screenshot mode regardless of the binary. Screenshot mode is slightly slower but visually identical.
|
|
|
|
**Fix (prevent — recommended):** install `chrome-headless-shell` so the engine can use the fast BeginFrame path:
|
|
|
|
```bash
|
|
npx puppeteer browsers install chrome-headless-shell
|
|
# or let the CLI do it
|
|
npx hyperframes browser --install
|
|
```
|
|
|
|
`scripts/setup.sh` runs this automatically.
|
|
|
|
## `npx hyperframes render` hangs for 120s then times out
|
|
|
|
**Cause:** the resolved browser is system Chrome (e.g., `/usr/bin/google-chrome`) and doesn't support the BeginFrame path, but auto-detect also missed it (older `hyperframes` version).
|
|
|
|
**Fix:**
|
|
1. Check which binary is being used: `npx hyperframes browser --path`
|
|
2. If it's system Chrome, either:
|
|
- Install `chrome-headless-shell`: `npx hyperframes browser --install`, OR
|
|
- Set the escape hatch: `export PRODUCER_FORCE_SCREENSHOT=true`, OR
|
|
- Upgrade: `npx hyperframes upgrade -y`
|
|
|
|
## `ffmpeg: command not found`
|
|
|
|
Install FFmpeg via your system package manager:
|
|
|
|
| OS / distro | Command |
|
|
| --------------- | ----------------------------------- |
|
|
| Ubuntu / Debian | `sudo apt-get install -y ffmpeg` |
|
|
| Fedora / RHEL | `sudo dnf install -y ffmpeg` |
|
|
| Arch | `sudo pacman -S ffmpeg` |
|
|
| macOS | `brew install ffmpeg` |
|
|
| Windows | `winget install Gyan.FFmpeg` |
|
|
|
|
Verify: `ffmpeg -version`.
|
|
|
|
## `Node version X is not supported`
|
|
|
|
HyperFrames requires Node.js >= 22. Check with `node --version`.
|
|
|
|
- **nvm:** `nvm install 22 && nvm use 22`
|
|
- **Homebrew (macOS):** `brew install node@22 && brew link --overwrite node@22`
|
|
- **apt:** follow [nodesource](https://github.com/nodesource/distributions) for Node 22 LTS.
|
|
|
|
## `ENOSPC: no space left on device` or OOM kills during render
|
|
|
|
Renders are memory- and disk-hungry. Minimums:
|
|
|
|
- **RAM:** 4 GB free (8 GB recommended for 60fps / `--quality high`)
|
|
- **Disk:** 2 GB free scratch space — frames are written to `/tmp` during capture
|
|
|
|
Mitigations:
|
|
- Lower quality: `--quality draft`.
|
|
- Lower fps: `--fps 24`.
|
|
- Lower worker count: `--workers 1`.
|
|
- Set `TMPDIR` to a volume with more space: `export TMPDIR=/mnt/scratch`.
|
|
|
|
## Lint passes but the render is blank / black frames
|
|
|
|
Check the browser console in `preview` — usually:
|
|
- A timeline was registered with the wrong key (`__timelines["typo"]` instead of `__timelines["root"]`).
|
|
- The root composition was wrapped in `<template>` (only sub-compositions use `<template>`).
|
|
- A script tag failed to load — check Network tab in preview.
|
|
|
|
Run `npx hyperframes lint --verbose` to see info-level findings.
|
|
|
|
## Contrast warnings from `hyperframes validate`
|
|
|
|
```
|
|
⚠ WCAG AA contrast warnings (3):
|
|
· .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)
|
|
```
|
|
|
|
- **Dark backgrounds:** brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text — 24px+ or 19px+ bold).
|
|
- **Light backgrounds:** darken it.
|
|
- Stay within the palette family — don't invent a new color, adjust the existing one.
|
|
- Skip the check temporarily with `--no-contrast` if iterating rapidly, but clear it before delivery.
|
|
|
|
## `Font family 'X' not supported by compiler`
|
|
|
|
The compiler embeds a curated set of web-safe + open-source fonts. If a font isn't supported, either:
|
|
- Swap to a supported alternative from the warning.
|
|
- Register a custom font via `@font-face` pointing to a `.woff2` in the project directory (the compiler embeds referenced `@font-face` files).
|
|
|
|
## Video plays back muted or with no audio
|
|
|
|
Check:
|
|
- The `<video>` element has `muted playsinline` (required — browser autoplay policy).
|
|
- Audio is a **separate** `<audio>` element, not the video element.
|
|
- Audio `data-volume` is set (defaults to 1).
|
|
- The audio file is at the expected path — compositions load relative to their own directory.
|
|
|
|
## Docker render fails on Linux with rootless Docker
|
|
|
|
Add `--privileged` or pass `--cap-add=SYS_ADMIN`:
|
|
|
|
```bash
|
|
npx hyperframes render --docker --docker-args "--cap-add=SYS_ADMIN"
|
|
```
|
|
|
|
The headless browser needs namespace permissions for sandboxing.
|
|
|
|
## Bug reports
|
|
|
|
Include `npx hyperframes info` output + the full error log. File at [github.com/heygen-com/hyperframes](https://github.com/heygen-com/hyperframes/issues).
|