README

A Laravel integration for Google's Shaka Packager, enabling you to create adaptive streaming content (HLS, DASH) with a fluent, Laravel-style API.

use Foxws\Shaka\Facades\Shaka;

$result = Shaka::fromDisk('s3')
    ->open('videos/input.mp4')
    ->addVideoStream('videos/input.mp4', 'video_1080p.mp4', ['bandwidth' => '5000000'])
    ->addVideoStream('videos/input.mp4', 'video_720p.mp4', ['bandwidth' => '3000000'])
    ->addAudioStream('videos/input.mp4', 'audio.mp4')
    ->withHlsMasterPlaylist('master.m3u8')
    ->withSegmentDuration(6)
    ->export()
    ->toDisk('export')
    ->save();

Features

• 🎬 Fluent API - Laravel-style chainable methods
• 📁 Multiple Disks - Works with local, S3, and custom filesystems
• 🎯 Adaptive Bitrate - Create multi-quality streams easily
• 🔒 Encryption & DRM - Built-in support for content protection
• 📺 HLS & DASH - Support for both streaming protocols
• 🧪 Testable - Clean architecture with mockable components
• 📝 Type-Safe - Full PHP 8.1+ type declarations

Documentation

📚 Full Documentation

• Quick Reference - Complete API reference
• Architecture Overview - Understanding the design
• Configuration - Configuring the package

Requirements

• PHP 8.1 or higher
• Laravel 11.x or higher
• Shaka Packager binary installed on your system or Docker container

Installation

Install the package via composer:

composer require foxws/laravel-shaka

Publish the config file:

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

Quick Start

Basic Usage

use Foxws\Shaka\Facades\Shaka;

$result = Shaka::open('input.mp4')
    ->addVideoStream('input.mp4', 'video.mp4')
    ->addAudioStream('input.mp4', 'audio.mp4')
    ->withHlsMasterPlaylist('master.m3u8')
    ->export()
    ->save();

Adaptive Bitrate Streaming

$result = Shaka::open('input.mp4')
    ->addVideoStream('input.mp4', 'video_1080p.mp4', ['bandwidth' => '5000000'])
    ->addVideoStream('input.mp4', 'video_720p.mp4', ['bandwidth' => '3000000'])
    ->addVideoStream('input.mp4', 'video_480p.mp4', ['bandwidth' => '1500000'])
    ->addAudioStream('input.mp4', 'audio.mp4')
    ->withHlsMasterPlaylist('master.m3u8')
    ->withSegmentDuration(6)
    ->export()
    ->save();

Working with Different Disks

$result = Shaka::fromDisk('s3')
    ->open('videos/input.mp4')
    ->addVideoStream('videos/input.mp4', 'video.mp4')
    ->addAudioStream('videos/input.mp4', 'audio.mp4')
    ->withHlsMasterPlaylist('master.m3u8')
    ->export()
    ->toDisk('export') // Save output to a different disk (e.g., local, s3, etc.)
    ->toPath('exports/') // (Optional) Save to a subdirectory on the target disk
    ->save();

HLS with Encryption

// For browser-compatible AES-128-CBC encryption, use .ts segments and 'cbc1' protection scheme
// Without protection_scheme, Shaka uses SAMPLE-AES which only works on native iOS/tvOS
$result = Shaka::open('input.mp4')
    ->addVideoStream('input.mp4', 'video.ts')  // Use .ts for encryption compatibility
    ->addAudioStream('input.mp4', 'audio.ts')  // Use .ts for encryption compatibility
    ->withHlsMasterPlaylist('master.m3u8')
    ->withEncryption([
        'keys' => 'label=:key_id=abc:key=def',
        'hls_key_uri' => 'encryption.key',
        'protection_scheme' => 'cbc1',  // Use 'cbc1' for browser-compatible AES-128-CBC
        'clear_lead' => 0,  // Encrypt all segments from the start (default is 5 seconds unencrypted)
    ])
    ->export()
    ->save();

// For unencrypted streams, .mp4 (fMP4) offers better performance
$result = Shaka::open('input.mp4')
    ->addVideoStream('input.mp4', 'video.mp4')  // .mp4 OK without encryption
    ->addAudioStream('input.mp4', 'audio.mp4')
    ->withHlsMasterPlaylist('master.m3u8')
    ->export()
    ->save();

Dynamic URL Resolvers (HLS & DASH)

Customize how URLs are generated for your streaming manifests:

HLS Example:

use Foxws\Shaka\Http\DynamicHLSPlaylist;

return (new DynamicHLSPlaylist('videos'))
    ->open('master.m3u8')
    ->setKeyUrlResolver(fn ($key) => route('video.key', ['key' => $key]))
    ->setMediaUrlResolver(fn ($file) => Storage::disk('cdn')->url($file))
    ->setPlaylistUrlResolver(fn ($playlist) => route('video.playlist', ['playlist' => $playlist]));

DASH Example:

use Foxws\Shaka\Http\DynamicDASHManifest;

return (new DynamicDASHManifest('videos'))
    ->open('manifest.mpd')
    ->setMediaUrlResolver(fn ($file) => Storage::disk('cdn')->url($file))
    ->setInitUrlResolver(fn ($file) => Storage::disk('cdn')->url("init/{$file}"));

Use cases for URL resolvers:

• 🔐 Generate signed URLs for secure content delivery
• 🌐 Integrate with CDN services
• 🏢 Support multi-tenant applications
• 🔄 Implement dynamic key rotation
• 📊 Track media access patterns

See URL Resolver Examples and Documentation for more details.

Available Methods

Disk Management

• fromDisk(string $disk) - Set the disk to use
• openFromDisk(string $disk, $paths) - Set disk and open files in one call
• getDisk() - Get the current disk instance

Media Management

• open($paths) - Open one or more media files
• get() - Get the MediaCollection
• streams() - Get auto-generated Stream objects

Stream Configuration

• addVideoStream(string $input, string $output, array $options = []) - Add video stream
• addAudioStream(string $input, string $output, array $options = []) - Add audio stream
• addTextStream(string $input, string $output, array $options = []) - Add text/caption/subtitle stream
• addStream(array $stream) - Add custom stream

Output Configuration

• withHlsMasterPlaylist(string $path) - Set HLS master playlist output
• withMpdOutput(string $path) - Set DASH manifest output
• withSegmentDuration(int $seconds) - Set segment duration
• withEncryption(array $config) - Enable encryption
• toDisk(string $disk) - Set the target disk for output
• toPath(string $path) - Set the target output path (subdirectory)
• withVisibility(string $visibility) - Set file visibility (e.g., 'public', 'private')

Execution & Utilities

• export() - Execute the packaging operation (returns result object)
• save(?string $path = null) - Save outputs to disk (optionally to a specific path)
• getCommand() - Get the final command string (for debugging)
• dd() - Dump the final command and end the script
• afterSaving(callable $callback) - Register a callback to run after saving

Dynamic URL Resolvers

DynamicHLSPlaylist:

• new DynamicHLSPlaylist(?string $disk) - Create HLS playlist processor
• open(string $path) - Open a playlist file
• setKeyUrlResolver(callable $resolver) - Set resolver for encryption key URLs
• setMediaUrlResolver(callable $resolver) - Set resolver for media segment URLs
• setPlaylistUrlResolver(callable $resolver) - Set resolver for sub-playlist URLs
• get() - Get processed playlist content
• all() - Get all processed playlists (master + segments)
• toResponse($request) - Return as HTTP response

DynamicDASHManifest:

• new DynamicDASHManifest(?string $disk) - Create DASH manifest processor
• open(string $path) - Open a manifest file
• setMediaUrlResolver(callable $resolver) - Set resolver for media segment URLs
• setInitUrlResolver(callable $resolver) - Set resolver for initialization segment URLs
• get() - Get processed manifest content
• toResponse($request) - Return as HTTP response

See the Quick Reference for complete API documentation.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover a security vulnerability, please report it via a private channel (e.g., email or GitHub issues) rather than publicly disclosing it.

Acknowledgments

This package was inspired by and learned from:

• Laravel FFmpeg - Architecture patterns and Laravel integration approach.
• quasarstream/shaka-php - Shaka Packager wrapper implementation and command building logic.

Much of the existing logic and design patterns from these excellent packages helped shape this implementation. Many thanks to their authors and contributors!

Projects Built on Laravel Shaka Packager

• Stry - A modern streaming platform built on top of Laravel Shaka Packager.

License

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