📝 Document attachments

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `ffmpeg-mappable-media` will be documented in this file.
 
+## 0.2.0
+
+-  ✨ Support attachments
+
 ## 0.1.3
 
 - ✨ Support progress listeners

README.md

@@ -98,7 +98,7 @@ use FFMpeg\Format\Video\X264;
 MappableMedia::make($ffmpeg)
     ->addInput('input.mkv')
     ->map()
-        ->saveAs('output.mk')
+        ->saveAs('output.mkv')
         ->stream()->setCodec(new X264())->saveStream()
         ->saveMap()
     ->save()
@@ -112,7 +112,7 @@ The `map` and `stream` methods can take an optional callback, allowing you to se
 MappableMedia::make($ffmpeg)
     ->addInput('input.mkv')
     ->map(function (Map $map) {
-        $map->saveAs('output.mk')
+        $map->saveAs('output.mkv')
             ->stream(function (Stream $stream) {
                 $stream->copy()->setInput('0:0');
             });
@@ -129,7 +129,7 @@ It is possible to set a listener on the individual streams, using the Format cla
 MappableMedia::make($ffmpeg)
     ->addInput('input.mkv')
     ->map()
-        ->saveAs('output.mk')
+        ->saveAs('output.mkv')
         ->stream()->copy()->saveStream()
         ->saveMap()
     ->on('progress', function (MappableMedia $media, int $percent, int $remaining, int $rate) {
@@ -138,6 +138,47 @@ MappableMedia::make($ffmpeg)
     ->save()
 ```
 
+### Attachments
+
+Some formats (mkv, for example) support arbitrary data attachments. These can be used as cover art, fonts for subtitles, or any arbitrary data.
+
+FFMpeg does support attachments as an additional input. This works well for images, but can be finicky for other file types. Because of this, FFMpeg also supports an `-attach` flag which can be used to explicitly attach a new stream.
+
+Due to the way FFMpeg handles `-attach` differently than `-i`, these need to be added as streams to a specific map, rather than the whole media. Here are a few examples.
+
+```php
+MappableMedia::make($ffmpeg)
+    ->addInput('input.mkv')
+    ->map()
+        ->saveAs('output.mkv')
+        ->stream()->copy()->saveStream()
+        ->attach('image.jpg')
+            ->mime('image/jpeg')
+            ->addMetadata('filename', 'cover.jpg')
+            ->saveAttachment()
+        ->saveMap()
+    ->save();
+```
+
+In this example, we added cover art to the file. Notice the use of the `mime` method to specify the mime-type. **This must always be done**. Note that we also specified a different filename so that the media player would recognize it as cover art. If you don't specify a filename, the original will be used.
+
+```php
+MappableMedia::make($ffmpeg)
+    ->addInput('input.mkv')
+    ->addInput('subs.ass')
+    ->map()
+        ->saveAs('output.mkv')
+        ->stream()->copy()->saveStream()
+        ->stream()->setInput('1:0')->copy()->saveStream()
+        ->attach(verdana.ttf')
+            ->mime('application/x-truetype-font')
+            ->saveAttachment()
+        ->saveMap()
+    ->save();
+```
+
+In this example, we've added a font, which is likely referenced in the subtitle file, `subs.ass`.
+
 ## Future Plans
 
 - [ ] Add listeners that return all the stdin/stderr