Skip to content

Commit 3d89f45

Browse files
ProjektGopherProjektGopher
authored
improve docs (#16)
1 parent 6619563 commit 3d89f45

File tree

7 files changed

+107
-96
lines changed

7 files changed

+107
-96
lines changed

‎README.md

Lines changed: 10 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Generate FFMpeg easing and tweening strings in Laravel.
1+
# Tools and utilities to help generate complex strings for FFMpeg in Laravel.
22
[![Latest Version on Packagist](https://img.shields.io/packagist/v/projektgopher/laravel-ffmpeg-tools.svg?style=flat-square)](https://packagist.org/packages/projektgopher/laravel-ffmpeg-tools)
33
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/projektgopher/laravel-ffmpeg-tools/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/projektgopher/laravel-ffmpeg-tools/actions?query=workflow%3Arun-tests+branch%3Amain)
44
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/projektgopher/laravel-ffmpeg-tools/phpstan.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/projektgopher/laravel-ffmpeg-tools/actions?query=workflow%3A"phpstan"+branch%3Amain)
@@ -32,107 +32,21 @@ composer require projektgopher/laravel-ffmpeg-tools
3232
```
3333

3434
## Usage
35+
- [Easing](docs/Easing.md)
36+
- [Expressions](docs/Expressions.md)
37+
- [Filters](docs/Filters.md)
38+
- [Filter Graphs](docs/FilterGraphs.md)
39+
- [Timelines and Keyframes](docs/Timelines.md)
40+
- [Tweening](docs/Tweening.md)
41+
3542
### Using outside of a Laravel application
3643
For now this package can only be used within a Laravel app, but there are plans to extract the core functionality into a separate package that can be used without being bound to the framework.
3744

38-
### Simple tween with delay and duration
39-
```php
40-
use ProjektGopher\FFMpegTools\Tween;
41-
use ProjektGopher\FFMpegTools\Timing;
42-
use ProjektGopher\FFMpegTools\Ease;
43-
44-
$x = (new Tween())
45-
->from("50")
46-
->to("100")
47-
->delay(Timing::seconds(1))
48-
->duration(Timing::milliseconds(300))
49-
->ease(Ease::OutSine);
50-
```
51-
52-
### Animation sequences using keyframes
53-
```php
54-
use ProjektGopher\FFMpegTools\Keyframe;
55-
use ProjektGopher\FFMpegTools\Timeline;
56-
use ProjektGopher\FFMpegTools\Timing;
57-
use ProjektGopher\FFMpegTools\Ease;
58-
59-
$x = new Timeline()
60-
$x->keyframe((new Keyframe)
61-
->value('-text_w') // outside left of frame
62-
->hold(Timing::seconds(1))
63-
);
64-
$x->keyframe((new Keyframe)
65-
->value('(main_w/2)-(text_w/2)') // center
66-
->ease(Ease::OutElastic)
67-
->duration(Timing::seconds(1))
68-
->hold(Timing::seconds(3))
69-
);
70-
$x->keyframe((new Keyframe)
71-
->value('main_w') // outside right of frame
72-
->ease(Ease::InBack)
73-
->duration(Timing::seconds(1))
74-
);
75-
```
76-
77-
> **Note** `new Timeline()` returns a _fluent_ api, meaning methods can be chained as well.
78-
79-
## Expression Helpers
80-
When writing _long_ and **complicated** evaluated expressions, it can be easy to lose track of extra/missing perentheses, missing parameters, or unescaped commas. Especially when the whole expression _has_ to be on one line without any linebreaks or whitespace.
81-
82-
The `Expr` class can help with this. If your expression is short enough this might be overkill, but for longer expressions this can really help with these issues.
83-
84-
```diff
85-
+ use ProjektGopher\FFMpegTools\Utils\Expr;
86-
87-
....
88-
89-
- return "if(eq(({$time})\\,0)\\,0\\,if(eq(({$time})\\,1)\\,1\\,pow(2\\,-10*({$time}))*sin((({$time})*10-0.75)*{$c4})+1))";
90-
+ return Expr::if(
91-
+ x: Expr::eq($time, '0'),
92-
+ y: '0',
93-
+ z: Expr::if(
94-
+ x: Expr::eq($time, '1'),
95-
+ y: '1',
96-
+ z: "pow(2\\,-10*({$time}))*sin((({$time})*10-0.75)*{$c4})+1",
97-
+ ),
98-
+ );
99-
```
100-
101-
## Docs
102-
Here's some more detailed information on some of this package's features:
103-
[Filter Graphs](docs/FilterGraphs.md)
104-
10545
## Testing
106-
```bash
107-
composer test
108-
```
109-
110-
### Visual Snapshot Testing
111-
#### Easing
112-
To generate plots of all `Ease` methods, from the project root, run
113-
```bash
114-
./scripts/generateEasings
115-
```
116-
The 256x256 PNGs will be generated in the `tests/Snapshots/Easings` directory.
117-
These snapshots will be ignored by git, but allow visual inspection of the plots to
118-
compare against known good sources, like [Easings.net](https://easings.net).
119-
120-
#### Timelines
121-
To generate a video using a `Timeline` with `Keyframes`, from the project root, run
122-
```bash
123-
./scripts/generateTimeline
124-
```
125-
The 256x256 MP4 will be generated in the `tests/Snapshots/Timelines` directory.
126-
These snapshots will also be ignored by git, but again allow for a visual
127-
inspection to ensure they match the expected output.
128-
129-
> **Note** The `scripts` directory _may_ need to have its permissions changed to allow script execution
130-
```bash
131-
chmod -R 777 ./scripts
132-
```
46+
- [Instructions](docs/Testing.md)
13347

13448
## Changelog
135-
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
49+
Please see [RELEASES](releases) for more information on what has changed recently.
13650

13751
## Contributing
13852
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

‎docs/Easing.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Easing

‎docs/Expressions.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Expression Helpers
2+
When writing _long_ and **complicated** evaluated expressions, it can be easy to lose track of extra/missing perentheses, missing parameters, or unescaped commas. Especially when the whole expression _has_ to be on one line without any linebreaks or whitespace.
3+
4+
The `Expr` class can help with this. If your expression is short enough this might be overkill, but for longer expressions this can really help with these issues. The named arguments aren't strictly necessary, but can help keep things more obviously in-line with the provided documentation which has been ported directly from the FFMpeg documentation.
5+
6+
> **note** Currently only the `eq`, `gt`, `if`, and `lt`, have been implemented.
7+
8+
## Example Diff
9+
```diff
10+
+ use ProjektGopher\FFMpegTools\Utils\Expr;
11+
12+
....
13+
14+
- return "if(eq(({$time})\\,0)\\,0\\,if(eq(({$time})\\,1)\\,1\\,pow(2\\,-10*({$time}))*sin((({$time})*10-0.75)*{$c4})+1))";
15+
+ return Expr::if(
16+
+ x: Expr::eq($time, '0'),
17+
+ y: '0',
18+
+ z: Expr::if(
19+
+ x: Expr::eq($time, '1'),
20+
+ y: '1',
21+
+ z: "pow(2\\,-10*({$time}))*sin((({$time})*10-0.75)*{$c4})+1",
22+
+ ),
23+
+ );
24+
```

‎docs/Filters.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Filters

‎docs/Testing.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## Testing
2+
```bash
3+
composer test
4+
```
5+
6+
### Visual Snapshot Testing
7+
#### Easing
8+
To generate plots of all `Ease` methods, from the project root, run
9+
```bash
10+
./scripts/generateEasings
11+
```
12+
The 256x256 PNGs will be generated in the `tests/Snapshots/Easings` directory.
13+
These snapshots will be ignored by git, but allow visual inspection of the plots to
14+
compare against known good sources, like [Easings.net](https://easings.net).
15+
16+
#### Timelines
17+
To generate a video using a `Timeline` with `Keyframes`, from the project root, run
18+
```bash
19+
./scripts/generateTimeline
20+
```
21+
The 256x256 MP4 will be generated in the `tests/Snapshots/Timelines` directory.
22+
These snapshots will also be ignored by git, but again allow for a visual
23+
inspection to ensure they match the expected output.
24+
25+
> **Note** The `scripts` directory _may_ need to have its permissions changed to allow script execution
26+
```bash
27+
chmod -R 777 ./scripts
28+
```

‎docs/Timelines.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Timelines and Keyframes
2+
3+
## Animation sequences using keyframes
4+
```php
5+
use ProjektGopher\FFMpegTools\Keyframe;
6+
use ProjektGopher\FFMpegTools\Timeline;
7+
use ProjektGopher\FFMpegTools\Timing;
8+
use ProjektGopher\FFMpegTools\Ease;
9+
10+
$x = new Timeline()
11+
$x->keyframe((new Keyframe)
12+
->value('-text_w') // outside left of frame
13+
->hold(Timing::seconds(1))
14+
);
15+
$x->keyframe((new Keyframe)
16+
->value('(main_w/2)-(text_w/2)') // center
17+
->ease(Ease::OutElastic)
18+
->duration(Timing::seconds(1))
19+
->hold(Timing::seconds(3))
20+
);
21+
$x->keyframe((new Keyframe)
22+
->value('main_w') // outside right of frame
23+
->ease(Ease::InBack)
24+
->duration(Timing::seconds(1))
25+
);
26+
```
27+
28+
> **Note** `new Timeline()` returns a _fluent_ api, meaning methods can be chained as well.

‎docs/Tweening.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Tweening
2+
3+
## Simple tween with delay and duration
4+
```php
5+
use ProjektGopher\FFMpegTools\Tween;
6+
use ProjektGopher\FFMpegTools\Timing;
7+
use ProjektGopher\FFMpegTools\Ease;
8+
9+
$x = (new Tween())
10+
->from("50")
11+
->to("100")
12+
->delay(Timing::seconds(1))
13+
->duration(Timing::milliseconds(300))
14+
->ease(Ease::OutSine);
15+
```

0 commit comments

Comments
 (0)