README

A Laravel package for AV1 video encoding with support for ab-av1 VMAF-targeted quality optimization and direct FFmpeg encoding with hardware acceleration (Intel QSV, AMD AMF, NVIDIA NVENC).

use Foxws\AV1\Facades\AV1;

// FFmpeg encoding with hardware acceleration
$result = AV1::open('videos/input.mp4')
    ->ffmpegEncode()
    ->useHardwareAcceleration()
    ->crf(28)
    ->preset('6')
    ->export()
    ->toDisk('s3')
    ->save('output.mp4');

// Or use ab-av1 for VMAF-targeted encoding
$result = AV1::open('videos/input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->save('output.mp4');

Features

🎬 Fluent API - Laravel-style chainable methods
📁 Multiple Disks - Works with local, S3, and custom filesystems
🎯 VMAF-Targeted Encoding - Automatically finds optimal CRF for target quality using ab-av1
⚡ Hardware Acceleration - GPU encoding support (Intel QSV, AMD AMF, NVIDIA NVENC)
🔄 Multiple Encoders - Support for ab-av1 and FFmpeg with auto-detection
📊 Quality Metrics - Built-in VMAF & XPSNR scoring
🚀 Auto CRF Optimization - Use ab-av1 to find optimal CRF, then encode with FFmpeg GPU
🧪 Testable - Clean architecture with mockable components
📝 Type-Safe - Full PHP 8.4+ type declarations

Requirements

PHP 8.3 or higher
Laravel 11.x or higher
FFmpeg with AV1 encoder support (libsvtav1 or hardware encoder)
Optional: ab-av1 for VMAF-targeted quality optimization

Installation

Install the package via composer:

composer require foxws/laravel-av1

Publish the config file:

php artisan vendor:publish --tag="av1-config"

Installing ab-av1 (Optional)

ab-av1 is optional but recommended for VMAF-targeted quality optimization. Install using cargo:

cargo install ab-av1

Or download a prebuilt binary from the releases page.

Installing FFmpeg with AV1 Support

FFmpeg is required for direct AV1 encoding. Ensure FFmpeg is compiled with AV1 encoder support:

# Check available AV1 encoders
ffmpeg -encoders | grep av1

# You should see one or more of:
# - libsvtav1 (CPU encoding)
# - av1_qsv (Intel Quick Sync)
# - av1_amf (AMD)
# - av1_nvenc (NVIDIA)

For hardware acceleration support, you'll need FFmpeg compiled with the appropriate hardware encoder for your GPU.

Verify Installation

After installation, verify that ab-av1 is properly configured:

php artisan av1:verify

This will check:

Binary exists and is executable
Can retrieve version information
Configuration is properly set up
Temporary directory is accessible

Package Information

View package and binary information:

php artisan av1:info

Quick Start

FFmpeg Hardware Encoding

Encode videos using FFmpeg with automatic hardware acceleration detection:

use Foxws\AV1\Facades\AV1;

// Auto-detect and use GPU acceleration
$result = AV1::open('input.mp4')
    ->ffmpegEncode()
    ->useHardwareAcceleration()
    ->crf(28)
    ->preset('6')
    ->export()
    ->save('output.mp4');

FFmpeg with Auto CRF Optimization

Combine ab-av1's CRF optimization with FFmpeg's GPU encoding:

// Use ab-av1 to find optimal CRF, then encode with FFmpeg GPU
$result = AV1::open('input.mp4')
    ->ffmpegAutoEncode()
    ->targetVmaf(95)
    ->preset('6')
    ->useHardwareAcceleration()
    ->export()
    ->save('output.mp4');

Using ab-av1 Encoder

Use ab-av1 for integrated VMAF-targeted encoding:

use Foxws\AV1\Facades\AV1;

$result = AV1::open('input.mp4')
    ->abav1() // Use ab-av1 encoder
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->save('output.mp4');

VMAF Encode

Automatically find the optimal CRF value to achieve a target VMAF quality score and encode the full video:

use Foxws\AV1\Facades\AV1;

$result = AV1::open('input.mp4')
    ->abav1() // Use ab-av1 encoder
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->save('output.mp4');

Hardware Acceleration

Check available hardware encoders and use the best available:

use Foxws\AV1\FFmpeg\HardwareDetector;

$detector = new HardwareDetector();

// Check available encoders
$encoders = $detector->getAvailableEncoders();
// ['av1_qsv' => [...], 'libsvtav1' => [...]]

// Check if hardware acceleration is available
if ($detector->hasHardwareAcceleration()) {
    $result = AV1::open('input.mp4')
        ->ffmpegEncode()
        ->useHardwareAcceleration()
        ->crf(28)
        ->export()
        ->save('output.mp4');
}

CRF Search (ab-av1)

Search for the optimal CRF value without encoding the full video:

$result = AV1::open('input.mp4')
    ->abav1()
    ->crfSearch()
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->save();

// The output will contain the recommended CRF value
echo $result->getOutput();

Sample Encode (ab-av1)

Encode a sample of the video to test settings:

$result = AV1::open('input.mp4')
    ->abav1()
    ->sampleEncode()
    ->crf(30)
    ->preset('6')
    ->sample(60) // Sample duration in seconds
    ->export()
    ->save('sample.mp4');

Full Encode (ab-av1)

Encode the entire video with a specific CRF:

$result = AV1::open('input.mp4')
    ->abav1()
    ->encode()
    ->crf(30)
    ->preset('6')
    ->export()
    ->save('output.mp4');

VMAF Score

Calculate VMAF score between two videos:

$result = AV1::vmaf()
    ->abav1()
    ->reference('original.mp4')
    ->distorted('encoded.mp4')
    ->export()
    ->save();

echo $result->getOutput(); // VMAF score

XPSNR Score

Calculate XPSNR score between two videos:

$result = AV1::xpsnr()
    ->abav1()
    ->reference('original.mp4')
    ->distorted('encoded.mp4')
    ->export()
    ->save();

echo $result->getOutput(); // XPSNR score

FFmpeg Encoding

Basic FFmpeg Encoding

// Simple FFmpeg encode
$result = AV1::open('input.mp4')
    ->ffmpegEncode()
    ->crf(28)
    ->preset('6')
    ->export()
    ->save('output.mp4');

// With 10-bit color
$result = AV1::open('input.mp4')
    ->ffmpegEncode()
    ->crf(28)
    ->pixFmt('yuv420p10le')
    ->export()
    ->save('output.mp4');

GPU Acceleration

// Auto-detect and use best hardware encoder
$result = AV1::open('input.mp4')
    ->ffmpegEncode()
    ->useHardwareAcceleration()
    ->crf(28)
    ->preset('6')
    ->export()
    ->save('output.mp4');

Auto CRF with FFmpeg

Combine ab-av1's CRF optimization with FFmpeg's GPU encoding:

// Find optimal CRF with ab-av1, encode with FFmpeg GPU
$result = AV1::open('input.mp4')
    ->ffmpegAutoEncode()
    ->targetVmaf(95)
    ->preset('6')
    ->useHardwareAcceleration()
    ->export()
    ->save('output.mp4');

For detailed FFmpeg examples including hardware-specific configurations, see FFMPEG_ENCODING.md.

Working with Different Disks

From S3

$result = AV1::fromDisk('s3')
    ->open('videos/input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->toDisk('s3')
    ->save('videos/output.mp4');

From Local to S3

$result = AV1::open('local/input.mp4')
    ->abav1()
    ->encode()
    ->crf(30)
    ->preset('6')
    ->export()
    ->toDisk('s3')
    ->toPath('videos/encoded')
    ->save('output.mp4');

S3 with Hardware Encoding

$result = AV1::fromDisk('s3')
    ->open('videos/input.mp4')
    ->ffmpegEncode()
    ->useHardwareAcceleration()
    ->crf(28)
    ->export()
    ->toDisk('s3')
    ->save('encoded/output.mp4');

Advanced Options

CRF Range

$result = AV1::open('input.mp4')
    ->abav1()
    ->crfSearch()
    ->minCrf(20)
    ->maxCrf(40)
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->save();

Max Encoded Size

$result = AV1::open('input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->maxEncodedPercent(95) // Max 95% of original size
    ->export()
    ->save('output.mp4');

Pixel Format

$result = AV1::open('input.mp4')
    ->abav1()
    ->encode()
    ->crf(30)
    ->preset('6')
    ->pixFmt('yuv420p10le')
    ->export()
    ->save('output.mp4');

Full VMAF

$result = AV1::open('input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->fullVmaf() // Calculate VMAF for entire video
    ->export()
    ->save('output.mp4');

VMAF Model

$result = AV1::open('input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->vmafModel('/path/to/vmaf_model.json')
    ->export()
    ->save('output.mp4');

Verbose Output

$result = AV1::open('input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->verbose()
    ->export()
    ->save('output.mp4');

echo $result->getOutput();

Batch Processing

Process multiple files:

$files = ['video1.mp4', 'video2.mp4', 'video3.mp4'];

AV1::fromDisk('s3')
    ->each($files, function ($av1, $file) {
        $av1->open($file)
            ->abav1()
            ->vmafEncode()
            ->preset('6')
            ->minVmaf(95)
            ->export()
            ->toDisk('s3')
            ->toPath('encoded')
            ->save();
    });

Callbacks

Add callbacks after encoding:

$result = AV1::open('input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->afterSaving(function ($result, $path) {
        Log::info("Encoded to: {$path}");
        Log::info("VMAF score: {$result->getOutput()}");
    })
    ->save('output.mp4');

Debugging

Get the command that will be executed:

$command = AV1::open('input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->getCommand();

echo $command;
// Output: ab-av1 auto-encode -i input.mp4 --preset 6 --min-vmaf 95

Or dump and die:

AV1::open('input.mp4')
    ->abav1()
    ->vmafEncode()
    ->preset('6')
    ->minVmaf(95)
    ->export()
    ->dd();

Configuration

Environment Variables

ab-av1 Configuration:

AB_AV1_BINARY_PATH - Path to ab-av1 binary (default: '/usr/local/bin/ab-av1')
AB_AV1_TIMEOUT - Maximum time in seconds for encoding commands (default: 14400)
AB_AV1_PRESET - Default encoder preset 0-13 for svt-av1 (default: 6)
AB_AV1_MIN_VMAF - Minimum VMAF score to target (default: 80)
AB_AV1_MAX_PERCENT - Maximum encoded file size as percentage (default: 300)

FFmpeg Configuration:

FFMPEG_BINARY_PATH - Path to ffmpeg binary (default: '/usr/local/bin/ffmpeg')
FFMPEG_TIMEOUT - Maximum time in seconds for FFmpeg encoding (default: 7200)
FFMPEG_ENCODER - Force specific encoder (null = auto-detect): av1_qsv, av1_amf, av1_nvenc, libsvtav1
FFMPEG_HARDWARE_ACCEL - Enable hardware acceleration (default: true)
FFMPEG_DEFAULT_CRF - Default CRF value (default: 30)
FFMPEG_DEFAULT_PRESET - Default preset (default: 6)
FFMPEG_AUDIO_CODEC - Default audio codec (default: 'libopus')
FFMPEG_PIXEL_FORMAT - Default pixel format (default: 'yuv420p')
FFMPEG_AUTO_CRF - Use ab-av1 for auto CRF by default (default: false)

General:

AB_AV1_LOG_CHANNEL - Log channel to use (false to disable, null for default)
AB_AV1_TEMPORARY_FILES_ROOT - Directory for temporary files (default: storage/app/av1/temp)

Configuration File

Publish and edit config/av1.php for more control:

return [
    'binaries' => [
        'ab-av1' => env('AB_AV1_BINARY_PATH', '/usr/local/bin/ab-av1'),
        'ffmpeg' => env('FFMPEG_BINARY_PATH', '/usr/local/bin/ffmpeg'),
    ],

    'ffmpeg' => [
        'timeout' => env('FFMPEG_TIMEOUT', 7200),
        'encoder' => env('FFMPEG_ENCODER', null),
        'hardware_acceleration' => env('FFMPEG_HARDWARE_ACCEL', true),
        'default_crf' => env('FFMPEG_DEFAULT_CRF', 30),
        'default_preset' => env('FFMPEG_DEFAULT_PRESET', 6),
        'audio_codec' => env('FFMPEG_AUDIO_CODEC', 'libopus'),
        'pixel_format' => env('FFMPEG_PIXEL_FORMAT', 'yuv420p'),
        'auto_crf' => env('FFMPEG_AUTO_CRF', false),
    ],

    'ab-av1' => [
        'timeout' => env('AB_AV1_TIMEOUT', 14400),
        'preset' => env('AB_AV1_PRESET', 6),
        'min_vmaf' => env('AB_AV1_MIN_VMAF', 80),
        'max_encoded_percent' => env('AB_AV1_MAX_PERCENT', 300),
    ],
];

Error Handling

try {
    $result = AV1::open('input.mp4')
        ->abav1()
        ->vmafEncode()
        ->preset('6')
        ->minVmaf(95)
        ->export()
        ->save('output.mp4');

    if ($result->isSuccessful()) {
        echo "Encoding successful!";
    } else {
        echo "Encoding failed: " . $result->getErrorOutput();
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Available Commands

vmafEncode()

Automatically finds the optimal CRF value to achieve a target VMAF score, then encodes the full video at that quality level.

Required options:

preset(string) - Encoder preset
minVmaf(float) - Minimum VMAF score

Optional:

maxEncodedPercent(int) - Max size as percentage of input
sample(int) - Sample duration in seconds
minCrf(int) - Minimum CRF to try
maxCrf(int) - Maximum CRF to try

crfSearch()

Searches for the optimal CRF value to achieve a target VMAF score without encoding the full video. Useful for testing before full encoding.

Required options:

preset(string) - Encoder preset (0-13 for svt-av1)
minVmaf(float) - Target VMAF score (0-100)

Optional: Same as vmafEncode()

sampleEncode()

Encodes a sample portion of the video for testing settings before committing to a full encode.

Required options:

crf(int) - CRF value to use for encoding
preset(string) - Encoder preset (0-13 for svt-av1)

Optional:

sample(int) - Sample duration in seconds (default varies by encoder)

encode()

Encodes the entire video using a manually specified CRF value. Use this when you know the exact CRF you want.

Required options:

crf(int) - CRF value (lower = higher quality, larger file)
preset(string) - Encoder preset (0-13 for svt-av1, higher = faster/larger)

vmaf()

Calculates the VMAF (Video Multimethod Assessment Fusion) quality score between a reference and distorted video.

Required options:

reference(string) - Reference (original) video path
distorted(string) - Distorted (encoded) video path

Optional:

vmafModel(string) - Path to custom VMAF model file

xpsnr()

Calculates the XPSNR (Extended Peak Signal-to-Noise Ratio) quality score between a reference and distorted video.

Required options:

reference(string) - Reference (original) video path
distorted(string) - Distorted (encoded) video path

Testing

composer test

Credits

ab-av1 - The underlying encoding tool

License

The MIT License (MIT). Please see License File for more information.

foxws / laravel-av1

Maintainers

Details

README

Features

Requirements

Installation

Installing ab-av1 (Optional)

Installing FFmpeg with AV1 Support

Verify Installation

Package Information

Quick Start

FFmpeg Hardware Encoding

FFmpeg with Auto CRF Optimization

Using ab-av1 Encoder

VMAF Encode

Hardware Acceleration

CRF Search (ab-av1)

Sample Encode (ab-av1)

Full Encode (ab-av1)

VMAF Score

XPSNR Score

FFmpeg Encoding

Basic FFmpeg Encoding

GPU Acceleration

Auto CRF with FFmpeg

Working with Different Disks

From S3

From Local to S3

S3 with Hardware Encoding

Advanced Options

CRF Range

Max Encoded Size

Pixel Format

Full VMAF

VMAF Model

Verbose Output

Batch Processing

Callbacks

Debugging

Configuration

Environment Variables

Configuration File

Error Handling

Available Commands

vmafEncode()

crfSearch()

sampleEncode()

encode()

vmaf()

xpsnr()

Testing

Credits

License