ffxpy 0.2.0

A project designed to simplify complex ffmpeg operations by providing a more user-friendly interface and workflow.

ffxpy

ffxpy is a highly optimized Python command-line tool designed to simplify and streamline complex ffmpeg workflows. It provides a structured way to manage video processing tasks via YAML configuration, featuring smart resource management and real-time visualization.

Key Features

• Smart Concurrency: Automatically detects CPU cores and selects the optimal number of parallel jobs to balance performance and system responsiveness.
• Turbo Mode: Intelligent workflow analysis. Automatically boosts concurrency up to 16 for I/O-bound copy tasks while maintaining a stable 2 concurrent jobs for CPU-intensive encoding to avoid resource contention.
• Rich Visualization: Beautiful, real-time progress bars for both individual jobs and the overall workflow, featuring smooth tracking based on video duration and live transcoding metrics (speed, FPS).
• Pre-flight Validation: Integrated ffprobe checks to verify video availability, duration, and time ranges before starting heavy operations.
• Dry-run Mode: Preview generated ffmpeg commands in blue-tinted console output without making any changes.
• Type Safety: Built with strict static analysis (Mypy) and modern Python standards for maximum reliability.

Installation

This project is managed using uv.

uv sync

Usage

Global Options:

• --working-dir, -w: Base directory for inputs and outputs.
• --output-path, -o: Explicit output path.
• --overwrite, -y: Overwrite existing files.
• --dry-run, -n: Print commands only.
• --concurrency, -c: Manually override the smart concurrency logic.
• --version, -v: Display current version.

Concurrency Policy

ffxpy uses an intelligent resource allocation strategy:

• I/O Bound (Copying): Up to 16 concurrent jobs for maximum throughput.
• CPU Bound (Encoding): Limited to 2 concurrent jobs to ensure system stability and peak efficiency.
• Hybrid: Automatically balanced based on the detected task types within your flow.

1. Split

# Precision splitting using time stamps or ISO durations
uv run ffx split input.mp4 --start 00:00:10 --end 00:00:20

2. Merge

Automatically concatenates files, especially those generated by the split command.

uv run ffx merge --with-split

3. Flow (Automated Pipeline)

The power of ffxpy lies in YAML-defined workflows.

# example_flow.yml
setting:
  input_path: "master.mp4"
  # Optional: concurrency: 4

jobs:
  - name: "Highlights"
    command: split
    setting: { start: "00:01:00", end: "00:02:00", output_path: "clip1.mp4" }
  
  - name: "Outro"
    command: split
    setting: { start: "00:55:00", output_path: "clip2.mp4" }

  - name: "Final Render"
    command: merge
    setting: { output_path: "summary.mp4" }

Running the flow:

uv run ffx flow example_flow.yml

Development and Quality

The project maintains high engineering standards:

• BDD Testing: Full coverage of core scenarios using behave and grappa.
• Static Analysis: 100% type-checked with mypy.
• Linting: Consistent style enforced by ruff.
• CI/CD: Fully automated GitLab pipeline for linting, testing, and publishing.

# Run the test suite
uv run behave

# Run type checks
uv run mypy .