core-flux 0.3.4

A blazing fast video editing library wrapping FFmpeg native filters.

core-flux (Concisely Optimized Render Engine - FFmpeg Linear User Xtension)

A high-performance video editing and compositing library built entirely on top of native FFmpeg complex filtergraphs. By bypassing Python-level pixel manipulation and compiling layers directly into a single native filter graph, core-flux runs at maximum speed with a beautiful, modern API.

---

Installation

Stable Channel (Compositing Layer Engine v0.3.x)

pip install core-flux

Legacy Channel (Linear Engine v0.2.x)

If you need the older linear pipeline structure, lock your installation to the 0.2 series:

pip install core-flux<0.3.0

---

Quick Start

Create independent video and audio pieces, layer them onto a master canvas, change volume, add fades, and compile instantly:

from fastvideo import VideoLayer, AudioLayer, Composition

# 1. Initialize and configure independent pieces
background = VideoLayer("bg.mp4").resize(1920, 1080).fade_out(start_fade=10.0)
facecam = (VideoLayer("gamer_cam.mp4")
           .resize(400, 300)
           .set_position(x=50, y=50)
           .mute())  # Mute native webcam background noise

# 2. Add an independent audio track
bg_music = AudioLayer("lofi_beats.mp3").with_volume_scaled_to(0.2)

# 3. Stack layers and tracks onto the composition timeline canvas
timeline = Composition(
    layers=[background, facecam],
    audio_tracks=[bg_music]
)

# 4. Render directly to a native FFmpeg stream
timeline.render("gaming_edit.mp4")

---

Performance Benchmarks

The following benchmark measures a standard core pipeline task: reading a 1080p source video, scaling it to 720p, re-encoding both video (H.264) and audio (AAC), and writing to an MP4 container. Timings represent the average of multiple production runs following an initial warmup run to eliminate cache noise.

Test Environment

• Hardware: Apple M1 (8-core CPU)
• Memory: 16GB RAM
• OS: macOS (Rosetta 2 translation layer)

Results

===========================================================================
   BENCHMARK SUMMARY REPORT (1080p Scaled H.264/AAC Export)
===========================================================================
Engine             | Avg Time     | Min Time     | Max Time     | Std Dev   
---------------------------------------------------------------------------
ffmpeg             |       7.68s  |       7.55s  |       7.89s  |     0.18s
core-flux          |       7.57s  |       7.51s  |       7.63s  |     0.06s
moviepy            |      14.08s  |      13.92s  |      14.24s  |     0.16s
===========================================================================
Conclusion: core-flux achieves a 1.86x speedup relative to MoviePy.
===========================================================================

NOTE ON RAW FFMPEG VS. CORE-FLUX TIMINGS:
The ~0.11s delta is within normal run-to-run variance (see std devs).
core-flux constructs the FFmpeg command with pre-validated parameters,
avoiding redundant flag resolution on each call. Both engines execute
at the FFmpeg process level with no meaningful architectural difference.
---------------------------------------------------------------------------

Note: These results were captured under Rosetta 2 translation. Native ARM performance may differ.

---

Features

• Compositing Canvas — Treat video and audio tracks as individual layers that can be stacked, sized, and placed anywhere.
• FFmpeg-Native Speed — Zero Python processing bottleneck; your timeline is compiled into a native C-level complex graph.
• Granular Audio Routing — Scale or completely mute individual video stream audio tracks independently before final mixing.
• Cinematic Transitions — Native hardware-accelerated video and audio fades.
• Audio Mixing — Automatically mixes all distinct audio tracks using FFmpeg's amix filter.

---

API Reference

VideoLayer(input_path: str)

Represents an independent video clip layer. Automatically detects whether the file contains native audio.

clip = VideoLayer("input.mp4")

.set_position(x: int, y: int)

Sets the pixel coordinates where the layer will sit relative to the base canvas background.

clip.set_position(x=100, y=50)

.resize(width: int, height: int)

Scale this specific layer to the given dimensions in pixels.

clip.resize(1280, 720)

.crop(x1: int, y1: int, width: int, height: int)

Crop a rectangular region of the layer, starting from the top-left corner (x1, y1).

clip.crop(100, 50, 640, 480)

.trim(start_time: float, end_time: float)

Cut this layer between two timestamps in seconds. Handles internal audio timing safely if audio is present.

clip.trim(0, 10)

.adjust_colors(contrast: float = 1.0, brightness: float = 0.0, saturation: float = 1.0)

Adjust contrast, brightness, and saturation for this layer.

clip.adjust_colors(contrast=1.2, saturation=1.5)

.blackwhite()

Convert this layer to black and white.

clip.blackwhite()

.with_volume_scaled_to(factor: float)

Scale the video's embedded native audio stream volume. 0.5 halves volume; 2.0 doubles it.

clip.with_volume_scaled_to(0.5)

.mute()

Completely silence the embedded native audio stream on this video layer.

clip.mute()

.fade_in(start_time: float, duration: float = 1.0)

Smoothly fades both video visuals and its native audio in from black/silence.

clip.fade_in(start_time=0.0, duration=2.0)

.fade_out(start_fade: float, duration: float = 1.0)

Smoothly fades both video visuals and its native audio out to black/silence.

clip.fade_out(start_fade=13.5, duration=1.5)

---

AudioLayer(input_path: str)

Represents an independent secondary audio track (e.g., sound effects, background music).

music = AudioLayer("music.mp3")

.with_volume_scaled_to(factor: float)

Scale the audio volume. 0.5 halves volume; 2.0 doubles it.

music.with_volume_scaled_to(0.5)

.fade_out(start_time: float, duration: float = 1.0)

Smoothly fades the audio track out to complete silence.

music.fade_out(start_time=45.0, duration=2.0)

.trim(start_time: float, end_time: float)

Cut the audio track between two timestamps in seconds.

music.trim(15, 45)

---

Composition(layers: list = None, audio_tracks: list = None)

The central timeline manager. The first object in layers behaves as the background video canvas; subsequent layers are overlaid sequentially on top.

timeline = Composition(layers=[bg, overlay_1], audio_tracks=[music])

.render(output_path: str, format_type: str = 'video')

Compiles all layer blocks into an optimal FFmpeg filtergraph and writes the result to disk.

The format_type parameter controls the output mode:

Value	Description
'video'	Standard multi-layer video with mixed audio tracks (default). Encodes with H.264 + AAC.
'gif'	Animated GIF output optimized with a custom high-fidelity color palette.
'audio'	Compiles and mixes audio streams only into an MP3 or AAC file.

# Render standard multi-layer video
timeline.render("output.mp4")

# Render high-fidelity GIF
timeline.render("output.gif", format_type='gif')

# Render audio compilation only
timeline.render("master_mix.mp3", format_type='audio')

Note: Attempting to render with format_type='audio' when no tracks or layer audio streams are active raises a ValueError.

---

Requirements

• Python 3.8+
• FFmpeg installed and available on your system PATH

---

License

MIT