{"id":6862,"plugin_id":"Plugin_d72b815ecf6481919e3beede9c71ef08","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T22:49:17.800Z","digest":"763384890e70dc56e80e839ade324d5ea6a2320536c9580249b69d321a7801ce","against":null,"payload":{"name":"hyperframes-cli","description":"HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":214}],"skill_md_contents":"---\nname: hyperframes-cli\ndescription: HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.\n---\n\n# HyperFrames CLI\n\nEverything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.\n\n## Workflow\n\n1. **Scaffold** — `npx hyperframes init my-video`\n2. **Write** — author HTML composition (see the `hyperframes` skill)\n3. **Lint** — `npx hyperframes lint`\n4. **Visual inspect** — `npx hyperframes inspect`\n5. **Preview** — `npx hyperframes preview`\n6. **Render** — `npx hyperframes render`\n\nLint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.\n\n## Scaffolding\n\n```bash\nnpx hyperframes init my-video                        # interactive wizard\nnpx hyperframes init my-video --example warm-grain   # pick an example\nnpx hyperframes init my-video --video clip.mp4        # with video file\nnpx hyperframes init my-video --audio track.mp3       # with audio file\nnpx hyperframes init my-video --non-interactive       # skip prompts (CI/agents)\n```\n\nTemplates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.\n\n`init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.\n\n## Linting\n\n```bash\nnpx hyperframes lint                  # current directory\nnpx hyperframes lint ./my-project     # specific project\nnpx hyperframes lint --verbose        # info-level findings\nnpx hyperframes lint --json           # machine-readable\n```\n\nLints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).\n\n## Visual Inspect\n\n```bash\nnpx hyperframes inspect                 # inspect rendered layout over the timeline\nnpx hyperframes inspect ./my-project    # specific project\nnpx hyperframes inspect --json          # agent-readable findings\nnpx hyperframes inspect --samples 15    # denser timeline sweep\nnpx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps\n```\n\nUse this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:\n\n- Text extending outside the nearest visual container or bubble\n- Text clipped by its own fixed-width/fixed-height box\n- Text extending outside the composition canvas\n- Children escaping clipping containers\n\nErrors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.\n\n`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.\n\n## Previewing\n\n```bash\nnpx hyperframes preview                   # serve current directory\nnpx hyperframes preview --port 4567       # custom port (default 3002)\n```\n\nHot-reloads on file changes. Opens the studio in your browser automatically.\n\nWhen handing a project back to the user, use the Studio project URL, not the\nsource `index.html` path:\n\n```text\nhttp://localhost:<port>/#project/<project-name>\n```\n\nUse the actual port from the preview output and the project directory name. For\nexample, after `npx hyperframes preview --port 3017` in `codex-openai-video`,\nreport `http://localhost:3017/#project/codex-openai-video`.\n\nTreat `index.html` as source-code context only. It is fine to link it as an\nimplementation file, but do not label it as the project or preview surface.\n\n## Rendering\n\n```bash\nnpx hyperframes render                                # standard MP4\nnpx hyperframes render --output final.mp4             # named output\nnpx hyperframes render --quality draft                # fast iteration\nnpx hyperframes render --fps 60 --quality high        # final delivery\nnpx hyperframes render --format webm                  # transparent WebM\nnpx hyperframes render --docker                       # byte-identical\n```\n\n| Flag           | Options               | Default                    | Notes                       |\n| -------------- | --------------------- | -------------------------- | --------------------------- |\n| `--output`     | path                  | renders/name_timestamp.mp4 | Output path                 |\n| `--fps`        | 24, 30, 60            | 30                         | 60fps doubles render time   |\n| `--quality`    | draft, standard, high | standard                   | draft for iterating         |\n| `--format`     | mp4, webm             | mp4                        | WebM supports transparency  |\n| `--workers`    | 1-8 or auto           | auto                       | Each spawns Chrome          |\n| `--docker`     | flag                  | off                        | Reproducible output         |\n| `--gpu`        | flag                  | off                        | GPU-accelerated encoding    |\n| `--strict`     | flag                  | off                        | Fail on lint errors         |\n| `--strict-all` | flag                  | off                        | Fail on errors AND warnings |\n\n**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.\n\n## Transcription\n\n```bash\nnpx hyperframes transcribe audio.mp3\nnpx hyperframes transcribe video.mp4 --model medium.en --language en\nnpx hyperframes transcribe subtitles.srt   # import existing\nnpx hyperframes transcribe subtitles.vtt\nnpx hyperframes transcribe openai-response.json\n```\n\n## Text-to-Speech\n\n```bash\nnpx hyperframes tts \"Text here\" --voice af_nova --output narration.wav\nnpx hyperframes tts script.txt --voice bf_emma\nnpx hyperframes tts --list  # show all voices\n```\n\n## Troubleshooting\n\n```bash\nnpx hyperframes doctor       # check environment (Chrome, FFmpeg, Node, memory)\nnpx hyperframes browser      # manage bundled Chrome\nnpx hyperframes info         # version and environment details\nnpx hyperframes upgrade      # check for updates\n```\n\nRun `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.\n\n## Other\n\n```bash\nnpx hyperframes compositions   # list compositions in project\nnpx hyperframes docs           # open documentation\nnpx hyperframes benchmark .    # benchmark render performance\n```\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}