diff --git a/web/project-website/content/usage/variables/_index.md b/web/project-website/content/usage/variables/_index.md index ef645fff..1b0eec84 100644 --- a/web/project-website/content/usage/variables/_index.md +++ b/web/project-website/content/usage/variables/_index.md @@ -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`. diff --git a/web/project-website/content/usage/variables/blender.md b/web/project-website/content/usage/variables/blender.md new file mode 100644 index 00000000..04c37dc8 --- /dev/null +++ b/web/project-website/content/usage/variables/blender.md @@ -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 diff --git a/web/project-website/content/usage/variables/ffmpeg.md b/web/project-website/content/usage/variables/ffmpeg.md new file mode 100644 index 00000000..d1b60c9f --- /dev/null +++ b/web/project-website/content/usage/variables/ffmpeg.md @@ -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. diff --git a/web/project-website/content/usage/variables/multi-platform.md b/web/project-website/content/usage/variables/multi-platform.md new file mode 100644 index 00000000..64008158 --- /dev/null +++ b/web/project-website/content/usage/variables/multi-platform.md @@ -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`.