Add a worker
A worker is any machine you want encoding. Adding one is the same three steps whether it is the computer already running the master or the tenth node in a rack.
The master coordinates but does not encode. Until at least one worker is connected and approved, jobs will sit in the queue. If you are running everything on one computer, you still need this page — run a worker on that machine alongside the master.
Before you start#
Two things about the machine you are adding decide whether this works at all. Check them now rather than debugging a silent refusal later.
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 is intentional. Chunk transfer and progress reporting on a congested wireless link produce encode times worse than not distributing at all, and the failure is hard to attribute after the fact. If your worker is a laptop on Wi-Fi, see Allowing non-wired workers below before you start it.
The second thing is disk. Each worker needs scratch space for the chunks it is handed. A worker with a full disk will accept work and then fail it.
Start the worker#
It is a separate download from the master and is portable in the same way — program, settings and bundled FFmpeg in one folder. Do not put a worker and a master in the same folder; they keep separate settings files.
Windows: double-click start.bat. macOS and Linux: run the launcher from that folder.
$ bash start.shThe worker looks for a master on the local network automatically. On a flat home or office LAN it finds it without configuration.
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.
Check that it is the machine you expect, then approve it. It moves to online and the scheduler starts giving it chunks.
A worker that has connected but not been approved looks healthy from its own console — it is connected and sending heartbeats. It will never receive a chunk. If a worker seems idle while jobs queue, check its status on the Workers page first.
When automatic discovery does not work#
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, point it 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. 7443 is the web interface for your browser; workers speak a different protocol on 50051. Pointing a worker at 7443 fails to connect.
If the master requires an enrollment token#
If you set TRNSCODE_GRPC_ENROLLMENT_TOKEN on the master, every worker must present the same value or registration is rejected.
TRNSCODE_WORKER_ENROLLMENT_TOKEN=the-same-value-as-the-masterSetting a token is worth doing 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#
If you accept the performance trade — a laptop on Wi-Fi contributing to a home fleet, or a test rig — you can tell the master to admit them. This is a master setting, not a worker one.
TRNSCODE_NETWORKING_ALLOW_TIER_2_FOR_TESTING=trueRestart the master for it to take effect. Each admitted worker logs a warning on the master so the override stays visible in the record rather than becoming invisible policy.
On a wireless worker the source has to travel to the machine and the encoded chunk has to travel back. For high-bitrate sources that transfer can take longer than the encode, and a slow worker holding the last chunk keeps the whole job open. Measure before assuming it helped.
Running a worker on the master machine#
This is the normal single-computer setup and it 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.
You still approve it on the Workers page. The advantage of a same-machine worker is that it reads the source file directly from disk — no chunk data crosses the network at all.
Confirm it is working#
A worker is contributing when all three of these 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 the machine itself, which is useful when the worker will not start and you want to know whether the process is alive.
$ curl http://127.0.0.1:9443/healthTaking a worker out#
Do not kill a worker mid-job unless you have to. Drain it instead: draining stops new chunks being assigned while letting in-flight work finish, after which the machine is free.
If a worker does disappear abruptly, the job survives — its unfinished chunk is reassigned to another worker. You lose the time spent on that one chunk.