blender/flamenco
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Website: split up variables section & adjust for argument split

Browse Source 
Split up the "Variables" section, and adjust the wording for the splitting
of `{blender}` into `{blender}` and `{blenderArgs}` (rFe5a20425c474).
This commit is contained in:
Sybren A. Stüvel 2022-08-30 17:56:38 +02:00
parent 5634ed3a6b
commit d88587f989
4 changed files with 144 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
web/project-website/content/usage/variables/_index.md
View File

@ -1,5 +1,5 @@
---
title: Variables & Multi-Platform Support
title: Variables
weight: 2
---
@ -8,7 +8,7 @@ mixed-platform render farms, Flamenco uses *variables*.
Each variable consists of:
- Its **name**: just a sequence of letters, like `ffmpeg` or `whateveryouwant`.
- Its **name**: just a sequence of letters, like `blender` or `whateveryouwant`.
- Its **values**: per *platform* and *audience*, described below.
The variables are configured in `flamenco-manager.yaml`.
@ -20,15 +20,25 @@ variables:
blender:
values:
- platform: linux
value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender -b -y
value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender
- platform: windows
value: B:\Downloads\blenders\blender-3.2.2-release\blender.exe -b -y
value: B:\Downloads\blenders\blender-3.2.2-release\blender.exe
- platform: darwin
value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender -b -y
value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender
```
Whenever a Worker gets a task that contains the string `{blender}`, that'll be
replaced by the appropriate value for that worker.
Whenever a Worker gets a task that contains `{blender}`, that'll be replaced by
the appropriate value for that worker.
{{< hint type=note title="Custom Job Types" >}}
This documentation section focuses on pre-existing variables, `blender` and
`blenderArgs`. There is nothing special about these. Apart from being part of
Flamenco's default configuration, that is. When you go the more advanced route
of creating your own [custom job types][jobtypes] you're free to create your own
set of variables to suit your needs.
[jobtypes]: {{< ref "usage/job-types" >}}
{{< /hint >}}
## Platform
@ -40,16 +50,6 @@ on the platform. The variables system allows you to configure this.
The platform can be `windows`, `linux`, or `darwin` for macOS. Other platforms
are also allowed, if you happen to use them in your farm.
{{< hint type=note title="Custom Job Types" >}}
This documentation section focuses on pre-existing variables, `blender` and
`ffmpeg`. There is nothing special about these. Apart from being part of
Flamenco's default configuration, that is. When you go the more advanced route
of creating your own [custom job types][jobtypes] you're free to create your own
set of variables to suit your needs.
[jobtypes]: {{< ref "usage/job-types" >}}
{{< /hint >}}
## Audience
The audience of a value is who that value is for: `workers`, `users`, or `all`
@ -64,126 +64,3 @@ might be different from where users go to pick them up.
- `users`: values are used when submitting jobs from Blender and showing them in
the web interface.
- `workers`: values that are used when sending tasks to workers.
## Blender and FFmpeg
The location of Blender and FFmpeg on the Worker, as well as their default
arguments, can be configured via the `blender` and `ffmpeg` variables.
- If the Blender or FFmpeg location is just plain `blender` resp. `ffmpeg`, the
worker will try and find those by itself. How this is done is different for
the two programs, and explained below.
- In other cases, it is assumed to be a path and the worker will just use it as
configured.
### Blender
The built-in [job types][jobtypes] use `{blender}` instead of hard-coding a
particular command. This makes it possible to configure your own Blender
command. The Worker has a few strategies for finding Blender, described below.
[jobtypes]: {{< ref "usage/job-types" >}}
#### Just `blender`
If the command is configured to be just `blender` with some arguments, for
example `blender -b -y`, some "smartness" will kick in. It will pick the first
Blender it finds in this order:
1. On Windows, the worker will figure out which Blender is associated with blend
files. In other words, it will run whatever Blender runs when you
double-click a `.blend` file. On other platforms this step is skipped.
2. The locations listed in the `PATH` environment variable are searched to find
Blender. This should run whatever Blender starts when you enter the `blender`
command in a shell.
3. If none of the above result in a usable Blender, the worker will fail its task.
#### An explicit path
If the command is configured to anything other than `blender` (arguments
excluded), it is assumed to be a path to the Blender executable. For an example,
see the top of this page.
### FFmpeg
Similar to `{blender}`, described above, the `{ffmpeg}` variable can be used to
configure both which FFmpeg executable to use, and which additional parameters
to pass.
#### Just `ffmpeg`
If the command is configured to be just `ffmpeg` with some arguments, for
example `ffmpeg -hide_banner`, the worker will try to use the bundled FFmpeg.
This is the default behavior, so if you do not have any `ffmpeg` variable
defined, this is what will happen.
The worker looks next to the `flamenco-worker` executable for a `tools`
directory. Given the current OS (`windows`, `linux`, `darwin`, etc.) and
architecture (`amd64`, `x86`, etc.) it will try to find the most-specific one
for your system in that `tools` directory.
The worker tries the following ones; the first one found is used:
1. `ffmpeg-OS-ARCHITECTURE`, for example `ffmpeg-windows-amd64.exe` or `ffmpeg-linux-x86`
2. `ffmpeg-OS`, for example `ffmpeg-windows.exe` or `ffmpeg-linux`
3. `ffmpeg`, so `ffmpeg.exe` on Windows and `ffmpeg` on any other platform.
#### An explicit path
If the command is configured to anything other than `ffmpeg` (arguments
excluded), it is assumed to be a path to the FFmpeg executable.
Example configuration from `flamenco-manager.yaml`:
```yaml
variables:
ffmpeg:
values:
- platform: linux
value: /media/shared/tools/ffmpeg-5.0/ffmpeg-linux
- platform: windows
value: S:\tools\ffmpeg-5.0\ffmpeg.exe
- platform: darwin
value: /Volumes/shared/tools/ffmpeg-5.0/ffmpeg-macos
```
## Two-way Variables
Two-way variables are there to support mixed-platform Flamenco farms. Basically
they perform *path prefix replacement*.
Let's look at an example configuration:
```yaml
variables:
shared_storage:
is_twoway: true
values:
- platform: linux
value: /media/shared/flamenco
- platform: windows
value: F:\flamenco
- platform: darwin
value: /Volumes/shared/flamenco
```
The difference with regular variables is that regular variables are one-way, so
only `{variablename}` is replaced with the value. Two-way variables go both ways, as follows:
- When submitting a job from a Linux workstation, `/media/shared/flamenco` (the
variable's value for Linux) will be replaced with `{shared_storage}`.
- When sending a task for this job to a Windows worker, `{shared_storage}` will
be replaced with `F:\flamenco`.
Let's look at a more concrete example, with the same configuration as above.
- Alice runs Blender on **macOS**. She submits a job that has its render output set
to `/Volumes/shared/flamenco/renders/shot_010_a_anim`.
- Flamenco recognises the path, and stores the job as rendering to
`{shared_storage}/renders/shot_010_a_anim`.
- Bob's computer is running the Worker on **Windows**, so when it receives a render
task Flamenco will tell it to render to
`F:\flamenco\renders\shot_010_a_anim`.
- Carol's computer is also running a worker, but on **Linux**. When it receives a
render task, Flamenco will tell it to render to
`/media/shared/flamenco/renders/shot_010_a_anim`.

61
web/project-website/content/usage/variables/blender.md Normal file
View File

@ -0,0 +1,61 @@
---
title: Blender
---
The location of Blender *on the Worker*, as well as its default arguments, can be
configured via the `blender` and `blenderArgs` variables.
- If the Blender location is just plain `blender`, the worker will try and find
those by itself. How this is done is different for the two programs, and
explained below.
- In other cases, it is assumed to be a path and the worker will just use it as
configured.
Here is an example configuration, which is part of `flamenco-manager.yaml`:
```yaml
variables:
blender:
values:
- platform: linux
value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender
- platform: windows
value: B:\Downloads\blenders\blender-3.2.2-release\blender.exe
- platform: darwin
value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender
blenderArgs:
values:
- platform: all
value: -b -y
```
## Just `blender`
If the `{blender}` variable is configured to be just `blender` some "smartness"
will kick in. It will pick the first Blender it finds in this order:
1. On Windows, the worker will figure out which Blender is associated with blend
files. In other words, it will run whatever Blender runs when you
double-click a `.blend` file. On other platforms this step is skipped.
2. The locations listed in the `PATH` environment variable are searched to find
Blender. This should run whatever Blender starts when you enter the `blender`
command in a shell.
3. If none of the above result in a usable Blender, the worker will fail its task.
## An explicit path
If the command is configured to anything other than `blender`, it is assumed to
be a path to the Blender executable.
## Setting Arguments
The `{blenderArgs}` variable can be used to provide arguments to Blender that
are used on every invocation. Flamenco uses these by default:
- `-b`: run Blender in the background, so that it doesn't pop up a window.
- `-y`: allow executing Python code without any confirmation, which is often
necessary for production rigs to work.
More can be found in Blender's [Command Line Arguments documentation][blendcli].
[blendcli]: https://docs.blender.org/manual/en/latest/advanced/command_line/arguments.html

18
web/project-website/content/usage/variables/ffmpeg.md Normal file
View File

@ -0,0 +1,18 @@
---
title: FFmpeg
---
FFmpeg is bundled with Flamenco, and at the moment it cannot be configured to
use any other install of FFmpeg. This is intended to be added in some future,
but there is no timeline when this will happen (patches welcome!).
The worker looks next to the `flamenco-worker` executable for a `tools`
directory. Given the current OS (`windows`, `linux`, `darwin`, etc.) and
architecture (`amd64`, `x86`, etc.) it will try to find the most-specific one
for your system in that `tools` directory.
The worker tries the following ones; the first one found is used:
1. `ffmpeg-OS-ARCHITECTURE`, for example `ffmpeg-windows-amd64.exe` or `ffmpeg-linux-x86`
2. `ffmpeg-OS`, for example `ffmpeg-windows.exe` or `ffmpeg-linux`
3. `ffmpeg`, so `ffmpeg.exe` on Windows and `ffmpeg` on any other platform.

48
web/project-website/content/usage/variables/multi-platform.md Normal file
View File

@ -0,0 +1,48 @@
---
title: Two-way Variables for Multi-Platform Support
---
Two-way variables are there to support mixed-platform Flamenco farms. Basically
they perform *path prefix replacement*.
Let's look at an example configuration:
```yaml
variables:
my_storage:
is_twoway: true
values:
- platform: linux
value: /media/shared/flamenco
- platform: windows
value: F:\flamenco
- platform: darwin
value: /Volumes/shared/flamenco
```
The difference with regular variables is that regular variables are one-way:
`{variablename}` is replaced with the value, and that's it.
Two-way variables go both ways, as follows:
- When submitting a job, values are replaced with variables.
- When sending a task to a worker, variables are replaced with values again.
This may seem like a lot of unnecessary work. After all, why go through the
trouble of replacing in one direction, when later the opposite is done? The
power lies in the fact that each replacement step can target a different
platform. In the first step the value for Linux can be recognised, and in the
second step the value for Windows can be put in its place.
Let's look at a more concrete example, based on the configuration shown above.
- Alice runs Blender on **macOS**. She submits a job that has its render output set
to `/Volumes/shared/flamenco/renders/shot_010_a_anim`.
- Flamenco recognises the path, and stores the job as rendering to
`{my_storage}/renders/shot_010_a_anim`.
- Bob's computer is running the Worker on **Windows**, so when it receives a render
task Flamenco will tell it to render to
`F:\flamenco\renders\shot_010_a_anim`.
- Carol's computer is also running a worker, but on **Linux**. When it receives a
render task, Flamenco will tell it to render to
`/media/shared/flamenco/renders/shot_010_a_anim`.