Download the PHP package b7s/fluentcut without Composer

This standalone, developer‑friendly library brings the full power of FFmpeg into a beautifully fluent PHP API. Effortless to use, built for real‑world production environments, and designed with expressive chaining in mind — it handles everything from simple slideshows and video trimming to complex multi‑clip compositions with text overlays, transitions, and audio mixing.

Whether you're automating video generation, building media pipelines, or creating dynamic content at scale, FluentCut gives you a clean, modern, and type‑safe toolkit that makes programmatic video editing feel natural.

✨ Features

• 🎯 Fluent API - Laravel-inspired chainable interface that reads like a sentence
• 🎬 Video Composition - Combine videos, images, and color clips into seamless productions
• ✍️ Text Overlays - Add styled text with borders, shadows, and custom positioning
• 🖼️ Image Overlays - Layer images on top of clips with precise positioning
• 🎵 Audio Control - Add background music, keep source audio, and adjust volume
• 🔄 Transitions - 30 built-in transitions including fades, wipes, slides, dissolves, radial, circle effects, and more
• 🎨 Video Effects - 23 built-in visual effects with stackable combinations: directional zoom (9 positions), sepia, grayscale, vignette, and more
• 📐 Smart Resize - Four resize modes: contain, contain with blur, cover, and stretch
• ⚡ Presets - One‑call presets for slideshows, social media, GIFs, and web output
• 🔒 Type‑Safe - Full PHP 8.3+ type hints / PHPStan level 6
• 🛠️ CLI Tools - Built‑in doctor and info commands for diagnostics and media inspection
• 🚀 GPU Acceleration - Auto-detects and uses NVIDIA NVENC, Intel QSV, VA-API, or VideoToolbox when available
• ⏱️ No Hard Timeout - Renders without time limits by default; auto-scales per operation

Easy to use

📦 Installation

Requirements

FFmpeg must be installed on your system. FluentCut uses ffmpeg and ffprobe under the hood for all media operations.

Check Installation

This will verify that PHP 8.3+, FFmpeg, and FFprobe are available and properly configured.

🚀 Quick Start

Basic Usage

Text Overlays

Resize Video

Cut/Trim Video

GIF Export

Video Effects

Apply visual effects to individual clips. Pass a single effect or an array — duplicates are automatically removed.

Complex Composition

GPU Acceleration

Leverage hardware-accelerated encoding for dramatically faster rendering. FluentCut auto-detects available GPU encoders and uses them automatically.

How it works: Segment rendering uses GPU encoding for parallel speed, while transition passes (xfade) use CPU — this is unavoidable since FFmpeg's xfade filter is CPU-only, but it's only re-encoding already-compressed segments.

🛠️ CLI Commands

doctor - Diagnose Installation

The doctor command checks your installation and shows:

• PHP version (8.3+ required)
• FFmpeg availability and version
• FFprobe availability and version

info - Media File Information

The info command probes a media file and displays:

• Format and duration
• File size and bitrate
• Video streams (resolution, framerate)
• Audio streams (sample rate, channels)

📖 API Reference

Canvas / Dimensions

Set the output canvas size and framerate for your composition. All dimension presets also set sensible default framerates.

Video Clips

Add video files to the composition. Optionally trim by specifying start and end times in seconds.

Image Clips

Add still images as clips with a specified duration. Perfect for building slideshows or title cards.

Color / Background Clips

Add solid-color clips to create title screens, interstitials, or backgrounds.

Text Overlays

Add text to the last added clip. All parameters except text are optional. Supports positioning with pixel values, percentages ('50%'), or keywords ('center', 'top', 'bottom', 'left', 'right').

Image Overlays

Layer images on top of the last added clip, such as watermarks or logos.

Audio

Control the audio layer of your composition. Add background music, preserve source audio, and adjust volume levels. You can add multiple audio tracks with independent control over volume, start time, and duration.

Parameters:

• path (string) - Path to the audio file
• volume (?float) - Volume level 0.0-1.0, defaults to 1.0
• startAt (int|float) - Start offset in seconds, defaults to 0.0
• endAt (null|int|float) - Cut audio at this timestamp (seconds), null = play until video ends
• loop (bool) - Loop audio until video ends, defaults to false
• fadeDuration (float) - Fade in/out duration in seconds, defaults to 0.0

Note: Each audio track plays once by default unless loop: true. When looping, fade is applied at the start and end of each audio iteration for smooth transitions.

Transitions

Define the transition between the current clip and the next one. Transitions are applied between consecutive clips in the timeline.

Available transitions:

Video Effects

Apply one or more visual effects per clip. Pass a single VideoEffect, an array of effects, or use the variadic effect() method. Duplicates and None are automatically removed.

Available effects:

Resize Modes

Control how clips are fitted to the canvas when their aspect ratio doesn't match.

Output Configuration

Configure where and how the final video is saved.

Presets

Pre-configured settings optimized for common use cases. Each preset sets canvas size, framerate, transition, and resize mode.

Progress Monitoring

Track render progress in real time with a callback that receives detailed progress information.

GPU Acceleration

Enable hardware-accelerated encoding for faster rendering. FluentCut auto-detects available GPU encoders.

Platform detection:

• macOS → VideoToolbox (Apple Silicon)
• Windows → Nvenc, then Qsv
• Linux → Nvenc, then Vaapi, then Qsv

Note: Transition effects (xfade) use CPU because FFmpeg's xfade filter has no GPU implementation. This is a minor re-encoding pass — the heavy segment rendering still uses GPU.

Execution (render)

The render() method is the terminal operation that builds the FFmpeg command and executes it, returning a RenderResult object.

Result Object

The RenderResult object contains information about the rendered video and metadata about the render process.

Static Helpers

Utility methods for media inspection and system checks without creating a FluentCut instance.

⚙️ Configuration

Create a fluentcut-config.php file in your project root:

Configuration File Location:

The configuration file is searched in the following order:

1. Explicit path (if provided programmatically)
2. Project root (where composer.json is located)
3. Current working directory
4. Package root (fallback)

📋 Requirements

• PHP 8.3+
• Composer 2+
• FFmpeg installed on system
• FFprobe installed on system (included with FFmpeg)

🌐 Platform Support

Running Tests

📄 License

MIT License - see LICENSE file.

🙏 Credits

• b7s/fluentvox - API design and patterns inspiration
• Example music from: Intense Doom Style Instrumental Metal - "SYNTHETIC EDEN" (Free Music Archive) and license type (CC BY)
• Video Composition by Onur Kaya
• Video Intro by Chandresh Uike