Quick Start

Last updated: April 8th, 2020

What is the PHP FFmpeg Video Streaming?

This library is a wrapper around PHP-FFMpeg and packages media content for online streaming such as DASH and HLS. You can also use DRM for HLS packaging. There are several options to open a file from clouds and save files to them as well.

Github Repository: https://github.com/aminyazdanpanah/PHP-FFmpeg-video-streaming

Bug Tracker and Issues: https://github.com/aminyazdanpanah/PHP-FFmpeg-video-streaming/issues

Installation

Step One: Requirement

    • FFMpeg

    • This Library requires a working FFmpeg. You will need both FFMpeg and FFProbe binaries to use it.

      Getting FFMpeg

      Useful Tip For Windows Users:

      For binary detection, you need to add FFmpeg and FFprobe paths to your system path

Step Two: Installing the Package

This version of the package is only compatible with PHP 7.2 or higher.

Install the package via composer:

composer require aminyazdanpanah/php-ffmpeg-video-streaming

Alternatively, add the dependency directly to your composer.json file:

"require": {
    "aminyazdanpanah/php-ffmpeg-video-streaming": "^1.2"
}

Usage

First of all, you need to include the package in your code:

require 'vendor/autoload.php'; // path to the autoload file

NOTE:

If you are using such a framework(e.g. Laravel) that includes the autoload automatically, then you can skip this step.

Configuration

This package will autodetect FFmpeg and FFprobe binaries. If you want to give binary paths explicitly, you can pass an array as configuration. A Psr\Logger\LoggerInterface can also be passed to log binary executions.

use Monolog\Handler\StreamHandler;
use Monolog\Logger;

use Streaming\FFMpeg;

$config = [
    'ffmpeg.binaries'  => '/usr/bin/ffmpeg',
    'ffprobe.binaries' => '/usr/bin/ffprobe',
    'timeout'          => 3600, // The timeout for the underlying process
    'ffmpeg.threads'   => 12,   // The number of threads that FFmpeg should use
];

$log = new Logger('FFmpeg_Streaming');
$log->pushHandler(new StreamHandler('/var/log/ffmpeg-streaming.log')); // path to log file
    
$ffmpeg = FFMpeg::create($config, $log);

Opening a Resource

There are several ways to open a resource.

1. From a FFmpeg supported resource

You can pass a local path of video(or a supported resource) to the open method:

$video = $ffmpeg->open('/var/media/video.mp4');

See FFmpeg Protocols Documentation for more information about supported resources such as http, ftp, and etc.

For example:

$video = $ffmpeg->open('https://www.aminyazdanpanah.com/?"PATH TO A VIDEO FILE" or "PATH TO A LIVE HTTP STREAM"');
2. From a Cloud

You can open a file from a cloud by passing an array of cloud configuration to the openFromCloud method.

$video = $ffmpeg->openFromCloud($from_google_cloud);

Visit this page to see some examples of opening a file from Amazon S3, Google Cloud Storage, Microsoft Azure Storage, and a custom cloud.

3. Capture Webcam or Screen (Live Streaming)

You can pass a name of the supported, connected capture device(i.e. a name of webcam, camera, screen and etc) to the `capture` method to stream a live media over network from your connected device.

$capture = $ffmpeg->capture("CAMERA NAME OR SCREEN NAME");

NOTE:

To list the supported, connected capture devices, see FFmpeg Capture Webcam and FFmpeg Capture Desktop

DASH

Dynamic Adaptive Streaming over HTTP (DASH), also known as MPEG-DASH, is an adaptive bitrate streaming technique that enables high quality streaming of media content over the Internet delivered from conventional HTTP web servers. Similar to Apple's HTTP Live Streaming (HLS) solution, MPEG-DASH works by breaking the content into a sequence of small HTTP-based file segments, each segment containing a short interval of playback time of content that is potentially many hours in duration, such as a movie or the live broadcast of a sports event. The content is made available at a variety of different bit rates, i.e., alternative segments encoded at different bit rates covering aligned short intervals of playback time. While the content is being played back by an MPEG-DASH client, the client uses a bit rate adaptation (ABR) algorithm to automatically select the segment with the highest bit rate possible that can be downloaded in time for playback without causing stalls or re-buffering events in the playback. The current MPEG-DASH reference client dash.js offers both buffer-based (BOLA) and hybrid (DYNAMIC) bit rate adaptation algorithms. Thus, an MPEG-DASH client can seamlessly adapt to changing network conditions and provide high quality playback with fewer stalls or re-buffering events.

MPEG-DASH is the first adaptive bit-rate HTTP-based streaming solution that is an international standard. MPEG-DASH should not be confused with a transport protocol — the transport protocol that MPEG-DASH uses is TCP. MPEG-DASH uses existing HTTP web server infrastructure that is used for delivery of essentially all World Wide Web content. It allows devices like Internet-connected televisions, TV set-top boxes, desktop computers, smartphones, tablets, etc. to consume multimedia content (video, TV, radio, etc.) delivered via the Internet, coping with variable Internet receiving conditions. Standardizing an adaptive streaming solution is meant to provide confidence to the market that the solution can be adopted for universal deployment, compared to similar but more proprietary solutions like Smooth Streaming by Microsoft, or HDS by Adobe. Unlike HLS, HDS, or Smooth Streaming, DASH is codec-agnostic, which means it can use content encoded with any coding format, such as H.265, H.264, VP9, etc. Learn more

Create DASH files:

It creates a MPD manifest file and segment files for streams automatically.

$video->dash()
    ->setAdaption('id=0,streams=v id=1,streams=a') // Set the adaption.
    ->x264() // Format of the video. Alternatives: x264() and vp9()
    ->autoGenerateRepresentations() // Auto generate representations
    ->save(); // It can be passed a path to the method or it can be null
Generate representations manually:

Specify the value of kilo bite rate and size for each stream explicitly.

use Streaming\Representation;

$r_144p  = (new Representation)->setKiloBitrate(95)->setResize(256, 144);
$r_240p  = (new Representation)->setKiloBitrate(150)->setResize(426, 240);
$r_360p  = (new Representation)->setKiloBitrate(276)->setResize(640, 360);
$r_480p  = (new Representation)->setKiloBitrate(750)->setResize(854, 480);
$r_720p  = (new Representation)->setKiloBitrate(2048)->setResize(1280, 720);
$r_1080p = (new Representation)->setKiloBitrate(4096)->setResize(1920, 1080);
$r_2k    = (new Representation)->setKiloBitrate(6144)->setResize(2560, 1440);
$r_4k    = (new Representation)->setKiloBitrate(17408)->setResize(3840, 2160);

$video->dash()
    ->setSegDuration(30) // Default value is 10 
    ->setAdaption('id=0,streams=v id=1,streams=a')
    ->x264()
    ->addRepresentations([$r_144p, $r_240p, $r_360p, $r_480p, $r_720p, $r_1080p, $r_2k, $r_4k])
    ->save('/var/media/dash-stream.mpd');
Generate HLS Playlist(DASH and HLS):

Publish master playlist repeatedly every after specified number of segment intervals.

$video->dash()
    ->generateHlsPlaylist()
    ->setAdaption('id=0,streams=v id=1,streams=a')
    ->x264()
    ->autoGenerateRepresentations()
    ->save();
DASH from Camera/Screen:

You can go on live video streaming using a supported, connected capture devices such as a camera/webcam or screen. This uses the camera on your local machine not a webcam from the web.

use Streaming\Representation;

$r_240p  = (new Representation)->setKiloBitrate(150)->setResize(426, 240);
$r_360p  = (new Representation)->setKiloBitrate(276)->setResize(640, 360);

$capture->dash()
    ->setAdaption('id=0,streams=v id=1,streams=a')
    ->x264()
    ->addRepresentations([$r_240p, $r_360p])
    ->save('/var/media/dash-stream.mpd');

NOTE:

You cannot use the "autoGenerateRepresentations()" method for opening from camera

NOTE:

See DASH options and DASH documentation for more information.

HLS

HTTP Live Streaming (also known as HLS) is an HTTP-based adaptive bitrate streaming communications protocol implemented by Apple Inc. as part of its QuickTime, Safari, OS X, and iOS software. Client implementations are also available in Microsoft Edge, Firefox and some versions of Google Chrome. Support is widespread in streaming media servers.

HLS 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. A list of available streams, encoded at different bit rates, is sent to the client using an extended M3U playlist.

Based on standard HTTP transactions, HTTP Live Streaming can traverse any firewall or proxy server that lets through standard HTTP traffic, unlike UDP-based protocols such as RTP. This also allows content to be offered from conventional HTTP servers and delivered over widely available HTTP-based content delivery networks. The standard also includes a standard encryption mechanism and secure-key distribution using HTTPS, which together provide a simple DRM system. Later versions of the protocol also provide for trick-mode fast-forward and rewind and for integration of subtitles.

Apple has documented HTTP Live Streaming as an Internet Draft (Individual Submission), the first stage in the process of publishing it as a Request for Comments (RFC). As of December 2015, the authors of that document have requested the RFC Independent Stream Editor (ISE) to publish the document as an informational (non-standard) RFC outside of the IETF consensus process. In August 2017, RFC8216 was published to describe version 7 of the protocol. Learn more

Create HLS files

It creates a playlist file, and one or more segment files automatically. The output filename specifies the playlist filename.

$video->hls()
    ->x264()
    ->autoGenerateRepresentations([720, 360]) // You can limit the numbers of representatons
    ->save();
Generate representations manually:

Specify the value of kilo bite rate and size for each stream explicitly.

use Streaming\Representation;

$r_360p  = (new Representation)->setKiloBitrate(276)->setResize(640, 360);
$r_480p  = (new Representation)->setKiloBitrate(750)->setResize(854, 480);
$r_720p  = (new Representation)->setKiloBitrate(2048)->setResize(1280, 720);

$video->hls()
    ->setHlsBaseUrl('https://bucket.s3-us-west-1.amazonaws.com/videos') // Add a base URL
    ->setHlsTime(5) // Set Hls Time. Default value is 10 
    ->setHlsAllowCache(false) // Default value is true 
    ->x264()
    ->addRepresentations([$r_360p, $r_480p, $r_720p])
    ->save();
Fragmented Mp4:

Output segment files in fragmented MP4 format, similar to MPEG-DASH. fmp4 files may be used in HLS version 7 and above.

$video->hls()
    ->fragmentedMP4()
    ->x264()
    ->autoGenerateRepresentations([720, 360]) // You can limit the numbers of representatons
    ->save();
HLS Live Streaming from Camera/Screen:

You can go on live video streaming using a supported, connected capture devices such as a camera/webcam or screen. This uses the camera on your local machine not a webcam from the web.

use Streaming\Representation;

$r_480p  = (new Representation)->setKiloBitrate(750)->setResize(854, 480);

$capture->hls()
    ->setHlsListSize(10) // Delete this line if you want to save video after live streaming
    ->setFlags([\Streaming\HLSFlag::DELETE_SEGMENTS]) // Delete this line if you want to save video after live streaming
    ->x264()
    ->addRepresentation($r_480p)
    ->save('/var/media/hls-stream.mpd');

NOTE:

You cannot use the "autoGenerateRepresentations()" method for opening a media from the camera

NOTE:

You cannot use HEVC and VP9 formats for HLS packaging except you are using HLS in fragmented MP4 format, then you can only use the HEVC format.

NOTE:

See HLS options and HLS documentation for more information.

Encryption(DRM)

The encryption process requires some kind of secret (key) together with an encryption algorithm. HLS uses AES in cipher block chaining (CBC) mode. This means each block is encrypted using the ciphertext of the preceding block. Learn more

You must specify a path to save a random key to your local machine and also specify a URL(or a path) to access the key on your website(the key you will save must be accessible from your website). You must pass both these parameters to the encryption method:

Single Key

The following code generates a key for all segment files.

//A path you want to save a random key to your local machine
$save_to = '/home/public_html/PATH_TO_KEY_DIRECTORY/key';

//A URL (or a path) to access the key on your website
$url = 'https://www.aminyazdanpanah.com/?PATH_TO_KEY_DIRECTORY/key';
// or $url = '/PATH_TO_KEY_DIRECTORY/random_key.key';

$video->hls()
    ->encryption($save_to, $url)
    ->x264()
    ->autoGenerateRepresentations([1080, 480, 240])
    ->save('/var/media/hls-stream.m3u8');


Key Rotation

An integer as a "key rotation period" can also be passed to the encryption method (i.e. encryption($save_to, $url, 10)) to use a different key for each set of segments, rotating to a new key after this many segments. For example, if 10 segment files have been generated then it will generate a new key. If you set this value to 1, each segment file will be encrypted with a new encryption key. This can improve security and allows for more flexibility.

//A path you want to save a random key to your local machine
$save_to = '/home/public_html/PATH_TO_KEY_DIRECTORY/key';

//A URL (or a path) to access the key on your website
$url = 'https://www.aminyazdanpanah.com/?PATH_TO_KEY_DIRECTORY/key';
// or $url = '/PATH_TO_KEY_DIRECTORY/random_key.key';

$video->hls()
    ->encryption($save_to, $url, 10)
    ->x264()
    ->autoGenerateRepresentations([720, 240])
    ->save('/var/media/hls-stream.m3u8');


DRM

However FFmpeg supports AES encryption for HLS packaging, which you can encrypt your streams, it is not a full DRM solution. If you want to use a full DRM solution, I recommend trying FairPlay Streaming solution which then securely exchange keys, and protect playback on devices.

Apple’s FairPlay is a recommended DRM system, but you can use other DRM systems such as Microsoft's PlayReady and Google’s Widevine.

IMPORTANT:

It is very important to protect your key(s) on your website. For example, you can use a token(using a Get or Post HTTP method) to check if the user is eligible to access to the key or not. You can also use a session(or cookie) on your website to restrict access to the key(s)(It is highly recommended).

Transcoding

A format can also extend FFMpeg\Format\ProgressableInterface to get realtime information about the transcoding.

$format = new Streaming\Format\X264();
$start_time = 0;

$percentage_to_time_left = function ($percentage) use (&$start_time) {
    if($start_time === 0){
        $start_time = time();
        return "Calculating...";
    }

    $diff_time = time() - $start_time;
    $seconds_left = 100 * $diff_time / $percentage - $diff_time;

    return gmdate("H:i:s", $seconds_left);
};
$format->on('progress', function ($video, $format, $percentage) use($percentage_to_time_left) {
    // You can update a field in your database or can log it to a file
    // You can also create a socket connection and show a progress bar to users
    echo sprintf("\rTranscoding...(%s%%) %s [%s%s]", $percentage, $percentage_to_time_left($percentage), str_repeat('#', $percentage), str_repeat('-', (100 - $percentage)));
});

$video->dash()
    ->setFormat($format)
    ->autoGenerateRepresentations()
    ->setAdaption('id=0,streams=v id=1,streams=a')
    ->save();

HLS Transcoding:

$format = new Streaming\Format\X264();
$format->on('progress', function ($video, $format, $percentage){
        echo sprintf("\r Transcoding... (%s%%)[%s%s]", $percentage, str_repeat('#', $percentage), str_repeat('-', (100 - $percentage)));
});

$video->hls()
    ->setFormat($format)
    ->autoGenerateRepresentations([240, 144]) 
    ->save('/var/media/dash/test.m3u8');
Output From a Terminal:

NOTE:

See Formats for more information.

Saving Files

There are several options to save files.

1. To a Local Path

You can pass a local path to the `save` method. If there is no directory, then the package will create it.

$dash = $video->dash()
            ->x264()
            ->autoGenerateRepresentations()
            ->setAdaption('id=0,streams=v id=1,streams=a');
            
$dash->save('/var/media/dash/test.mpd');

It can also be null. The default path to save files is the input directory.

$hls = $video->hls()
            ->x264()
            ->autoGenerateRepresentations();
            
$hls->save();

NOTE:

If you open a file from a cloud and do not pass a path to save the file to your local machine, you will have to pass a local path to the "save" method.

2. To a Cloud:

You can save your files to a cloud by passing an array of cloud configuration to the save method.

$dash->save(null, [$to_aws_cloud, $to_google_cloud, $to_microsoft_azure, $to_custom_cloud]);

Visit this page to see some examples of saving files to Amazon S3, Google Cloud Storage, Microsoft Azure Storage, and a custom cloud.

A path can also be passed to save a copy of files to your local machine.

$hls->save('/var/media/hls.m3u8', [$to_google_cloud, $to_custom_cloud]);

NOTE:

This option is only valid for VOD (it does not support live streaming).

Schema:

The relation is one-to-many

3. To a Server Instantly

You can pass a url to live method to upload all the segments files to the HTTP server using the HTTP PUT method, and update the manifest files every refresh times.

// DASH
$dash->live('http://YOUR-WEBSITE.COM/live-stream/out.mpd');

// HLS
$hls
    ->setMasterPlaylist('/var/media/live-master-manifest.m3u8')
    ->live('http://YOUR-WEBSITE.COM/live-stream/out.m3u8');

NOTE:

In the HLS method, you must upload the master playlist to the server manually. (Upload the /var/media/live-master-manifest.m3u8 file to the http://YOUR-WEBSITE.COM)

Metadata Extraction

You can get information from multimedia streams and the video file using the following code.

$hls = $hls->save();

$metadata = $hls->metadata();

print_r($metadata->get()); // print an array
$metadata->saveAsJson('path/to/meta.json'); // save metadata as a json file

var_dump($metadata->getVideoStreams()); // FFMpeg\FFProbe\DataMapping\StreamCollection object
var_dump($metadata->getFormat()); // FFMpeg\FFProbe\DataMapping\Format object
echo gmdate("H:i:s", intval($metadata->getFormat()->get('duration'))); // get the duration of the video (i.e. "01:34:26")

print_r($metadata->export()); // print and save metadata

Output:

Array
(
    [video] => Array
        (
            [format] => Array
                (
                    ...
                )

            [streams] => Array
                (
                    ...
                )

        )

    [streams] => Array
        (
            ...
        )

    [filename] => path/to/meta.json
)

Conversion

You can convert your stream to a file or to another stream protocols. You should pass a link of master playlist to the open method:

1. HLS To DASH
$stream = $ffmpeg->open('https://www.aminyazdanpanah.com/PATH/TO/HLS-MANIFEST.M3U8');

$stream->dash()
    ->x264()
    ->addRepresentations([$r_360p, $r_480p]) 
    ->save('/var/media/dash-stream.mpd');
2. DASH To HLS
$stream = $ffmpeg->open('https://www.aminyazdanpanah.com/PATH/TO/DASH-MANIFEST.MPD');

$stream->hls()
           ->x264()
           ->autoGenerateRepresentations([720, 360])
           ->save('/var/media/hls-stream.m3u8');
3. Stream(DASH or HLS) To File:
$format = new Streaming\Format\X264();
$format->on('progress', function ($video, $format, $percentage){
    echo sprintf("\rTranscoding...(%s%%) [%s%s]", $percentage, str_repeat('#', $percentage), str_repeat('-', (100 - $percentage)));
});

$stream->stream2file()
           ->setFormat($format)
           ->save('/var/media/new-video.mp4');

Other Advanced Features

You can easily use other advanced features in the PHP-FFMpeg library. In fact, when you open a file with the open method(or openFromCloud), it holds the Media object that belongs to the PHP-FFMpeg.

$ffmpeg = Streaming\FFMpeg::create()
$video = $$ffmpeg->fromURL("https://www.aminyazdanpanah.com/my_sweetie.mp4", "/var/wwww/media/my/new/video.mp4");

Extracting image

You can extract a frame at any timecode using the FFMpeg\Media\Video::frame method.

$frame = $video->frame(FFMpeg\Coordinate\TimeCode::fromSeconds(42));
$frame->save('/var/media/poster.jpg');

NOTE:

You can use the image as a video's poster.

Gif

A gif is an animated image extracted from a sequence of the video. You can save gif files using the FFMpeg\Media\Gif::save method.

$video
    ->gif(FFMpeg\Coordinate\TimeCode::fromSeconds(2), new FFMpeg\Coordinate\Dimension(640, 480), 3)
    ->save('/var/media/animated_image.gif');

This method has a third optional boolean parameter, which is the duration of the animation. If you don't set it, you will get a fixed gif image.

NOTE:

You can use the gif as a video's thumbnail.

Asynchronous Task Execution

Packaging process might take a while and it is recommended to run it in the background(or in a cloud e.g. AWS). There are some libraries that you can use for this use case.

Symphony(The Console Component): You can use this library to create command-line commands. Your console commands can be used for any recurring task, such as cronjobs, imports, or other batch jobs. Learn more.

Laravel(Queues): If you are using Laravel for development, Laravel Queues is a wonderful tool for this use case. It allows you to create a job and dispatch it. Learn more

NOTE:

You can also create a script to create packaged video files and create your own crontab file to run the script.

Several Open Source Players

You can use these players to play your packaged videos.




NOTE:

You must pass a link of the master playlist(manifest)(i.e. https://www.aminyazdanpanah.com/?"PATH TO STREAM DIRECTORY"/dash-stream.mpd or /PATH_TO_STREAM_DIRECTORY/hls-stream.m3u8 ) to these players.

NOTE:

If you save your stream content to a cloud(i.e. Amazon S3), the link of content MUST BE PUBLIC.

NOTE:

As you may know, IOS does not have native support for DASH. Although there are some libraries such as Viblast and MPEGDASH-iOS-Player to support this technique, I have never tested them. So maybe som of them will not work correctly.

Demos

DASH(dash.js)

HLS(hls.js)

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.

If you discover a security vulnerability within this package, please contact me.

Plese NOTE:

If you have any questions about this package or FFmpeg, please DO NOT send an email to me (or DO NOT submit the contact form on my website). Emails regarding these issues WILL BE IGNORED. Instead, you should file an issue in the repository on Github.

If you like this project, please ⭐️ Star it on Github.