Add additional detail about host lists and install

README.md

@@ -28,11 +28,73 @@ The `rffmpeg.yml.sample` is self-documented for the most part. Some additional i
 
 rffmpeg supports setting multiple hosts. It keeps state in `/run/shm/rffmpeg` of all running processes, and these state files are used during rffmpeg's initialization in order to determine the optimal target host. rffmpeg will run through these hosts sequentially, choosing the one with the fewest running rffmpeg jobs. This helps distribute the transcoding load across multiple servers, and can also provide redundancy if one of the servers is offline - rffmpeg will detect if a host is unreachable and set it "bad" for the remainder of the run, thus skipping it until the process completes.
 
-Hosts can also be assigned weights (see `rffmpeg.yml.sample` for an example) that allow the host to take on that many times the number of active processes versus weight-1 hosts. The `rffmpeg` process does a floor division of the number of active processes on a host with that host weight to determine its "weighted [process] count", which is then used instead to determine the lease-loaded host to use.
+Hosts can also be assigned weights (see `rffmpeg.yml.sample` for an example) that allow the host to take on that many times the number of active processes versus weight-1 hosts. The `rffmpeg` process does a floor division of the number of active processes on a host with that host weight to determine its "weighted [process] count", which is then used instead to determine the lease-loaded host to use. Note that `rffmpeg` does not take into account actual system load, etc. when determining which host to use; it treats each running command equally regardless of how intensive it actually is.
 
-Note that `rffmpeg` does not take into account actual system load, etc. when determining which host to use; it treats each running command equally regardless of how intensive it actually is.
+#### Host lists
 
-### Localhost and fallback
+Hosts are specified as a YAML list in the relevant section of `rffmpeg.yml`, with one list entry per target. A single list entry can be specfied in one of two ways. Either a direct list value of the hostame/IP:
+
+```
+- myhostname.domain.tld
+```
+
+Or as a fully expanded `name:`/`weight:` pair.
+
+```
+- name: myhostname.domain.tld
+  weight: 2
+```
+
+The first, direct list value formatting implies `weight: 1`. Examples of both styles can be found in the same configuration.
+
+You can get creative with this list, especially since `rffmpeg` always checks the list in order to find the next available host. For an example of a complex setup, if you had 3 hosts, and wanted 1+2+2 processes, the following would be the default way to acheive this:
+
+```
+- name: host1
+  weight: 1
+- name: host2
+  weight: 2
+- name: host3
+  weight: 2
+```
+
+This would however spread processes out like this, which might work well, but might not for some usecases:
+
+```
+proc1: host1
+proc2: host2
+proc3: host2
+proc4: host3
+proc5: host3
+proc6: host1
+etc.
+```
+
+You could instead specify the hosts like this:
+
+```
+- host1
+- host2
+- host3
+- host2
+- host3
+```
+
+Which would instead give a process spread like:
+
+```
+proc1: host1
+proc2: host2
+proc3: host3
+proc4: host2
+proc5: host3
+proc6: host1
+etc.
+```
+
+Experiment with the ordering based on your load and usecase.
+
+#### Localhost and fallback
 
 If one of the hosts in the config file is called "localhost", rffmpeg will run locally without SSH. This can be useful if the local machine is also a powerful transcoding device.
 

SETUP.md

@@ -48,27 +48,33 @@ 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.yml` in the next step. 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).
 
-1. Install the `rffmpeg` utility. First, create a directory for the configuration at `/etc/rffmpeg`, copy `rffmpeg.yml.sample` to `/etc/rffmpeg/rffmpeg.yml` and edit it to suit your needs. Then install the actual `rffmpeg.py` binary somewhere (I recommend `/usr/local/bin`) and make it executable. Finally, create symlinks so that the names `ffmpeg` and `ffprobe` map to the `rffmpeg.py` binary.
+1. Install the required dependencies of `rffmpeg`:
+
+   ```
+   jellyfin1 $ sudo apt -y install python3-yaml
+   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.
+
+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.
 
    ```
    jellyfin1 $ git clone https://github.com/joshuaboniface/rffmpeg  # or download the files manually
-   jellyfin1 $ sudo mkdir -p /etc/rffmpeg
-   jellyfin1 $ sudo cp rffmpeg/rffmpeg.yml.sample /etc/rffmpeg/rffmpeg.yml
-   jellyfin1 $ sudo $EDITOR /etc/rffmpeg/rffmpeg.yml  # edit it to suit your needs
    jellyfin1 $ sudo cp rffmpeg/rffmpeg.py /usr/local/bin/rffmpeg.py
    jellyfin1 $ sudo chmod +x /usr/local/bin/rffmpeg.py
    jellyfin1 $ sudo ln -s /usr/local/bin/rffmpeg.py /usr/local/bin/ffmpeg
    jellyfin1 $ sudo ln -s /usr/local/bin/rffmpeg.py /usr/local/bin/ffprobe
    ```
 
-1. Install the required dependencies of `rffmpeg`:
-
+1. Create a directory for the `rffmpeg` configuration at `/etc/rffmpeg`, then copy `rffmpeg.yml.sample` to `/etc/rffmpeg/rffmpeg.yml` and edit it to suit your needs.
    ```
-   jellyfin1 $ sudo apt -y install python3-yaml
-   jellyfin1 $ sudo apt -y install python3-subprocess
+   jellyfin1 $ sudo mkdir -p /etc/rffmpeg
+   jellyfin1 $ sudo cp rffmpeg/rffmpeg.yml.sample /etc/rffmpeg/rffmpeg.yml
+   jellyfin1 $ sudo $EDITOR /etc/rffmpeg/rffmpeg.yml  # edit it to suit your needs
    ```
 
-   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.
+   Generally, if you're following this guide exactly, the only part that needs to be modified is the `rffmpeg` -> `remote` -> `hosts` section, where you define the target hosts. For more detail on weights, see the main [README.md](README.md#remote-hosts).
 
 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.