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 = FFMpeg\FFMpeg::create();
43 $video = $ffmpeg->open('video.mpg');
44 $video
45 ->filters()
46 ->resize(new FFMpeg\Coordinate\Dimension(320, 240))
47 ->synchronize();
48 $video
49 ->frame(FFMpeg\Coordinate\TimeCode::fromSeconds(10))
50 ->save('frame.jpg');
51 $video
52 ->save(new FFMpeg\Format\Video\X264(), 'export-x264.mp4')
53 ->save(new FFMpeg\Format\Video\WMV(), 'export-wmv.wmv')
54 ->save(new FFMpeg\Format\Video\WebM(), '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 `FFMpeg\FFMpeg` is the main object to use to manipulate medias. To build it,
65 use the static `FFMpeg\FFMpeg::create` :
66
67 ```php
68 $ffmpeg = FFMpeg\FFMpeg::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 `Psr\Logger\LoggerInterface`
73 can also be passed to log binary executions.
74
75 ```php
76 $ffmpeg = FFMpeg\FFMpeg::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 `FFMpeg\FFMpeg` 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 `FFMpeg\FFMpeg::open` method.
97
98 ```php
99 $ffmpeg->open('video.mpeg');
100 ```
101
102 Two types of media can be resolved : `FFMpeg\Media\Audio` and `FFMpeg\Media\Video`.
103 A third type, `FFMpeg\Media\Frame`, is available through videos.
104
105 #### Video
106
107 `FFMpeg\Media\Video` 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 `FFMpeg\Media\Video:save` method. You will
113 pass a `FFMpeg\Format\FormatInterface` for that.
114
115 Please note that audio and video bitrate are set on the format.
116
117 ```php
118 $format = new Format\Video\X264();
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 `FFMpeg\Media\Video::frame`
137 method.
138
139 This code return a `FFMpeg\Media\Frame` instance corresponding to the second 42.
140 You can pass any `FFMpeg\Coordinate\TimeCode` as argument, see dedicated
141 documentation below for more information.
142
143 ```php
144 $frame = $video->frame(FFMpeg\Coordinate\TimeCode::fromSeconds(42));
145 $frame->save('image.jpg');
146 ```
147
148 ##### Filters
149
150 You can apply filters on `FFMpeg\Media\Video` with the `FFMpeg\Media\Video::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 `FFMpeg\Media\Video::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 - `FFMpeg\Filters\Video\RotateFilter::ROTATE_90` : 90° clockwise
177 - `FFMpeg\Filters\Video\RotateFilter::ROTATE_180` : 180°
178 - `FFMpeg\Filters\Video\RotateFilter::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 `FFMpeg\Coordinate\Dimension`
191 - `$mode`, one of the constants `FFMpeg\Filters\Video\ResizeFilter::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 `FFMpeg\Coordinate\Framerate`
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(FFMpeg\Coordinate\TimeCode::fromSeconds(30), FFMpeg\Coordinate\TimeCode::fromSeconds(15));
253 ```
254
255 The clip filter takes two parameters:
256
257 - `$start`, an instance of `FFMpeg\Coordinate\TimeCode`, specifies the start point of the clip
258 - `$duration`, optional, an instance of `FFMpeg\Coordinate\TimeCode`, specifies the duration of the clip
259
260 #### Audio
261
262 `FFMpeg\Media\Audio` 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 `FFMpeg\Media\Audio:save` method. You will
268 pass a `FFMpeg\Format\FormatInterface` for that.
269
270 Please note that audio kilobitrate is set on the audio format.
271
272 ```php
273 $ffmpeg = FFMpeg\FFMpeg::create();
274 $audio = $ffmpeg->open('track.mp3');
275
276 $format = new FFMpeg\Format\Audio\Flac();
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 `FFMpeg\Media\Audio` with the `FFMpeg\Media\Audio::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 `FFMpeg\Media\Audio::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 `FFMpeg\Media\Frame::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 `FFMpeg\Format\FormatInterface`. To save to a video file,
328 use `FFMpeg\Format\VideoInterface`, and `FFMpeg\Format\AudioInterface` for
329 audio files.
330
331 Format can also extends `FFMpeg\Format\ProgressableInterface` to get realtime
332 informations about the transcoding.
333
334 Predefined formats already provide progress informations as events.
335
336 ```php
337 $format = new Format\Video\X264();
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 `FFMpeg\Format\Video\DefaultVideo` and `FFMpeg\Format\Audio\DefaultAudio`.
351 and implement the following methods.
352
353 ```php
354 class CustomWMVFormat extends FFMpeg\Format\Video\DefaultVideo
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 - `FFMpeg\Coordinate\AspectRatio` represents an aspect ratio.
385 - `FFMpeg\Coordinate\Dimension` represent a dimension.
386 - `FFMpeg\Coordinate\FrameRate` represent a framerate.
387 - `FFMpeg\Coordinate\Point` represent a point.
388 - `FFMpeg\Coordinate\TimeCode` represent a timecode.
389
390 ### FFProbe
391
392 `FFMpeg\FFProbe` is used internally by `FFMpeg\FFMpeg` to probe medias. You can
393 also use it to extract media metadata.
394
395 ```php
396 $ffprobe = FFMpeg\FFProbe::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 = FFMpeg\FFProbe::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 Silex\Application();
417 $app->register(new FFMpeg\FFMpegServiceProvider());
418
419 $video = $app['ffmpeg']->open('video.mpeg');
420 ```
421
422 Available options are as follow :
423
424 ```php
425 $app->register(new FFMpeg\FFMpegServiceProvider(), 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).