rffmpeg is a remote FFmpeg wrapper used to execute FFmpeg commands on a remote server via SSH. It is most useful in situations involving media servers such as Jellyfin (our reference user), where one might want to perform transcoding actions with FFmpeg on a remote machine or set of machines which can better handle transcoding, take advantage of hardware acceleration, or distribute transcodes across multiple servers for load balancing.

Quick usage

1. Install the required Python 3 dependencies: click, yaml and subprocess (sudo apt install python3-click python3-yaml python3-subprocess in Debian).

2. Create the directory /etc/rffmpeg.

3. Copy the rffmpeg.yml.sample file to /etc/rffmpeg/rffmpeg.yml and edit it to suit your needs if required.

4. Install rffmpeg somewhere useful, for instance at /usr/local/bin/rffmpeg.

5. Create symlinks for the command names ffmpeg and ffprobe to rffmpeg, for example sudo ln -s /usr/local/bin/rffmpeg /usr/local/bin/ffmpeg and sudo ln -s /usr/local/bin/rffmpeg /usr/local/bin/ffprobe.

6. Initialize the database and add a target host, for example sudo rffmpeg init && rffmpeg add myhost.domain.tld.

7. Set your media program to use rffmpeg via the ffmpeg symlink name created above, instead of any other ffmpeg binary.

8. Profit!

rffmpeg does require a little bit more configuration to work properly however. For a comprehensive installation tutorial based on a reference setup, please see the SETUP guide.

Important Considerations

The rffmpeg Configuration file

The rffmpeg configuration file located at rffmpeg.yml.sample is an example that shows all default options. Even though this file is effectively "empty", it must be present at /etc/rffmpeg/rffmpeg.yml or at an alternative location specified by the environment variable RFFMPEG_CONFIG; the latter is only useful for testing, as media programs like Jellyfin provide no way to specify this.

To override a default option, simply uncomment the relevant line and adjust it to suit your needs. For those using Jellyfin and following the SETUP guide, no default options will need to be changed.

NOTE: If you are running into problems with rffmpeg, please adjust logging -> debug to true to obtain more detailed logs before requesting help.

Each option has an explanatory comment above it detailing its purpose.

Since the configuration file is YAML, ensure that you do not use "Tab" characters inside of it, only spaces.

Initializing rffmpeg

After first installing rffmpeg, ensure you initialize the database with the sudo rffmpeg init command. Note that sudo is required here to create the required data paths, but afterwards, rffmpeg can be run by anyone in the configured group (by default the sudo group).

rffmpeg is a Click-based application; thus, all commands have a -h or --help flag to show usage and additional options that may be specified.

Viewing Status

Once installed and initialized, the status of the rffmpeg system can be viewed with the command rffmpeg status. This will show all configured target hosts, their states, and any active commands being run.

Adding or Removing Target Hosts

To add a target host, use the command rffmpeg add. This command takes the optional -w/--weight flag to adjust the weight of the target host (see below). A host can be added more than once.

To remove a target host, use the command rffmpeg remove. This command takes either a target host name/IP, which affects all instances of that name, or a specific host ID. Removing an in-use target host will not terminate any running processes, though it may result in undefined behaviour within rffmpeg. Before removing a host it is best to ensure there is nothing using it.

Viewing the Logfile