diff --git a/docs/source/Recipes.rst b/docs/source/Recipes.rst deleted file mode 100644 index 95cd105..0000000 --- a/docs/source/Recipes.rst +++ /dev/null @@ -1,673 +0,0 @@ -Recipes -======= - -Initializing FFMpeg -------------------- - -In the following examples, we assume we work in an environnment where -FFMpeg has been initialized to ``$ffmpeg``; there are two ways to -initialize the environment (see below). - -PHP-FFMpeg supports both ``avconv`` and legacy ``ffmpeg``. If both are installed -on your system, ``avconv`` will be loaded in first priority. Please read the -dedicated chapter below if you want to load ``FFMpeg``. - -Load FFMpeg automatically -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The easiest way to initialize ``FMpeg`` it is to call the loader ; this will -look in your PATH environment variable to find ffmpeg/avconv binary : - -.. code-block:: php - - pushHandler(new NullHandler()); - - // You have to pass a Monolog logger - // This logger provides some usefull infos about what's happening - $ffmpeg = FFMpeg::load($logger); - -.. note:: FFMpeg and FFProbe both requires a logger for giving feedback about - what's happening. By passing a NullHandler to the logger, you will disable - the log system. - - -Use custom binary -^^^^^^^^^^^^^^^^^ - -You can also initialize with a custom path to the binary : - -.. code-block:: php - - `_, you can -use FFMpeg-PHP with the bundled Service Provider : - -.. code-block:: php - - register(new FFMpegServiceProvider()); - - // Instance of FFMpeg\FFMpeg - $app['ffmpeg.ffmpeg']; - - // Instance of FFMpeg\FFProbe - $app['ffmpeg.ffprobe']; - - -Service Provider options -^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, `FFMpegServiceProvider` will look for monolog service to log -messages. You can customize FFMpeg logger with the 'ffmpeg.logger' option. - -You can also customize the number of threads to open and the path to FFMpeg and -FFProbe binaries : - -.. code-block:: php - - pushHandler(new NullHandler()); - - $options = array( - 'ffmpeg.ffmpeg.binary' => '/path/to/custom/ffmpeg/binary', - 'ffmpeg.ffprobe.binary' => '/path/to/custom/ffprobe/binary', - 'ffmpeg.threads' => 8, # number of threads to open - 'ffmpeg.logger' => $logger, # custom logger service - ); - - $app->register(new FFMpegServiceProvider(), $options); - - -Formats -------- - -PHP-FFMpeg provides a set of predefined audio and video formats. These formats -are usefull, but you'll probably need to define your own format with their own -resize rules, etc... - -This section describe how to use media formats, and how to define them. - -.. note:: Defining a format is just about implementing interfaces. - -.. _video-reference: - -Video -^^^^^ - -This section describes video processing and Interfaces for building video -formats. As Video is an extension of audio, all these features can be combined -with audio features (see :ref:`dedicated audio section`). - -Simple transcoding -++++++++++++++++++ - -To transcode a video, you have to pass the target format to FFMpeg. - -When you define a format which implements the -:ref:`Resizable ` interface. -You must set FFprobe (see :ref:`FF-probe`) -for probing the media and found its height and size. - -The following example initialize a Ogg format and encodes a `Video.mpeg` to a -target file `file.ogv` : - -.. code-block:: php - - setProber($ffprobe); - - $oggFormat = new Ogg(); - - $ffmpeg->open('Video.mpeg') - ->encode($oggFormat, 'file.ogv') - ->close(); - -.. note:: ``FFmpeg`` methods always return the object itself so you can chain - multiple methods. - -HTML5 -+++++ - -PHP-FFMpeg provides three video formats out of the box : HTML5 video formats - - - ``FFMpeg\Format\Video\WebM`` - - ``FFMpeg\Format\Video\X264`` - - ``FFMpeg\Format\Video\Ogg`` - -.. code-block:: php - - setDimensions(320, 240) - ->setFrameRate(15) - ->setGopSize(25); - - $x264Format = new Video\X264(); - $x264Format->setDimensions(320, 240) - ->setFrameRate(15) - ->setGopSize(25); - - $oggFormat = new Video\Ogg(); - $oggFormat->setDimensions(320, 240) - ->setFrameRate(15) - ->setGopSize(25); - - $ffmpeg->open('Video.mpeg') - ->encode($webMFormat, 'file.webm') - ->encode($x264Format, 'file.mp4') - ->encode($oggFormat, 'file.ogv') - ->close(); - -.. note:: All formats provided by PHP-FFMpeg extends DefaultVideo, have a look - at the API doc for more information on its behavior. - -.. note:: Use PHP-MP4Box to make it compatible with pseudo stream ! - -Create your own media type -++++++++++++++++++++++++++ - -PHP-FFMpeg provides ``FFMpeg\Format\VideoInterface``, as base interface for -creating a Video format. To define a target format, all you need to do is -implement this Interface. - -.. code-block:: php - - open('Video.mpeg') - ->encode($format, 'file.mp4') - ->close(); - -PHP-FFmpeg brings more interfaces for your video formats : - - - ``FFMpeg\Format\Video\Resamplable`` - - ``FFMpeg\Format\Video\Resizable`` - - ``FFMpeg\Format\Video\Transcodable`` - - ``FFMpeg\Format\Video\Interactive`` - -.. note:: You can combine these features in one video format. - -Advanced media type -+++++++++++++++++++ - -This section presents usage for the different interfaces. You can combine -them for your own formats. - -.. _resizable-reference: - -Resizable -......... - -This interface provide an easy way to resize a video. -The example below resizes a video by half. - -.. code-block:: php - - open('Video.mpeg') - ->encode($format, 'file.mp4') - ->close(); - -.. _resamplable-reference: - -Resamplable -........... - -This interface provides video resampling. The example below resample the video -at 15 frame per second with a I-frame every 30 image (see -`GOP on wikipedia `_) and supports -B-frames (see `B-frames on wikipedia `_) - -.. code-block:: php - - open('Video.mpeg') - ->encode($format, 'file.mp4') - ->close(); - -Interactive -........... - -This interface provides a method to list available codecs for the format. -The example below provides a format object listing available video-codecs for -video supported in flash player. - -.. code-block:: php - - open('Video.mpeg') - ->encode($format, 'file.mp4') - ->close(); - -.. _audio-reference: - -Audio -^^^^^ - -This section describes audio processing and Interfaces for building video -formats. As Video is an extension of audio, all these features can be combined -with video features (see :ref:`dedicated video section`). - -Simple transcoding -++++++++++++++++++ - -To transcode audio file or extract an audio soundtrack from a video, you have to -pass the target format to FFMpeg. - -The following example initialize a Mp3 format and transcode the file `tune.wav` -to `tune.mp3` : - -.. code-block:: php - - open('tune.wav') - ->encode($mp3Format, 'tune.mp3') - ->close(); - -Extract soundtrack from movie -+++++++++++++++++++++++++++++ - -The following example initialize a Flac format and extract the audio track from -`Video.mpeg` to a target file `soudtrack.flac` : - -.. code-block:: php - - open('Video.mpeg') - ->encode($flacFormat, 'soundtrack.flac') - ->close(); - -.. note:: You must ensure that FFmpeg support the format you request, otherwise - a FFMpeg\Exception\RuntimeException will be thrown. - -Create your own media type -++++++++++++++++++++++++++ - -PHP-FFMpeg provides ``FFMpeg\Format\AudioInterface``, as base interface for -creating an Audio format. To define a target format, all you need to do is -implement this Interface. - -This example transcodes the mp3 track to a 128kb mp3 : - -.. code-block:: php - - open('song.mp3') - ->encode($format, 'song-128.mp3') - ->close(); - -PHP-FFmpeg brings more interfaces for your audio formats : - - - ``FFMpeg\Format\Audio\Resamplable`` - - ``FFMpeg\Format\Audio\Transcodable`` - - ``FFMpeg\Format\Audio\Interactive`` - -.. note:: You can combine these features in one video format. - -Advanced media type -+++++++++++++++++++ - -This section presents usage for the different audio interfaces. You can combine -them for your own formats. - -Resamplable -........... - -This interface provides video resampling. The example below resample the video -at 15 frame per second with a I-frame every 30 image (see -`GOP on wikipedia `_). - -.. code-block:: php - - open('song.mp3') - ->encode($format, 'song-44100.mp3') - ->close(); - - -Interactive -........... - -This interface provides a method to list available codecs for the format. -The example below provides a format object listing available audio-codecs for -a portable player. - -.. code-block:: php - - open('Video.mp4') - ->encode($format, 'output-aac.mp4') - ->close(); - -.. _ffprobe-reference: - -FFProbe recipes ---------------- - -FFProbe / AvProbe is a usefull tool for probing media files. PHP-FFMpeg -implementation is currenly light. - -Load FFProbe -^^^^^^^^^^^^ - -As FFMpeg, you can load FFProbe two ways ; either with the binary detector or -specifying the binary you want to use - -.. code-block:: php - - pushHandler(new NullHandler()); - - // ------------------------------------------------------------------------ - // Load with binary detection - - // You have to pass a Monolog logger - // This logger provides some usefull infos about what's happening - $ffprobe = FFProbe::load($logger); - - - // ------------------------------------------------------------------------ - // Or load manually - - $ffprobe = new FFProbe('/usr/local/src/ffmpeg/bin/ffprobe', $logger); - - -Probe streams -^^^^^^^^^^^^^ - -Probe streams returns the output of ``avprobe -show_streams`` as a json -object. - -.. code-block:: php - - probeStreams('Video.ogv'); - -will output something like - -.. code-block:: json - - [ - { - "index": 0, - "codec_name": "theora", - "codec_long_name": "Theora", - "codec_type": "video", - "codec_time_base": "1/15", - "codec_tag_string": "[0][0][0][0]", - "codec_tag": "0x0000", - "width": 400, - "height": 304, - "has_b_frames": 0, - "pix_fmt": "yuv420p", - "level": "-99", - "r_frame_rate": "15/1", - "avg_frame_rate": "15/1", - "time_base": "1/15", - "start_time": "0.000000", - "duration": "29.533333" - }, - { - "index": 1, - "codec_name": "vorbis", - "codec_long_name": "Vorbis", - "codec_type": "audio", - "codec_time_base": "1/44100", - "codec_tag_string": "[0][0][0][0]", - "codec_tag": "0x0000", - "sample_rate": "44100.000000", - "channels": 2, - "bits_per_sample": 0, - "r_frame_rate": "0/0", - "avg_frame_rate": "0/0", - "time_base": "1/44100", - "start_time": "0.000000", - "duration": "29.489342", - "TAG:TITLE": "Halo", - "TAG:LICENSE": "http://creativecommons.org/licenses/publicdomain/", - "TAG:LOCATION": "http://www.archive.org/details/ctvc" - } - ] - - -Probe formats -^^^^^^^^^^^^^ - -Probe format returns the output of ``avprobe -show_format`` as a json -object. - -.. code-block:: php - - probeFormat('Video.ogv'); - -will output something like - -.. code-block:: json - - { - "filename": "Video.ogv", - "nb_streams": 2, - "format_name": "ogg", - "format_long_name": "Ogg", - "start_time": "0.000000", - "duration": "29.533333", - "size": "1786693.000000", - "bit_rate": "483980.000000" - } diff --git a/docs/source/index.rst b/docs/source/index.rst index aed3874..979c60c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,187 +1,6 @@ PHP FFMpeg documentation ======================== -Introduction ------------- +This documentation is obsolete. Please have a look on `PHP-FFMpeg`_. -PHP-FFmpeg is an object oriented PHP wrapper for FFmpeg (AVconv on recent Linux -distribution). This tool gives access to the tools provided by FFmpeg such as -FFprobe and FFmpeg. These are the two binary currently supported by PHP-FFmpeg. - -This library depends on `Symfony Process Component `_ -and `Monolog `_. - -Design ------- - -This library is designed to deal with legacy binaries of FFMpeg. It does not rely -on the FFmpeg extension. - -This library is object oriented, this means that nearly everything is an object, -or ought to be. So you won't find any out of-the-box function to extract -images or encode video. This design is headed for tests and a fail fast behavior. -We hope you'll enjoy it ! - -Installation ------------- - -We rely on `composer `_ to use this library. If you do -no still use composer for your project, you can start with this ``composer.json`` -at the root of your project: - -.. code-block:: json - - { - "require": { - "php-ffmpeg/php-ffmpeg": "master" - } - } - -Install composer : - -.. code-block:: bash - - # Install composer - curl -s http://getcomposer.org/installer | php - # Upgrade your install - php composer.phar install - -You now just have to autoload the library to use it : - -.. code-block:: php - - `_. - -Basic Usage ------------ - -.. code-block:: php - - pushHandler(new NullHandler()); - - // You have to pass a Monolog logger - // This logger provides some usefull infos about what's happening - $ffmpeg = FFMpeg::load($logger); - - // open a video, extract an image at second 5 and 12 then close - $ffmpeg->open('Video.mpeg') - ->extractImage(5, 'first-screenshot.jpg') - ->extractImage(12, 'second-screenshot.jpg') - ->close(); - -Process Timeout ---------------- - -PHP-FFMpeg runs ffmpeg commands to process your medias. A default timeout of -60 seconds is set, but you can override this by passing a second argument to the -``load`` method : - -.. code-block:: php - - getTimeOut(); - -You can also set and get the timeout with the appropriate getter and setter : - -.. code-block:: php - - setTimeout(200); - - // 200 - echo $ffmpeg->getTimeOut(); - -.. note:: - - To disable timeout, set its value to 0. - -Recipes -------- - -You'll find usefull recipes in our :doc:`Recipes` - -.. toctree:: - :maxdepth: 4 - - Recipes - -Handling Exceptions -------------------- - -PHP-FFMpeg throws 4 different types of exception : - -- ``\FFMpeg\Exception\BinaryNotFoundException`` is thrown when no acceptable - pdf2text binary is found. -- ``\FFMpeg\Exception\InvalidArgumentException`` is thrown when an invalid - argument (file, format, ...) is provided -- ``\FFMpeg\Exception\LogicException`` which extends SPL LogicException -- ``\FFMpeg\Exception\RuntimeException`` which extends SPL RuntimeException - -All these Exception implements ``\FFMpeg\Exception\Exception`` so you can catch -any of these exceptions by catching this exception interface. - -Report a bug ------------- - -If you experience an issue, please report it in our -`issue tracker `_. Before -reporting an issue, please be sure that it is not already reported by browsing -open issues. - -When reporting, please give us information to reproduce it by giving your -platform (Linux / MacOS / Windows) and its version, the version of PHP you use -(the output of ``php --version``), the version of ffmpeg or avconv you use -(the output of ``ffmpeg -version``) and the codec configuration (``ffmpeg -formats``) - -Ask for a feature ------------------ - -We would be glad you ask for a feature ! Feel free to add a feature request in -the `issues manager `_ on GitHub ! - -Contribute ----------- - -You find a bug and resolved it ? You added a feature and want to share ? You -found a typo in this doc and fixed it ? Feel free to send a -`Pull Request `_ on GitHub, we will -be glad to merge your code. - -Run tests ---------- - -PHP-FFMpeg relies on `PHPUnit `_ for -unit tests. To run tests on your system, ensure you have PHPUnit installed, -and, at the root of PHP-FFMpeg, execute it : - -.. code-block:: bash - - phpunit - -About ------ - -PHP-FFMpeg has been written by Romain Neutron @ `Alchemy `_ -for `Phraseanet `_, our DAM software. -Try it, it's awesome ! - -License -------- - -PHP-FFMpeg is licensed under the `MIT License `_ +.. _PHP-FFMpeg: https://github.com/alchemy-fr/PHP-FFmpeg