Skip to main content

Quick Reference

Fluent API with fromDisk support​

Basic usage​

use Foxws\Shaka\Facades\Shaka;

// Default disk
$result = Shaka::open('input.mp4')
    ->addVideoStream('input.mp4', 'video.mp4')
    ->addAudioStream('input.mp4', 'audio.mp4')
    ->withMpdOutput('manifest.mpd')
    ->export();

Using different disks​

// From S3, save to a different disk (e.g., local, s3, etc.)
$result = Shaka::fromDisk('s3')
    ->open('videos/input.mp4')
    ->addVideoStream('videos/input.mp4', 'video.mp4')
    ->withMpdOutput('manifest.mpd')
    ->export()
    ->toDisk('export')
    ->save();

// Helper method
$result = Shaka::openFromDisk('s3', 'videos/input.mp4')
    ->addVideoStream('videos/input.mp4', 'video.mp4')
    ->export()
    ->toDisk('export')
    ->save();

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 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(Stream|array $stream) - Add custom stream with full control

Output configuration​

  • withMpdOutput(string $path) - Set DASH manifest output
  • withBaseUrls(string|array $urls) - Set DASH <BaseURL> element(s) under <MPD>
  • withHlsMasterPlaylist(string $path) - Set HLS master playlist output
  • withSegmentDuration(int $seconds) - Set segment duration
  • withAESEncryption(string $keyFilename = 'key', ProtectionScheme|string|null $protectionScheme = 'cbc1', ?string $label = null): EncryptionKey - Enable AES-128 encryption (does not return $this — breaks the fluent chain)
  • 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 URL Resolvers for full documentation of both classes.

Common patterns​

Adding captions/subtitles (WebVTT)​

Shaka::fromDisk('s3')
    ->open('videos/source.mp4')
    ->addVideoStream('videos/source.mp4', 'video_1080p.mp4', [
        'bandwidth' => '5000000',
    ])
    ->addAudioStream('videos/source.mp4', 'audio.mp4')
    ->addTextStream('captions/english.vtt', 'english.vtt', [
        'language' => 'en',
    ])
    ->withMpdOutput('manifest.mpd')
    ->withSegmentDuration(6)
    ->export();

Adaptive bitrate streaming​

Shaka::fromDisk('s3')
    ->open('videos/source.mp4')
    ->addVideoStream('videos/source.mp4', 'video_1080p.mp4', [
        'bandwidth' => '5000000',
    ])
    ->addVideoStream('videos/source.mp4', 'video_720p.mp4', [
        'bandwidth' => '3000000',
    ])
    ->addVideoStream('videos/source.mp4', 'video_480p.mp4', [
        'bandwidth' => '1500000',
    ])
    ->addAudioStream('videos/source.mp4', 'audio.mp4')
    ->withMpdOutput('manifest.mpd')
    ->withSegmentDuration(6)
    ->export();

HLS with encryption​

Shaka::fromDisk('s3')
    ->open('secure/video.mp4')
    ->addVideoStream('secure/video.mp4', 'video.m3u8')
    ->addAudioStream('secure/video.mp4', 'audio.m3u8')
    ->withHlsMasterPlaylist('master.m3u8')
    ->withEncryption([
        'keys' => 'label=:key_id=abc:key=def',
        'key_server_url' => 'https://example.com/license',
    ])
    ->export();

See AES Encryption for the recommended withAESEncryption() API.

Multiple files​

Shaka::fromDisk('videos')
    ->open(['intro.mp4', 'main.mp4', 'outro.mp4'])
    ->addVideoStream('intro.mp4', 'intro_video.mp4')
    ->addVideoStream('main.mp4', 'main_video.mp4')
    ->addVideoStream('outro.mp4', 'outro_video.mp4')
    ->withMpdOutput('manifest.mpd')
    ->export();

Error handling​

try {
    $result = Shaka::fromDisk('s3')
        ->open('video.mp4')
        ->addVideoStream('video.mp4', 'output.mp4')
        ->withMpdOutput('manifest.mpd')
        ->export();

    logger()->info('Success', $result->getOutput());
} catch (\Foxws\Shaka\Exceptions\RuntimeException $e) {
    logger()->error('Packaging failed', ['error' => $e->getMessage()]);
} catch (\InvalidArgumentException $e) {
    logger()->error('Invalid input', ['error' => $e->getMessage()]);
}

Configuration​

config/laravel-shaka.php​

return [
    'packager' => [
        'binaries' => env('PACKAGER_PATH', '/usr/local/bin/packager'),
    ],
    'timeout' => 60 * 60 * 4, // 4 hours
    'log_channel' => env('PACKAGER_LOG_CHANNEL', false),
    'temporary_files_root' => env('PACKAGER_TEMPORARY_FILES_ROOT', storage_path('app/packager/temp')),
    'concurrency_workers' => env('PACKAGER_CONCURRENCY_WORKERS', 30), // Max concurrent S3 uploads (default: 30)
];

concurrency_workers

  • Maximum number of concurrent S3 uploads when copying packaged files to an S3-backed disk.
  • Ignored for local disks.
  • Default: 30
  • Raise further only after measuring: this bounds an async promise pool (GuzzleHttp\Promise\EachPromise), so throughput scales with concurrency until you saturate the destination's write throughput or the local disk read I/O for segment files. Against a local/self-hosted S3-compatible store (low latency, high bandwidth) higher values pay off faster than against real AWS S3 over the WAN — but there's no universally correct number, watch upload duration and destination-side load before pushing past 30-50.

See the full Configuration page for every available option.

Artisan commands​

# Verify packager installation
php artisan shaka:info

Direct driver usage​

use Foxws\Shaka\Support\Packager\ShakaPackager;

$driver = ShakaPackager::create();
$version = $driver->getVersion();
$driver->setTimeout(7200);

CommandBuilder direct usage​

use Foxws\Shaka\Support\Packager\CommandBuilder;
use Foxws\Shaka\Support\Packager\Packager;

$builder = CommandBuilder::make()
    ->addVideoStream('input.mp4', 'output.mp4')
    ->withMpdOutput('manifest.mpd');

$packager = app(Packager::class);
$result = $packager->packageWithBuilder($builder);

Stream objects​

use Foxws\Shaka\Support\Packager\Stream;
use Foxws\Shaka\Support\Filesystem\Media;

$media = Media::make('videos', 'input.mp4');

$videoStream = Stream::video($media)
    ->setOutput('video.mp4')
    ->addOption('bandwidth', '5000000');

$audioStream = Stream::audio($media)
    ->setOutput('audio.mp4');

$commandString = $videoStream->toCommandString();

Examples location​

  • Basic examples: examples/PackagerExamples.php
  • Fluent API examples: examples/FluentBuilderExamples.php
  • fromDisk examples: examples/FromDiskExamples.php

Testing​

// Unit tests
vendor/bin/pest tests/Unit/ShakaPackagerTest.php
vendor/bin/pest tests/Unit/PackagerTest.php
vendor/bin/pest tests/Unit/FromDiskTest.php