# beat-sync-video-editing

This skill builds music-driven edits: it picks clips from your footage, cuts them on the beat and renders the result with FFmpeg.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 775 installs · ★ 1
- Author: ecliptic-ai
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ecliptic-ai/skills/tree/HEAD/plugins/ecliptic/skills/beat-sync-video-editing/SKILL.md
- Updated: 2026-08-13
- HTML: https://affpapa.org/en/nevibecode/skills/beat-sync-video-editing

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/beat-sync-video-editing/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/beat-sync-video-editing/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/beat-sync-video-editing/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/beat-sync-video-editing/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ecliptic-ai/skills beat-sync-video-editing
```

2. **Manually: put the files in place**
- File: `.github/skills/beat-sync-video-editing/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ecliptic-ai/skills --path plugins/ecliptic/skills/beat-sync-video-editing
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/beat-sync-video-editing/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add ecliptic-ai/skills --skill beat-sync-video-editing -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ecliptic-ai/skills/tree/HEAD/plugins/ecliptic/skills/beat-sync-video-editing/SKILL.md

## When to use it
- 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_complex` string for FFmpeg
- reuse files already uploaded to Gemini across runs

## Example prompts
- 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

## Similar
- [video-processing-editing](https://affpapa.org/en/nevibecode/skills/video-processing-editing.md) — skill · 1400 installs
- [anycap-gemini-omni-video-edit](https://affpapa.org/en/nevibecode/skills/anycap-gemini-omni-video-edit.md) — skill · 444 installs
- [video-editing](https://affpapa.org/en/nevibecode/skills/video-editing.md) — skill · 6600 installs
- [beat-sync-editing](https://affpapa.org/en/nevibecode/skills/beat-sync-editing.md) — skill · 2900 installs
- [video-use](https://affpapa.org/en/nevibecode/skills/video-use.md) — skill · 5100 installs
- [video-translation](https://affpapa.org/en/nevibecode/skills/video-translation.md) — skill · 2000 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md