[Feat] FilterGraphs (#15)

* wip

* code style

* wip: docs

* add to doc

* add stream validation

* tests

Author: ProjektGopher

README.md

@@ -98,6 +98,10 @@ The `Expr` class can help with this. If your expression is short enough this mig
 +   );
 ```
 
+## Docs
+Here's some more detailed information on some of this package's features:
+[Filter Graphs](docs/FilterGraphs.md)
+
 ## Testing
 ```bash
 composer test

docs/FilterGraphs.md

@@ -0,0 +1,48 @@
+# Filter Graphs
+A filter graph is what's used in the `-filter_complex` option of an FFMpeg command. These take in labelled audio or video streams, run a filter over them, then return newly labelled streams for further processing. As more filters are applied, these strings can become cumbersome to manage.
+
+## Usage
+When cast to a `string` either by explicitly _type hinting_ (eg. `(string) $filter_complex`), or by simply **using** it as a string (eg. `$cmd = "...{$filter_complex}";`) the `FilterGraph` class will call the `__toString()` magic method, which in turn calls the `build()` method. This makes debugging and testing easier as the `__toString` method cannot throw useful exceptions. You can **chain** the `build()` method to take advantage of this, but it's not ultimately necessary outside of testing and debugging.
+
+```php
+use ProjektGopher\FFMpegTools\Filters\FilterGraph;
+use ProjektGopher\FFMpegTools\Filters\Video\VideoFilter;
+
+$filter_complex = (string) FilterGraph::make()->addFilter(
+    in: '[0:v]',
+    filters: VideoFilter::drawtext()->text('Hello World'),
+    out: '[vid_with_text]',
+);
+
+$cmd = "ffmpeg -y -i input.mp4 ${filter_complex} out.mp4";
+```
+
+### Instantiation
+The `FilterGraph` class can be instatiated using the class constructor `(new FilterGraph)` or using the _static_ `make()` method, which simply calls the class constructor. The constructor takes no arguments, and all properties are protected. The choice here is usually just a matter of which option looks better with the way in which your command is formatted.
+
+### Adding Filter(s)
+The `addFilter()` method is really the only method you should need to use in this class. It returns `self` to allow chaining **multiple** filters. For the sake of clarity, it's recommended to use **named** arguments when calling this method. It accepts **3** arguments: a `string` representing the **named** input streams `$in` (eg: `[0:v]`, `[named_input]`); A `string`, `array`, or `Filter` object, representing the filter to be applied `$filters`; And a **nullable** `string` representing the **named** output streams `$out` (eg: `[bg_with_text]`).
+
+Named streams should **not** be re-used. A stream should only be exported and imported **once**. This has nothing to do with this package, it's just an FFMpeg thing.
+
+If `$filters` is passed an `array`, the `validateFilters()` method is called recursively until a final list of `strings` or `Filters` has been created. This is generally only done when very simple filters that accept/output single streams are used to avoid intermediate named outputs (eg: `[1:v] scale=-1:1080 [photo];[photo] split [photo_1][photo_2]` becomes `[1:v] scale=-1:1080, split [photo_1][photo_2]`).
+
+This example can now be written as:
+```php
+$filter_complex = (string) FilterGraph::make()->addFilter(
+    in: '[1:v]',
+    filters: [
+        'scale=-1:1080',
+        'split',
+    ],
+    out: '[photo_1][photo_2]',
+);
+```
+
+For something this simple, the `FilterGraph` class might be a bit overkill; But the more `complex` your graph becomes (pun intended), the more useful this abstraction becomes. It also just helps limit line-length in your IDE, which is always nice.
+
+### Extending
+The `FilterGraph` class is `final` and can therefor not be extended.
+
+## Testing
+You can call the `->build()` method after the end of your method chain in order to `dd()` for manual inspection, or to `assert` against.

src/Filters/FilterGraph.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace ProjektGopher\FFMpegTools\Filters;
+
+final class FilterGraph
+{
+    protected array $filters = [];
+
+    public static function make(): static
+    {
+        return new static();
+    }
+
+    public function addFilter(
+        string $in,
+        string|array|Filter $filters,
+        string|null $out = null,
+    ): self {
+        $this->filters[] = [
+            'in' => $this->validateStreams($in),
+            'filters' => $this->validateFilters($filters),
+            'out' => $out ? $this->validateStreams($out) : null,
+        ];
+
+        return $this;
+    }
+
+    public function validateStreams(string $streams): string
+    {
+        if (! preg_match('/^(\[[a-zA-Z0-9-_:]+\])+$/', $streams)) {
+            throw new \Exception("Could not parse stream {$streams}");
+        }
+
+        return $streams;
+    }
+
+    public function validateFilters(string|array|Filter $filters): array
+    {
+        if ($filters instanceof Filter) {
+            return [(string) $filters];
+        }
+
+        if (is_string($filters)) {
+            return [$filters];
+        }
+
+        $thing = [];
+        foreach ($filters as $filter) {
+            $thing[] = $this->validateFilters($filter)[0];
+        }
+
+        return $thing;
+    }
+
+    public function buildFilterString(array $filter): string
+    {
+        $filterString = "{$filter['in']} ";
+        $filterString .= implode(', ', $filter['filters']);
+        if ($filter['out']) {
+            $filterString .= " {$filter['out']}";
+        }
+
+        return $filterString;
+    }
+
+    public function build(): string
+    {
+        $filters = [];
+        foreach ($this->filters as $filter) {
+            $filters[] = $this->buildFilterString($filter);
+        }
+        $filters = implode(';', $filters);
+
+        return "-filter_complex \"{$filters}\"";
+    }
+
+    public function __toString(): string
+    {
+        return $this->build();
+    }
+}

tests/src/Filters/FilterGraphTest.php

@@ -0,0 +1,45 @@
+<?php
+
+use ProjektGopher\FFMpegTools\Filters\FilterGraph;
+use ProjektGopher\FFMpegTools\Filters\Video\VideoFilter;
+
+it('expects a stream to be wrapped in brackets', function () {
+    expect(fn () => FilterGraph::make()->validateStreams('foo'))
+        ->toThrow(\Exception::class);
+});
+
+it('accepts multiple streams', function () {
+    expect(FilterGraph::make()->validateStreams('[foo][1:v]'))->toEqual('[foo][1:v]');
+});
+
+it('builds a filter graph', function () {
+    expect((string) FilterGraph::make()
+        ->addFilter(
+            in: '[0:v]',
+            filters: VideoFilter::drawtext()->text('Hello World'),
+            out: '[vid_with_text]',
+        )
+    )->toEqual("-filter_complex \"[0:v] drawtext=text='Hello World' [vid_with_text]\"");
+});
+
+it('can skip the named output stream', function () {
+    expect((string) FilterGraph::make()
+        ->addFilter(
+            in: '[0:v]',
+            filters: VideoFilter::drawtext()->text('Hello World'),
+        )
+    )->toEqual("-filter_complex \"[0:v] drawtext=text='Hello World'\"");
+});
+
+it('builds a filter graph with multiple string filters', function () {
+    expect((string) FilterGraph::make()
+        ->addFilter(
+            in: '[1:v]',
+            filters: [
+                'scale=-1:1080',
+                'split',
+            ],
+            out: '[photo_1][photo_2]',
+        )
+    )->toEqual('-filter_complex "[1:v] scale=-1:1080, split [photo_1][photo_2]"');
+});