Video Optimizer Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require tonymans33/video-optimizer
   

2. Publish the config (optional, but recommended for customization):

   php artisan vendor:publish --provider="TonyMans33\VideoOptimizer\VideoOptimizerServiceProvider" --tag="video-optimizer-config"
   

3. Configure FFmpeg path in .env:

   FFMPEG_BINARY=/usr/bin/ffmpeg
   FFMPEG_FFMPEG_PATH=/usr/bin/ffmpeg
   FFMPEG_FFPROBE_PATH=/usr/bin/ffprobe
   

4. Enable optimization in config/video-optimizer.php:

   'enabled' => env('VIDEO_OPTIMIZER_ENABLED', true),
   

First Use Case: Basic Filament File Upload

Add the OptimizeVideo trait to your Filament resource or form component:

use TonyMans33\VideoOptimizer\Traits\OptimizeVideo;

class VideoResource extends Resource
{
    use OptimizeVideo;

    // ...
}

Now, videos uploaded via Filament forms will automatically be optimized before saving.

Implementation Patterns

1. Integration with Filament Forms

For Standard File Uploads

use Filament\Forms\Components\FileUpload;
use TonyMans33\VideoOptimizer\Traits\OptimizeVideo;

class VideoForm
{
    use OptimizeVideo;

    public function form(Form $form): Form
    {
        return $form
            ->schema([
                FileUpload::make('video')
                    ->label('Upload Video')
                    ->image()
                    ->imagePreviewHeight('200'),
            ]);
    }
}

For Spatie Media Library

use Spatie\MediaLibrary\HasMedia;
use TonyMans33\VideoOptimizer\Traits\OptimizeSpatieMedia;

class VideoModel extends Model implements HasMedia
{
    use OptimizeSpatieMedia;

    // ...
}

2. Customizing Optimization Settings

Override defaults in config/video-optimizer.php:

'formats' => [
    'webm' => [
        'enabled' => true,
        'quality' => 'medium', // low, medium, high
        'crf' => 28, // Custom CRF value (overrides quality if set)
    ],
    'mp4' => [
        'enabled' => false,
        'quality' => 'high',
    ],
],

3. Manual Optimization (Outside Filament)

use TonyMans33\VideoOptimizer\Facades\VideoOptimizer;

$optimizedPath = VideoOptimizer::optimize(
    $originalPath,
    'webm',
    'high'
);

4. Handling Fallbacks

Check if optimization succeeded:

$optimizedPath = VideoOptimizer::optimize($path, 'webm');
if ($optimizedPath->isOptimized()) {
    // Success
} else {
    // Fallback to original
    $originalPath = $optimizedPath->getOriginalPath();
}

5. Queueing Optimization Jobs

For large files, offload processing to a queue:

use TonyMans33\VideoOptimizer\Jobs\OptimizeVideoJob;

OptimizeVideoJob::dispatch($originalPath, 'webm', 'medium')
    ->onQueue('optimizations');

Gotchas and Tips

Pitfalls

1. FFmpeg Not Installed:

   • Symptom: Optimization fails silently or throws FFmpegNotFoundException.
   • Fix: Install FFmpeg and update paths in .env. Verify with:

     ffmpeg -version
     

   • Debugging: Use php artisan video-optimizer:check to validate setup.

2. File Size Limits:

   • Symptom: Large videos (>100MB) time out or fail.
   • Fix: Increase PHP max_execution_time and memory_limit or use queueing.

3. Unsupported Formats:

   • Symptom: Optimization fails for non-MP4/WEBM inputs.
   • Fix: Pre-convert files to MP4 using FFmpeg before upload or whitelist allowed formats in config:

     'allowed_extensions' => ['mp4', 'mov', 'avi', 'mkv'],
     

4. Filament Caching Issues:

   • Symptom: Optimized files don’t appear in the UI.
   • Fix: Clear Filament cache:

     php artisan filament:cache-clear
     

Debugging Tips

• Log FFmpeg Output: Enable verbose logging in config/video-optimizer.php:

  'debug' => true,
  

  Check logs at storage/logs/laravel.log.

• Test Locally: Use Docker or a local FFmpeg setup to replicate production:

  docker run --rm -it jrottenberg/ffmpeg
  

• Validate Config: Run the config validator:

  php artisan video-optimizer:validate
  

Extension Points

1. Custom FFmpeg Commands: Override the default command builder in a service provider:

   VideoOptimizer::extend(function ($optimizer) {
       $optimizer->setCustomCommand(function ($path, $format, $quality) {
           return "ffmpeg -i {$path} -c:v libvpx-vp9 -b:v 1M -c:a libopus output.{$format}";
       });
   });
   

2. Post-Optimization Hooks: Add callbacks for post-processing:

   'hooks' => [
       'after_optimize' => function ($originalPath, $optimizedPath, $format) {
           // Example: Generate thumbnails
           ThumbnailGenerator::generate($optimizedPath);
       },
   ],
   

3. Dynamic Quality Settings: Pass dynamic quality settings per upload:

   FileUpload::make('video')
       ->extraAttributes([
           'data-video-quality' => 'high',
       ]),
   

   Then access in a custom optimizer:

   $quality = $request->input('data.video_quality', 'medium');
   

Performance Tips

• Pre-optimize Locally: Use tools like HandBrake to pre-optimize videos before upload to reduce server load.
• Cache Optimized Files: Store optimized files in a separate disk (e.g., optimized_videos) and cache their paths.
• Batch Processing: For bulk uploads, use chunked processing:

  foreach ($videos as $video) {
      OptimizeVideoJob::dispatch($video->path)->delay(now()->addMinutes(1));
  }