|Classes of Oliver Lillie||>||PHP Video Toolkit||>||README.md||>||Download|
...is a set of PHP classes aimed to provide a modular, object oriented and accessible interface for interacting with videos and audio through FFmpeg.
It also currently provides FFmpeg-PHP emulation in pure PHP so you wouldn't need to compile and install the module. As FFmpeg-PHP has not been updated since 2007 using FFmpeg-PHP with a new version of FFmpeg can often break the module. Using PHPVideoToolkits' emulation of FFmpeg-PHP's functionality allows you to upgrade FFmpeg without worrying about breaking existing funcitonality.
IMPORTANT PHPVideoToolkit has only been tested with v1.1.2 of FFmpeg. Whilst the majority of functionality should work regardless of your version of FFmpeg I cannot guarantee it. If you find a bug or have a patch please open a ticket or submit a pull request on https://github.com/buggedcom/phpvideotoolkit-v2
Table of Contents
PHPVideoToolkit Copyright (c) 2008-2014 Oliver Lillie
DUAL Licensed under MIT and GPL v2
See LICENSE.md for more details.
Extensive documentation and examples are bundled with the download and is available in the documentation directory.
Whilst the extensive documentation covers just about everything, here are a few examples of what you can do.
PHPVideoToolkit requires some basic configuration and is one through the Config class. The Config class is then used in the constructor of most PHPVideoToolkit classes. Any child object initialised within an already configured class will inherit the configuration options of the parent.
If a config object is not defined and supplied to the PHPVideoToolkit classes, then a default Config object is created and assigned to the class.
Every example below uses
Accessing Data About FFmpeg
Simple demonstration about how to access information about FfmpegParser object.
Accessing Data About media files
Simple demonstration about how to access information about media files using the MediaParser object.
PHPVideoToolkit utilises Timecode objects when extracting data such as duration or start points, or when extracting portions of a media file. They are fairly simple to understand. All of the example timecodes created below are the same time.
You can manipulate timecodes fairly simply.
It's very important to note, as in the last example, that there is a massive difference between accessing
Extract a Single Frame of a Video
The code below extracts a frame from the video at the 40 second mark.
Extract Multiple Frames from a Segment of a Video
The code below extracts frames at the parent videos' frame rate from between 40 and 50 seconds. If the parent video has a frame rate of 24 fps then 240 images would be extracted from this code.
Extract Multiple Frames of a Video at 1 frame per second
There are two ways you can export at a differing frame rate from that of the parent video. The first is to use an output format to set the video frame rate.
The second is to use the $force_frame_rate option of the extractFrames function.
Extracting an Animated Gif
Now, FFmpeg's animated gif support is a pile of doggy do do. I can't understand why. However what PHPVideoToolkit does is bypass the native gif exporting of FFmpeg and provide it's own much better alternative.
There are several options available to you when exporting an animated gif. You can use Gifsicle, Imagemagicks convert, or native PHP GD with the symbio/gif-creator composer library.
For high quality, but very slow encoding a combination of Gifsicle with Convert pre processing is suggested, alternatively for a quicker encode but lower quality, you can use native PHP GD or Convert. The examples below show you how to differentiate between the different methods.
Regards to performance. High frame rates greatly impact how fast a high quality encoding completes. It's suggested that if you need a high quality animated gif, that you limit your frame rate to around 5 frames per second.
Gifsicle with Imagemagick Convert
Quick Encoding, but lower quality (still better than FFmpeg mind)
The examples below are listed in order of performance.
Native PHP GD with symbio/gif-creator library
Gifsicle with native PHP GD
Extracting Audio or Video Channels from a Video
Extracting a Segment of an Audio or Video file
The code below extracts a portion of the video at the from 2 minutes 22 seconds to 3 minutes (ie 180 seconds). Note the different settings for constructing a timecode. The timecode object can accept different formats to create a timecode from.
Spliting a Audio or Video file into multiple parts
There are multiple ways you can configure the split parameters. If an array is supplied as the first argument. It must be an array of either, all Timecode instances detailing the timecodes at which you wish to split the media, or all integers. If integers are supplied the integers are treated as frame numbers you wish to split at. You can however also split at even intervals by suppling a single integer as the first paramenter. That integer is treated as the number of seconds that you wish to split at. If you have a video that is 3 minutes 30 seconds long and set the split to 60 seconds, you will get 4 videos. The first three will be 60 seconds in length and the last would be 30 seconds in length.
The code below splits a video into multiple of equal length of 45 seconds each.
Purging and then adding Meta Data
Unfortunately there is no way using FFmpeg to add meta data without re-encoding the file. There are other tools that can do that though, however if you wish to write meta data to the media during encoding you can do so using code like the example below.
Changing Codecs of the audio or video stream
By default PHPVideoToolkit uses the file extension of the output file to automatically generate the required ffmpeg settings (if any) of your desired file format. However if you want to specify different codecs or settings, it is nessicary to specify them within an output format container. There are three different format objects you can use, depending on the format of your output. They are AudioFormat, VideoFormat and ImageFormat.
Note; the examples below are for demonstration purposes only and _may not work_.
Changing the audio and video codecs of an outputted video
Changing the audio codec of an audio export
The default/main save() function blocks PHP untill the encoding process has completed. This means that depending on the size of the media you are encoding it could leave your script running for a long time. To combat this you can call saveNonBlocking() to start the encoding process without blocking PHP.
However there are some caveats you need to be aware of before doing so. Once the non blocking process as started, if your PHP script closes PHPVideoToolkit can not longer "tidy up" temporary files or perform dynamic renaming of %index or %timecode output files. All repsonsibility is handed over to you. Of course, if you leave the PHP script open untill the encode has finished PHPVideoToolkit will do everything for you.
The code below is an example of how to manage a non-blocking save.
Encoding with Progress Handlers
Whilst the code above from Non-Blocking Saves looks like it is a progress handler (and it is in a sense, but it doesn't provide data on the encode), progress handlers provide much more detailed information about the current encoding process.
PHPVideoToolkit allows you to monitor the encoding process of FFmpeg. This is done by using ProgressHandler objects. There are three types of progress handlers.
ProgressHandlerNative and ProgressHandlerOutput work and function in the same way, however one uses a native ffmpeg command, and the out outputs ffmpeg output buffer to a temp file. If your copy of FFmpeg is recent you will be able to use ProgressHandlerNative which uses FFmpegs '-progress' command to provide data. Apart from that difference both handlers return the same data and act in the same way and there is no real need to prioritise one over another unless you version of ffmpeg does not support '-progress'. If it doesn't then when you initialise the ProgressHandlerNative an exception will be thrown.
The third type of handler ProgressHandlerPortable (shown in example 3 below) operates somewhat differently and is specifically design to work with separate HTTP requests or threads. ProgressHandlerPortable can be initiated in a different script entirely, supplied with the PHPVideoToolkit portable process id and then probed independantly of the encoding script. This allows developers to decouple encoding and encoding status scripts.
Progress Handlers can be made to block PHP or can be used in a non blocking fashion. They can even be utilized to work from a seperate script once the encoding has been initialised. However for purposes of the first two examples the progress handlers are in the same script essentially blocking the PHP process. Again however, the first two examples shown function very differently.
Example 1. Callback in the handler constructor
This example supplies the progress callback handler as a paramater to the constructor. This function is then called (every second, by default). Creating the callback in this way will block PHP and cannot be assigned as a progress handler when calling saveNonBlocking().
Example 2. Probing the handler
This example initialises a handler but does not supply a callback function. Instead you create your own method for creating a "progress loop" (or similar) and instead just call probe() on the handler.
So you see whilst the two examples look very similar and both block PHP, the second example does not need to block at all.
Example 3. Non Blocking Save with Remove Progress Handling
This example (a better example is found in /examples/progress-handler-portability.php) shows that a non blocking save can be made in one request, and then subsequent requests (i.e. ajax) can be made to a different script to probe the encoding progress.
IMPORTANT: When encoding MP4s and having enabled qt-faststart usage either through setting
Accessing Executed Commands and the Command Line Buffer
There may be instances where things go wrong and PHPVideoToolkit hasn't correctly prevented or reported any encoding/decoding errors, or, you may just want to log what is going on. You can access any executed commands and the command lines output fairly simply as the example below shows.
It's important to note, the the ExecBuffer object actually manipulates the raw command string given to it by the FfmpegProcess object. This is done so that the ExecBuffer can successfully track errors and process completion. The data returned by getExecutedCommand() and getBuffer() are values that are expected but not actual.
To get the actual executed command and buffer you can use the following.
Supplying custom commands
Because FFmpeg has a specific order in which certain commands need to be added there are a few functions you should be aware of. First of the code below shows you how to access the code FfmpegProcess object. The process object is itself a wrapper around the ProcessBuilder (helps to build queries) and ExceBuffer (executes and controls the query) objects.
The process object is passed by reference so any changes to the object are also made within the Video object.
Now you have access to the process object you can add specific commands to it.
Now all of the example commands above will cause FFmpeg to fail, and they are just to illustrate a point.
To help explain it further, here is a simplified command string using the above custom commands.
HOWEVER, there is an important caveat you need to be aware of, the above command is just and example to show you the position of the added commands. Using the same additional commands as above, the actual executed command looks like this:
Imposing a processing timelimit
You may wish to impose a processing timelimit on encoding. There are various reasons for doing this and should be self explanitory. FFmpeg supplies a command to be able to do this and can be invoked like so...