Beatcut is the decision and rendering layer between raw footage and a finished cut. You bring the music and clips; it analyzes the music's structure (beats, downbeats, sections, energy curve), looks at your clips (scene boundaries, motion), then arranges and renders an MP4 that lands cuts on the right notes.
Not a beat-detection library — it stands on beat-this and friends. Not AI video generation. Not a full NLE. It's the editorial brain that picks which clip lands on which beat, plus the render pipeline that ships an MP4.
- Rhythm-reactive transitions — the same song picks
flash_cutat drops,fadeon quiet passages, hard cuts during fast sequences, and crossfades on energy buildups. Driven by the music's energy curve, not a static preset. - Cut feels, not just presets — pick
EDM,Vlog,Cinematic,Punchy, orSingle Takeand the matcher's whole shape changes (slot density, scene-fit weighting, transition policy). - Hot-pluggable text templates — drop a folder into
~/.beatcut/plugins/text_templates/and it appears in the WebUI. Templates are Jinja2-rendered ASS for libass. - Three interfaces, one core — Python SDK, CLI (Typer), local WebUI (FastAPI + React) all share the same library.
The Editor surfaces the musical structure first: section labels (INTRO / CHORUS / VERSE), beat-grid ruler, frequency-band energy bars, and candidate windows the system picked. Tweak MODE, DURATION, and CUT FEEL, then re-pick — every choice is reversible and re-runnable.
Until v0.2 ships to PyPI, install from source:
git clone https://github.com/alanhuang67/beatcut
cd beatcut
./scripts/install.sh
source .venv/bin/activate # on Windows: .venv\Scripts\activate
beatcut serve # → http://localhost:7860install.sh does the full setup in one shot:
- Validates Python ≥ 3.11 and Node ≥ 18
- Auto-installs
ffmpegvia Homebrew on macOS (skipped if already on PATH; Linux prints theapt install ffmpeghint instead, since sudo would block the script) - Creates a
.venv(uv if available, falls back topython -m venv) - Installs
beatcut[full,gemini](~500 MB — torch + beat-this + opencv + scenedetect + google-genai) - Builds the React WebUI bundle
Takes ~5 min on a clean macOS box. If ffmpeg isn't found and can't auto-install, Beatcut falls back to bundled imageio-ffmpeg at runtime (system ffmpeg is preferred for hardware encoders, but not strictly required).
Why no
pip install beatcutyet? Beatcut depends onbeat-this, which is currently distributed only as agit+URL — and PyPI rejects packages that pull source dependencies. Oncebeat-this(or a fork) is republished as a regular PyPI package, install becomes a one-liner:pip install beatcut[full].
# One-shot end-to-end:
beatcut auto song.mp3 ./footage/ -o output.mp4
# Project flow:
beatcut project create "My Vlog"
beatcut project add-audio <id> song.mp3 --copy
beatcut project add-videos <id> ./footage/ --copy
beatcut auto --project <id> -o output.mp4
# Diagnostics:
beatcut doctor # ffmpeg / torch / libass / cache report
beatcut cache info # cache size + breakdown- ✅ Local project management (CLI + WebUI) with auto-cleanup of derived artifacts
- ✅ Audio analysis —
beat-this(SOTA beat / downbeat) +librosafor sections + frequency-band energy - ✅ Scene detection — PySceneDetect content-aware splitting + auto-proxy for big sources
- ✅ Optional per-scene visual understanding via Gemini (bring your own API key)
- ✅ Cut-feel matcher — 5 feels × variety window × scene-fit scoring
- ✅ Multi-candidate batch picker — system finds N good musical windows, you pick the winner
- ✅ Rhythm-reactive transitions —
cut/fade/xfade_crossfade/flash_cut - ✅ Render pipeline — chunked, resumable, hardware-accelerated when available
- ✅ Multi-version delivery gallery — render the same window with different feels and compare
- ✅ Optional RIFE frame interpolation (NCNN / Vulkan, no CUDA required)
- 🔄 More cut feels and additional text templates (
title_card,caption) - 🔄 Manual timeline editing — drag-to-replace clips, manual beat overrides
- 🔄 Full xfade catalog (50+ transition variants)
- 🔄 FCPXML export for Premiere / DaVinci / FCP roundtrips
- 🔄 PyPI publication once
beat-thisis republished as a regular package
Beatcut stands on excellent open-source work. Credit where due:
- beat-this (CPJKU · ISMIR 2024 SOTA) — beat / downbeat detection
- PySceneDetect — content-aware scene-change detection
- librosa — section detection and frequency-band energy
- TNTwise/rife-ncnn-vulkan — frame interpolation (RIFE v4.26 ensemble, NCNN/Vulkan port)
- FFmpeg — encoding / rendering / hardware acceleration backbone
- imageio-ffmpeg — bundled-binary fallback when system FFmpeg isn't found
- Google Gemini — optional per-clip visual understanding (user's own API key)
- FastAPI + React + Vite + TanStack Query — server + WebUI stack
Beatcut's contribution is the integration layer: rhythm-reactive transition policy, beat-aligned cut snapping, project-level state machine, hot-pluggable text effect templates, and the WebUI / CLI / SDK packaging that makes the above usable as one tool.
git clone https://github.com/alanhuang67/beatcut
cd beatcut
uv venv --python 3.13 .venv
uv pip install -e ".[dev]"
# Run tests
uv run pytest
# Lint + format
uv run ruff check .
uv run ruff format .
# Build the React WebUI (one-time + after frontend changes)
bash scripts/build_frontend.shAGPL-3.0-or-later. External contributors are required to sign the CLA.
Beatcut does not check copyright on the music or footage you use. You are responsible for ensuring you have rights to the media you process. For royalty-free music, try Pixabay Music or Free Music Archive.
Made by Alan Huang.