Mirrors/rffmpeg
1
0
Fork 0
mirror of https://github.com/joshuaboniface/rffmpeg.git synced 2026-01-23 02:24:03 +00:00
Code Issues Projects Releases Packages Wiki Activity

Reformat and refactor setup guide further

Browse source
This commit is contained in:
Joshua M. Boniface 2022-07-20 03:07:48 -04:00
parent 3291f5edf3
commit 1006583fff
2 changed files with 47 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

12
README.md
View file

@ -74,7 +74,7 @@ If one of the hosts in the config file is called "localhost", `rffmpeg` will run
In addition, `rffmpeg` will fall back to "localhost" should it be unable to find any working remote hosts. This helps prevent situations where `rffmpeg` cannot be run due to none of the remote host(s) being available.
In both cases, note that, if hardware acceleraton is configured, it *must* be available on the local host as well, or the `ffmpeg` commands will fail. There is no easy way around this without rewriting arguments, and this is currently out-of-scope for `rffmpeg`. You should always use a lowest-common-denominator approach when deciding on what additional option(s) to enable, such that any configured host can run any process.
In both cases, note that, if hardware acceleration is configured, it *must* be available on the local host as well, or the `ffmpeg` commands will fail. There is no easy way around this without rewriting arguments, and this is currently out-of-scope for `rffmpeg`. You should always use a lowest-common-denominator approach when deciding on what additional option(s) to enable, such that any configured host can run any process.
The exact path to the local `ffmpeg` and `ffprobe` binaries can be overridden in the configuration, should their paths not match those of the remote system(s).
@ -84,7 +84,7 @@ When more than one target host is present, `rffmpeg` uses the following rules to
1. Any hosts marked `bad` are ignored.
1. All remaining hosts are iterated through in an indetermine order (Python dictionary with root key as the host ID). For each host:
1. All remaining hosts are iterated through in an indeterminate order (Python dictionary with root key as the host ID). For each host:
a. If the host is not `localhost`/`127.0.0.1`, it is tested to ensure it is reachable (responds to `ffmpeg -version` over SSH). If it is not reachable, it is marked `bad` for the duration of this processes' runtime and skipped.
@ -100,7 +100,7 @@ When adding a host to `rffmpeg`, a weight can be specified. Weights are used dur
For example, consider two hosts: `host1` with weight 1, and `host2` with weight 5. `host2` would have its actual number of processes floor divided by `5`, and thus any number of processes under `5` would count as `0`, any number of processes between `5` and `10` would count as `1`, and so on, resulting in `host2` being chosen over `host1` even if it had several processes. Thus, `host2` would on average handle 5x more `ffmpeg` processes than `host1` would.
Host weighting is a fairly blunt instrument, and only becomes important when many simultaneous `ffmpeg` processes/transcodes are occurring at once, and where the target hosts have very different performance profiles. Generally leaving all hosts at weight 1 would be sufficient for most usecases.
Host weighting is a fairly blunt instrument, and only becomes important when many simultaneous `ffmpeg` processes/transcodes are occurring at once, and where the target hosts have very different performance profiles. Generally leaving all hosts at weight 1 would be sufficient for most use-cases.
Furthermore, it is possible to add a host of the same name more than once in the `rffmpeg add` command. This has a very similar, but subtly different, effect from setting a higher weight. A host present in the list is more likely to be seen before another host, and thus this can further influence the desired target.
@ -110,7 +110,7 @@ As mentioned above under [Target Host Selection](README.md#target-host-selection
Once a host is marked `bad`, it will remain so for as long as the `rffmpeg` process that marked it `bad` is running. This can last from a few seconds to several tens of minutes. During this time, any new `rffmpeg` processes that start will see the host marked as `bad` and thus skip it for target selection. Once the marking `rffmpeg` process completes or is terminated, the `bad` status of that host will be cleared, allowing the next run to try it again. This strikes a balance between always retrying known-unresponsive hosts over and over (and thus delaying process startup), and ensuring that hosts will eventually be retried.
If for some reason all configured hosts are marked `bad`, fallback will be engaged; see the above section [Localhost and Fallback](README.md#localhost-and-fallback) for details on what occurrs in this situation. An explicit `localhost` host entry cannot be marked `bad`.
If for some reason all configured hosts are marked `bad`, fallback will be engaged; see the above section [Localhost and Fallback](README.md#localhost-and-fallback) for details on what occurs in this situation. An explicit `localhost` host entry cannot be marked `bad`.
## FAQ
@ -138,11 +138,11 @@ This has a number of side effects:
* `rffmpeg` does not know what media is playing or where it's outputting files to, and cannot alter these paths.
* `rffmpeg` cannot turn on or off special `ffmpeg` options depending on the host selected.
Thus it is imperitive that you set up your entire system correctly for `rffmpeg` to work. Please see the [SETUP guide](SETUP.md) for more information.
Thus it is imperative that you set up your entire system correctly for `rffmpeg` to work. Please see the [SETUP guide](SETUP.md) for more information.
### Can `rffmpeg` do Wake-On-LAN or other similar options to turn on a transcode server?
Right now, no. I've thought about implementing this more than once (most recently, in response to [Issue #21](https://github.com/joshuaboniface/rffmpeg/issues/21)) but ultimately I've never though this was worth the complexity and delays in spwaning that it would add to the tool. That issue does provide one example of a workaround wrapper script that could accomplish this, but I don't see it being a part of the actual tool itself.
Right now, no. I've thought about implementing this more than once (most recently, in response to [Issue #21](https://github.com/joshuaboniface/rffmpeg/issues/21)) but ultimately I've never though this was worth the complexity and delays in spawning that it would add to the tool. That issue does provide one example of a workaround wrapper script that could accomplish this, but I don't see it being a part of the actual tool itself.
### I'm getting an error, help!

66
SETUP.md
View file

@ -6,6 +6,8 @@ This guide is provided as a basic starting point - there are myriad possible com
## Set up the media server (`jellyfin1`)
### Basic Setup
1. Install Jellyfin (or similar FFMPEG-using media server) on your machine. This guide assumes you're using native `.deb` packages.
1. Make note of the Jellyfin service user's details, specifically the UID and any groups (and GIDs) it is a member of; this will be needed later on.
@ -50,6 +52,8 @@ This guide is provided as a basic starting point - there are myriad possible com
* **NOTE:** Ensure you use the exact name here that you will use in `rffmpeg`. If this is an FQDN (e.g. `jellyfin1.mydomain.tld`) or an IP (e.g. `192.168.0.101`) instead of a short name, use that instead in this command, or repeat it for every possible option (it doesn't hurt).
### `rffmpeg` Setup
1. Install the required Python3 dependencies of `rffmpeg`:
```
@ -58,9 +62,9 @@ This guide is provided as a basic starting point - there are myriad possible com
jellyfin1 $ sudo apt -y install python3-subprocess
```
Note: On some Ubuntu versions, `python3-subprocess` does not exist, and should instead be part of the Python standard library. Skip installing this package if it can't be found.
* **NOTE:** On some Ubuntu versions, `python3-subprocess` does not exist, and should instead be part of the Python standard library. Skip installing this package if it can't be found.
1. Clone the `rffmpeg` repository somewhere ont he system, then install the `rffmpeg` binary, make it executable, and prepare symlinks for the command names `ffmpeg` and `ffprobe` to it. I recommend storing these in `/usr/local/bin` for simplicity.
1. Clone the `rffmpeg` repository somewhere onto the system, then install the `rffmpeg` binary, make it executable, and prepare symlinks for the command names `ffmpeg` and `ffprobe` to it. I recommend storing these in `/usr/local/bin` for simplicity and so that they are present on the default `$PATH` for most users.
```
jellyfin1 $ git clone https://github.com/joshuaboniface/rffmpeg # or download the files manually
@ -78,13 +82,17 @@ This guide is provided as a basic starting point - there are myriad possible com
jellyfin1 $ sudo $EDITOR /etc/rffmpeg/rffmpeg.yml # if required
```
1. Initialize `rffmpeg` (note the `sudo` command) and add at least one remote host to it. You can add multiple hosts now or later, set weights of hosts, and add a host more than once. For full details see the [main README](README.md).
1. Initialize `rffmpeg` (note the `sudo` command) and add at least one remote host to it. You can add multiple hosts now or later, set weights of hosts, and add a host more than once. For full details see the [main README](README.md) or run `rffmpeg --help` to view the CLI help menu.
```
jellyfin1 $ sudo rffmpeg init --yes
jellyfin1 $ rffmpeg add --weight 1 gpu1
```
### NFS Setup
* **WARNING:** This guide assumes your hosts are on the same private local network. It is not recommended to run NFS over the Internet as it is unencrypted and bandwidth-intensive. Consider other remote filesystems like SSHFS in such cases as these will offer greater privacy and robustness.
1. Install the NFS kernel server. We will use NFS to export the various required directories so the transcode machine can read from and write to them.
```
@ -128,6 +136,14 @@ This guide is provided as a basic starting point - there are myriad possible com
1. Install the `jellyfin-ffmpeg` (Jellyfin <= 10.7.7) or `jellyfin-ffmpeg5` (Jellyfin >= 10.8.0) package; follow the same steps as you would to install Jellyfin on the media server, only don't install `jellyfin` (and `jellyfin-server`/`jellyfin-web`) itself, just `jellyfin-ffmpeg[5]`.
```
transcode1 $ sudo apt -y install curl gnupg
transcode1 $ curl -fsSL https://repo.jellyfin.org/ubuntu/jellyfin_team.gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/jellyfin.gpg
transcode1 $ echo "deb [arch=$( dpkg --print-architecture )] https://repo.jellyfin.org/$( awk -F'=' '/^ID=/{ print $NF }' /etc/os-release ) $( awk -F'=' '/^VERSION_CODENAME=/{ print $NF }' /etc/os-release ) main" | sudo tee /etc/apt/sources.list.d/jellyfin.list
transcode1 $ sudo apt update
transcode1 $ sudo apt install jellyfin-ffmpeg5 # or jellyfin-ffmpeg with Jellyfin <= 10.7.7
```
1. Install the NFS client utilities:
```
@ -152,7 +168,7 @@ This guide is provided as a basic starting point - there are myriad possible com
transcode1 $ sudo chattr +i ${jellyfin_data_path}
```
* Don't worry about permissions here; the mount will set those.
* **NOTE:** Don't worry about permissions here; the mount will set those.
1. Create the NFS client mount. There are two main ways to do this:
@ -165,31 +181,31 @@ This guide is provided as a basic starting point - there are myriad possible com
* Use a SystemD `mount` unit, which is a newer way of doing mounts with SystemD. I personally prefer this method as I find it easier to set up automatically, but this is up to preference. An example based on mine would be:
```
transcode1 $ cat /etc/systemd/system/var-lib-jellyfin.mount
[Unit]
Description = NFS volume for Jellyfin data directory
Requires = network-online.target
After = network-online.target
```
transcode1 $ cat /etc/systemd/system/var-lib-jellyfin.mount
[Unit]
Description = NFS volume for Jellyfin data directory
Requires = network-online.target
After = network-online.target
[Mount]
type = nfs
What = jellyfin1:/var/lib/jellyfin
Where = /var/lib/jellyfin
Options = _netdev,sync,vers=3
[Mount]
type = nfs
What = jellyfin1:/var/lib/jellyfin
Where = /var/lib/jellyfin
Options = _netdev,sync,vers=3
[Install]
WantedBy = remote-fs.target
```
[Install]
WantedBy = remote-fs.target
```
Once the unit file is created, you can then reload the unit list and mount it:
Once the unit file is created, you can then reload the unit list and mount it:
```
transcode1 $ sudo systemctl daemon-reload
transcode1 $ sudo systemctl start var-lib-jellyfin.mount
```
```
transcode1 $ sudo systemctl daemon-reload
transcode1 $ sudo systemctl start var-lib-jellyfin.mount
```
Note that mount units are fairly "new" and can be a bit finicky, be sure to read the SystemD documentation if you get stuck! Generally for new users, I'd recommend the `/etc/fstab` method instead.
Note that mount units are fairly "new" and can be a bit finicky, be sure to read the SystemD documentation if you get stuck! Generally for new users, I'd recommend the `/etc/fstab` method instead.
1. Mount your media directories in the same location(s) as on the media server. If you exported them via NFS from your media server, use the process above only for those directories instead.
@ -229,7 +245,7 @@ As long as these steps work, all further steps should as well.
1. Try to play a movie that requires transcoding, and verify that everything is working as expected.
## NOTE for NVEnv/NVDec HWA
## NOTE for NVEnv/NVDec Hardware Acceleration
If you are using NVEnv/NVDec, it's probably a good idea to symlink the `.nv` folder inside the Jellyfin user's homedir (i.e. `/var/lib/jellyfin/.nv`) to somewhere outside of the NFS volume on both sides. For example: