The x264 encoding service

New in version 1.15.0.

Purpose 

The x264 encoding service is an open-source (local) TCP service that provides an asynchronous remote procedure call interface for AVC video encoding using the x264 library. It is distributed under the terms of the GNU General Public License version 2. Its source code, including the libraries implementing its communication protocol, can be found in the Unified Streaming media processing source repository.

The x264 plugin for AVC video encoding uses a running instance of the x264 encoding service as its encoding backend. Please see the media processing unit anatomy chapter for how the x264 encoding service is used in the context of a media processing unit.

Installation and configuration 

Alpine Linux 

Please ensure the right Unified Streaming apk package repository is included in your apk configuration, as described here.
Install the x264-encoding-service package:
```
sudo apk add x264-encoding-service
```

Start the x264 encoding service:

sudo rc-service x264_encoding_service start

The x264 encoding service should now be running, and openrc should start it automatically on boot.

You can check this by typing...
```
sudo rc-service x264_encoding_service status
```
...and:
```
sudo rc-update show
```

Debian and Ubuntu Linux 

Please ensure the right Unified Streaming deb package repository is included in your apt configuration, as described here.
Install the x264-encoding-service package:
```
sudo apt install x264-encoding-service
```
The x264 encoding service should now be running, and systemd should start it automatically on boot. You can check its status by typing:
```
sudo systemctl status x264_encoding_service
```

Rocky Linux, AlmaLinux, and Red Hat Enterprise Linux (RHEL)

Please ensure the right Unified Streaming rpm package repository is included in your rpm configuration, as described here.
Install the x264-encoding-service package:
```
sudo yum install x264-encoding-service
```
Tell systemd to start the x264 encoding service automatically on boot:
```
sudo systemctl enable x264_encoding_service
```

Start the x264 encoding service:

sudo systemctl start x264_encoding_service

The x264 encoding service should now be running. You can check its status by typing:
```
sudo systemctl status x264_encoding_service
```

Windows 

Install the libcuti, libx264-proto and x264-encoding-service packages, as described here.

From an administrator command prompt, create a registry entry for the x264 encoding service with the sc create command. For example, if your installation directory is C:\Program Files\Unified Streaming:
```
sc create x264_encoding_service binpath= "\"C:\Program Files\Unified Streaming\bin\x264_encoding_service.exe\" --config \"C:\Program Files\Unified Streaming\etc\x264_encoding_service.conf\"" start= auto
```
Note

Please note the spaces after the binpath= and start= stanzas, and the backslashes before the opening and closing double quotes in the filesystem paths.
If the x264 plugin for AVC video encoding will be used to serve remote transcoding requests, configure the service start-up order by adding a dependency of the Apache webserver on the x264 encoding service:
- First, use the sc qc command to retrieve the current dependencies of the Apache webserver:
```
sc qc Apache2.4
```
  Example output:
```
[SC] QueryServiceConfig SUCCESS

SERVICE_NAME: Apache2.4
        <...others elided...>
        DEPENDENCIES       : Tcpip
                           : AFD
```
- Then, use the sc config command to add the dependency on the x264_encoding_service:
```
sc config Apache2.4 depend= Tcpip/AFD/x264_encoding_service
```
  Note
  
  Please note the space after the depend= stanza, and the forward slashes between the individual dependencies.
  
  Warning
  
  The above command replaces the complete dependency set of the Apache2.4 service. Be sure not to lose the previously set dependencies reported by the sc qc command.
Start the service:
```
net start x264_encoding_service
```

The configuration file 

As installed, the x264 encoding service takes a command line option that causes it to read additional options from a user-maintained configuration file (/etc/x264_encdoding_service.conf on Linux, <your installation directory>\etc\x264_encoding_service.conf on Windows).

Note

Changes to the configuration file only take effect when the service is restarted.

Logging 

When run as a service/daemon, the x264 encoding service logs to the system event log by default.

If you are logging at a higher loglevel, such as info, it is probably more convenient to use a dedicated logfile for the x264 encoding service. For this, you can add the --logfile and --logfile-size-limit options to the configuration file of the x264 encoding service. For example:

--loglevel info
--logfile "<absolute path to log file>"
--logfile-size-limit 100000

Please ensure that the user account used by the x264 encoding service (as packaged: x264-es on Linux, LocalSystem on Windows) has the required permissions in the logfile's directory.

Command line options reference 

Printing a summary 

Assuming the x264_encoding_service executable is somewhere on your PATH, the command

x264_encoding_service --help

prints a short summary of the service's command line options.

Note

On Linux, a default set of command line options is specified in the packaged service file for systemd/openrc.

Individual options 

--config <path>

Inserts additional options from the configuration file named <path> at this point in the command line. Within the configuration file, empty lines and comments (anything from a # to the end of a line) are skipped, and option arguments with embedded spaces or backslashes must be surrounded by single or double quotes.

Configuration files may contain further --config options; this is useful for including the contents of one configuration file into another configuration file.

--daemon

Runs the service as a daemon, placing it in the background and detaching it from its terminal. This is a Unix-only option; on Windows, the program automatically behaves as a daemon when it is started as a Windows service. Running the program in the foreground may be useful for testing purposes.

--deterministic

Uses deterministic encoding, where identical inputs should produce identical outputs. This may be useful for testing purposes, but comes at a performance cost.

--directory <path>

Changes the program's current directory to <path>. Use this option to prevent the program from unexpectedly holding on to a mounted filesystem or directory.

--dry-run

Initializes the service, but does not run it, stopping immediately instead. This may be useful for testing purposes.

--endpoint <port>@<IP address>

Adds <port>@<IP address> to the list of endpoints the program listens on for incoming TCP connections. If no endpoints are specified, the program listens on port 11264@::1 (IPv6) and port 11264@127.0.0.1 (IPv4), so it only accepts local connections.

Warning

The communication protocol does not support any form of encryption or authentication. Accepting connections on the IP address of a non-local interface, including the wildcard addresses :: (IPv6) and 0.0.0.0 (IPv4), may be a security risk.

--logfile <path>

Appends log messages to the file named <path> instead of the terminal (foreground mode) or the system log (daemon mode).

Note

It is up to the system administrator to ensure the program has permission

to create the logfile and append messages to it, and
to rename and delete files in its directory.

The use of a single logfile for multiple running instances of the x264 encoding service is not supported and may result in unpredictable behavior.

--logfile-rotation-depth <depth>

Sets the logfile rotation depth. When the logfile size limit is exceeded (see the ---logfile-size-limit option), the current logfile is renamed and eventually discarded. This option specifies the number of old logfiles preserved before they are discarded. Defaults to 9.

--logfile-size-limit <limit>

Sets the logfile size limit, where 0 means no limit. When this limit is exceeded, the current logfile is renamed (and eventually discarded, see the --logfile-rotation-depth option) and a new logfile is created. Defaults to 0.

--loglevel <level>

Sets the logging level. Valid levels are error, warning, info, and debug. Defaults to warning.

--max-concurrent-requests <n>

Sets the maximum number of concurrent requests (encoding sessions) to <n>, where 0 means no limit. This limit is intended to prevent excessive resource usage; when it is reached, additional requests are blocked while waiting for other requests to complete. Defaults to 17. Also see the --session-threads option.

--max-connections <n>

Sets the maximum number of client connections to <n>, where 0 means no limit. This limit is intended to prevent excessive resource usage; when it is exceeded, the least recently used quiet connection is evicted. Defaults to 128.

--pidfile <path>

Stores the program's process identifier (PID) in the file named <path>, which is useful for communicating with Unix service control managers such as systemd or openrc. By default, no PID file is created.

--preset <presets>

This is an experimental option for overriding the encoding session presets string for the x264 library.

--selector <type>

Specifies which TCP socket event detection mechanism is used. This is an experimental option; the default <type> (poll on Unix, select on Windows) is usually best.

--session-threads <n>

Sets the maximum number of OS-level threads the x264 library will use for handling a single encoding request to <n>, where 0 refers to the default picked by the x264 library. Defaults to 0.

Use of this option in combination with the --max-concurrent-requests option may help to prevent CPU oversubscription.

--syslog

Sends log messages to the system log as x264_encoding_service.

--syslog-name <name>

Sends log messages to the system log as <name>. Useful if multiple instances of the x264_encoding_service are active.

--tune <tunings>

This is an experimental option for overriding the encoding session tunings string for the x264 library.

--umask <umask>

Sets the program's umask, which affects the permissions of any files it creates. By default, the umask is inherited from the parent process. This is a Unix-only option.

--user <user>

Runs the program as user <user>, including all of the user's group memberships. This is a Unix-only option; on Windows, the program's user identity (when run as a service) is determined by the service control manager.

Note

Use of this option is recommended when the program is started from the root user account.