Metadata-Version: 2.4
Name: core-flux
Version: 0.3.4
Summary: A blazing fast video editing library wrapping FFmpeg native filters.
Author: Faaris
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Requires-Dist: ffmpeg-python>=0.2.0

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

```bash
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:

```bash
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:

```python
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

```text
===========================================================================
   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.

```python
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.

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

#### `.resize(width: int, height: int)`

Scale this specific layer to the given dimensions in pixels.

```python
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)`.

```python
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.

```python
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.

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

#### `.blackwhite()`

Convert this layer to black and white.

```python
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.

```python
clip.with_volume_scaled_to(0.5)
```

#### `.mute()`

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

```python
clip.mute()
```

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

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

```python
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.

```python
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).

```python
music = AudioLayer("music.mp3")
```

#### `.with_volume_scaled_to(factor: float)`

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

```python
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.

```python
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.

```python
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.

```python
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. |

```python
# 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
