trove-beat-sync
Fit and validate a music beat grid before storyboarding, map motion and cuts to beatF(n), control full-frame impacts, compensate measured audio offsets, and verify beat sync on delivered renders. Use when a video timeline needs music-driven timing or BGM and no-BGM versions.
- License 许可
- MIT
- 所属仓库
- bravew/trove
- 最近更新
- 2026-11-12
- Stars
- ★ 10
- Forks
- 1
01 前言 Front Matter
- name
- trove-beat-sync
- license
- MIT
- metadata
- { "source": "Vincentwei1021/video-shotcraft", "trove-category": "designs-media", "upstream-skill": "music-beat-sync and sound-design", "upstream-revision": "5ddbf521038b0a7accfb6dc1e0a9eb29c67277ab", "trove-category-label": "Designs & media" }
- description
- Fit and validate a music beat grid before storyboarding, map motion and cuts to beatF(n), control full-frame impacts, compensate measured audio offsets, and verify beat sync on delivered renders. Use when a video timeline needs music-driven timing or BGM and no-BGM versions.
- when_to_use
- sync video cuts to music beats; fit a BPM and phase grid before storyboarding; verify beat timing after rendering a promo; render matching BGM and no-BGM versions
- user-invocable
- true
02 资源文件 3
- 参考文档references/beat-analysis.md2.6 KB
- 许可证references/LICENSE.md11.7 KB
- 参考文档references/sound-design.md1.6 KB
03 SKILL.md 正文
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run build:skills -->
Beat-synced timelines
Use this skill when a chosen music track should shape a video timeline. Analyze and accept the beat grid before storyboarding. If no track is chosen, pace the edit to its content and leave beat sync for later. Defer media measurements and normalization to trove-ffmpeg.
Measure and accept the grid
scenes.py --beatsrequires a video stream, so it cannot read an audio-only track directly. For an audio-only track, first get consent to create temporary media. Usebackground.pyto make a silent carrier at least as long as the track, thenaudio.py --replaceto add the track. Read the installed manual for file arguments. Runscenes.py ANALYSIS_VIDEO.mp4 --beats. Do not claim direct MP3 support.- Record BPM, phase, onset count, supported-beat count, confidence, and
usablefrom the result. Check likely half-time and double-time interpretations against supported onsets. Do not choose a tempo from the scalar alone. - Apply the acceptance gate in Beat analysis.
usable: trueis necessary, but it does not prove every residual criterion. Do not claim match or residual limits passed unless measured evidence provides them. - If the gate fails or the grid remains uncertain, ask before running
uv run --with librosa --with scipy --python 3.11. State that the command downloads packages. Without consent, report the measured result and use content pacing. Do not quietly install, download, or substitute another package. - When
trove-ffmpegis unavailable, mark grid analysis and dependent checks unchecked. Do not invent command output.
Build the timeline
Keep source phase and beat interval in floating-point seconds. Convert to frames only when writing the Remotion timeline. Use one shared beatF(n) function for beat-anchored cuts and keyframes. Keep source phase unchanged when compensating output offset. The formula and an example are in Beat analysis.
Use the grid for regular cuts and tightly repeated steps. Anchor isolated accents and ending holds to measured transients. Treat onsets as candidates, not automatic instructions for a visual hit. Let dense drums carry rhythm without pulsing the whole frame on every beat.
Allow no more than three full-frame impacts in the entire video. Match each one to a strongest measured hit, with at least sixteen beats between impacts. Keep ordinary beat movement on the subject or graphic layer. Do not turn every beat into a zoom, shake, flash, or inversion.
Align sound and compensate offsets
Align sound effects by their audible peak, not by the source file's first sample. Measure the output audio offset for the actual render pipeline. Apply source peak lag and measured output offset as separate values. Keep both in the timing calculation rather than hand-editing individual hit frames. See Sound design.
Render and verify delivery
- Render the BGM version from the Remotion timeline.
- Render the no-BGM version from the same timeline with the Remotion BGM prop, such as
{"bgm": false}. Never make the no-BGM version by removing a track from the finished file with a media command. - Normalize the BGM version for the named destination with
loudness.py. Measure the no-BGM stem and report its peak without applying the platform target. - Re-run
scenes.py DELIVERED_NORMALISED_BGM_FILE --beatson the delivered, loudness-normalised file. Compare every designed cut against the nearest measured beat, and report the error in frames. Do not use the pre-normalised render as the final re-test. - Re-measure output offset after the final audio encode. Record the codec and bitrate with the measured offset. Run
check.py DELIVERED_FILE --platform DESTINATION --contentfor each delivered file. - If any measurement tool is absent, list its check as unchecked. Do not report an unchecked test as passed.
See LICENSE.md for the upstream license and adaptation notice.
04 同仓库更多 Skills
using-trove
Skill discipline anchor for the Trove marketplace. Loaded once per session; routes the agent to the right trove-* skill before code, planning, review, or git actions.
trove-write-skill
Skill authoring workflow. Use when creating or updating a Codex or Trove skill, including rubrics, tasks, metadata, and validation.
trove-worktree
Git worktree workflow for spikes, risky experiments, and broad refactors that should not disturb the user's current branch.
trove-why
Reconstruct design rationale and decision history from evidence — source control, issue tracker (Linear), docs (Notion), chat (Slack), error tracking (Sentry) — with calibrated confidence. Use for "why does X work this way", "why did we pick Y", regressions, and postmortems. Use trove-explain for how it works now.
trove-verify
Completion verification workflow. Use before claiming done, fixed, complete, ready, or shipped.
trove-unslop
Cut AI tells from writing — PR descriptions, release notes, specs, commit bodies, and replies. Use before finalizing prose, or when the user asks to clean up, de-slop, or make text sound human.