Reference

Configuration

Settings live in master.env and worker.env beside each executable. The launcher loads the file before starting the service.

The prefixes differ, on purpose

Master settings begin TRNSCODE_. Worker settings begin TRNSCODE_WORKER_. A worker setting placed in master.env is ignored silently — no error, no warning. This is the most common configuration mistake.

Each file is read as environment variables, so anything set in the real environment overrides the file. Changes take effect on restart.

Master — listening#

Variable	Default	Purpose
`TRNSCODE_HOST`	`0.0.0.0`	Interface for the web interface and REST API. `0.0.0.0` accepts connections from the network; `127.0.0.1` restricts to the local machine.
`TRNSCODE_PORT`	`7443`	Port your browser connects to.
`TRNSCODE_GRPC_HOST`	`0.0.0.0`	Interface workers connect to.
`TRNSCODE_GRPC_PORT`	`50051`	Worker control channel port.
`TRNSCODE_GRPC_ENABLED`	`true`	Set false to run the interface with no fleet — useful for reviewing history on a machine that should not accept workers.

Master — storage#

TRNSCODE_DATABASE_URLstringoptional

Where jobs, chunks, workers, presets and audit history are stored. The bundled default is a SQLite file inside the bundle folder, which is appropriate for a single master.

default sqlite+aiosqlite:///./data/trnscode.db

The parent directory is created if it does not exist, so any writable path works. This file is the thing to back up — use master backup rather than copying it while the service runs.

Master — authentication#

TRNSCODE_JWT_SECRETstringrequired

Signs the session tokens the web interface issues. Anyone who knows this value can mint a valid administrator session, so treat the file holding it as a credential.

generate with openssl rand -hex 32

TRNSCODE_ADMIN_USERNAMEstringoptional

Username for the bootstrap administrator account.

default admin

TRNSCODE_ADMIN_PASSWORDstringrequired

Used only on first run, to create the administrator account. Changing it afterwards does not change the stored password — use master reset-admin-password for that.

Master — fleet policy#

TRNSCODE_GRPC_ENROLLMENT_TOKENstringoptional

A shared secret every worker must present to register. Empty means open enrollment — any machine that can reach the port may register and wait for approval. Acceptable on an isolated network, not on a shared one.

must match each worker's TRNSCODE_WORKER_ENROLLMENT_TOKEN

TRNSCODE_NETWORKING_ALLOW_TIER_2_FOR_TESTINGbooleanoptional

When false, the master refuses any worker whose link is Wi-Fi, cellular or sub-gigabit ethernet. Set true to admit them; each admission is logged as a warning so the override stays auditable.

default false — see Allowing non-wired workers

TRNSCODE_MDNS_ENABLEDbooleanoptional

Advertise the master on the local network so workers find it without configuration. Turn it off on networks where broadcast traffic is unwelcome, and point workers directly instead.

default true

Master — logging#

Variable	Default	Purpose
`TRNSCODE_LOG_LEVEL`	`INFO`	Verbosity. `DEBUG` when diagnosing a problem.
`TRNSCODE_LOG_JSON`	`false`	Emit structured JSON instead of human-readable lines. Turn on when shipping logs to a collector.

Worker — finding the master#

TRNSCODE_WORKER_MASTER_GRPC_TARGETstringoptional

Skip discovery and connect to this address directly. Set this when the worker is on a different subnet from the master, or where mDNS is blocked.

example 192.168.50.101:50051 — the gRPC port, not 7443

TRNSCODE_WORKER_ENROLLMENT_TOKENstringoptional

Required when the master sets an enrollment token. Must match exactly.

TRNSCODE_WORKER_MASTER_CERT_FINGERPRINTstringoptional

Pin the master's certificate fingerprint so the worker refuses to talk to anything else. Unset means trust on first use, which is reasonable on a network you control and weak on one you do not.

lowercase hex, 64 characters

Worker — runtime#

Variable	Default	Purpose
`TRNSCODE_WORKER_FFMPEG_BINARY`	bundled	Use a host-installed FFmpeg instead of the tested build in `bin/`. See the warning below.
`TRNSCODE_WORKER_HEARTBEAT_SECONDS`	`5`	How often the worker reports in. Longer intervals delay detection of a dead worker.
`TRNSCODE_WORKER_RECONNECT_INITIAL_SECONDS`	`1.0`	First retry delay after losing the master.
`TRNSCODE_WORKER_RECONNECT_MAX_SECONDS`	`60.0`	Ceiling for the backoff between reconnection attempts.
`TRNSCODE_WORKER_HEALTH_HOST`	`127.0.0.1`	Interface for the local health endpoint.
`TRNSCODE_WORKER_HEALTH_PORT`	`9443`	Port for the local health endpoint.
`TRNSCODE_WORKER_LOG_LEVEL`	`INFO`	Verbosity.
`TRNSCODE_WORKER_LOG_JSON`	`false`	Structured JSON output.

Overriding the bundled FFmpeg

Every bundle ships the same tested FFmpeg so that all workers produce identical output from identical arguments. Pointing one worker at a different build breaks that guarantee, and the resulting inconsistency appears inside a finished file rather than as an error. Change this only when you know why you are doing it, and change it across the whole fleet.

Applying changes#

Settings are read at startup. Edit the file, then restart that service — the master for master settings, the affected worker for worker settings. Changing a master fleet-policy setting does not retroactively admit workers that were already refused; they must attempt registration again.