From 2672580a54eec74ea0356e4dbd11ddaa08f8e2fc Mon Sep 17 00:00:00 2001 From: Dan Jones Date: Mon, 29 Aug 2022 11:09:17 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Update=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 1 + README.md | 96 ++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 73 insertions(+), 24 deletions(-) diff --git a/.gitignore b/.gitignore index 841e6e5..ce4942f 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ psalm.xml vendor .php-cs-fixer.cache +*.mkv diff --git a/README.md b/README.md index 1308c8c..bb15272 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,11 @@ - -[](https://supportukrainenow.org) - -# This is my package ffmpeg-mappable-media +# Mappable Media for PHP-FFMPEG [![Latest Version on Packagist](https://img.shields.io/packagist/v/danjones000/ffmpeg-mappable-media.svg?style=flat-square)](https://packagist.org/packages/danjones000/ffmpeg-mappable-media) -[![Tests](https://codeberg.org/danjones000/ffmpeg-mappable-media/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://codeberg.org/danjones000/ffmpeg-mappable-media/actions/workflows/run-tests.yml) [![Total Downloads](https://img.shields.io/packagist/dt/danjones000/ffmpeg-mappable-media.svg?style=flat-square)](https://packagist.org/packages/danjones000/ffmpeg-mappable-media) -This is where your description should go. Try and limit it to a paragraph or two. Consider adding a small example. +Mappable Media is a plugin for [PHP-FFMpeg](https://github.com/PHP-FFMpeg/PHP-FFMpeg/) which provides a mechanism for mapping individual streams from input to output files. -## Support us - -[](https://spatie.be/github-ad-click/ffmpeg-mappable-media) - -We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). - -We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). +It allows for greater control regarding specific codecs and metadata from a particular input stream to a particular output stream than the built-in [AdvancedMedia](https://github.com/PHP-FFMpeg/PHP-FFMpeg/#advancedmedia) provides. ## Installation @@ -28,28 +18,86 @@ composer require danjones000/ffmpeg-mappable-media ## Usage ```php -$skeleton = new Danjones\FFMpeg(); -echo $skeleton->echoPhrase('Hello, Danjones!'); +use Danjones\FFMpeg\MappableMedia; +use FFMpeg\FFMpeg; + +$ffmpeg = FFMpeg::create(); +$media = MappableMedia::make($ffmpeg); + +$media->addInput('video.mp4'); +$media->addInput('audio.opus'); +$media->addInput('sub.srt'); + +$output1 = $media->map(); +$output1->saveAs('no-subs.webm'); +$output1->metadata('title', 'The Greatest Stury Ever Hulaed'); + +$stream1 = $output1->stream(); +$stream1->setInput('0:0'); +$stream1->video('libvp9'); +$stream1->saveStream(); + +$stream2 = $output1->stream(); +$stream2->setInput('1:0'); +$stream2->copy(); +$stream2->saveStream(); + +$output1->saveMap(); + +$output2 = $media->map(); +$output2->saveAs('all-copy.mkv'); + +// Most methods return the object that calls them. +$output2->stream()->setInput('0:0')->copy()->saveStream(); +$output2->stream()->setInput('1:0')->copy()->saveStream(); +$output2->stream()->setInput('2:0')->copy()->metadata('language', 'eng')->saveStream(); +$output2->saveMap(); + +$media->save(); ``` -## Testing +The `saveStream` method returns the `Map`` that created it. Likewise, the `saveMap` returns the `MappableMedia` that created it. All other methods are chainable. -```bash -composer test +So, this could be written as a very long single call like this: + +```php +MappableMedia::make($ffmpeg) + ->addInput('video.mp4') + ->addInput('audio.opus') + ->addInput('sub.srt') + ->map() + ->saveAs('no-subs.webm') + ->metadata('title', 'The Greatest Story Ever Hulaed') + ->stream()->setInput('0:0')->video('libvp9')->saveStream() + ->stream()->setInput('1:0')->copy()->saveStream() + ->saveMap() + ->map() + ->saveAs('all-copy.mkv') + ->stream()->setInput('0:0')->copy()->saveStream() + ->stream()->setInput('1:0')->copy()->saveStream() + ->stream()->setInput('2:0')->copy()->metadata('language', 'eng')->saveStream() + ->saveMap() + ->save() + ``` + +Both of these calls would result in the following command being run: + +```shell +ffmpeg -y -i video.mp4 -i audio.opus -i sub.srt -map 0:0 -c:0 libvp9 -map 1:0 -c:1 copy -metadata title="The Greatest Story Ever Hulaed" no-subs.webm -map 0:0 -c:0 copy -map 1:0 -c:1 copy -map 2:0 -c:2 copy -metadata:s:2 language=eng all-copy.mkv ``` -## Changelog +This will result in two files. The first will be a webm file (suitable for play in a browser) with a `title` field on the file set to "The Greatest Story Ever Hulaed". The second file will copy the first stream from each file directly, and set the language of the subtitle stream to English. -Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. +## What's not yet done? + +Mostly documentation. There are a lot more ways to use this, including using the `Format` objects from PHP-FFMpeg to set the codecs, and the ability to use callbacks to set additional data on both maps and individual streams. + +I also need to figure out how to set the listeners on the codecs to get realtime progress updates (see [Formats](https://github.com/PHP-FFMpeg/PHP-FFMpeg/#formats)). Once that's figured out, I need to document it properly here. ## Contributing Please see [CONTRIBUTING](https://codeberg.org/spatie/.github/blob/main/CONTRIBUTING.md) for details. -## Security Vulnerabilities - -Please review [our security policy](../../security/policy) on how to report security vulnerabilities. - ## Credits - [Dan Jones](https://codeberg.org/danjones000)