edit-to-beat
Edit a video timeline and overlays to the beat of a track whose BPM, downbeat, accents, and sections have been declared. Use for music-driven promos, highlights, showcases, beat-aligned cuts, or audio-reactive motion. Use analyze-music to mark a track first, and plan-edit to plan from scratch without media.(旧名: beat-sync-edit)
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 214
- Forks
- 25
01 前言 Front Matter
- name
- edit-to-beat
- description
- Edit a video timeline and overlays to the beat of a track whose BPM, downbeat, accents, and sections have been declared. Use for music-driven promos, highlights, showcases, beat-aligned cuts, or audio-reactive motion. Use analyze-music to mark a track first, and plan-edit to plan from scratch without media.(旧名: beat-sync-edit)
02 资源文件 4
- 参考文档generator.md4.5 KB
- 参考文档pitfalls.md4.1 KB
- 脚本templates/gen-timeline.mjs7.6 KB
- 参考文档verify-loop.md3.8 KB
03 SKILL.md 正文
FORBIDDEN-level hard rules
Language: Respond in the user's language — conversation, questions, approval prompts, and the reports and records you write (including decision-log rows) follow the language the user writes in.
Never proceed in a way that violates any of the following. These rules always take precedence over the detailed leaves.
Do not read all of edit.json or captions.json; grep by id and read only the matching lines, as described in How to read edit.json. Write through the Edit operation or edit-store script API; this skill uses the generator for that work.
- Never enter times by hand. Calculate every cut, overlay, and SFX time from the beat positions derived from the declaration's BPM, downbeat, accent hits, or sections. A hand-entered time such as "about 12 seconds" immediately falls out of sync with the music.
- Never edit
edit.jsonby hand. The generator (gen-timeline.mjs) is the sole assembler. Correct the generator and rerun it so the change survives regeneration. - Start only with declared audio. If
declarations.jsonlacks BPM orbeat_offset_s, use analyze-music so a person can verify the values by ear. Do not present automatic estimates as measured values. - Never use a full render as the verification step. Check visuals with a mini-project lasting only a few seconds (verify-loop.md). The difference between a 40-second iteration and a 40-minute iteration is a difference in quality.
- Verify the render artifact. Never report completion from a log
PASSalone; inspect the actual file inexports/withffprobe. - Never judge motion from a single still. Capture at least three consecutive points—start, middle, and end—to verify the movement. Especially for 3D, never guess what the default pose means.
Suitable use cases
| Suitable | Less suitable |
|---|---|
| Music determines the duration and drives a promo, showcase, or highlight reel | Speech drives the piece; use plan-edit |
| Dozens or hundreds of coordinated visual changes | A few cuts can be positioned manually |
| The same composition may be regenerated for another track | A one-off edit will not be regenerated |
Execution order
- Read the declaration. Inspect BPM,
beat_offset_s,hit_points, andsectionsindeclarations.json. If any required value is missing, run analyze-music and wait for the person's declaration. - Build a beat map. Calculate the beat grid and per-beat intensity for audio-reactive motion. See generator.md §1.
- Assign the structure. Use the declared intro/build/drop/bridge/outro labels in
sectionsas the structure, with the strongest passage at the drop. See generator.md §2. - Write the generator. Generate overlay HTML and
edit.jsonfrom the declarations. See generator.md §3–§5. - Lint. Run
node packages/edit-lint/bin/edit-lint.mjs <project>until it passes. - Verify a short segment. Render only the suspect fragment in a project lasting a few seconds, then inspect it visually. See verify-loop.md.
- Render the full piece. Wait for available machine capacity and use the extended timeout. See verify-loop.md §3.
- Inspect the export. Check frames around each highlight, probe with
ffprobe, and measure loudness. See verify-loop.md §4. - Apply review changes. Fix the generator, regenerate, and repeat the focused checks. See verify-loop.md §5.
Why use a generator?
- Timing stays aligned: Every event is derived from the same beat grid. A hand-entered time makes that event drift; with a generator, drift cannot occur structurally.
- Changes stay local: Adjust a constant for text size or replace a sound reference in one place, then regenerate.
- Tracks can be replaced: New declarations rebuild the same design around a new beat grid.
- The design is recorded: The generator shows how the piece was assembled.
Further instructions
- generator.md: beat map, section assignment, overlays, and audio-reactive motion.
- verify-loop.md: short verification, render operation, acceptance, and review changes.
- pitfalls.md: observed implementation and render pitfalls.
Tools
| Tool | Purpose |
|---|---|
templates/gen-timeline.mjs |
Generator template to copy and adapt |
akari internal beat-sync-beatmap |
Convert declarations and audio into a beat grid, per-beat volume, and waveform envelope |
akari internal beat-sync-probe-frame |
Capture one frame from the render path at a chosen time |
akari internal beat-sync-render-when-idle |
Wait for the machine to become available before rendering |
Related skills: author-overlay for fragment authoring, analyze-music for declarations, and render-cut for export.
04 同仓库更多 Skills
verify-project
Verify an AKARI Video project with the L0 / L1 / L2 verification ladder required by an AKARI Video task contract on the current Theia stack. Read when acceptance criteria specify levels such as L0 or L0+L1, to determine exactly what to run and how at each level.(旧名: verify)
verify-edit
Verify edit.json and optional analysis.json / captions.json / media with a deterministic CLI, then finish QA with frame inspection and reporting after PASS. Use immediately after writing or modifying edit.json, before export, and after applying review feedback.(旧名: edit-lint)
setup-remote
Set up remote access to approval reports and previews from another device such as a phone, and send footage to the workspace. Use doctor to assess Tailscale, guide installation and login (human actions), expose the preview server (default 4567) and approval report helper over tailnet-only HTTPS with tailscale serve, connect Taildrop reception to workspace inbox/, and verify access from another device. Use for requests to view reports on a phone, approve remotely, send footage from a phone, or set up remote access. Public internet exposure (funnel) is outside the default scope.
setup-project
Set up an AKARI Video project headlessly. Recursively copy `templates/project-default/`, record the template version, initialize git only when safe, and generate an HTML creation report. No app launch is needed. Use to create a video project or fill in an existing folder as an AKARI Video project.(旧名: create-project)
setup-library
Use for first-time AKARI Video setup or when the current project needs more usable assets. This first-run skill checks ffmpeg / whisper-cli (and can install with approval), reads the bundled catalog with akari assets to propose a starter pack, obtains explicit human approval, then acquires, places, validates, and updates INDEX entries. It also covers the audio library (BGM and sound effects): bulk acquisition of first-party AKARI Sounds from GitHub Releases, a free-source candidate HTML list with drop-folder matching or assisted acquisition for missing families, and keep/drop decisions in the listening gallery. Use for requests such as "I want more BGM" or "add sound effects to the library".(旧名: setup-audio-library)
setup-connections
Set up and inspect AKARI Video connections: AI-service keys, which models are allowed, cost-approval policy, the tool and media-service state, and 3D settings. Use for first-time setup, adding a provider or key later, checking what is usable (「何が使える?」 'what can I use?'), setting a key such as fal (「fal の鍵を設定したい」), 3D settings (「3D の設定を使いたい」), connection checks, and gates before paid generation or external publication. Model selection belongs to the production skills (they read the ledger and preferences); this skill decides allowed models and the cost policy. Works with `.akari/connections.json` and a free, read-only doctor.(旧名: manage-connections)(旧名: connect)