clarify

Ask the user a question when you need clarification, feedback, or a decision before proceeding. Supports two modes:

1. **Multiple choice** — provide up to 4 choices. The user picks one or types their own answer via a 5th 'Other' option.
2. **Open-ended** — omit choices entirely. The user types a free-form response.

Use this tool when:
- The task is ambiguous and you need the user to choose an approach
- You want post-task feedback ('How did that work out?')
- You want to offer to save a skill or update memory
- A decision has meaningful trade-offs the user should weigh in on

Do NOT use this tool for simple yes/no confirmation of dangerous commands (the terminal tool handles that). Prefer making a reasonable default choice yourself when the decision is low-stakes.

The question to present to the user.

Choices:
Up to 4 answer choices. Omit this parameter entirely to ask an open-ended question. When provided, the UI automatically appends an 'Other (type your answer)' option.

cronjob

Manage scheduled cron jobs with a single compressed tool.

Use action='create' to schedule a new job from a prompt or one or more skills.
Use action='list' to inspect jobs.
Use action='update', 'pause', 'resume', 'remove', or 'run' to manage an existing job.

To stop a job the user no longer wants: first action='list' to find the job_id, then action='remove' with that job_id. Never guess job IDs — always list first.

Jobs run in a fresh session with no current-chat context, so prompts must be self-contained.
If skills are provided on create, the future cron run loads those skills in order, then follows the prompt as the task instruction.
On update, passing skills=[] clears attached skills.

NOTE: The agent's final response is auto-delivered to the target. Put the primary
user-facing content in the final response. Cron jobs run autonomously with no user
present — they cannot ask questions or request clarification.

Important safety rule: cron-run sessions should not recursively schedule more cron jobs.

One of: create, list, update, pause, resume, remove, run

Required for update/pause/resume/remove/run

For create: the full self-contained prompt. If skills are also provided, this becomes the task instruction paired with those skills.

For create/update: '30m', 'every 2h', '0 9 * * *', or ISO timestamp

Optional human-friendly name

Optional repeat count. Omit for defaults (once for one-shot, forever for recurring).

Omit this parameter to auto-deliver back to the current chat and topic (recommended). Auto-detection preserves thread/topic context. Only set explicitly when the user asks to deliver somewhere OTHER than the current conversation. Values: 'origin' (same as omitting), 'local' (no delivery, save only), or platform:chat_id:thread_id for a specific destination. Examples: 'telegram:-1001234567890:17585', 'discord:#engineering', 'sms:+15551234567'. WARNING: 'platform:chat_id' without :thread_id loses topic targeting.

Optional ordered list of skill names to load before executing the cron prompt. On update, pass an empty array to clear attached skills.

Optional per-job model override. If provider is omitted, the current main provider is pinned at creation time so the job stays stable.

Provider name (e.g. 'openrouter', 'anthropic'). Omit to use and pin the current provider.

Model name (e.g. 'anthropic/claude-sonnet-4', 'claude-sonnet-4')

Optional path to a Python script that runs before each cron job execution. Its stdout is injected into the prompt as context. Use for data collection and change detection. Relative paths resolve under ~/.hermes/scripts/. On update, pass empty string to clear.

Optional job ID or list of job IDs whose most recent completed output is injected into the prompt as context before each run. Use this to chain cron jobs: job A collects data, job B processes it. Each entry must be a valid job ID (from cronjob action='list'). Note: injects the most recent completed output — does not wait for upstream jobs running in the same tick. On update, pass an empty array to clear.

Optional list of toolset names to restrict the job's agent to (e.g. ["web", "terminal", "file", "delegation"]). When set, only tools from these toolsets are loaded, significantly reducing input token overhead. When omitted, all default tools are loaded. Infer from the job's prompt — e.g. use "web" if it calls web_search, "terminal" if it runs scripts, "file" if it reads files, "delegation" if it calls delegate_task. On update, pass an empty array to clear.

Optional absolute path to run the job from. When set, AGENTS.md / CLAUDE.md / .cursorrules from that directory are injected into the system prompt, and the terminal/file/code_exec tools use it as their working directory — useful for running a job inside a specific project repo. Must be an absolute path that exists. When unset (default), preserves the original behaviour: no project context files, tools use the scheduler's cwd. On update, pass an empty string to clear. Jobs with workdir run sequentially (not parallel) to keep per-job directories isolated.

Spawn one or more subagents to work on tasks in isolated contexts. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary is returned -- intermediate tool results never enter your context window.

TWO MODES (one of 'goal' or 'tasks' is required):
1. Single task: provide 'goal' (+ optional context, toolsets)
2. Batch (parallel): provide 'tasks' array with up to delegation.max_concurrent_children items (default 3, configurable via config.yaml, no hard ceiling). All run concurrently and results are returned together. Nested delegation requires role='orchestrator' and delegation.max_spawn_depth >= 2.

WHEN TO USE delegate_task:
- Reasoning-heavy subtasks (debugging, code review, research synthesis)
- Tasks that would flood your context with intermediate data
- Parallel independent workstreams (research A and B simultaneously)

WHEN NOT TO USE (use these instead):
- Mechanical multi-step work with no reasoning needed -> use execute_code
- Single tool call -> just call the tool directly
- Tasks needing user interaction -> subagents cannot use clarify
- Durable long-running work that must outlive the current turn -> use cronjob (action='create') or terminal(background=True, notify_on_complete=True) instead. delegate_task runs SYNCHRONOUSLY inside the parent turn: if the parent is interrupted (user sends a new message, /stop, /new) the child is cancelled with status='interrupted' and its work is discarded. Children cannot continue in the background.

IMPORTANT:
- Subagents have NO memory of your conversation. Pass all relevant info (file paths, error messages, constraints) via the 'context' field.
- If the user is writing in a non-English language, or asked for output in a specific language / tone / style, say so in 'context' (e.g. "respond in Chinese", "return output in Japanese"). Otherwise subagents default to English and their summaries will contaminate your final reply with the wrong language.
- Subagent summaries are SELF-REPORTS, not verified facts. A subagent that claims "uploaded successfully" or "file written" may be wrong. For operations with external side-effects (HTTP POST/PUT, remote writes, file creation at shared paths, publishing), require the subagent to return a verifiable handle (URL, ID, absolute path, HTTP status) and verify it yourself — fetch the URL, stat the file, read back the content — before telling the user the operation succeeded.
- Leaf subagents (role='leaf', the default) CANNOT call: delegate_task, clarify, memory, send_message, execute_code.
- Orchestrator subagents (role='orchestrator') retain delegate_task so they can spawn their own workers, but still cannot use clarify, memory, send_message, or execute_code. Orchestrators are bounded by delegation.max_spawn_depth (default 2) and can be disabled globally via delegation.orchestrator_enabled=false.
- Each subagent gets its own terminal session (separate working directory and state).
- Results are always returned as an array, one entry per task.

What the subagent should accomplish. Be specific and self-contained -- the subagent knows nothing about your conversation history.

Background information the subagent needs: file paths, error messages, project structure, constraints. The more specific you are, the better the subagent performs.

Toolsets to enable for this subagent. Default: inherits your enabled toolsets. Available toolsets: 'browser', 'cronjob', 'discord', 'discord_admin', 'feishu_doc', 'feishu_drive', 'file', 'homeassistant', 'image_gen', 'kanban', 'search', 'session_search', 'skills', 'spotify', 'terminal', 'todo', 'tts', 'vision', 'web', 'yuanbao'. Common patterns: ['terminal', 'file'] for code work, ['web'] for research, ['browser'] for web interaction, ['terminal', 'file', 'web'] for full-stack tasks.

Task goal

Task-specific context

Toolsets for this specific task. Available: 'browser', 'cronjob', 'discord', 'discord_admin', 'feishu_doc', 'feishu_drive', 'file', 'homeassistant', 'image_gen', 'kanban', 'search', 'session_search', 'skills', 'spotify', 'terminal', 'todo', 'tts', 'vision', 'web', 'yuanbao'. Use 'web' for network access, 'terminal' for shell, 'browser' for web interaction.

Per-task ACP command override (e.g. 'claude'). Overrides the top-level acp_command for this task only.

Per-task ACP args override.

Per-task role override. See top-level 'role' for semantics.

Batch mode: tasks to run in parallel (limit configurable via delegation.max_concurrent_children, default 3). Each gets its own subagent with isolated context and terminal session. When provided, top-level goal/context/toolsets are ignored.

Role of the child agent. 'leaf' (default) = focused worker, cannot delegate further. 'orchestrator' = can use delegate_task to spawn its own workers. Requires delegation.max_spawn_depth >= 2 in config; ignored (treated as 'leaf') when the child would exceed max_spawn_depth or when delegation.orchestrator_enabled=false.

Override ACP command for child agents (e.g. 'claude', 'copilot'). When set, children use ACP subprocess transport instead of inheriting the parent's transport. Enables spawning Claude Code (claude --acp --stdio) or other ACP-capable agents from any parent, including Discord/Telegram/CLI.

Arguments for the ACP command (default: ['--acp', '--stdio']). Only used when acp_command is set. Example: ['--acp', '--stdio', '--model', 'claude-opus-4-6']

Run a Python script that can call Hermes tools programmatically. Use this when you need 3+ tool calls with processing logic between them, need to filter/reduce large tool outputs before they enter your context, need conditional branching (if X then Y else Z), or need to loop (fetch N pages, process N files, retry on failure).

Use normal tool calls instead when: single tool call with no processing, you need to see the full result and apply complex reasoning, or the task requires interactive user input.

Available via `from hermes_tools import ...`:

  read_file(path: str, offset: int = 1, limit: int = 500) -> dict
    Lines are 1-indexed. Returns {"content": "...", "total_lines": N}
  write_file(path: str, content: str) -> dict
    Always overwrites the entire file.
  search_files(pattern: str, target="content", path=".", file_glob=None, limit=50) -> dict
    target: "content" (search inside files) or "files" (find files by name). Returns {"matches": [...]}
  patch(path: str, old_string: str, new_string: str, replace_all: bool = False) -> dict
    Replaces old_string with new_string in the file.
  terminal(command: str, timeout=None, workdir=None) -> dict
    Foreground only (no background/pty). Returns {"output": "...", "exit_code": N}

Limits: 5-minute timeout, 50KB stdout cap, max 50 tool calls per script. terminal() is foreground-only (no background or pty).

Scripts run in the session's working directory with the active venv's python, so project deps (pandas, etc.) and relative paths work like in terminal().

Print your final result to stdout. Use Python stdlib (json, re, math, csv, datetime, collections, etc.) for processing between tool calls.

Also available (no import needed — built into hermes_tools):
  json_parse(text: str) — json.loads with strict=False; use for terminal() output with control chars
  shell_quote(s: str) — shlex.quote(); use when interpolating dynamic strings into shell commands
  retry(fn, max_attempts=3, delay=2) — retry with exponential backoff for transient failures

Python code to execute. Import tools with `from hermes_tools import terminal, ...` and print your final result to stdout.

memory

Save durable information to persistent memory that survives across sessions. Memory is injected into future turns, so keep it compact and focused on facts that will still matter later.

WHEN TO SAVE (do this proactively, don't wait to be asked):
- User corrects you or says 'remember this' / 'don't do that again'
- User shares a preference, habit, or personal detail (name, role, timezone, coding style)
- You discover something about the environment (OS, installed tools, project structure)
- You learn a convention, API quirk, or workflow specific to this user's setup
- You identify a stable fact that will be useful again in future sessions

PRIORITY: User preferences and corrections > environment facts > procedural knowledge. The most valuable memory prevents the user from having to repeat themselves.

Do NOT save task progress, session outcomes, completed-work logs, or temporary TODO state to memory; use session_search to recall those from past transcripts.
If you've discovered a new way to do something, solved a problem that could be necessary later, save it as a skill with the skill tool.

TWO TARGETS:
- 'user': who the user is -- name, role, preferences, communication style, pet peeves
- 'memory': your notes -- environment facts, project conventions, tool quirks, lessons learned

ACTIONS: add (new entry), replace (update existing -- old_text identifies it), remove (delete -- old_text identifies it).

SKIP: trivial/obvious info, things easily re-discovered, raw data dumps, and temporary task state.

The action to perform.

Which memory store: 'memory' for personal notes, 'user' for user profile.

The entry content. Required for 'add' and 'replace'.

Short unique substring identifying the entry to replace or remove.

patch

Targeted find-and-replace edits in files. Use this instead of sed/awk in terminal. Uses fuzzy matching (9 strategies) so minor whitespace/indentation differences won't break it. Returns a unified diff. Auto-runs syntax checks after editing.

Replace mode (default): find a unique string and replace it.
Patch mode: apply V4A multi-file patches for bulk changes.

Edit mode: 'replace' for targeted find-and-replace, 'patch' for V4A multi-file patches

File path to edit (required for 'replace' mode)

Text to find in the file (required for 'replace' mode). Must be unique in the file unless replace_all=true. Include enough surrounding context to ensure uniqueness.

Replacement text (required for 'replace' mode). Can be empty string to delete the matched text.

Replace all occurrences instead of requiring a unique match (default: false)

V4A format patch content (required for 'patch' mode). Format:
*** Begin Patch
*** Update File: path/to/file
@@ context hint @@
 context line
-removed line
+added line
*** End Patch

process

Manage background processes started with terminal(background=true). Actions: 'list' (show all), 'poll' (check status + new output), 'log' (full output with pagination), 'wait' (block until done or timeout), 'kill' (terminate), 'write' (send raw stdin data without newline), 'submit' (send data + Enter, for answering prompts), 'close' (close stdin/send EOF).

list poll log wait kill write submit close

Action to perform on background processes

Process session ID (from terminal background output). Required for all actions except 'list'.

Text to send to process stdin (for 'write' and 'submit' actions)

Max seconds to block for 'wait' action. Returns partial output on timeout.

Line offset for 'log' action (default: last 200 lines)

Max lines to return for 'log' action

Read a text file with line numbers and pagination. Use this instead of cat/head/tail in terminal. Output format: 'LINE_NUM|CONTENT'. Suggests similar filenames if not found. Use offset and limit for large files. Reads exceeding ~100K characters are rejected; use offset and limit to read specific sections of large files. NOTE: Cannot read images or binary files — use vision_analyze for images.

Path to the file to read (absolute, relative, or ~/path)

Line number to start reading from (1-indexed, default: 1)

Maximum number of lines to read (default: 500, max: 2000)

Search file contents or find files by name. Use this instead of grep/rg/find/ls in terminal. Ripgrep-backed, faster than shell equivalents.

Content search (target='content'): Regex search inside files. Output modes: full matches with line numbers, file paths only, or match counts.

File search (target='files'): Find files by glob pattern (e.g., '*.py', '*config*'). Also use this instead of ls — results sorted by modification time.

Regex pattern for content search, or glob pattern (e.g., '*.py') for file search

'content' searches inside file contents, 'files' searches for files by name

Directory or file to search in (default: current working directory)

Filter files by pattern in grep mode (e.g., '*.py' to only search Python files)

Maximum number of results to return (default: 50)

Skip first N results for pagination (default: 0)

Output format for grep mode: 'content' shows matching lines with line numbers, 'files_only' lists file paths, 'count' shows match counts per file

Number of context lines before and after each match (grep mode only)

Send a message to a connected messaging platform, or list available targets.

IMPORTANT: When the user asks to send to a specific channel or person (not just a bare platform name), call send_message(action='list') FIRST to see available targets, then send to the correct one.
If the user just says a platform name like 'send to telegram', send directly to the home channel without listing first.

Action to perform. 'send' (default) sends a message. 'list' returns all available channels/contacts across connected platforms.

Delivery target. Format: 'platform' (uses home channel), 'platform:#channel-name', 'platform:chat_id', or 'platform:chat_id:thread_id' for Telegram topics and Discord threads. Examples: 'telegram', 'telegram:-1001234567890:17585', 'discord:999888777:555444333', 'discord:#bot-home', 'slack:#engineering', 'signal:+155****4567', 'matrix:!roomid:server.org', 'matrix:@user:server.org', 'yuanbao:direct:<account_id>' (DM), 'yuanbao:group:<group_code>' (group chat)

The message text to send. To send an image or file, include MEDIA:<local_path> (e.g. 'MEDIA:/tmp/hermes/cache/img_xxx.jpg') in the message — the platform will deliver it as a native media attachment.

Search your long-term memory of past conversations, or browse recent sessions. This is your recall -- every past session is searchable, and this tool summarizes what happened.

TWO MODES:
1. Recent sessions (no query): Call with no arguments to see what was worked on recently. Returns titles, previews, and timestamps. Zero LLM cost, instant. Start here when the user asks what were we working on or what did we do recently.
2. Keyword search (with query): Search for specific topics across all past sessions. Returns LLM-generated summaries of matching sessions.

USE THIS PROACTIVELY when:
- The user says 'we did this before', 'remember when', 'last time', 'as I mentioned'
- The user asks about a topic you worked on before but don't have in current context
- The user references a project, person, or concept that seems familiar but isn't in memory
- You want to check if you've solved a similar problem before
- The user asks 'what did we do about X?' or 'how did we fix Y?'

Don't hesitate to search when it is actually cross-session -- it's fast and cheap. Better to search and confirm than to guess or ask the user to repeat themselves.

Search syntax: keywords joined with OR for broad recall (elevenlabs OR baseten OR funding), phrases for exact match ("docker networking"), boolean (python NOT java), prefix (deploy*). IMPORTANT: Use OR between keywords for best results — FTS5 defaults to AND which misses sessions that only mention some terms. If a broad OR query returns nothing, try individual keyword searches in parallel. Returns summaries of the top matching sessions.

Search query — keywords, phrases, or boolean expressions to find in past sessions. Omit this parameter entirely to browse recent sessions instead (returns titles, previews, timestamps with no LLM cost).

Optional: only search messages from specific roles (comma-separated). E.g. 'user,assistant' to skip tool outputs.

Max sessions to summarize (default: 3, max: 5).

Manage skills (create, update, delete). Skills are your procedural memory — reusable approaches for recurring task types. New skills go to ~/.hermes/skills/; existing skills can be modified wherever they live.

Actions: create (full SKILL.md + optional category), patch (old_string/new_string — preferred for fixes), edit (full SKILL.md rewrite — major overhauls only), delete, write_file, remove_file.

Create when: complex task succeeded (5+ calls), errors overcome, user-corrected approach worked, non-trivial workflow discovered, or user asks you to remember a procedure.
Update when: instructions stale/wrong, OS-specific failures, missing steps or pitfalls found during use. If you used a skill and hit issues not covered by it, patch it immediately.

After difficult/iterative tasks, offer to save as a skill. Skip for simple one-offs. Confirm with user before creating/deleting.

Good skills: trigger conditions, numbered steps with exact commands, pitfalls section, verification steps. Use skill_view() to see format examples.

Pinned skills are off-limits — all write actions refuse with a message pointing the user to `hermes curator unpin <name>`. Don't try to route around this by renaming or recreating.

create patch edit delete write_file remove_file

The action to perform.

Skill name (lowercase, hyphens/underscores, max 64 chars). Must match an existing skill for patch/edit/delete/write_file/remove_file.

Full SKILL.md content (YAML frontmatter + markdown body). Required for 'create' and 'edit'. For 'edit', read the skill first with skill_view() and provide the complete updated text.

Text to find in the file (required for 'patch'). Must be unique unless replace_all=true. Include enough surrounding context to ensure uniqueness.

Replacement text (required for 'patch'). Can be empty string to delete the matched text.

For 'patch': replace all occurrences instead of requiring a unique match (default: false).

Optional category/domain for organizing the skill (e.g., 'devops', 'data-science', 'mlops'). Creates a subdirectory grouping. Only used with 'create'.

Path to a supporting file within the skill directory. For 'write_file'/'remove_file': required, must be under references/, templates/, scripts/, or assets/. For 'patch': optional, defaults to SKILL.md if omitted.

Content for the file. Required for 'write_file'.

Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a 'linked_files' dict showing available references/templates/scripts. To access those, call again with file_path parameter.

The skill name (use skills_list to see available skills). For plugin-provided skills, use the qualified form 'plugin:skill' (e.g. 'superpowers:writing-plans').

OPTIONAL: Path to a linked file within the skill (e.g., 'references/api.md', 'templates/config.yaml', 'scripts/validate.py'). Omit to get the main SKILL.md content.

List available skills (name + description). Use skill_view(name) to load full content.

Optional category filter to narrow results

terminal

Execute shell commands on a Linux environment. Filesystem usually persists between calls.

Do NOT use cat/head/tail to read files — use read_file instead.
Do NOT use grep/rg/find to search — use search_files instead.
Do NOT use ls to list directories — use search_files(target='files') instead.
Do NOT use sed/awk to edit files — use patch instead.
Do NOT use echo/cat heredoc to create files — use write_file instead.
Reserve terminal for: builds, installs, git, processes, scripts, network, package managers, and anything that needs a shell.

Foreground (default): Commands return INSTANTLY when done, even if the timeout is high. Set timeout=300 for long builds/scripts — you'll still get the result in seconds if it's fast. Prefer foreground for short commands.
Background: Set background=true to get a session_id. Two patterns:
  (1) Long-lived processes that never exit (servers, watchers).
  (2) Long-running tasks with notify_on_complete=true — you can keep working on other things and the system auto-notifies you when the task finishes. Great for test suites, builds, deployments, or anything that takes more than a minute.
For servers/watchers, do NOT use shell-level background wrappers (nohup/disown/setsid/trailing '&') in foreground mode. Use background=true so Hermes can track lifecycle and output.
After starting a server, verify readiness with a health check or log signal, then run tests in a separate terminal() call. Avoid blind sleep loops.
Use process(action="poll") for progress checks, process(action="wait") to block until done.
Working directory: Use 'workdir' for per-command cwd.
PTY mode: Set pty=true for interactive CLI tools (Codex, Claude Code, Python REPL).

Do NOT use vim/nano/interactive tools without pty=true — they hang without a pseudo-terminal. Pipe git output to cat if it might page.

The command to execute on the VM

Run the command in the background. Two patterns: (1) Long-lived processes that never exit (servers, watchers). (2) Long-running tasks paired with notify_on_complete=true — you can keep working and get notified when the task finishes. For short commands, prefer foreground with a generous timeout instead.

Max seconds to wait (default: 180, foreground max: 600). Returns INSTANTLY when command finishes — set high for long tasks, you won't wait unnecessarily. Foreground timeout above 600s is rejected; use background=true for longer commands.

Working directory for this command (absolute path). Defaults to the session working directory.

Run in pseudo-terminal (PTY) mode for interactive CLI tools like Codex, Claude Code, or Python REPL. Only works with local and SSH backends. Default: false.

When true (and background=true), you'll be automatically notified exactly once when the process finishes. **This is the right choice for almost every long-running task** — tests, builds, deployments, multi-item batch jobs, anything that takes over a minute and has a defined end. Use this and keep working on other things; the system notifies you on exit. MUTUALLY EXCLUSIVE with watch_patterns — when both are set, watch_patterns is dropped.

Strings to watch for in background process output. HARD RATE LIMIT: at most 1 notification per 15 seconds per process — matches arriving inside the cooldown are dropped. After 3 consecutive 15-second windows with dropped matches, watch_patterns is automatically disabled for that process and promoted to notify_on_complete behavior (one notification on exit, no more mid-process spam). USE ONLY for truly rare, one-shot mid-process signals on LONG-LIVED processes that will never exit on their own — e.g. ['Application startup complete'] on a server so you know when to hit its endpoint, or ['migration done'] on a daemon. DO NOT use for: (1) end-of-run markers like 'DONE'/'PASS' — use notify_on_complete instead; (2) error patterns like 'ERROR'/'Traceback' in loops or multi-item batch jobs — they fire on every iteration and you'll hit the strike limit fast; (3) anything you'd ever combine with notify_on_complete. When in doubt, choose notify_on_complete. MUTUALLY EXCLUSIVE with notify_on_complete — set one, not both.

Convert text to speech audio. Returns a MEDIA: path that the platform delivers as native audio. Compatible providers render as a voice bubble on Telegram; otherwise audio is sent as a regular attachment. In CLI mode, saves to ~/voice-memos/. Voice and provider are user-configured (built-in providers like edge/openai or custom command providers under tts.providers.<name>), not model-selected.

The text to convert to speech. Provider-specific character caps apply and are enforced automatically (OpenAI 4096, xAI 15000, MiniMax 10000, ElevenLabs 5k-40k depending on model); over-long input is truncated.

Optional custom file path to save the audio. Defaults to ~/.hermes/audio_cache/<timestamp>.mp3

todo

Manage your task list for the current session. Use for complex tasks with 3+ steps or when the user provides multiple tasks. Call with no parameters to read the current list.

Writing:
- Provide 'todos' array to create/update items
- merge=false (default): replace the entire list with a fresh plan
- merge=true: update existing items by id, add any new ones

Each item: {id: string, content: string, status: pending|in_progress|completed|cancelled}
List order is priority. Only ONE item in_progress at a time.
Mark items completed immediately when done. If something fails, cancel it and add a revised item.

Always returns the full current list.

Task items to write. Omit to read current list.

Unique item identifier

Task description

Current status

true: update existing items by id, add new ones. false (default): replace the entire list.

Inspect an image from a URL, file path, or tool output when you need closer detail than what's visible in the conversation. If the user's image is already attached to the conversation and you can see it, just answer directly — only call this tool for images referenced by URL/path, images returned inside other tool results (browser screenshots, search thumbnails), or when you need a deeper look at a specific region the main model's vision may have missed.

Image URL (http/https) or local file path to analyze.

Your specific question or request about the image to resolve. The AI will automatically provide a complete image description AND answer your specific question.

Write content to a file, completely replacing existing content. Use this instead of echo/cat heredoc in terminal. Creates parent directories automatically. OVERWRITES the entire file — use 'patch' for targeted edits.

Path to the file to write (will be created if it doesn't exist, overwritten if it does)

Complete content to write to the file


https://github.com/heygen-com/hyperframes 这个项目是干什么的


Explanation: The user wants to know what this GitHub project does. Let me fetch the README.

terminal

curl -sL https://raw.githubusercontent.com/heygen-com/hyperframes/main/README.md | head -200


Output:
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/logo/dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/logo/light.svg">

  </picture>

Write HTML. Render video. Built for agents.

Hyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents.

## Quick Start

### Option 1: With an AI coding agent (recommended)

Install the HyperFrames skills, then describe the video you want:

```bash
npx skills add heygen-com/hyperframes
```

This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for the dev-loop commands (init, lint, preview, render), `/hyperframes-media` for asset preprocessing (TTS, transcription, background removal), `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, or the adapter skills (`/animejs`, `/css-animations`, `/lottie`, `/three`, `/waapi`) when a composition uses those runtimes.

For Claude Design, open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub and click the download button (↓) to save it, then attach the file to your Claude Design chat. It produces a valid first draft; refine in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design).

For Codex specifically, the same skills are also exposed as an [OpenAI Codex plugin](./.codex-plugin/plugin.json) — sparse-install just the plugin surface:

```bash
codex plugin marketplace add heygen-com/hyperframes --sparse .codex-plugin --sparse skills --sparse assets
```

For Claude Code, the repo also ships a [Claude Code plugin manifest](./.claude-plugin/plugin.json): test it locally with `claude --plugin-dir .`. The manifest intentionally omits `skills` because Claude Code auto-discovers the root `skills/` directory by convention, and for marketplace submission use the title `HyperFrames by HeyGen` plus the black/white icon assets at [`assets/claude-code-icon-dark.svg`](./assets/claude-code-icon-dark.svg) and [`assets/claude-code-icon-light.svg`](./assets/claude-code-icon-light.svg) for the two theme slots.
For Cursor, the same skills are packaged as a [Cursor plugin](./.cursor-plugin/plugin.json) — install from the Cursor Marketplace, or sideload by cloning this repo and pointing **Settings → Plugins → Load unpacked** at the repo root.

#### Try it: example prompts

Copy any of these into your agent to get started. The `/hyperframes` prefix loads the skill context explicitly so you get correct output the first time.

**Cold start — describe what you want:**

> Using `/hyperframes`, create a 10-second product intro with a fade-in title, a background video, and background music.

**Warm start — turn existing context into a video:**

> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`.

> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`.

> Turn this CSV into an animated bar chart race using `/hyperframes`.

**Format-specific:**

> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.

**Iterate — talk to the agent like a video editor:**

> Make the title 2x bigger, swap to dark mode, and add a fade-out at the end.

> Add a lower third at 0:03 with my name and title.

The agent handles scaffolding, animation, and rendering. See the [prompting guide](https://hyperframes.heygen.com/guides/prompting) for more patterns.

### Option 2: Start a project manually

```bash
npx hyperframes init my-video
cd my-video
npx hyperframes preview      # preview in browser (live reload)
npx hyperframes render       # render to MP4
```

`hyperframes init` installs skills automatically, so you can hand off to your AI agent at any point.

**Requirements:** Node.js >= 22, FFmpeg

## Why Hyperframes?

- **HTML-native** — compositions are HTML files with data attributes. No React, no proprietary DSL.
- **AI-first** — agents already speak HTML. The CLI is non-interactive by default, designed for agent-driven workflows.
- **Deterministic rendering** — same input = identical output. Built for automated pipelines.
- **Frame Adapter pattern** — bring your own animation runtime (GSAP, Lottie, CSS, Three.js).

## Hyperframes vs Remotion

Hyperframes is inspired by [Remotion](https://www.remotion.dev) — we used Remotion at HeyGen in production, learned a ton from it, and kept attribution comments in the source for the patterns it pioneered (Chrome launch flags, image2pipe → FFmpeg streaming, frame buffering). Both tools drive headless Chrome and both are deterministic. They differ on one decision: **what the primary author writes.** Remotion's bet is React components; Hyperframes' bet is HTML.

|                                                       | **Hyperframes**                | **Remotion**                      |
| ----------------------------------------------------- | ------------------------------ | --------------------------------- |
| Authoring                                             | HTML + CSS + GSAP              | React components (TSX)            |
| Build step                                            | None; `index.html` plays as-is | Required (bundler)                |
| Library-clock animations (GSAP, Anime.js, Motion One) | Seekable, frame-accurate       | Plays at wall-clock during render |
| Arbitrary HTML / CSS passthrough                      | Paste and animate              | Rewrite as JSX                    |
| Distributed rendering                                 | Single-machine today           | Lambda, production-ready          |

### Licensing: fully open source vs source-available

**Hyperframes is completely open source under [Apache 2.0](LICENSE)** — an OSI-approved license. Use it commercially at any scale, with no per-render fees, no seat caps, no company-size thresholds.

**Remotion is [source-available, not open source](https://www.remotion.pro/license).** The code is on GitHub under a custom Remotion License that requires a paid company license above small-team thresholds. It's a great product with a real team behind it — but if open-source licensing matters to you (OSI compliance, redistribution rights, no per-use fees), that's a first-order decision point.

Full write-up with benchmarks, an honest list of where each tool wins, and a GSAP side-by-side: **[Hyperframes vs Remotion guide](https://hyperframes.heygen.com/guides/hyperframes-vs-remotion)**.

## How It Works

Define your video as HTML with data attributes:

```html
<div id="stage" data-composition-id="my-video" data-start="0" data-width="1920" data-height="1080">
  <video
    id="clip-1"
    data-start="0"
    data-duration="5"
    data-track-index="0"
    src="intro.mp4"
    muted
    playsinline
  ></video>
  <img
    id="overlay"
    class="clip"
    data-start="2"
    data-duration="3"
    data-track-index="1"
    src="logo.png"
  />
  <audio
    id="bg-music"
    data-start="0"
    data-duration="9"
    data-track-index="2"
    data-volume="0.5"
    src="music.wav"
  ></audio>
</div>
```

Preview instantly in the browser. Render to MP4 locally or in Docker.

## Catalog

50+ ready-to-use blocks and components — social overlays, shader transitions, data visualizations, and cinematic effects:

```bash
npx hyperframes add flash-through-white   # shader transition
npx hyperframes add instagram-follow      # social overlay
npx hyperframes add data-chart            # animated chart
```

Browse the full catalog at **[hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart)**.

## Documentation

Full documentation at **[hyperframes.heygen.com/introduction](https://hyperframes.heygen.com/introduction)** — [Quickstart](https://hyperframes.heygen.com/quickstart) | [Guides](https://hyperframes.heygen.com/guides/gsap-animation) | [API Reference](https://hyperframes.heygen.com/packages/core) | [Catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart)

## Packages

| Package                                                          | Description                                                 |
| ---------------------------------------------------------------- | ----------------------------------------------------------- |
| [`hyperframes`](packages/cli)                                    | CLI — create, preview, lint, and render compositions        |
| [`@hyperframes/core`](packages/core)                             | Types, parsers, generators, linter, runtime, frame adapters |
| [`@hyperframes/engine`](packages/engine)                         | Seekable page-to-video capture engine (Puppeteer + FFmpeg)  |
| [`@hyperframes/producer`](packages/producer)                     | Full rendering pipeline (capture + encode + audio mix)      |
| [`@hyperframes/studio`](packages/studio)                         | Browser-based composition editor UI                         |
| [`@hyperframes/player`](packages/player)                         | Embeddable `<hyperframes-player>` web component             |
| [`@hyperframes/shader-transitions`](packages/shader-transitions) | WebGL shader transitions for compositions                   |

## Skills

HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI agents framework-specific patterns that generic docs don't cover.

```bash
npx skills add heygen-com/hyperframes
```

| Skill                     | What it teaches                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `hyperframes`             | HTML composition authoring, captions, TTS, audio-reactive animation, transitions                                    |
| `hyperframes-cli`         | Dev-loop CLI: init, lint, inspect, preview, render, doctor                                                          |
| `hyperframes-media`       | Asset preprocessing: tts (Kokoro), transcribe (Whisper), remove-background (u2net) — voice/model/codec selection    |
| `hyperframes-registry`    | Block and component installation via `hyperframes add`                                                              |
| `website-to-hyperframes`  | Capture a URL and turn it into a video — full website-to-video pipeline                                             |
| `remotion-to-hyperframes` | Translate a Remotion (React) composition into a HyperFrames HTML composition                                        |
| `gsap`                    | GSAP timelines for HyperFrames: paused registration, deterministic seeking, easing, sequencing, performance         |
| `animejs`                 | Anime.js animations and timelines registered on `window.__hfAnime` for deterministic HyperFrames seeking            |
| `css-animations`          | CSS keyframe animation patterns that HyperFrames can discover, pause, and seek                                      |
| `lottie`                  | `lottie-web` and dotLottie players registered on `window.__hfLottie` with local assets and paused playback          |
| `three`                   | Three.js scenes that render from HyperFrames `hf-seek` events and `window.__hfThreeTime` instead of wall-clock time |


**HyperFrames** 是 HeyGen 开源的一个**视频渲染框架**，核心理念是：

> **用 HTML 写视频，渲染成 MP4。专为 AI Agent 设计。**

### 主要特点

1. **HTML 原生** — 视频合成就是 HTML 文件 + data 属性，不需要 React 或专有 DSL
2. **AI 优先** — Agent（Claude Code、Cursor、Codex 等）天然懂 HTML，可以用自然语言描述视频，自动生成
3. **确定性渲染** — 相同输入 = 相同输出，适合自动化流水线
4. **Frame Adapter 模式** — 支持多种动画运行时：GSAP、Lottie、CSS 动画、Three.js 等

### 工作方式

用 HTML + data 属性定义视频的时间轴、素材、轨道：

```html
<div id="stage" data-start="0" data-width="1920" data-height="1080">
  <video data-start="0" data-duration="5" src="intro.mp4" muted></video>
  <img data-start="2" data-duration="3" src="logo.png" />
  <audio data-start="0" data-duration="9" src="music.wav" />
</div>
```

浏览器预览 → FFmpeg 渲染成 MP4。

### 和 Remotion 的区别

Remotion 用 React 写，HyperFrames 用纯 HTML 写。而且 HyperFrames 是 **Apache 2.0 完全开源**，Remotion 是 source-available（商用有门槛）。

### 50+ 现成组件

社交叠加层、着色器转场、数据可视化、电影特效等，`npx hyperframes add xxx` 直接用。

简单说：**把 HTML 当视频编辑器用，AI 帮你写 HTML，框架帮你渲染成视频。** 🎬

Explanation: Got enough info.


如何部署的,能部署到你当前服务器吗


Explanation: Let me check the deployment requirements and see if we can run it on the current server.

node --version && npx --version && ffmpeg -version 2>/dev/null | head -1 || echo "ffmpeg not installed"


Output:
v22.22.2
10.9.7
ffmpeg version 6.1.1-3ubuntu5 Copyright (c) 2000-2023 the FFmpeg developers


当前服务器完全满足要求 ✅

**环境检查：**
- Node.js v22.22.2 ✅（要求 >= 22）
- FFmpeg 6.1 ✅
- npx 10.9.7 ✅

### 部署方式

**方式一：快速体验（不装项目，直接用）**

```bash
# 初始化一个视频项目
npx hyperframes init my-video
cd my-video

# 浏览器预览（会开一个本地服务器）
npx hyperframes preview

# 渲染成 MP4
npx hyperframes render
```

**方式二：Docker 部署**（适合无头服务器）

项目自带 Dockerfile，可以容器化运行。

---

要我现在在服务器上初始化一个示例项目试一下吗？⚠ 注意 `preview` 需要浏览器访问，当前服务器没有桌面环境，但 `render` 可以直接渲染出 MP4 文件。

Explanation: Node.js >= 22 ✓, FFmpeg ✓. The server has all prerequisites. Let me give the user deployment instructions.


1. preview生成不了MP4视频吗,
2. render不用浏览器打开吗,
3. 你是说在你的服务器用浏览器打开还是其他局域网电脑浏览器打开
4. docker部署和方式一有什么区别


好问题，逐个回答：

### 1. preview 生成不了 MP4 吗？

**不能。** preview 是开一个本地开发服务器，让你在浏览器里实时预览视频效果（类似热更新），不产出文件。只有 `render` 才会渲染出 MP4。

### 2. render 不用浏览器打开吗？

**不用。** render 底层用的是 **Puppeteer（无头 Chrome）**，完全在后台运行，不需要打开任何可见的浏览器窗口，直接输出 MP4 文件。所以服务器没有桌面环境也能跑。

### 3. preview 的浏览器怎么访问？

preview 会启动一个本地 HTTP 服务（比如 `http://localhost:3000`）。你可以：
- **同一局域网的电脑**浏览器打开 `http://服务器IP:3000` 访问
- 或者用 SSH 端口转发：`ssh -L 3000:localhost:3000 服务器`，然后本地浏览器访问 `localhost:3000`

### 4. Docker 方式 vs 直接安装的区别

| | 直接安装 | Docker |
|---|---|---|
| 环境 | 依赖本机的 Node.js、FFmpeg | 自带所有依赖，隔离环境 |
| 适合 | 开发调试、交互式编辑 | CI/CD 流水线、批量渲染、干净环境 |
| 灵活度 | 高，直接改文件 | 需要挂载卷或进入容器改 |
| 资源 | 轻量 | 多一层容器开销 |

**总结：** 你当前服务器环境齐全，直接用方式一最简单。要我现在装一个试试？

Explanation:
Good questions. Let me answer based on the README.

1. Preview is for browser preview with live reload, not for generating MP4. Render generates MP4.
2. Render uses headless Chrome (Puppeteer) - no visible browser needed, it runs in the background.
3. Preview opens a local dev server, you can access it from any machine that can reach the server's IP.
4. Docker wraps everything in a container, useful for CI/CD or environments without Node/FFmpeg installed.

Let me clarify these for the user.


preview和render能不能同事实现


**可以同时跑，互不影响。**

它们是两个独立进程：
- **preview** → 起一个 HTTP 开发服务器给你浏览器看
- **render** → 启动无头 Chrome 后台渲染输出 MP4

各用各的端口和 Chrome 实例，不冲突。

典型的开发流程就是左边 `preview` 实时预览调效果，右边 `render` 最终出片。

Explanation:
The user is asking if preview and render can run at the same time (simultaneously).

Technically yes - they're just two separate processes. Preview runs a dev server, render runs headless Chrome to capture frames. They could potentially conflict if they try to use the same Chrome instance or same port, but generally they should be able to run concurrently since render uses its own headless Chrome and preview is just a static server.

Let me think more carefully - preview likely uses a port for the dev server, and render likely spins up its own headless Chrome pointing at the composition file directly or through its own server. They should be independent processes.

The answer is: yes, they can run simultaneously as they're independent processes.


那我现在在局域网另一台电脑用render生成视频,是要到命令行中操作是吗


对，**render 是命令行操作**。你需要 SSH 到服务器执行：

```bash
# SSH 连到服务器
ssh longshao@服务器IP

# 进入项目目录
cd my-video

# 渲染
npx hyperframes render
```

渲染完成后 MP4 文件就在项目目录里，你可以用 `scp` 或其他方式拷到本地。

---

**如果你不想用命令行**，有两个替代思路：

1. **preview 预览 + 录屏** — 浏览器里看效果，用录屏工具录制
2. **把 render 包一层 Web 界面** — 需要自己开发或用其他工具，原生不支持

目前原生就是 CLI 工具，没有图形界面的渲染按钮。

Explanation:
The user is asking if they need to use the command line to run render from another machine on the LAN.

Yes, `render` is a CLI command. You'd SSH into the server and run the command. Or you could set up some kind of web interface, but by default it's CLI.

Let me give a clear answer.


你帮我将两个都装上,preview和render


Explanation: The user wants me to install hyperframes and set up both preview and render on the server. Let me do that.

todo

初始化 hyperframes 项目

启动 preview 预览服务

测试 render 渲染 MP4


初始化 hyperframes 项目

启动 preview 预览服务

测试 render 渲染 MP4


Explanation: Let me initialize the hyperframes project first.

terminal

cd /home/longshao && npx hyperframes init my-video 2>&1


Output:
npm warn exec The following package was not found and will be installed: hyperframes@0.5.5
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead


Explanation: It seems like it failed silently. Let me check what happened.

cd /home/longshao && npx hyperframes init my-video 2>&1; echo "EXIT: $?"


Output:
npm warn exec The following package was not found and will be installed: hyperframes@0.5.5
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
EXIT: 1


Explanation: It's failing silently. Let me try installing it globally first or see what's going on.

cd /home/longshao && npx --yes hyperframes@latest init my-video 2>&1


Output: npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead


Explanation: Still failing. Let me try installing it globally and then running the command.


Output:
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
npm error code 1
npm error path /home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node
npm error command failed
npm error command sh -c node ./script/install
npm error /home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node/script/install-utils.js:57
npm error           reject(new Error(`Failed to download build list. HTTP status code = ${statusCode}`));
npm error                  ^
npm error
npm error Error: Failed to download build list. HTTP status code = 302
npm error     at ClientRequest.<anonymous> (/home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node/script/install-utils.js:57:18)
npm error     at Object.onceWrapper (node:events:634:26)
npm error     at ClientRequest.emit (node:events:519:28)
npm error     at HTTPParser.parserOnIncomingClient (node:_http_client:780:27)
npm error     at HTTPParser.parserOnHeadersComplete (node:_http_common:125:17)
npm error     at TLSSocket.socketOnData (node:_http_client:615:22)
npm error     at TLSSocket.emit (node:events:519:28)
npm error     at addChunk (node:internal/streams/readable:561:12)
npm error     at readableAddChunkPushByteMode (node:internal/streams/readable:512:3)
npm error     at Readable.push (node:internal/streams/readable:392:5)
npm error
npm error Node.js v22.22.2
npm error A complete log of this run can be found in: /home/longshao/.npm/_logs/2026-05-09T05_05_52_163Z-debug-0.log


Explanation: The issue is with onnxruntime-node trying to download something and getting a 302 redirect which it doesn't handle. This is likely a proxy issue since the server uses mihomo/Clash proxy on port 7890. Let me try setting the proxy for npm.

npm config get proxy && npm config get https-proxy


Output:
null
null


Explanation: The npm proxy isn't set. Let me set it and try again.

npm config set proxy http://127.0.0.1:7890 && npm config set https-proxy http://127.0.0.1:7890 && npm install -g hyperframes 2>&1


Output:
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
npm error code 1
npm error path /home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node
npm error command failed
npm error command sh -c node ./script/install
npm error /home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node/script/install-utils.js:57
npm error           reject(new Error(`Failed to download build list. HTTP status code = ${statusCode}`));
npm error                  ^
npm error
npm error Error: Failed to download build list. HTTP status code = 302
npm error     at ClientRequest.<anonymous> (/home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node/script/install-utils.js:57:18)
npm error     at Object.onceWrapper (node:events:634:26)
npm error     at ClientRequest.emit (node:events:519:28)
npm error     at HTTPParser.parserOnIncomingClient (node:_http_client:780:27)
npm error     at HTTPParser.parserOnHeadersComplete (node:_http_common:125:17)
npm error     at TLSSocket.socketOnData (node:_http_client:615:22)
npm error     at TLSSocket.emit (node:events:519:28)
npm error     at addChunk (node:internal/streams/readable:561:12)
npm error     at readableAddChunkPushByteMode (node:internal/streams/readable:512:3)
npm error     at Readable.push (node:internal/streams/readable:392:5)
npm error
npm error Node.js v22.22.2
npm error A complete log of this run can be found in: /home/longshao/.npm/_logs/2026-05-09T05_06_05_702Z-debug-0.log


Explanation: Still failing on onnxruntime-node. The issue is that onnxruntime-node's install script uses its own HTTP client and doesn't respect npm proxy settings. Let me try a different approach - set environment variables for the proxy.

export HTTP_PROXY=http://127.0.0.1:7890 && export HTTPS_PROXY=http://127.0.0.1:7890 && npm install -g hyperframes 2>&1


Output:
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
npm error code 1
npm error path /home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node
npm error command failed
npm error command sh -c node ./script/install
npm error /home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node/script/install-utils.js:57
npm error           reject(new Error(`Failed to download build list. HTTP status code = ${statusCode}`));
npm error                  ^
npm error
npm error Error: Failed to download build list. HTTP status code = 302
npm error     at ClientRequest.<anonymous> (/home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/onnxruntime-node/script/install-utils.js:57:18)
npm error     at Object.onceWrapper (node:events:634:26)
npm error     at ClientRequest.emit (node:events:519:28)
npm error     at HTTPParser.parserOnIncomingClient (node:_http_client:780:27)
npm error     at HTTPParser.parserOnHeadersComplete (node:_http_common:125:17)
npm error     at TLSSocket.socketOnData (node:_http_client:615:22)
npm error     at TLSSocket.emit (node:events:519:28)
npm error     at addChunk (node:internal/streams/readable:561:12)
npm error     at readableAddChunkPushByteMode (node:internal/streams/readable:512:3)
npm error     at Readable.push (node:internal/streams/readable:392:5)
npm error
npm error Node.js v22.22.2
npm error A complete log of this run can be found in: /home/longshao/.npm/_logs/2026-05-09T05_06_15_892Z-debug-0.log


Explanation:
The onnxruntime-node install script is following a 302 redirect but treating it as an error. This is a known issue with onnxruntime-node when behind a proxy. The onnxruntime-node package is a dependency that hyperframes probably uses for some AI feature (like background removal with u2net).

Let me try to see if I can install it without the onnxruntime dependency, or try a different approach. Let me check the npm log for more details, and also see if I can use `--ignore-scripts` to skip the onnxruntime build step.

export HTTP_PROXY=http://127.0.0.1:7890 && export HTTPS_PROXY=http://127.0.0.1:7890 && npm install -g hyperframes --ignore-scripts 2>&1


Output:
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead

added 162 packages in 5s

35 packages are looking for funding
  run `npm fund` for details


Explanation: It installed successfully by skipping scripts. The onnxruntime-node post-install script was the problem. Let me now try to manually fix the onnxruntime-node issue and then initialize the project.


Explanation: Good, hyperframes is installed. Now let me initialize the project.

cd /home/longshao && hyperframes init my-video 2>&1


Output:
Hyperframes collects anonymous usage data to improve the tool.
  No personal info, file paths, or content is collected.

  Disable anytime: hyperframes telemetry disable

Created my-video/
  AGENTS.md
  CLAUDE.md
  hyperframes.json
  index.html
  meta.json
  package.json

Get started:

  1. Install AI coding skills (one-time):
     npx skills add heygen-com/hyperframes

  2. Open this project with your AI coding agent:
     cd my-video then start Claude Code, Cursor, or your preferred agent

  3. Try a starter prompt:
     "Using /hyperframes, create a 15-second intro about [your topic]"
     More patterns: hyperframes.heygen.com/guides/prompting

  4. Preview in the browser:
     cd my-video && npm run dev

  5. Check the composition:
     cd my-video && npm run check

  6. Render to MP4 when ready:
     cd my-video && npm run render

  Full docs: hyperframes.heygen.com


Explanation: Project initialized. Now let me install the dependencies and fix the onnxruntime-node issue, then set up preview and render.

todo

初始化 hyperframes 项目

安装项目依赖并修复 onnxruntime

启动 preview 预览服务

测试 render 渲染 MP4


初始化 hyperframes 项目

安装项目依赖并修复 onnxruntime

启动 preview 预览服务

测试 render 渲染 MP4


Explanation: Let me check the project structure and install dependencies.

terminal

cd /home/longshao/my-video && cat package.json 2>&1


{"output": "{\n  \"name\": \"my-video\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"scripts\": {\n    \"dev\": \"npx --yes hyperframes@0.5.5 preview\",\n    \"check\": \"npx --yes hyperframes@0.5.5 lint && npx --yes hyperframes@0.5.5 validate && npx --yes hyperframes@0.5.5 inspect\",\n    \"render\": \"npx --yes hyperframes@0.5.5 render\",\n    \"publish\": \"npx --yes hyperframes@0.5.5 publish\"\n  }\n}", "exit_code": 0, "error": null}

[Subdirectory context discovered: my-video/AGENTS.md]
# HyperFrames Composition Project

## Skills

This project uses AI agent skills for framework-specific patterns. Install them if not already present:

```bash
npx skills add heygen-com/hyperframes
```

Skills encode patterns like `window.__timelines` registration, `data-*` attribute semantics, Tailwind v4 browser-runtime styling for `--tailwind` projects, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start.

## Commands

```bash
npm run dev          # preview in browser (studio editor)
npm run check        # lint + validate + inspect
npm run render       # render to MP4
npm run publish      # publish and get a shareable link
npx hyperframes docs <topic> # reference docs in terminal
```

## Project Structure

- `index.html` — main composition (root timeline)
- `compositions/` — sub-compositions referenced via `data-composition-src`
- `assets/` — media files (video, audio, images)
- `meta.json` — project metadata (id, name)
- `transcript.json` — whisper word-level transcript (if generated)

## Linting — Always Run After Changes

After creating or editing any `.html` composition, run the full check before considering the task complete:

```bash
npm run check
```

Fix all errors before presenting the result.

## Key Rules

1. Every timed element needs `data-start`, `data-duration`, and `data-track-index`
2. Visible timed elements **must** have `class="clip"` — the framework uses this for visibility control
3. GSAP timelines must be paused and registered on `window.__timelines`:
   ```js
   window.__timelines = window.__timelines || {};
   window.__timelines["composition-id"] = gsap.timeline({ paused: true });
   ```
4. Videos use `muted` with a separate `<audio>` element for the audio track
5. Sub-compositions use `data-composition-src="compositions/file.html"`
6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches

## Documentation

Full docs: https://hyperframes.heygen.com/introduction

Machine-readable index for AI tools: https://hyperframes.heygen.com/llms.txt


Explanation: The project doesn't have any npm dependencies in package.json - it uses `npx hyperframes` directly. So no `npm install` needed. Let me look at the index.html to understand the sample composition, then start preview and render.

cd /home/longshao/my-video && cat index.html 2>&1


Output:
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=1920, height=1080" />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <style>
      * {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      html,
      body {
        margin: 0;
        width: 1920px;
        height: 1080px;
        overflow: hidden;
        background: #000;
      }
    </style>
  </head>
  <body>
    <div
      id="root"
      data-composition-id="main"
      data-start="0"
      data-duration="10"
      data-width="1920"
      data-height="1080"
    >

      <!--
        Add your clips here. Example:
        <div id="title" class="clip" data-start="0" data-duration="5" data-track-index="1"
             style="font-size: 64px; color: #fff; padding: 40px">
          Hello World
        </div>
      -->
    </div>

    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // Example: tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
      window.__timelines["main"] = tl;
    </script>
  </body>
</html>


Explanation: The project is initialized. Let me add some content to the sample video so we have something to render. Then I'll start preview in background and also try render.

todo

初始化 hyperframes 项目

安装项目依赖并修复 onnxruntime

添加示例内容并启动 preview

测试 render 渲染 MP4


初始化 hyperframes 项目

安装项目依赖并修复 onnxruntime

添加示例内容并启动 preview

测试 render 渲染 MP4


Explanation: Let me add a sample clip to the HTML so we have something to preview and render.

<!doctype html>

    <meta charset="UTF-8" />
    <meta name="viewport" content="width=1920, height=1080" />

        Hello HyperFrames 🎬

        Rendered on Server ✨


先启动 **preview** 服务：

Explanation: Now let me start preview in the background and also try render.

terminal

cd /home/longshao/my-video && npm run dev 2>&1 &
sleep 5
# Check if preview started
curl -s http://localhost:3000 | head -5 || echo "Trying other ports..."
# Also check what port it's on
ss -tlnp | grep node 2>/dev/null || netstat -tlnp 2>/dev/null | grep node


Foreground command uses '&' backgrounding. Use terminal(background=true) for long-lived processes, then run health checks and tests in follow-up terminal calls.


Explanation: Need to use background mode for the preview server.

cd /home/longshao/my-video && npm run dev


Output: Background process started


Explanation: Let me check the output of the preview server.


Explanation: Let me wait a bit and check again.


Explanation: The process is running but no output. Let me check what ports are listening.

ss -tlnp | grep -E 'node|hyper' 2>/dev/null; lsof -i -P -n 2>/dev/null | grep -E 'node|LISTEN' | head -10


Explanation: Hmm, no ports are listening. Let me check if the process is still running and look at the full output.


Explanation: It's running but no output. The npx might be downloading packages. Let me wait longer.


Explanation: Still running with no output. Let me kill this and try running it directly to see what's happening.


Explanation: Let me try running the preview directly to see what's happening.

cd /home/longshao/my-video && hyperframes preview 2>&1 &
PID=$!
sleep 15
kill $PID 2>/dev/null


Explanation: Let me try running it directly without backgrounding and with a timeout.

cd /home/longshao/my-video && timeout 20 hyperframes preview 2>&1 || true


Output:
⚠ gsap_exit_missing_hard_kill: GSAP exit on "#title" ends at the 5.00s clip start boundary without a matching tl.set hard kill. Non-linear seeking can land after the fade and leave stale visibility state.
    Fix: Add `tl.set("#title", { opacity: 0 }, 5.00)` after the exit tween.

┌  hyperframes preview
│
◇  Studio running

  Project   my-video
  Studio    http://localhost:3002

  Edit with your AI agent — it has HyperFrames skills installed.
  Changes reload automatically in the studio.

  Press Ctrl+C to stop

  Shutting down studio...


Preview 启动了！运行在 **http://localhost:3002**。现在后台启动它：

Explanation: The preview is running on port 3002. Now let me start it as a background process and also try render.

cd /home/longshao/my-video && hyperframes preview


Output: Background process started


同时测试 **render**：

Explanation: Good, now let me try render in parallel.

cd /home/longshao/my-video && timeout 120 hyperframes render 2>&1


Output:
◆  Rendering my-video → /home/longshao/my-video/renders/my-video_2026-05-09_05-09-31.mp4
   30fps · standard · auto workers (28 cores detected)
   GPU: browser GPU (auto-detect)

│
◇  Browser not available

✗  Chrome not found

   All providers failed for chrome-headless-shell 131.0.6778.85:
  - DefaultProvider: connect ECONNREFUSED 127.0.0.1:7890
   Run: npx hyperframes browser ensure


需要安装 Chrome。来装一下：

Explanation: Chrome is not installed. Let me install Chrome headless and also check if there's a puppeteer or chromium available.

which google-chrome chromium-browser chromium 2>/dev/null; dpkg -l | grep -i chrom 2>/dev/null | head -5


Output: ii  libchromaprint1:amd64                 1.5.1-5                                 amd64        audio fingerprint library


Explanation: Chrome is not installed. Let me install it. The error says "chrome-headless-shell" is needed. Let me install Chrome/Chromium.


Output:
┌  hyperframes browser ensure
│
◇  No browser found — downloading
│
Error: All providers failed for chrome-headless-shell 131.0.6778.85:
  - DefaultProvider: connect ECONNREFUSED 127.0.0.1:7890
    at installWithProviders (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/@puppeteer/browsers/lib/esm/install.js:108:11)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
    at async install (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/@puppeteer/browsers/lib/esm/install.js:118:12)
    at async ensureBrowser (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:26299:21)
    at async runEnsure (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:43184:18)
    at async runCommand (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:303:49)
    at async runCommand (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:300:25)
    at async runMain (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:399:12)

■  Canceled


Explanation: The issue is that puppeteer is trying to connect to port 7890 (the proxy) but it's being treated as a direct connection. The proxy setting in npm is interfering. Let me unset the npm proxy and try again, or set the environment variable properly for puppeteer.

npm config delete proxy && npm config delete https-proxy && unset HTTP_PROXY && unset HTTPS_PROXY && hyperframes browser ensure 2>&1


Output:
┌  hyperframes browser ensure
│
◇  No browser found — downloading
│
◒  Downloading Chrome Headless Shell v131.0.6778.85◐  Downloading Chrome Headless Shell v131.0.6778.85◓  Downloading Chrome Headless Shell v131.0.6778.85◑  Downloading Chrome Headless Shell v131.0.6778.85◒  Downloading Chrome Headless Shell v131.0.6778.85◐  Downloading Chrome Headless Shell v131.0.6778.85◓  Downloading Chrome Headless Shell v131.0.6778.85◑  Downloading Chrome Headless Shell v131.0.6778.85◒  Downloading Chrome Headless Shell v131.0.6778.85.◐  Downloading Chrome Headless Shell v131.0.6778.85.◓  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB)..◑  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB)..◒  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB)..◑  Downloading Chrome Headless Shell v131.0.6778.85 — 0% (452 B / 107.4 MB)..◒  Downloading Chrome Headless Shell v131.0.6778.85 — 1% (1.1 MB / 107.4 MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 1% (1.1 MB / 107.4 MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 2% (2.2 MB / 107.4 MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 3% (3.2 MB / 107.4 MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 3% (3.2 MB / 107.4 MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 4% (4.3 MB / 107.4 MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 5% (5.4 MB / 107.4 MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 6% (6.5 MB / 107.4 MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 7% (7.5 MB / 107.4 MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 7% (7.5 MB / 107.4 MB)◓  Downloading Chrome Headless Shell v131.0.6778.85 — 8% (8.6 MB / 107.4 MB)◑  Downloading Chrome Headless Shell v131.0.6778.85 — 9% (9.7 MB / 107.4 MB)◒  Downloading Chrome Headless Shell v131.0.6778.85 — 10% (10.7 MB / 107.4 MB)◐  Downloading Chrome Headless Shell v131.0.6778.85 — 11% (11.8 MB / 107.4 MB)◓  Downloading Chrome Headless Shell v131.0.6778.85 — 11% (11.8 MB / 107.4 MB)◑  Downloading Chrome Headless Shell v131.0.6778.85 — 12% (12.9 MB / 107.4 MB)◒  Downloading Chrome Headless Shell v131.0.6778.85 — 13% (14.0 MB / 107.4 MB)◐  Downloading Chrome Headless Shell v131.0.6778.85 — 14% (15.0 MB / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 15% (16.1 MB / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 15% (16.1 MB / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 16% (17.2 MB / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 17% (18.3 MB / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 18% (19.3 MB / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 19% (20.4 MB / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 20% (21.5 MB / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 20% (21.5 MB / 107.4 MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 21% (22.6 MB / 107.4 MB)..◑  Downloading Chrome Headless Shell v131.0.6778.85 — 22% (23.6 MB / 107.4 MB)..◒  Downloading Chrome Headless Shell v131.0.6778.85 — 23% (24.7 MB / 107.4 MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 24% (25.8 MB / 107.4 MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 24% (25.8 MB / 107.4 MB)..◑  Downloading Chrome Headless Shell v131.0.6778.85 — 25% (26.8 MB / 107.4 MB)..◒  Downloading Chrome Headless Shell v131.0.6778.85 — 26% (27.9 MB / 107.4 MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 27% (29.0 MB / 107.4
MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 28% (30.1 MB / 107.4
MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 28% (30.1 MB / 107.4
MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 29% (31.1 MB / 107.4
MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 30% (32.2 MB / 107.4
MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 31% (33.3 MB / 107.4
MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 32% (34.4 MB / 107.4
MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 32% (34.4 MB / 107.4
MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 33% (35.4 MB / 107.4
MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 34% (36.5 MB / 107.4 MB)◑  Downloading Chrome Headless Shell v131.0.6778.85 — 35% (37.6 MB / 107.4 MB)◒  Downloading Chrome Headless Shell v131.0.6778.85 — 36% (38.7 MB / 107.4 MB)◐  Downloading Chrome Headless Shell v131.0.6778.85 — 37% (39.7 MB / 107.4 MB)◓  Downloading Chrome Headless Shell v131.0.6778.85 — 37% (39.7 MB / 107.4 MB)◑  Downloading Chrome Headless Shell v131.0.6778.85 — 38% (40.8 MB / 107.4 MB)◒  Downloading Chrome Headless Shell v131.0.6778.85 — 39% (41.9 MB / 107.4 MB)◐  Downloading Chrome Headless Shell v131.0.6778.85 — 40% (43.0 MB / 107.4 MB)◓  Downloading Chrome Headless Shell v131.0.6778.85 — 41% (44.0 MB / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 41% (44.0 MB / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 42% (45.1 MB / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 43% (46.2 MB / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 44% (47.2 MB / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 45% (48.3 MB / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 45% (48.3 MB / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 46% (49.4 MB / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 47% (50.5 MB / 107.4 MB)..◑  Downloading Chrome Headless Shell v131.0.6778.85 — 48% (51.5 MB / 107.4 MB)..◒  Downloading Chrome Headless Shell v131.0.6778.85 — 49% (52.6 MB / 107.4 MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 49% (52.6 MB / 107.4 MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 50% (53.7 MB / 107.4 MB)..◑  Downloading Chrome Headless Shell v131.0.6778.85 — 51% (54.8 MB / 107.4 MB)..◒  Downloading Chrome Headless Shell v131.0.6778.85 — 52% (55.8 MB / 107.4 MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 53% (56.9 MB / 107.4 MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 54% (58.0 MB / 107.4
MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 54% (58.0 MB / 107.4
MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 55% (59.1 MB / 107.4
MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 55% (59.1 MB / 107.4
MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 56% (60.1 MB / 107.4
MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 56% (60.1 MB / 107.4
MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 57% (61.2 MB / 107.4
MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 57% (61.2 MB / 107.4
MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 58% (62.3 MB / 107.4
MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 59% (63.4 MB / 107.4 MB)◒  Downloading Chrome Headless Shell v131.0.6778.85 — 60% (64.4 MB / 107.4 MB)◐  Downloading Chrome Headless Shell v131.0.6778.85 — 61% (65.5 MB / 107.4 MB)◓  Downloading Chrome Headless Shell v131.0.6778.85 — 61% (65.5 MB / 107.4 MB)◑  Downloading Chrome Headless Shell v131.0.6778.85 — 62% (66.6 MB / 107.4 MB)◒  Downloading Chrome Headless Shell v131.0.6778.85 — 63% (67.6 MB / 107.4 MB)◐  Downloading Chrome Headless Shell v131.0.6778.85 — 64% (68.7 MB / 107.4 MB)◓  Downloading Chrome Headless Shell v131.0.6778.85 — 65% (69.8 MB / 107.4 MB)◑  Downloading Chrome Headless Shell v131.0.6778.85 — 66% (70.9 MB / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 66% (70.9 MB / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 67% (71.9 MB / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 68% (73.0 MB / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 69% (74.1 MB / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 70% (75.2 MB / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 70% (75.2 MB / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 71% (76.2 MB / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 72% (77.3 MB / 107.4 MB)..◒  Downloading Chrome Headless Shell v131.0.6778.85 — 73% (78.4 MB / 107.4 MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 74% (79.5 MB / 107.4 MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 74% (79.5 MB / 107.4 MB)..◑  Downloading Chrome Headless Shell v131.0.6778.85 — 75% (80.5 MB / 107.4 MB)..◒  Downloading Chrome Headless Shell v131.0.6778.85 — 76% (81.6 MB / 107.4 MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 77% (82.7 MB / 107.4 MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 78% (83.7 MB / 107.4 MB)..◑  Downloading Chrome Headless Shell v131.0.6778.85 — 78% (83.7 MB / 107.4
MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 79% (84.8 MB / 107.4
MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 80% (85.9 MB / 107.4
MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 81% (87.0 MB / 107.4
MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 81% (87.0 MB / 107.4
MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 82% (88.0 MB / 107.4
MB)...◐  Downloading Chrome Headless Shell v131.0.6778.85 — 83% (89.1 MB / 107.4
MB)...◓  Downloading Chrome Headless Shell v131.0.6778.85 — 84% (90.2 MB / 107.4
MB)...◑  Downloading Chrome Headless Shell v131.0.6778.85 — 85% (91.3 MB / 107.4
MB)...◒  Downloading Chrome Headless Shell v131.0.6778.85 — 85% (91.3 MB / 107.4 MB)◐  Downloading Chrome Headless Shell v131.0.6778.85 — 86% (92.3 MB / 107.4 MB)◓  Downloading Chrome Headless Shell v131.0.6778.85 — 87% (93.4 MB / 107.4 MB)◑  Downloading Chrome Headless Shell v131.0.6778.85 — 88% (94.5 MB / 107.4 MB)◒  Downloading Chrome Headless Shell v131.0.6778.85 — 89% (95.6 MB / 107.4 MB)◐  Downloading Chrome Headless Shell v131.0.6778.85 — 89% (95.6 MB / 107.4 MB)◓  Downloading Chrome Headless Shell v131.0.6778.85 — 90% (96.6 MB / 107.4 MB)◑  Downloading Chrome Headless Shell v131.0.6778.85 — 91% (97.7 MB / 107.4 MB)◒  Downloading Chrome Headless Shell v131.0.6778.85 — 92% (98.8 MB / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 93% (99.9 MB / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 93% (99.9 MB / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 94% (100.9 MB / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 95% (102.0 MB / 107.4 MB).◐  Downloading Chrome Headless Shell v131.0.6778.85 — 96% (103.1 MB / 107.4 MB).◓  Downloading Chrome Headless Shell v131.0.6778.85 — 97% (104.2 MB / 107.4 MB).◑  Downloading Chrome Headless Shell v131.0.6778.85 — 97% (104.2 MB / 107.4 MB).◒  Downloading Chrome Headless Shell v131.0.6778.85 — 98% (105.2 MB / 107.4
MB)..◐  Downloading Chrome Headless Shell v131.0.6778.85 — 99% (106.3 MB / 107.4
MB)..◓  Downloading Chrome Headless Shell v131.0.6778.85 — 100% (107.4 MB / 107.4
MB)..Error: All providers failed for chrome-headless-shell 131.0.6778.85:
  - DefaultProvider: ENOENT: no such file or directory, open '/home/longshao/.cache/hyperframes/chrome/chrome-headless-shell/131.0.6778.85-chrome-headless-shell-linux64.zip'
    at installWithProviders (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/@puppeteer/browsers/lib/esm/install.js:108:11)
    at async install (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/node_modules/@puppeteer/browsers/lib/esm/install.js:118:12)
    at async ensureBrowser (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:26299:21)
    at async runEnsure (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:43184:18)
    at async runCommand (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:303:49)
    at async runCommand (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:300:25)
    at async runMain (file:///home/longshao/.hermes/node/lib/node_modules/hyperframes/dist/cli.js:399:12)

■  Canceled


Explanation: The download completed but it's failing with ENOENT when trying to extract. The zip file might be in a different location or there's a path issue. Let me check the cache directory.

ls -la /home/longshao/.cache/hyperframes/chrome/ 2>/dev/null; find /home/longshao/.cache/hyperframes/ -type f 2>/dev/null | head -20


Output:
total 12
drwxrwxr-x 3 longshao longshao 4096 May  9 05:09 .
drwxrwxr-x 3 longshao longshao 4096 May  9 05:09 ..
drwxrwxr-x 3 longshao longshao 4096 May  9 05:09 chrome-headless-shell


Explanation: The cache directory exists but there's no zip file. The download might have been interrupted or the file was cleaned up. Let me try again with more debug info.

find /home/longshao/.cache/hyperframes/ -type f -o -type d 2>/dev/null


Explanation: The download directory exists but the zip file is missing. Let me try downloading the chrome headless shell manually.

# Download chrome headless shell manually
mkdir -p /home/longshao/.cache/hyperframes/chrome/chrome-headless-shell
cd /home/longshao/.cache/hyperframes/chrome/chrome-headless-shell

# Try downloading directly
curl -L -o chrome-headless-shell-linux64.zip "https://storage.googleapis.com/chrome-for-testing-public/131.0.6778.85/linux64/chrome-headless-shell-linux64.zip" 2>&1


Output:
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed

  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
  0  107M    0  105k    0     0  87388      0  0:21:28  0:00:01  0:21:27 87356
  3  107M    3 3840k    0     0  1586k      0  0:01:09  0:00:02  0:01:07 1586k
  9  107M    9 10.1M    0     0  3220k      0  0:00:34  0:00:03  0:00:31 3219k
 17  107M   17 18.7M    0     0  4463k      0  0:00:24  0:00:04  0:00:20 4462k
 26  107M   26 27.9M    0     0  5481k      0  0:00:20  0:00:05  0:00:15 5891k
 36  107M   36 38.7M    0     0  6363k      0  0:00:17  0:00:06  0:00:11 7911k
 44  107M   44 47.7M    0     0  6758k      0  0:00:16  0:00:07  0:00:09 9363k
 54  107M   54 58.4M    0     0  7271k      0  0:00:15  0:00:08  0:00:07 9886k
 63  107M   63 67.8M    0     0  7528k      0  0:00:14  0:00:09  0:00:05  9.9M
 71  107M   71 76.9M    0     0  7706k      0  0:00:14  0:00:10  0:00:04  9.7M
 79  107M   79 85.0M    0     0  7669k      0  0:00:14  0:00:11  0:00:03 9257k
 86  107M   86 93.2M    0     0  7796k      0  0:00:14  0:00:12  0:00:02 9290k
 94  107M   94  101M    0     0  7855k      0  0:00:13  0:00:13 --:--:-- 8810k
100  107M  100  107M    0     0  7791k      0  0:00:14  0:00:14 --:--:-- 8289k


Explanation: Downloaded. Now let me extract it to the right place.

cd /home/longshao/.cache/hyperframes/chrome/chrome-headless-shell
ls -la chrome-headless-shell-linux64.zip
# Extract it
unzip -o chrome-headless-shell-linux64.zip 2>&1 | tail -5
ls -la


Output:
-rw-rw-r-- 1 longshao longshao 112577542 May  9 05:10 chrome-headless-shell-linux64.zip
/usr/bin/bash: line 10: unzip: command not found
total 109952
drwxrwxr-x 3 longshao longshao      4096 May  9 05:10 .
drwxrwxr-x 3 longshao longshao      4096 May  9 05:09 ..
-rw-rw-r-- 1 longshao longshao 112577542 May  9 05:10 chrome-headless-shell-linux64.zip
drwxrwxr-x 2 longshao longshao      4096 May  9 05:09 linux-131.0.6778.85


Explanation: No unzip. Let me use python or 7z or install unzip.

cd /home/longshao/.cache/hyperframes/chrome/chrome-headless-shell
python3 -c "import zipfile; zipfile.ZipFile('chrome-headless-shell-linux64.zip').extractall('.')"
ls -la
ls -la chrome-headless-shell-linux64/ 2>/dev/null || ls -la


Output:
total 109956
drwxrwxr-x 4 longshao longshao      4096 May  9 05:12 .
drwxrwxr-x 3 longshao longshao      4096 May  9 05:09 ..
drwxrwxr-x 4 longshao longshao      4096 May  9 05:12 chrome-headless-shell-linux64
-rw-rw-r-- 1 longshao longshao 112577542 May  9 05:10 chrome-headless-shell-linux64.zip
drwxrwxr-x 2 longshao longshao      4096 May  9 05:09 linux-131.0.6778.85
total 202180
drwxrwxr-x 4 longshao longshao      4096 May  9 05:12 .
drwxrwxr-x 4 longshao longshao      4096 May  9 05:12 ..
-rw-rw-r-- 1 longshao longshao       248 May  9 05:12 ABOUT
-rw-rw-r-- 1 longshao longshao 177298656 May  9 05:12 chrome-headless-shell
-rw-rw-r-- 1 longshao longshao       679 May  9 05:12 deb.deps
-rw-rw-r-- 1 longshao longshao      2923 May  9 05:12 headless_command_resources.pak
-rw-rw-r-- 1 longshao longshao   1514652 May  9 05:12 headless_lib_data.pak
-rw-rw-r-- 1 longshao longshao   3419597 May  9 05:12 headless_lib_strings.pak
drwxrwxr-x 2 longshao longshao      4096 May  9 05:12 hyphen-data
-rw-rw-r-- 1 longshao longshao  10464176 May  9 05:12 icudtl.dat
-rw-rw-r-- 1 longshao longshao    240368 May  9 05:12 libEGL.so
-rw-rw-r-- 1 longshao longshao   6937472 May  9 05:12 libGLESv2.so
-rw-rw-r-- 1 longshao longshao   4650312 May  9 05:12 libvk_swiftshader.so
-rw-rw-r-- 1 longshao longshao    565520 May  9 05:12 libvulkan.so.1
-rw-rw-r-- 1 longshao longshao   1199738 May  9 05:12 LICENSE.headless_shell
drwxrwxr-x 2 longshao longshao      4096 May  9 05:12 locales
-rw-rw-r-- 1 longshao longshao      2592 May  9 05:12 rpm.deps
-rw-rw-r-- 1 longshao longshao    690349 May  9 05:12 v8_context_snapshot.bin
-rw-rw-r-- 1 longshao longshao       107 May  9 05:12 vk_swiftshader_icd.json

Command required approval (script execution via -e/-c flag) and was approved by the user.


Explanation: Chrome headless shell is extracted. Now I need to make sure it's in the right location for hyperframes to find it. The error said it was looking for `131.0.6778.85-chrome-headless-shell-linux64.zip`. Let me check what puppeteer expects and move the files accordingly.

# Make the chrome-headless-shell executable
chmod +x /home/longshao/.cache/hyperframes/chrome/chrome-headless-shell/chrome-headless-shell-linux64/chrome-headless-shell

# Try render now
cd /home/longshao/my-video && hyperframes render 2>&1


Output:
◆  Rendering my-video → /home/longshao/my-video/renders/my-video_2026-05-09_05-12-19.mp4
   30fps · standard · auto workers (28 cores detected)
   GPU: browser GPU (auto-detect)

│
◇  Browser: cache

  ⚠ gsap_exit_missing_hard_kill: GSAP exit on "#title" ends at the 5.00s clip start boundary without a matching tl.set hard kill. Non-linear seeking can land after the fade and leave stale visibility state.
    Fix: Add `tl.set("#title", { opacity: 0 }, 5.00)` after the exit tween.
  Continuing render despite lint issues. Use --strict to block.

  █░░░░░░░░░░░░░░░░░░░░░░░░  5%  Compiling composition[Compiler] Inlined CDN script: https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js
[INFO] Compiled composition metadata {"entryFile":"index.html","staticDuration":10,"width":1920,"height":1080,"videoCount":1,"audioCount":0,"renderModeHints":{"recommendScreenshot":false,"reasons":[]}}

  ██░░░░░░░░░░░░░░░░░░░░░░░  10%  Extracting video frames[Compiler] WARNING: Video "3_29_1" has sparse keyframes (max interval: 5s). This causes seek failures and frame freezing. Re-encode with: ffmpeg -i "3月29日 (1).mp4" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4
[INFO] [Render] No HDR sources detected — rendering SDR

  █████░░░░░░░░░░░░░░░░░░░░  20%  Processing audio tracks
  ██████░░░░░░░░░░░░░░░░░░░  25%  Starting frame capture[hyperframes] browserGpuMode auto → software (probe failed (Browser was not found at the configured executablePath (/home/longshao/.cache/hyperframes/chrome/chrome-headless-shell/linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell)))
[WARN] [Render] Auto-worker calibration failed; using conservative worker budget. {"protocolTimeout":30000,"error":"Browser was not found at the configured executablePath (/home/longshao/.cache/hyperframes/chrome/chrome-headless-shell/linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell)"}
[WARN] [Render] Reduced auto worker count for high-cost capture workload to avoid Chrome compositor starvation. {"from":6,"to":1,"costMultiplier":8,"reasons":["calibration-failed"]}
[INFO] streaming-encode gate {"enabled":true,"configFlag":true,"outputFormat":"mp4","workerCount":1,"durationSeconds":10,"maxDurationSeconds":240}

  ██████░░░░░░░░░░░░░░░░░░░  25%  Failed: Browser was not found at the configured executablePath (/home/longshao/.cache/hyperframes/chrome/chrome-headless-shell/linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell)
✗  Render failed

   Browser was not found at the configured executablePath (/home/longshao/.cache/hyperframes/chrome/chrome-headless-shell/linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell)
   Try --docker for containerized rendering


Explanation: The issue is that hyperframes expects the chrome-headless-shell to be at `linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell` but I put it in `chrome-headless-shell-linux64/chrome-headless-shell`. Let me move it to the right place.

# Move chrome to the expected path
cd /home/longshao/.cache/hyperframes/chrome/chrome-headless-shell
mkdir -p linux-131.0.6778.85/chrome-headless-shell-linux64
cp -r chrome-headless-shell-linux64/* linux-131.0.6778.85/chrome-headless-shell-linux64/
chmod +x linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell

# Verify
ls -la linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell


Output: -rwxrwxr-x 1 longshao longshao 177298656 May  9 05:12 linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell


Explanation: Now let me try render again.

cd /home/longshao/my-video && hyperframes render 2>&1


Output:
◆  Rendering my-video → /home/longshao/my-video/renders/my-video_2026-05-09_05-12-28.mp4
   30fps · standard · auto workers (28 cores detected)
   GPU: browser GPU (auto-detect)

│
◇  Browser: cache

  ⚠ gsap_exit_missing_hard_kill: GSAP exit on "#title" ends at the 5.00s clip start boundary without a matching tl.set hard kill. Non-linear seeking can land after the fade and leave stale visibility state.
    Fix: Add `tl.set("#title", { opacity: 0 }, 5.00)` after the exit tween.
  Continuing render despite lint issues. Use --strict to block.

  █░░░░░░░░░░░░░░░░░░░░░░░░  5%  Compiling composition[Compiler] Inlined CDN script: https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js
[INFO] Compiled composition metadata {"entryFile":"index.html","staticDuration":10,"width":1920,"height":1080,"videoCount":1,"audioCount":0,"renderModeHints":{"recommendScreenshot":false,"reasons":[]}}

  ██░░░░░░░░░░░░░░░░░░░░░░░  10%  Extracting video frames[Compiler] WARNING: Video "3_29_1" has sparse keyframes (max interval: 5s). This causes seek failures and frame freezing. Re-encode with: ffmpeg -i "3月29日 (1).mp4" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4
[INFO] [Render] No HDR sources detected — rendering SDR

  █████░░░░░░░░░░░░░░░░░░░░  20%  Processing audio tracks
  ██████░░░░░░░░░░░░░░░░░░░  25%  Starting frame capture[hyperframes] browserGpuMode auto → hardware (WebGL probe succeeded)
[Browser:WARN] The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu
[WARN] [Render] BeginFrame auto-worker calibration timed out; retrying calibration in screenshot capture mode. {"protocolTimeout":30000,"error":"Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed."}
[Browser:WARN] The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu
[INFO] streaming-encode gate {"enabled":false,"configFlag":true,"outputFormat":"mp4","workerCount":6,"durationSeconds":10,"maxDurationSeconds":240}
[Browser:WARN] The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu
[Browser:WARN] The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu
[Browser:WARN] The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu
[Browser:WARN] The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu
[Browser:WARN] The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu
[Browser:WARN] The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu

  ███████░░░░░░░░░░░░░░░░░░  30%  Capturing frame 30/300 (6 workers)
  ████████░░░░░░░░░░░░░░░░░  34%  Capturing frame 60/300 (6 workers)
  █████████░░░░░░░░░░░░░░░░  39%  Capturing frame 90/300 (6 workers)
  ██████████░░░░░░░░░░░░░░░  43%  Capturing frame 120/300 (6 workers)
  ████████████░░░░░░░░░░░░░  48%  Capturing frame 150/300 (6 workers)
  █████████████░░░░░░░░░░░░  52%  Capturing frame 180/300 (6 workers)
  ██████████████░░░░░░░░░░░  57%  Capturing frame 210/300 (6 workers)
  ███████████████░░░░░░░░░░  61%  Capturing frame 240/300 (6 workers)
  ████████████████░░░░░░░░░  66%  Capturing frame 270/300 (6 workers)
  █████████████████░░░░░░░░  70%  Capturing frame 300/300 (6 workers)
  ██████████████████░░░░░░░  75%  Encoding video
  ██████████████████████░░░  90%  Assembling final video
  █████████████████████████  100%  Render complete
◇  /home/longshao/my-video/renders/my-video_2026-05-09_05-12-28.mp4
   4.0 MB · 1m 24.3s · completed


Explanation: Both preview and render are working. Let me also check that the preview is still running.


Explanation: Both are running. Let me update the todo and give the user a summary.

todo

初始化 hyperframes 项目

安装项目依赖并修复 onnxruntime

添加示例内容并启动 preview

测试 render 渲染 MP4


初始化 hyperframes 项目

安装项目依赖并修复 onnxruntime

添加示例内容并启动 preview

测试 render 渲染 MP4


全部搞定！✅

### 当前状态

**✅ Preview** — 后台运行中
- 地址：`http://localhost:3002`
- 局域网访问：`http://服务器IP:3002`

**✅ Render** — 已测试成功
- 渲染出的视频：`/home/longshao/my-video/renders/my-video_2026-05-09_05-12-28.mp4`（4.0 MB，10秒）

### 使用方式

```bash
# 预览（已后台运行）
http://服务器IP:3002

# 渲染新视频（SSH到服务器执行）
cd /home/longshao/my-video
hyperframes render

# 编辑 index.html 后重新渲染即可
```

我把渲染好的示例视频发给你看看效果：

Explanation: Let me also check the rendered file.


Output:
total 4128
drwxrwxr-x 2 longshao longshao    4096 May  9 05:13 .
drwxrwxr-x 3 longshao longshao    4096 May  9 05:10 ..
-rw-rw-r-- 1 longshao longshao 4217690 May  9 05:13 my-video_2026-05-09_05-12-28.mp4


MEDIA:/home/longshao/my-video/renders/my-video_2026-05-09_05-12-28.mp4

这是用 HTML 写的示例视频：前5秒紫色渐变 "Hello HyperFrames 🎬"，后5秒粉色渐变 "Rendered on Server ✨"，带缩放和淡入淡出动画。

编辑 `/home/longshao/my-video/index.html` 就能做自己的视频，改完跑 `hyperframes render` 即可出片。

Explanation: Let me send the video to the user.


这两个preview和render分别是怎么使用的,我想直接通过一段文字生成视频是如何操作的


### Preview 和 Render 的用法

**Preview（预览）**— 编辑 HTML 时实时看效果，不生成文件
```bash
cd /home/longshao/my-video
hyperframes preview
# 浏览器打开 http://服务器IP:3002 实时预览
# 改 index.html 保存后自动刷新
```

**Render（渲染）**— 把 HTML 渲染成 MP4 文件
```bash
cd /home/longshao/my-video
hyperframes render
# 生成到 renders/ 目录下
```

---

### 文字生成视频的方式

HyperFrames 本身是 HTML→视频的渲染工具，**不直接支持文字→视频**。流程是：

**你描述 → AI 写 HTML → HyperFrames 渲染 MP4**

你只需要告诉我想要什么样的视频，比如：

> "帮我做一个15秒的产品介绍视频，标题是'智能安防系统'，有渐入动画，深色背景"

我来帮你：
1. 写 HTML 合成（动画、布局、时间轴）
2. 跑 `hyperframes render` 出 MP4

**要现在试试吗？告诉我你想要什么样的视频内容，我来生成。**

Explanation:
The user wants to understand how to use preview and render, and specifically how to generate a video from text description. Based on the README, the recommended way is to use an AI agent with the HyperFrames skills - you describe what you want and the agent writes the HTML.

Let me explain the workflow clearly.


那hyperframes负责生成html吗


**不是。** HyperFrames 只负责**把 HTML 渲染成视频**，不负责生成 HTML。

整个流程分成三步，由不同角色完成：

| 步骤 | 谁来做 | 干什么 |
|---|---|---|
| ① 写 HTML | **你**或**AI** | 写视频的布局、动画、时间轴 |
| ② 预览 | **HyperFrames** | 浏览器里看效果 |
| ③ 渲染 | **HyperFrames** | HTML → MP4 |

它的定位就像一个**视频渲染引擎**，你给它 HTML，它还你 MP4。

至于 HTML 从哪来：
- **手写** — 你自己写 HTML + CSS + GSAP 动画
- **AI 生成** — 你描述需求，AI（比如我）帮你写 HTML
- **Claude Code / Cursor** — 官方推荐的方式，装 skills 后 AI agent 自动写

所以你想要"文字生成视频"，实际是**你告诉我内容 → 我写 HTML → 跑 HyperFrames 出片**。要试试吗？

Explanation: The user is asking whether hyperframes is responsible for generating the HTML. The answer is no - hyperframes only renders HTML to video. The HTML authoring is done by the user or an AI agent. Let me clarify this.


那你看下这种的html你能不能写:
【画面】 0–10 秒,城市夜景航拍,灯火璀璨,字幕渐入:“夜·云浮”。
【画面】 10–20 秒,镜头下沉,市民家中——孩子安睡、老人看电视——突然由远及近摩托引擎轰鸣声爆响,玻璃震动,孩子惊醒哭闹。
【画面】 20–35 秒,快速剪辑:夜市市民侧目、外卖小哥被逼让道、监控里十余辆改装摩托并排压线、车头翘起做“翘头”动作。
【画面】 35–40 秒,黑场,白字推出标题。


**能写，但要跟你说清楚限制。**

### HyperFrames 能做的 ✅

- 字幕、标题动画（渐入、缩放、位移）
- 黑场白字推出
- 画面切换转场
- **图片/视频素材的合成和排版**
- 背景音乐、音效混合

### HyperFrames 做不到的 ❌

- **生成真实的视频画面**（航拍、人物、摩托等）
- 它不是 Sora、Runway 那种 AI 视频生成工具

### 实际做法

你需要**自己提供素材**，HyperFrames 负责"组装"：

| 需求 | 素材来源 |
|---|---|
| 城市夜景航拍 | 自己拍 / 买素材 / AI 生成视频片段 |
| 孩子安睡、老人看电视 | 同上 |
| 改装摩托画面 | 监控录像 / 实拍 |
| 字幕、标题、黑场 | HyperFrames 直接做 ✅ |
| 转场、动画效果 | HyperFrames 直接做 ✅ |

**简单说：HyperFrames 是视频剪辑+包装工具，不是视频生成工具。**

---

如果你有素材文件（视频、图片），我可以帮你把这个脚本写成 HTML 合成，加上字幕动画、转场、黑场标题，渲染成完整的 MP4。你有现成的素材吗？

Explanation:
The user is asking if I can write HTML for this kind of video script. This is a fairly complex video with multiple scenes, but I need to be honest about what HyperFrames can and can't do.

Key issue: HyperFrames renders HTML/CSS/GSAP animations to video. It CANNOT generate real footage like "城市夜景航拍", "孩子安睡", "改装摩托" etc. It's not an AI video generator like Sora or Runway.

What I CAN do with HyperFrames:
- Text animations, titles, subtitles
- CSS/GSAP animations (fade, slide, scale, etc.)
- Show images/videos if the user provides them
- Data visualizations, charts
- Motion graphics, overlays

- If they supply actual video clips and images, I can composite them together with text overlays and animations. But I can't generate the actual footage they're describing.

Let me give them an honest answer about what's possible and what isn't.


我现在没有素材,你看我上面那段话大概需要那些素材,


按你脚本的4个段落，需要这些素材：

### 场景1（0-10秒）城市夜景
- 🎬 **城市夜景航拍视频** 1段（10秒，俯瞰灯火璀璨）
- 📝 字幕："夜·云浮"（HyperFrames 自带做）

### 场景2（10-20秒）家中+摩托声
- 🎬 **孩子睡觉画面** 1段（3-4秒）
- 🎬 **老人看电视画面** 1段（2-3秒）
- 🎬 **玻璃震动/惊醒画面** 1段（3-4秒）
- 🔊 **摩托引擎轰鸣音效** 1个（由远及近）
- 🔊 **孩子哭闹音效** 1个

### 场景3（20-35秒）快速剪辑
- 🎬 **夜市市民侧目** 1段（3-4秒）
- 🎬 **外卖小哥被逼让道** 1段（3-4秒）
- 🎬 **监控：改装摩托并排压线** 1段（4-5秒）
- 🎬 **摩托翘头动作** 1段（3-4秒）

### 场景4（35-40秒）黑场标题
- 📝 黑底白字标题（HyperFrames 自带做）
- 🔊 背景音乐（贯穿全片，可选）

---

### 汇总

| 类型 | 数量 | 获取方式 |
|---|---|---|
| 视频片段 | **8段** | 自己拍 / 监控录像 / 素材网站购买 |
| 音效 | **2-3个** | 免费音效网站 |
| 背景音乐 | **1首** | 免版权音乐网站 |
| 字幕/标题 | HyperFrames 直接做 | 不需要额外素材 |

其中**监控画面**（改装摩托并排压线、翘头）这种比较特殊，基本只能靠真实监控录像或实拍，素材网站很少有。

素材准备好后我可以一次性帮你组装成完整视频。

Explanation: The user wants me to list out what materials/assets they need based on the script they provided. Let me break it down scene by scene.