DEV Community

Cover image for I got tired of fighting ffmpeg for basic video trimming, so I built clipflow
Ronald Gosso
Ronald Gosso

Posted on

I got tired of fighting ffmpeg for basic video trimming, so I built clipflow

#python #showdev #opensource #ffmpeg

I got tired of fighting ffmpeg for basic video trimming. So I built clipflow.

You know the drill. You just want to trim a 10-minute video.

You open a terminal and type:
ffmpeg -i input.mp4 -ss 00:30 -to 02:15 -c copy output.mp4

Then you pray you got the flags right.

But wait, you need frame-accurate cutting. So you scrap -c copy. Now you are re-encoding a 4 GB file. Twenty minutes later, you are still staring at a progress bar.

R.I.P. to the 400MB node_modules folder

I hit this wall for the fifteenth time last month. Honestly, enough was enough. I decided to build a better way.

What clipflow actually does

clipflow is a typed Python API and CLI for video clipping.

It manages ffmpeg for you. It auto-downloads the binary on first use, caches it locally, and falls back to your system PATH if you already have it installed.

No manual setup. No "install ffmpeg first" warnings.

Here is the core idea. It builds and runs ffmpeg commands directly as subprocess calls.

No NumPy array conversions. No memory-heavy frame processing. Just clean, typed dataclasses going in and structured results coming out.

Three things I obsessed over

  1. Lossless stream-copy by default. Trimming a 10 GB file takes seconds with zero quality loss. Need frame-accurate cuts? Just flip a compress flag and it re-encodes properly.
  2. Highlights as a first-class concept. Most Python video libraries treat highlights as an afterthought. In clipflow, you mark a clip with highlight=True. It automatically copies that slice to a highlights/ directory. That is it.
  3. Zero runtime dependencies. The library uses only the Python standard library plus the ffmpeg binary it manages. No bloated dependency tree to debug.

Quick taste

Here is what the Python API looks like:

import clipflow
from clipflow import ClipSpec, parse_range

results = clipflow.trim(
    "raw_footage.mp4",
    ClipSpec(
        parse_range("05:00", "06:30"),
        highlight=True,
        compress=COMPRESS_HIGH,
        aspect_ratio=AR_9_16,
        label="hero_moment"
    ),
    output_dir="out"
)

print(results[0].highlight_path)
# out/highlights/hero_moment.mp4
Enter fullscreen mode Exit fullscreen mode

And the CLI is just as straightforward:

# Lossless trim
clipflow trim lecture.mp4 01:00-02:30

# Compress + crop + highlight
clipflow trim concert.mp4 05:00-06:30 --compress high --aspect 9:16 --highlight

# Inspect metadata
clipflow inspect documentary.mp4
Enter fullscreen mode Exit fullscreen mode

Scenario A: 20 minutes and 4GB of re-encode. Scenario B: 2 seconds, lossless.

Why not just use moviepy or ffmpeg-python?

Good question. I asked myself the same thing.

Most Python video libraries convert frames to NumPy arrays. That is slow. It is memory-heavy. And it is completely unnecessary for simple trimming.

clipflow does not touch a single frame. It just constructs the ffmpeg command and runs it as a subprocess.

The entire subprocess layer is isolated in clipflow/_ffmpeg.py. You can audit exactly what is being executed. No magic.

Under the hood

  1. Pure Python (requires ≥ 3.9). No Swift or Rust wrappers.
  2. Cross-platform support for macOS 14+, Windows, and Linux.
  3. ffmpeg auto-downloaded and cached per platform.
  4. 82 tests with >90% coverage.
  5. Docker-ready for instant local development.

What is next

I am currently working on batch processing improvements and a highlight-reel example script.

The repo is open and MIT licensed.

If you have ever spent more time fighting ffmpeg than actually editing video, give it a shot. And if something breaks, open an issue. I read every single one.

Links:

  1. GitHub: github.com/ronaldgosso/clipflow
  2. Docker Hub: ronaldgosso/clipflow
  3. PyPI: pip install clipflow

Top comments (0)