core-flux 0.3.1b1

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 (Linear Engine v0.2.x)

pip install core-flux

Beta Channel (Compositing Layer Engine v0.3.x+)

To test the new non-linear pieces and layers architecture, install the pre-release explicitly:

pip install core-flux==0.3.0b1

---

Quick Start (v0.3.0b1+)

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

from fastvideo import VideoLayer, AudioLayer, Composition

# 1. Initialize and configure independent pieces
background = VideoLayer("bg.mp4").resize(1920, 1080)
facecam = VideoLayer("gamer_cam.mp4").resize(400, 300).set_position(x=50, y=50)

# 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")

---

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.
• Audio Mixing — Automatically mixes audio tracks using FFmpeg's amix filter.
• Silent-File Safe — Layer audio components are automatically skipped when a source video contains no sound stream.

---

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 (x, y) 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()

---

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 multiplier. 0.5 halves volume; 2.0 doubles it.

music.with_volume_scaled_to(0.5)

.trim(start_time: float, end_time: float)

Cut the audio track piece between two timestamps in seconds.

music.trim(15, 45)

---

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

The central timeline manager. The first object passed into the layers list behaves as the background video canvas. Subsequent video 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 canvas
timeline.render("output.gif", format_type='gif')

# Render audio track 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