Beatcut: A Custom Beat-Synced Video Editor

Description

A Python CLI that takes two source videos and an audio track, detects the song's BPM, cuts between the two sources on every beat, applies a subtle color grade, and exports a finished 9:16 MP4 ready to post. Every behavior is driven by a JSON config, so the client can tweak the look and iterate on new edits.

The engine auto-selects between two modes based on edit length. A 15-second Punch mode uses tight, beat-grid-locked cuts for viral hooks. A 30-second Breathe mode uses looser cuts with occasional 808 bass snaps for cinematic reels.

How it works

Five-stage pipeline: config, audio analysis, cut plan, clip assignment, render.

Audio analysis uses librosa, tuned looser than default for trap and hip-hop, with a half/double clamp to fix the common BPM double-reporting issue. A second pass isolates sub-bass frequencies to detect 808 attacks.

Cut planning walks the beat grid, keeps each beat as a possible cut with a configurable probability, and enforces a minimum segment duration. In the 30-second mode, cuts within tolerance of an 808 snap to the actual bass attack. Source alternation has a max-consecutive cap so the edit never reads as A-B-A-B.

Rendering runs through FFmpeg subprocess calls, with frame-accurate extraction, concat-demuxer stitching, and a single mux pass for audio. Long silent stretches are held through, not cut across.

Stack

Python 3.12, librosa, scipy, NumPy, FFmpeg via subprocess, Docker multi-stage build with a static FFmpeg binary, pytest with 100 percent test coverage, ruff, mypy strict mode, pre-commit hooks, and a GitHub Actions CI pipeline that runs lint, typecheck, and test on every push.:

Check it out