beat-sync-video-editing — Claude Code skill: cut video to the beat
This skill builds music-driven edits: it picks clips from your footage, cuts them on the beat and renders the result with FFmpeg.
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a claude-codeWhat beat-sync-video-editing does
The skill defines the EditPlan format — a JSON structure holding the audio start point and the list of video clips to place. Clip starts use MM:SS strings, durations are numbers in seconds. The clip durations have to add up to the audio duration, with 0.5s of tolerance. Clip order is deliberate and does not have to follow the source timeline.
The workflow runs in four steps. gemini-edit-plan.sh uploads the video and audio to Gemini, which watches the footage and listens to the track at the same time. Then validate-plan.sh checks the plan, build-filter.sh turns it into a -filter_complex string, and FFmpeg does the render with libx264 and aac. The first step needs GEMINI_API_KEY, plus curl and jq on the machine. Accepted video and audio formats are limited to what the Interactions API takes — mkv is not on that list, so convert it beforehand.
Uploaded files stay for 48 hours by default, which saves a re-upload on the next run. The script prints an ECLIPTIC_FILES line to stderr with names and URIs; lose it and list-gemini-files.sh shows what is currently uploaded. The default model is gemini-3.6-flash, and GEMINI_MODEL swaps it out.
What it helps with
- cut clips so the joins land on the beat
- turn a source video and a track into an EditPlan JSON
- catch a duration mismatch before rendering
- get a ready
-filter_complexstring for FFmpeg - reuse files already uploaded to Gemini across runs
Example prompts for the agent
- edit this footage to the track, cuts on the beat
- validate my EditPlan and list the errors
- build the FFmpeg filter from this plan and render it
How to install beat-sync-video-editing
1Skills CLI (Vercel)
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a claude-code2Manually: put the files in place
~/.claude/skills/beat-sync-video-editing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/beat-sync-video-editing/
1Skills CLI (Vercel)
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a codex2Manually: put the files in place
.agents/skills/beat-sync-video-editing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a cursor2Manually: put the files in place
.cursor/skills/beat-sync-video-editing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ecliptic-ai/skills beat-sync-video-editing2Manually: put the files in place
.github/skills/beat-sync-video-editing/SKILL.md1Skills CLI (Vercel)
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a gemini-cli2Platform CLI
gemini skills install https://github.com/ecliptic-ai/skills --path plugins/ecliptic/skills/beat-sync-video-editingManually: put the files in place
.devin/skills/beat-sync-video-editing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about beat-sync-video-editing
How do I install beat-sync-video-editing in Claude?
Run npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a claude-code. The skill file then lives at ~/.claude/skills/beat-sync-video-editing/SKILL.md.
What does beat-sync-video-editing do?
It walks the agent through a beat-synced edit: build an EditPlan with clip timings, validate it, generate the FFmpeg filter and render the output.
What do I need before using it?
A GEMINI_API_KEY, curl and jq, and FFmpeg for the final render. mkv footage has to be converted first, since the Interactions API rejects that format.
