skills/hyperframes-cli/references/beats.md

> Modified by Juicy Lucy AI, UAB for JuicyLucy Ads: CLI invocations (pointed at the installed launchers, never npm latest), the review-approval reference, the pointer to HyperFrames' own plugin rules, third-party install instructions, references to omitted provider integrations and usage telemetry, unpinned install and HeyGen video instructions, the environment a script passes to its local preview server and the pattern it reads Chrome's local address with, one line break and/or frontmatter (description layout, upstream-only metadata) adjusted at build time. See the plugin root NOTICE for details.

# Generate a project beat grid

Use `~/.juicylucy/bin/hyperframes beats` when an existing HyperFrames project needs the Studio-compatible beat file for its music track. This is a CLI utility, not a complete video workflow.

```bash
~/.juicylucy/bin/hyperframes beats
~/.juicylucy/bin/hyperframes beats ./my-video
~/.juicylucy/bin/hyperframes beats ./my-video --json
```

The project must contain a local music `<audio>` source. Mark it with `data-timeline-role="music"`; an id containing `music`, `bgm`, or `soundtrack` is also recognized. The command decodes that file with ffmpeg, tracks its beats, and writes `beats/<audio-relative-path>.json`.

If the track has no steady beat, the command fails and writes nothing. If ffmpeg is missing, run `~/.juicylucy/bin/hyperframes doctor`.

For a complete beat-synced video, route through `/music-to-video`. That workflow owns a different audio-driven pipeline and its `audiomap.json`; do not replace its analyzer with this Studio utility.