nixpkgs/nixos/modules/services/misc/tdarr/tdarr.md

Tdarr

Source: {file}modules/services/misc/tdarr

Upstream documentation: https://docs.tdarr.io/\

Tdarr is a distributed transcoding system for automating media library transcoding operations using FFmpeg and HandBrake. It provides a web interface for managing transcoding nodes and configuring media processing pipelines.

Basic Usage

A minimal Tdarr setup with a server and one local node:

{
  services.tdarr = {
    enable = true;
    nodes.main = { };
  };
}

This creates a Tdarr server accessible at http://localhost:8265 (web UI) with one processing node. The service runs as the tdarr user with data stored in /var/lib/tdarr.

::: {.note} The services.tdarr.enable option is a convenience that enables both the server and all configured nodes. For finer control, use services.tdarr.server.enable and configure nodes independently. :::

Server Only

To run only the Tdarr server without local nodes:

{
  services.tdarr.server.enable = true;
}

Nodes Only

To run node(s) connecting to a remote server:

{
  services.tdarr.nodes.worker1 = {
    serverURL = "http://192.168.1.100:8266";
    environmentFile = "/run/secrets/tdarr-node-env";
    # /run/secrets/tdarr-node-env contains:
    # apiKey=tapi_your_api_key_here
  };
}

Authentication

Authentication should be enabled for any installation accessible beyond localhost. Secrets are passed via environment files to avoid leaking them into the Nix store:

{
  services.tdarr = {
    enable = true;
    server = {
      auth.enable = true;
      environmentFile = "/run/secrets/tdarr-server-env";
      # /run/secrets/tdarr-server-env contains:
      # authSecretKey=your-secret-key
      # seededApiKey=tapi_your_api_key_here
    };
    nodes.main = {
      environmentFile = "/run/secrets/tdarr-node-env";
      # /run/secrets/tdarr-node-env contains:
      # apiKey=tapi_your_api_key_here
    };
  };
}

::: {.warning} When using unmapped nodes, files in Tdarr's library source and cache folders become accessible through the network API. Authentication is strongly recommended in this configuration. :::

Node Configuration

Multiple Nodes

You can run multiple nodes on the same machine with different configurations:

{
  services.tdarr = {
    enable = true;
    nodes = {
      cpu-node = {
        workers = {
          transcodeCPU = 4;
          healthcheckCPU = 2;
        };
      };
      gpu-node = {
        workers = {
          transcodeGPU = 2;
          transcodeCPU = 1;
          healthcheckGPU = 1;
        };
      };
    };
  };
}

Worker Configuration

Workers determine how many parallel transcoding and healthcheck operations a node can perform:

{
  services.tdarr.nodes.main = {
    workers = {
      transcodeCPU = 4; # default: 2
      transcodeGPU = 1; # default: 0
      healthcheckCPU = 2; # default: 1
      healthcheckGPU = 0; # default: 0
    };
  };
}

::: {.note} GPU workers require appropriate hardware and drivers. Worker counts can also be adjusted at runtime through the Tdarr web UI. :::

Node Types

Tdarr supports two node types:

• Mapped nodes (default): Access files directly from the library paths configured in the Tdarr web interface.
• Unmapped nodes: Receive files over the network, useful for nodes without direct storage access.

{
  services.tdarr.nodes = {
    local.type = "mapped";
    remote = {
      type = "unmapped";
    };
  };
}

Path Translators

Path translators enable cross-mount-point file access by mapping server paths to node paths:

{
  services.tdarr.nodes.remote-node = {
    pathTranslators = [
      {
        server = "/media/videos";
        node = "/mnt/nfs/videos";
      }
      {
        server = "/media/music";
        node = "/mnt/nfs/music";
      }
    ];
  };
}

Networking

Firewall Configuration

{
  services.tdarr.server = {
    enable = true;
    openFirewall = true; # Opens ports 8265 (web UI) and 8266 (server API)
  };
}

Custom Ports

{
  services.tdarr.server = {
    enable = true;
    serverPort = 9266; # default: 8266
    webUIPort = 9265; # default: 8265
  };
}

IPv6 Support

Enable dual-stack networking for IPv4 and IPv6 support:

{
  services.tdarr.server = {
    enable = true;
    serverDualStack = true;
  };
}

Advanced Configuration

Plugin Updates

Configure automatic plugin updates using cron expressions:

{
  services.tdarr.server = {
    enable = true;
    cronPluginUpdate = "0 2 * * *"; # Daily at 2 AM
  };
}

Custom Data Directory

{
  services.tdarr = {
    enable = true;
    dataDir = "/mnt/storage/tdarr";
  };
}

Per-Node Data Directories

{
  services.tdarr.nodes = {
    ssd-node.dataDir = "/mnt/ssd/tdarr-node";
    hdd-node.dataDir = "/mnt/hdd/tdarr-node";
  };
}

Distributed Setup

Tdarr's distributed architecture allows running nodes on separate machines from the server.

Server Machine

{
  services.tdarr.server = {
    enable = true;
    serverIP = "0.0.0.0";
    openFirewall = true;
    auth.enable = true;
    environmentFile = "/run/secrets/tdarr-server-env";
  };
}

Worker Machines

{
  services.tdarr.nodes.remote-worker = {
    serverURL = "http://192.168.1.100:8266";
    environmentFile = "/run/secrets/tdarr-node-env";
    workers = {
      transcodeCPU = 4;
      healthcheckCPU = 2;
    };
  };
}

::: {.note} Ensure the server's firewall allows incoming connections on the configured ports. Both server and nodes must have access to the same media and transcode cache paths (for mapped nodes). :::