Doc update: close #10, close #9, #8

soluble-io · Aug 22, 2018 · 71e633f · 71e633f
1 parent db4c50c
commit 71e633f
Show file tree

Hide file tree

Showing 4 changed files with 150 additions and 66 deletions.
diff --git a/docs/video-conversion-service.md b/docs/video-conversion-service.md
@@ -245,64 +245,25 @@ Here's a list of categorized built-in methods you can use. See the ffmpeg doc fo
 
 #### Filters
 
-Video filters can be set to the VideoConvertParams through the `withVideoFilter(VideoFilterInterface $videoFilter)` method:
-
+Video filters can be set to the VideoConvertParams through the `->withVideoFilter(VideoFilterInterface $videoFilter)` method:
 
 ```php
 <?php
 use Soluble\MediaTools\Video\Filter;
 
 $params = (new VideoConvertParams())
     ->withVideoFilter(
-        // A denoise filter
-        new Filter\Hqdn3DVideoFilter()
+        new Filter\VideoFilterChain([
+            // A scaling filter
+            new Filter\ScaleFilter(800, 600),
+            // A denoise filter
+            new Filter\Hqdn3DVideoFilter()
+        ])
     );
 
 ```
 
-If you need to chain multiple filters, you can use the [`VideoFilterChain`](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/VideoFilterChain.php) object:
-
-```php
-<?php
-use Soluble\MediaTools\Video\Filter;
-
-// from the constructor
-$filters = new Filter\VideoFilterChain([    
-    new Filter\YadifVideoFilter(),
-    new Filter\Hqdn3DVideoFilter() 
-]);
-
-// Alternatively, use ->addFilter method
-$filters->addFilter(new Filter\NlmeansVideoFilter());
-
-$params = (new VideoConvertParams())
-    ->withVideoFilter($filters);
-
-// ....
-
-```
-
-Currently there's only few built-in filters available:
-
-| Filter                   |Note(s)                               |
-| ------------------------ | ------------------------------------ | 
-| [`YadifVideoFilter`](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/YadifVideoFilter.php)       | Deinterlacer  | 
-| [`Hqdn3DVideoFilter`](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/Hqdn3DVideoFilter.php)       | Basic denoiser  | 
-| [`NlmeansVideoFilter`](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/NlmeansVideoFilter.php)       | Very slow but good denoiser  | 
-| [`ScaleFilter`](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/ScaleFilter.php)       | Scaleing filter  |
-
-
-> But it's quite easy to add yours, simply implements the [FFMpegVideoFilterInterface](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/Type/FFMpegVideoFilterInterface.php).
-> We :heart: pull request, so don't forget to share :)
-  
-
-
-??? Question "Is the order of parameters, filters... important ?" 
-    Generally FFMpeg will evaluate the parameters in the order they appear... 
-    So if you're about to clip a video (from 1s to 3s) and use a denoise filter, 
-    setting the clipping params before the filter will generally be more performant
-    *(the denoise filter will only be applied on the clipped part of the video 
-    and not it's entire length)*.     
+See the **[complete video filters doc here](./video-filters.md)** 
 
 #### Exceptions
 

diff --git a/docs/video-filters.md b/docs/video-filters.md
@@ -0,0 +1,125 @@
+
+
+## Video filters
+
+Both `VideoConverter` and `VideoThumbGenerator` services allows setting up video filters through
+the `->withVideoFilter(VideoFilterInterface $videoFilter)` method. 
+
+???+ question "What are video filters used for ? "
+    We try to keep close to what ffmpeg does. In ffmpeg 
+    filters accomplish tasks as different as cropping, scaling, 
+    identifying (interlace, black detection), denoising, parts selection, 
+    colouring, generators...
+
+    The complete list of ffmpeg filters can be found [here](https://ffmpeg.org/ffmpeg-filters.html)
+
+
+Mediatools provide some common filters implementations but it's very easy to create your own, see last section.
+
+```php
+<?php
+use Soluble\MediaTools\Video\Filter;
+
+$params = (new VideoConvertParams())
+    ->withVideoFilter(
+        new Filter\VideoFilterChain([
+            // A scaling filter
+            new Filter\ScaleFilter(800, 600),
+            // A denoise filter
+            new Filter\Hqdn3DVideoFilter(),
+            // A custom filter
+            new class implements Filter\Type\FFMpegVideoFilterInterface {
+                public function getFFmpegCLIValue(): string {
+                    return 'frei0r=vertigo:0.2';
+                }
+            }
+        ])
+    );
+
+```
+
+### Built-in filters    
+
+
+| Filter                   | Type          | Argument(s)                            | Link(s)    | 
+| ------------------------ | ------------- | -------------------------------------- | ---------- |
+| `ScaleFilter`            | Dimension     | $width, $height, ?$aspect_ratio_mode   | [src](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/ScaleFilter.php) |
+| `YadifVideoFilter`       | Deinterlace   | ?$mode, ?$parity, ?$deint              | [src](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/YadifVideoFilter.php) |            
+| `Hqdn3DVideoFilter`      | Denoise       |                                        | [src](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/Hqdn3DVideoFilter.php) |           
+| `NlmeansVideoFilter`     | Denoise (slow)|                                        | [src](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/NlmeansVideoFilter.php) |         
+
+
+### Chaining filters
+
+#### VideoFilterChain
+
+To apply multiple filters, use the `VideoFilterChain` object. Filters will be processed
+in the order they've been added.
+
+```php
+<?php
+use Soluble\MediaTools\Video\Filter;
+
+// from the constructor
+$filters = new Filter\VideoFilterChain([    
+    new Filter\YadifVideoFilter(),
+    new Filter\Hqdn3DVideoFilter() 
+]);
+
+// Alternatively, use ->addFilter method
+$filters->addFilter(new Filter\NlmeansVideoFilter());
+
+$params = (new VideoConvertParams())
+    ->withVideoFilter($filters);
+
+// ....
+
+```
+
+???+ question "Filter graph support ?"
+     FFMpeg support a complex notation for advanced filter chaining named
+     [filtergraph](http://ffmpeg.org/ffmpeg-filters.html#Filtergraph-description).
+
+     The `VideoFilterChain` does not support this notation to keep the surface API
+     as intuitive as possible. If you need to use the filtergraph notation, you'll 
+     need to create your own filter:   
+
+     ```php
+     <?php
+     $myComplexFilter = new class interface FFMpegVideoFilterInterface {
+        public function getFFmpegCLIValue(): string
+        {
+             return '[in]yadif=0:0:0[middle];[middle]scale=iw/2:-1[out]';
+        }
+     }
+     ```
+
+     We :heart: contributions, if you have nice ideas about how to support filtergraph, 
+     make your voice loud in this [issue](https://github.com/soluble-io/soluble-mediatools/issues/10)
+
+
+### Custom filter
+
+Making your own filter is easy, you just have to implement `FFMpegVideoFilterInterface`:
+
+```php
+<?php
+use Soluble\MediaTools\Video\Filter\Type\FFMpegVideoFilterInterface;
+
+$vertigoFilter = new class implements FFMpegVideoFilterInterface {
+    public function getFFmpegCLIValue(): string
+    {
+        return 'frei0r=vertigo:0.2';
+    }
+};
+
+```
+
+And voilà !
+
+
+
+
+
+
+
diff --git a/docs/video-thumb-service.md b/docs/video-thumb-service.md
@@ -208,32 +208,27 @@ Here's a list of categorized built-in methods you can use. See the ffmpeg doc fo
 
 #### Filters
 
-Video filters can be set to the VideoConvertParams through the `withVideoFilter(VideoFilterInterface $videoFilter)` method:
+Video filters can be set to the VideoThumbParams through the `->withVideoFilter(VideoFilterInterface $videoFilter)` method:
 
 ```php
 <?php
-use Soluble\MediaTools\Video\VideoThumbParams;
 use Soluble\MediaTools\Video\Filter;
 
-$params = (new VideoThumbParams())
-    ->withTime(1.123)
-    ->withVideoFilter(new Filter\VideoFilterChain([
-        new Filter\YadifVideoFilter(),
-        new Filter\NlmeansVideoFilter()
-    ])); 
+$params = (new VideoConvertParams())
+    ->withVideoFilter(
+        new Filter\VideoFilterChain([
+            // A scaling filter
+            new Filter\ScaleFilter(800, 600),
+            // Deint filter
+            new Filter\YadifVideoFilter(),
+            // Denoise (slow but best denoiser, ok for thumbs)
+            new Filter\NlmeansVideoFilter()
+        ])
+    );
 
 ```
 
-Currently there's only few built-in filters available:
-
-| Filter                   |Note(s)                               |
-| ------------------------ | ------------------------------------ | 
-| [`YadifVideoFilter`](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/YadifVideoFilter.php)       | Deinterlacer  | 
-| [`Hqdn3DVideoFilter`](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/Hqdn3DVideoFilter.php)       | Basic denoiser  | 
-| [`NlmeansFilter`](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/NlmeansVideoFilter.php)       | Very slow but good denoiser  | 
-
-> But it's quite easy to add yours, simply implements the [FFMpegVideoFilterInterface](https://github.com/soluble-io/soluble-mediatools/blob/master/src/Video/Filter/Type/FFMpegVideoFilterInterface.php).
-> We :heart: pull request, so don't forget to share :)
+See the **[complete video filters doc here](./video-filters.md)** 
 
 
 #### Exceptions

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -26,8 +26,11 @@ nav:
       - 'InfoReader': 'video-info-service.md'
       - 'ThumbGenerator': 'video-thumb-service.md'
       - 'Analyzer': 'video-detection-service.md'
+      - 'Notes':
+        - 'Video filters': 'video-filters.md'
     - Notes:
-      - 'Ffmpeg install': 'install-ffmpeg.md'
+      - 'Install':
+        - FFMpeg: 'install-ffmpeg.md'
 
 theme:
   name: 'material'