aminyazdanpanah / php-shaka
Shaka PHP is a library that uses Shaka Packager for DASH and HLS packaging and encryption, supporting Common Encryption for Widevine and other DRM Systems.
Requires
- php: ^7.2
- symfony/process: ^4.2|^5.0
Requires (Dev)
- phpunit/phpunit: 9.1.4
This package is auto-updated.
Last update: 2024-11-06 11:29:25 UTC
README
Shaka PHP is a library that uses Shaka Packager for DASH and HLS packaging and encryption, supporting Common Encryption for Widevine and other DRM Systems.
Contents
- Requirements
- Installation
- Usage
- Several Open Source Players
- Contributing and Reporting Bugs
- Credits
- License
Requirements
-
This version of the package is only compatible with PHP 7.2 or higher.
-
This library requires a working Shaka Packager binary. Be that the binary can be located with system PATH to auto get binary file in PHP. You can also give the binary path on load.
Getting Shaka Packager
There are several ways you can get Shaka Packager.
- Using Docker. Instructions are available at Using Docker.
- Get prebuilt binaries from release.
- Built from source, see Build Instructions for details.
For users who get prebuilt binary: Please rename packager-'OS'
to packager
and add the path of shaka packager to your system PATH.(e.g. 'packager-win.exe' to 'packager.exe')
Installation
Use Composer to install this library from Packagist:
Run the following command from your project directory to add the dependency:
composer require aminyazdanpanah/php-shaka
Alternatively, add the dependency directly to your composer.json
file:
"require": { "aminyazdanpanah/php-shaka": "^1.0" }
Usage
The best way to learn how to use this library is to review the examples and browse the source code as it is self-documented.
It is highly recommended to read Shaka Packager Documentation.
Basic Usage
Initializing
Shaka PHP auto-detect packager
binary. An associative array of config can also be passed to the initialize
method to give binary path and timout explicitly:
$config = [ 'packager.binaries' => 'path/to/packager/binary', 'timeout' => 3600 ]; $shaka = \Shaka\Shaka::initialize($config);
Streams
There can be multiple streams
with input from the same “file” or multiple different “files”.
$stream1 = \Shaka\Options\Streams\Stream::input('/the/path/to/the/file'); $stream2 = \Shaka\Options\Streams\Stream::input('/the/path/to/the/file'); //...
you can add options to your streams
$stream1->streamSelector('video') ->output('video.mp4');
Stream Options
Media File Analysis
It can be used to inspect the content of a media file and dump basic stream information:
$export = $shaka->streams($stream) ->mediaFileAnalysis() ->export();
The $export
is instance of StreamCollection
. For more information, please see examples.
Basic Transmuxing
It can be used to extract streams, optionally transmuxes the streams from one container format to another container format.
$stream1 = Stream::input('/the/path/to/the/file') ->streamSelector('video') ->output('video.mp4'); $stream2 = Stream::input('/the/path/to/the/file') ->streamSelector('audio') ->output('audio.mp4'); $export = $shaka->streams($stream1, $stream2) ->mediaPackaging() ->export();
Basic Usage Examples
Please see examples/Basic for details.
DASH
Dynamic Adaptive Streaming over HTTP (DASH) is an adaptive bitrate streaming technique that enables high quality streaming of media content over HTTP.
DASH Stream Options
Besides Stream Options and DRM Stream Options, you can add DASHRoles()
method to your DASHStream object. You can pass roles to the method. The roles can be separated by colon or semi-colon. The value should be one of: caption, subtitle, main, alternate, supplementary, commentary and dub. See DASH (ISO/IEC 23009-1) specification for details.
$stream1 = $stream1 = DASHStream::input('/the/path/to/the/file') //->other options
DASH Packaging
This library supports DASH content packaging.
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->DASH('output.mpd') ->export();
You can add options to your DASH object using a callback method:
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->DASH('output.mpd', function ($options) { return $options->generateStaticLiveMpd(); //->other options; }) ->export();
DASH Options
Also you can add some Chunking
and MP4 output
options to your DASH Object(before using these options, please read the Description
):
Chunking and MP4 Output Options
The implementation is based on Template-based Segment URL construction described in ISO/IEC 23009-1:2014.
Segment Template Formatting
- Note: Identifiers and are not supported in this version. Please file an issue if you want it to be supported.
DASH Examples
Please see examples/DASH for details.
HLS
HTTP Live Streaming (also known as HLS) is an HTTP-based media streaming communications protocol implemented by Apple Inc. as part of its QuickTime, Safari, OS X, and iOS software. It resembles MPEG-DASH in that it works by breaking the overall stream into a sequence of small HTTP-based file downloads, each download loading one short chunk of an overall potentially unbounded transport stream. As the stream is played, the client may select from a number of different alternate streams containing the same material encoded at a variety of data rates, allowing the streaming session to adapt to the available data rate. At the start of the streaming session, HLS downloads an extended M3U playlist containing the metadata for the various sub-streams which are available.
HLS Stream Options
Besides Stream Options and DRM Stream Options, you can add options below:
$stream1 = $stream1 = HLSStream::input('/the/path/to/the/file') //->other options
HLS Packaging
This library supports HLS content packaging.
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->HLS('output.m3u8') ->export();
You can add options to your HLS object using a callback method:
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->HLS('output.m3u8', function ($options) { return $options->HLSMasterPlaylistOutput(); //->other options; }) ->export();
HLS Options
Also you can add some Chunking and MP4 output options to your HLS Object(before using these options, please read the Description
).
-
Note: Also you can use Segment template formatting in your output.
-
Note: DASH and HLS options can both be specified to output DASH and HLS manifests at the same time. Note that it works only for MP4 outputs.
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->HLS('hls.m3u8') ->DASH('dash.mpd') ->export();
HLS Examples
Please see examples/HLS for details.
Live
A typical live source is UDP multicast, which is the only live protocol packager supports directly right now.
For other unsupported protocols, you can use FFmpeg to pipe the input. See FFmpeg piping for details.
UDP File Options
UDP file is of the form:
udp://<ip>:<port>[?<option>[&<option>]...]
Example:
udp://224.1.2.30:88?interface=10.11.12.13&reuse=1
HLS Examples
Please see examples/Live for details.
DRM
Shaka Packager supports fetching encryption keys from Widevine Key Server and PlayReady Key Server. Shaka Packager also supports Raw Keys, for which keys are provided to Shaka Packager directly.
Regardless of which key server you are using, you can instruct Shaka Packager to generate other protection systems in additional to the native protection system from the key server. This allows generating multi-DRM contents easily.
DRM Stream options
Besides Stream Options, you can add options below:
General encryption options
Widevine Key Server
The easiest way to generate Widevine protected content is to use Widevine Cloud Service.
Shaka Packager can talk to Widevine Cloud Service or any key server that implements Common Encryption API for Widevine DRM to fetch encryption keys.
Widevine Common Encryption API supports request validation using either AES or RSA.
Enable encryption with Widevine key server. User should provide either AES signing key (aesSigningKey()
, aesSigningIv()
) or RSA signing key (rsaSigningKeyPath()
).
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->DRM('widevine', function ($options) { return $options->keyServerUrl('https://license.uat.widevine.com/cenc/getcontentkey/widevine_test')** ->//other options }) ->HLS('hls.m3u8') ->DASH('dash.mpd') ->export();
Widevine Options
Besides General encryption options, you can add options below:
Widevine Examples
Please see examples/DRM/Widevine for details.
PlayReady Key Server
This library can talk to PlayReady Key Server that implements AcquirePackagingData Web Method specification to fetch encryption keys.
Refer to DRM if you are interested in generating multi-DRM contents.
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->DRM('playReady', function ($options) { return $options->playreadyServerUrl('http://playready.get.key') ->//other options }) ->HLS('hls.m3u8') ->DASH('dash.mpd') ->export();
PlayReady Options
Besides General encryption options, you can add options below:
Raw Key Server
This library supports raw keys, for which keys and key_ids are provided to Shaka Packager directly.
This is often used if you are managing the encryption keys yourself. It also allows you to support multi-DRM by providing custom PSSHs.
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->DRM('raw', function ($options) { return $options->keys('...keys') ->//other options }) ->HLS('hls.m3u8') ->DASH('dash.mpd') ->export();
Raw Options
Besides General encryption options, you can add options below:
pssh-box (Utility to generate PSSH boxes)
https://github.com/google/shaka-packager/tree/master/packager/tools/pssh
Raw Examples
Please see examples/DRM/Raw for details.
Ad Insertion
This package does not do Ad Insertion directly, but it can precondition content for Dynamic Ad Insertion with Google Ad Manager.
Both DASH and HLS are supported.
$export = $shaka->streams($stream1, $stream2, ...) ->mediaPackaging() ->HLS('hls.m3u8', function ($options) { return $options->adCues('600;1800;3000'); }) ->DASH('dash.mpd', function ($options) { return $options->adCues('600;1800;3000'); }) ->export();
Ad Insertion Examples
Please see examples/adInsertion for details.
Several Open Source Players
- DASH and HLS on Web: Shaka Player
- DASH on Web: dash.js
- HLS on Web: hls.js
- DASH and HLS on Android: ExoPlayer
Contributing and Reporting Bugs
I'd love your help in improving, correcting, adding to the specification. Please file an issue or submit a pull request.
- Please see Contributing File for more information.
- If you have any questions or you want to report a bug, please just file an issue
- If you discover a security vulnerability within this package, please see SECURITY File for more information to help with that.
NOTE: If you have any questions about this package or Shaka Packager, please DO NOT send an email to me(or submit the contact form on my website). Emails relate to these issues will be ignored.
Credits
License
The MIT License (MIT). Please see License File for more information.