Add a worker
A worker is any machine designated for encoding. The same three-step procedure applies whether the worker is the computer already running the master or the tenth node in a rack.
The master service coordinates but does not encode. Until at least one worker service is connected and approved, jobs remain in the queue. A single-computer installation also requires this procedure: run a worker on that machine alongside the master.
Prerequisites#
Two properties of the machine determine whether registration succeeds. Verify both before starting the worker.
The master refuses a worker whose network link is Wi-Fi, cellular, or slower than gigabit ethernet. Registration fails with a permission error and the worker never appears in the fleet.
This restriction is by design. Chunk transfer and progress reporting on a congested wireless link produce encode times worse than not distributing at all, and the failure is difficult to attribute after the fact. For a worker on Wi-Fi, see Allowing non-wired workers before starting it.
The second requirement is disk space. Each worker needs scratch space for the chunks it is assigned. A worker with a full disk accepts work and then fails it.
Start the worker#
The worker bundle is a separate download from the master and is portable in the same way: program, settings, and bundled FFmpeg in one folder. Do not place a worker and a master in the same folder; each keeps its own settings file.
On Windows, double-click start.bat. On macOS and Linux, run the launcher from that folder.
$ bash start.shThe worker searches the local network for a master automatically. On a flat home or office LAN it finds the master without configuration.
A screenshot walkthrough of this step is available at How-to: Approve a worker.
Open the master's Workers page. The new machine appears with status pending approval, showing its hostname, processor count and what it reports being able to encode.
Confirm that the entry is the machine you expect, then approve it. The worker moves to online and the scheduler begins assigning chunks to it.
A worker that has connected but has not been approved appears healthy in its own window: the dashboard shows it connected and sending heartbeats. It will not receive chunks until it is approved. If a worker is idle while jobs queue, check its status on the Workers page first.
The worker's window#
The worker service opens a desktop window of its own on the machine it runs on, styled to match the web console and carrying the same dark themes and theme picker. The window is a dashboard for that one machine: connection state, live CPU, RAM, GPU and disk tiles, the chunk currently being encoded, and a history of recent chunks.
Closing the window does not stop the worker. The service minimises to the system tray and a running encode continues; reopen the window from the tray icon. An option in the window suppresses the console window that otherwise accompanies the service on Windows.
Windows workers detect NVIDIA, Intel and AMD GPUs. Earlier releases surfaced only NVIDIA hardware, so if an Intel or AMD GPU is missing from a worker's reported capabilities, update the worker bundle.
The window also reports refusals. When the master refuses a worker's enrollment — most commonly because the license already has its full number of worker seats online — the window shows the reason, rather than the machine failing silently and never appearing in the fleet. See Licensing.
Set the master address manually#
Discovery uses mDNS, the same mechanism printers and media devices use. It does not cross subnets, and many managed networks block it. If the worker does not find the master within a few seconds, configure the master's address directly.
Edit worker.envin the worker's folder and set the master's address and gRPC port:
# the master's IP address, not its web port
TRNSCODE_WORKER_MASTER_GRPC_TARGET=192.168.50.101:50051Use port 50051, not 7443. Port 7443 serves the web interface for browsers; workers use a different protocol on 50051. A worker pointed at 7443 fails to connect.
Enrollment tokens#
If TRNSCODE_GRPC_ENROLLMENT_TOKEN is set on the master, every worker must present the same value or registration is rejected.
TRNSCODE_WORKER_ENROLLMENT_TOKEN=the-same-value-as-the-masterSet a token on any network you do not fully control. Without one, any machine that can reach port 50051 may register and wait for approval.
Allowing non-wired workers#
To accept the performance trade-off — for example a laptop on Wi-Fi contributing to a home fleet, or a test rig — configure the master to admit non-wired workers. This is a master setting, not a worker setting.
TRNSCODE_NETWORKING_ALLOW_TIER_2_FOR_TESTING=trueRestart the master for the change to take effect. Each admitted worker logs a warning on the master, so the override remains auditable.
On a wireless worker, the source must transfer to the machine and the encoded chunk must transfer back. For high-bitrate sources the transfer can take longer than the encode, and a slow worker holding the last chunk keeps the whole job open. Measure job times before concluding that the additional worker improves throughput.
Run a worker on the master machine#
This is the standard single-computer configuration and is fully supported. Unzip the worker bundle into its own folder on the same machine and start it. It discovers the master over the loopback interface and registers like any other worker.
Approval on the Workers page is still required. A same-machine worker reads the source file directly from disk, so no chunk data crosses the network.
Verify the worker#
A worker is contributing when all three of the following are true.
- It shows as online on the Workers page, not pending approval and not offline.
- Its reported capabilities list the codecs you intend to encode with.
- During a job, chunks in the chunk map carry its colour.
Each worker also exposes a local health endpoint on its own machine. Use it to determine whether the process is alive when the worker does not start.
$ curl http://127.0.0.1:9443/healthRemove a worker#
Do not stop a worker mid-job unless necessary. Drain it instead: draining stops new chunks being assigned while letting in-flight work finish, after which the machine is free. Drain from the worker's detail page in the web console — see Lifecycle actions.
If a worker disappears abruptly, the job survives. The unfinished chunk is reassigned to another worker; only the time spent on that chunk is lost.