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
AES Encryption - Encryption with key rotation
Architecture Overview - Understanding the design
Configuration - Configuring the package

Requirements

PHP 8.3 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"

Installing Shaka Packager

Install Shaka Packager binary on your system. Visit the Shaka Packager releases page for installation instructions.

Verify Installation

After installation, verify that Shaka Packager is properly configured:

php artisan shaka: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 shaka:info

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

// Basic encryption with auto-generated AES-128 key
Shaka::open('input.mp4')
    ->addVideoStream('input.mp4', 'video.mp4')
    ->addAudioStream('input.mp4', 'audio.mp4')
    ->withHlsMasterPlaylist('master.m3u8')
    ->withAESEncryption()  // Auto-generates key with 'cbc1' scheme
    ->export()
    ->save();

// With key rotation (generates key_0.key, key_1.key, etc.)
Shaka::open('input.mp4')
    ->addVideoStream('input.mp4', 'video.mp4')
    ->addAudioStream('input.mp4', 'audio.mp4')
    ->withHlsMasterPlaylist('master.m3u8')
    ->withAESEncryption()
    ->withKeyRotationDuration(60)  // Rotate every 60 seconds
    ->export()
    ->toDisk('s3')
    ->save();

See AES Encryption Guide for complete documentation.

Dynamic URL Resolvers (HLS & DASH)

Serve encrypted streaming content with S3 signed URLs:

HLS Example:

use Foxws\Shaka\Http\DynamicHLSPlaylist;
use Illuminate\Support\Facades\Storage;

public function playlist(Video $video)
{
    return (new DynamicHLSPlaylist('s3'))
        ->open("videos/{$video->id}/master.m3u8")
        ->setKeyUrlResolver(fn ($key) => Storage::disk('s3')->temporaryUrl(
            "videos/{$video->id}/{$key}",
            now()->addHour()
        ))
        ->setMediaUrlResolver(fn ($file) => Storage::disk('s3')->temporaryUrl(
            "videos/{$video->id}/{$file}",
            now()->addHours(2)
        ))
        ->toResponse(request());
}

DASH Example:

use Foxws\Shaka\Http\DynamicDASHManifest;
use Illuminate\Support\Facades\Storage;

public function manifest(Video $video)
{
    return (new DynamicDASHManifest('s3'))
        ->open("videos/{$video->id}/manifest.mpd")
        ->setKeyUrlResolver(fn ($key) => Storage::disk('s3')->temporaryUrl(
            "videos/{$video->id}/{$key}",
            now()->addHour()
        ))
        ->setMediaUrlResolver(fn ($file) => Storage::disk('s3')->temporaryUrl(
            "videos/{$video->id}/{$file}",
            now()->addHours(2)
        ))
        ->setInitUrlResolver(fn ($file) => Storage::disk('s3')->temporaryUrl(
            "videos/{$video->id}/{$file}",
            now()->addHours(2)
        ))
        ->toResponse(request());
}

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
withAESEncryption(string $keyFilename = 'key', ?string $protectionScheme = 'cbc1', ?string $label = null) - Enable AES-128 encryption
withKeyRotationDuration(int $seconds) - Enable key rotation for 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.

foxws / laravel-shaka

Maintainers

Details