1 #PHP FFmpeg 2 3 [](http://travis-ci.org/PHP-FFMpeg/PHP-FFMpeg) 4 5 [](https://insight.sensiolabs.com/projects/607f3111-e2d7-44e8-8bcc-54dd64521983) 6 7 An Object Oriented library to convert video/audio files with FFmpeg / AVConv. 8 9 Check another amazing repo : [PHP FFMpeg extras](https://github.com/alchemy-fr/PHP-FFMpeg-Extras), you will find lots of Audio/Video formats there. 10 11 ## Your attention please 12 13 ### How this library works : 14 15 This library requires a working FFMpeg install. You will need both FFMpeg and FFProbe binaries to use it. 16 Be sure that these binaries can be located with system PATH to get the benefit of the binary detection, 17 otherwise you should have to explicitely give the binaries path on load. 18 19 For Windows users : Please find the binaries at http://ffmpeg.zeranoe.com/builds/. 20 21 ### Known issues : 22 23 - Using rotate and resize will produce a corrupted output when using 24 [libav](http://libav.org/) 0.8. The bug is fixed in version 9. This bug does not 25 appear in latest ffmpeg version. 26 27 ## Installation 28 29 The recommended way to install PHP-FFMpeg is through [Composer](https://getcomposer.org). 30 31 ```json 32 { 33 "require": { 34 "php-ffmpeg/php-ffmpeg": "~0.5" 35 } 36 } 37 ``` 38 39 ## Basic Usage 40 41 ```php 42 $ffmpeg = FFMpegFFMpeg::create(); 43 $video = $ffmpeg->open('video.mpg'); 44 $video 45 ->filters() 46 ->resize(new FFMpegCoordinateDimension(320, 240)) 47 ->synchronize(); 48 $video 49 ->frame(FFMpegCoordinateTimeCode::fromSeconds(10)) 50 ->save('frame.jpg'); 51 $video 52 ->save(new FFMpegFormatVideoX264(), 'export-x264.mp4') 53 ->save(new FFMpegFormatVideoWMV(), 'export-wmv.wmv') 54 ->save(new FFMpegFormatVideoWebM(), 'export-webm.webm'); 55 ``` 56 57 ## Documentation 58 59 This documentation is an introduction to discover the API. It's recommended 60 to browse the source code as it is self-documented. 61 62 ### FFMpeg 63 64 `FFMpegFFMpeg` is the main object to use to manipulate medias. To build it, 65 use the static `FFMpegFFMpeg::create` : 66 67 ```php 68 $ffmpeg = FFMpegFFMpeg::create(); 69 ``` 70 71 FFMpeg will autodetect ffmpeg and ffprobe binaries. If you want to give binary 72 paths explicitely, you can pass an array as configuration. A `PsrLoggerLoggerInterface` 73 can also be passed to log binary executions. 74 75 ```php 76 $ffmpeg = FFMpegFFMpeg::create(array( 77 'ffmpeg.binaries' => '/opt/local/ffmpeg/bin/ffmpeg', 78 'ffprobe.binaries' => '/opt/local/ffmpeg/bin/ffprobe', 79 'timeout' => 3600, // The timeout for the underlying process 80 'ffmpeg.threads' => 12, // The number of threads that FFMpeg should use 81 ), $logger); 82 ``` 83 84 ### Manipulate media 85 86 `FFMpegFFMpeg` creates media based on URIs. URIs could be either a pointer to a 87 local filesystem resource, an HTTP resource or any resource supported by FFmpeg. 88 89 **Note** : To list all supported resource type of your FFmpeg build, use the 90 `-protocols` command : 91 92 ``` 93 ffmpeg -protocols 94 ``` 95 96 To open a resource, use the `FFMpegFFMpeg::open` method. 97 98 ```php 99 $ffmpeg->open('video.mpeg'); 100 ``` 101 102 Two types of media can be resolved : `FFMpegMediaAudio` and `FFMpegMediaVideo`. 103 A third type, `FFMpegMediaFrame`, is available through videos. 104 105 #### Video 106 107 `FFMpegMediaVideo` can be transcoded, ie : change codec, isolate audio or 108 video. Frames can be extracted. 109 110 ##### Transcoding 111 112 You can transcode videos using the `FFMpegMediaVideo:save` method. You will 113 pass a `FFMpegFormatFormatInterface` for that. 114 115 Please note that audio and video bitrate are set on the format. 116 117 ```php 118 $format = new FormatVideoX264(); 119 $format->on('progress', function ($video, $format, $percentage) { 120 echo "$percentage % transcoded"; 121 }); 122 123 $format 124 -> setKiloBitrate(1000) 125 -> setAudioChannels(2) 126 -> setAudioKiloBitrate(256); 127 128 $video->save($format, 'video.avi'); 129 ``` 130 131 Transcoding progress can be monitored in realtime, see Format documentation 132 below for more informations. 133 134 ##### Extracting image 135 136 You can extract a frame at any timecode using the `FFMpegMediaVideo::frame` 137 method. 138 139 This code return a `FFMpegMediaFrame` instance corresponding to the second 42. 140 You can pass any `FFMpegCoordinateTimeCode` as argument, see dedicated 141 documentation below for more information. 142 143 ```php 144 $frame = $video->frame(FFMpegCoordinateTimeCode::fromSeconds(42)); 145 $frame->save('image.jpg'); 146 ``` 147 148 ##### Filters 149 150 You can apply filters on `FFMpegMediaVideo` with the `FFMpegMediaVideo::addFilter` 151 method. Video accepts Audio and Video filters. 152 153 You can build your own filters and some are bundled in PHP-FFMpeg - they are 154 accessible through the `FFMpegMediaVideo::filters` method. 155 156 Filters are chainable 157 158 ```php 159 $video 160 ->filters() 161 ->resize($dimension, $mode, $useStandards) 162 ->framerate($framerate, $gop) 163 ->synchronize(); 164 ``` 165 166 ###### Rotate 167 168 Rotates a video to a given angle. 169 170 ```php 171 $video->filters()->rotate($angle); 172 ``` 173 174 The `$angle` parameter must be one of the following constants : 175 176 - `FFMpegFiltersVideoRotateFilter::ROTATE_90` : 90° clockwise 177 - `FFMpegFiltersVideoRotateFilter::ROTATE_180` : 180° 178 - `FFMpegFiltersVideoRotateFilter::ROTATE_270` : 90° counterclockwise 179 180 ###### Resize 181 182 Resizes a video to a given size. 183 184 ```php 185 $video->filters()->resize($dimension, $mode, $useStandards); 186 ``` 187 188 The resize filter takes three parameters : 189 190 - `$dimension`, an instance of `FFMpegCoordinateDimension` 191 - `$mode`, one of the constants `FFMpegFiltersVideoResizeFilter::RESIZEMODE_*` constants 192 - `$useStandards`, a boolean to force the use of the nearest aspect ratio standard. 193 194 ###### Watermark 195 196 Watermark a video with a given image. 197 198 ```php 199 $video 200 ->filters() 201 ->watermark($watermarkPath, array( 202 'position' => 'relative', 203 'bottom' => 50, 204 'right' => 50, 205 )); 206 ``` 207 208 The watermark filter takes two parameters: 209 210 `$watermarkPath`, the path to your watermark file. 211 `$coordinates`, an array defining how you want your watermark positioned. You can use relative positioning as demonstrated above or absolute as such: 212 213 ```php 214 $video 215 ->filters() 216 ->watermark($watermarkPath, array( 217 'position' => 'absolute', 218 'x' => 1180, 219 'y' => 620, 220 )); 221 ``` 222 223 ###### Framerate 224 225 Changes the frame rate of the video. 226 227 ```php 228 $video->filters()->framerate($framerate, $gop); 229 ``` 230 231 The framerate filter takes two parameters : 232 233 - `$framerate`, an instance of `FFMpegCoordinateFramerate` 234 - `$gop`, a [GOP](https://wikipedia.org/wiki/Group_of_pictures) value (integer) 235 236 ###### Synchronize 237 238 Synchronizes audio and video. 239 240 Some containers may use a delay that results in desynchronized outputs. This 241 filters solves this issue. 242 243 ```php 244 $video->filters()->synchronize(); 245 ``` 246 247 ###### Clip 248 249 Cuts the video at a desired point. 250 251 ```php 252 $video->filters()->clip(FFMpegCoordinateTimeCode::fromSeconds(30), FFMpegCoordinateTimeCode::fromSeconds(15)); 253 ``` 254 255 The clip filter takes two parameters: 256 257 - `$start`, an instance of `FFMpegCoordinateTimeCode`, specifies the start point of the clip 258 - `$duration`, optional, an instance of `FFMpegCoordinateTimeCode`, specifies the duration of the clip 259 260 #### Audio 261 262 `FFMpegMediaAudio` can be transcoded, ie : change codec, isolate audio or 263 video. Frames can be extracted. 264 265 ##### Transcoding 266 267 You can transcode audios using the `FFMpegMediaAudio:save` method. You will 268 pass a `FFMpegFormatFormatInterface` for that. 269 270 Please note that audio kilobitrate is set on the audio format. 271 272 ```php 273 $ffmpeg = FFMpegFFMpeg::create(); 274 $audio = $ffmpeg->open('track.mp3'); 275 276 $format = new FFMpegFormatAudioFlac(); 277 $format->on('progress', function ($audio, $format, $percentage) { 278 echo "$percentage % transcoded"; 279 }); 280 281 $format 282 -> setAudioChannels(2) 283 -> setAudioKiloBitrate(256); 284 285 $audio->save($format, 'track.flac'); 286 ``` 287 288 Transcoding progress can be monitored in realtime, see Format documentation 289 below for more informations. 290 291 ##### Filters 292 293 You can apply filters on `FFMpegMediaAudio` with the `FFMpegMediaAudio::addFilter` 294 method. It only accepts audio filters. 295 296 You can build your own filters and some are bundled in PHP-FFMpeg - they are 297 accessible through the `FFMpegMediaAudio::filters` method. 298 299 ###### Resample 300 301 Resamples an audio file. 302 303 ```php 304 $audio->filters()->resample($rate); 305 ``` 306 307 The resample filter takes two parameters : 308 309 - `$rate`, a valid audio sample rate value (integer) 310 311 #### Frame 312 313 A frame is a image at a timecode of a video ; see documentation above about 314 frame extraction. 315 316 You can save frames using the `FFMpegMediaFrame::save` method. 317 318 ```php 319 $frame->save('target.jpg'); 320 ``` 321 322 This method has a second optional boolean parameter. Set it to true to get 323 accurate images ; it takes more time to execute. 324 325 #### Formats 326 327 A format implements `FFMpegFormatFormatInterface`. To save to a video file, 328 use `FFMpegFormatVideoInterface`, and `FFMpegFormatAudioInterface` for 329 audio files. 330 331 Format can also extends `FFMpegFormatProgressableInterface` to get realtime 332 informations about the transcoding. 333 334 Predefined formats already provide progress informations as events. 335 336 ```php 337 $format = new FormatVideoX264(); 338 $format->on('progress', function ($video, $format, $percentage) { 339 echo "$percentage % transcoded"; 340 }); 341 342 $video->save($format, 'video.avi'); 343 ``` 344 345 The callback provided for the event can be any callable. 346 347 ##### Create your own format 348 349 The easiest way to create a format is to extend the abstract 350 `FFMpegFormatVideoDefaultVideo` and `FFMpegFormatAudioDefaultAudio`. 351 and implement the following methods. 352 353 ```php 354 class CustomWMVFormat extends FFMpegFormatVideoDefaultVideo 355 { 356 public function __construct($audioCodec = 'wmav2', $videoCodec = 'wmv2') 357 { 358 $this 359 ->setAudioCodec($audioCodec) 360 ->setVideoCodec($videoCodec); 361 } 362 363 public function supportBFrames() 364 { 365 return false; 366 } 367 368 public function getAvailableAudioCodecs() 369 { 370 return array('wmav2'); 371 } 372 373 public function getAvailableVideoCodecs() 374 { 375 return array('wmv2'); 376 } 377 } 378 ``` 379 380 #### Coordinates 381 382 FFMpeg use many units for time and space coordinates. 383 384 - `FFMpegCoordinateAspectRatio` represents an aspect ratio. 385 - `FFMpegCoordinateDimension` represent a dimension. 386 - `FFMpegCoordinateFrameRate` represent a framerate. 387 - `FFMpegCoordinatePoint` represent a point. 388 - `FFMpegCoordinateTimeCode` represent a timecode. 389 390 ### FFProbe 391 392 `FFMpegFFProbe` is used internally by `FFMpegFFMpeg` to probe medias. You can 393 also use it to extract media metadata. 394 395 ```php 396 $ffprobe = FFMpegFFProbe::create(); 397 $ffprobe 398 ->streams('/path/to/video/mp4') // extracts streams informations 399 ->videos() // filters video streams 400 ->first() // returns the first video stream 401 ->get('codec_name'); // returns the codec_name property 402 ``` 403 404 ```php 405 $ffprobe = FFMpegFFProbe::create(); 406 $ffprobe 407 ->format('/path/to/video/mp4') // extracts file informations 408 ->get('duration'); // returns the duration property 409 ``` 410 411 ##Using with Silex Microframework 412 413 Service provider is easy to set up : 414 415 ```php 416 $app = new SilexApplication(); 417 $app->register(new FFMpegFFMpegServiceProvider()); 418 419 $video = $app['ffmpeg']->open('video.mpeg'); 420 ``` 421 422 Available options are as follow : 423 424 ```php 425 $app->register(new FFMpegFFMpegServiceProvider(), array( 426 'ffmpeg.configuration' => array( 427 'ffmpeg.threads' => 4, 428 'ffmpeg.timeout' => 300, 429 'ffmpeg.binaries' => '/opt/local/ffmpeg/bin/ffmpeg', 430 'ffprobe.timeout' => 30, 431 'ffprobe.binaries' => '/opt/local/ffmpeg/bin/ffprobe', 432 ), 433 'ffmpeg.logger' => $logger, 434 )); 435 ``` 436 437 ## API Browser 438 439 Browse the [API](http://readthedocs.org/docs/ffmpeg-php/en/latest/_static/API/) 440 441 ## License 442 443 This project is licensed under the [MIT license](http://opensource.org/licenses/MIT).