AGENT SKILL

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

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.

  1. 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.
  2. Never edit edit.json by hand. The generator (gen-timeline.mjs) is the sole assembler. Correct the generator and rerun it so the change survives regeneration.
  3. Start only with declared audio. If declarations.json lacks BPM or beat_offset_s, use analyze-music so a person can verify the values by ear. Do not present automatic estimates as measured values.
  4. 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.
  5. Verify the render artifact. Never report completion from a log PASS alone; inspect the actual file in exports/ with ffprobe.
  6. 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

  1. Read the declaration. Inspect BPM, beat_offset_s, hit_points, and sections in declarations.json. If any required value is missing, run analyze-music and wait for the person's declaration.
  2. Build a beat map. Calculate the beat grid and per-beat intensity for audio-reactive motion. See generator.md §1.
  3. Assign the structure. Use the declared intro/build/drop/bridge/outro labels in sections as the structure, with the strongest passage at the drop. See generator.md §2.
  4. Write the generator. Generate overlay HTML and edit.json from the declarations. See generator.md §3–§5.
  5. Lint. Run node packages/edit-lint/bin/edit-lint.mjs <project> until it passes.
  6. Verify a short segment. Render only the suspect fragment in a project lasting a few seconds, then inspect it visually. See verify-loop.md.
  7. Render the full piece. Wait for available machine capacity and use the extended timeout. See verify-loop.md §3.
  8. Inspect the export. Check frames around each highlight, probe with ffprobe, and measure loudness. See verify-loop.md §4.
  9. 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

AkariLabs
AkariLabs/akari-video

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)

★ 214
AkariLabs
AkariLabs/akari-video

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)

★ 214
AkariLabs
AkariLabs/akari-video

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.

★ 214
AkariLabs
AkariLabs/akari-video

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)

★ 214
AkariLabs
AkariLabs/akari-video

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)

★ 214
AkariLabs
AkariLabs/akari-video

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)

★ 214