docker.recipes

Tdarr Media Transcoding

intermediate

Tdarr distributed transcoding system for media libraries.

Overview

Tdarr is a distributed media transcoding system designed to automate the optimization of video libraries across multiple nodes. The tdarr-server component acts as the central orchestrator, managing transcoding jobs, monitoring media libraries, and providing a web-based interface for configuration and monitoring. It coordinates with worker nodes to distribute processing loads and maintains a database of transcoding operations and media file metadata. The tdarr-node components serve as distributed workers that execute the actual transcoding operations using tools like FFmpeg and HandBrake. This architecture allows media libraries to be processed efficiently across multiple machines, whether they're running on the same host or distributed across a network. The server component scans media directories, applies user-defined rules and plugins, and queues files for transcoding based on criteria like codec, resolution, or file size. This distributed transcoding setup is ideal for homelab enthusiasts, content creators, and media server administrators who need to optimize large video collections for storage efficiency or compatibility across different devices. The combination of centralized management with distributed processing power makes it possible to tackle massive transcoding jobs that would overwhelm a single machine, while the plugin system allows for highly customized transcoding workflows tailored to specific media requirements.

Key Features

  • Distributed transcoding architecture with centralized job management and multiple worker nodes
  • Plugin-based transcoding system with pre-built and custom workflow options
  • Real-time media library scanning with automatic file detection and metadata extraction
  • Web-based dashboard showing transcoding progress, queue status, and system statistics
  • Hardware acceleration support for GPU-based transcoding using NVENC, QuickSync, and VAAPI
  • Conditional transcoding rules based on file properties like codec, bitrate, resolution, and age
  • Built-in support for popular transcoding engines including FFmpeg and HandBrake
  • Health checking system that validates transcoded files and rolls back failed operations

Common Use Cases

  • 1Home media server optimization to reduce Plex or Jellyfin storage requirements
  • 2Content preparation for streaming services requiring specific codec and resolution standards
  • 3Legacy video archive modernization to convert old formats to contemporary codecs
  • 4Multi-location media processing across home lab environments with distributed compute resources
  • 5Automated video optimization for mobile device compatibility and bandwidth constraints
  • 6Batch processing of recorded TV content to remove commercials and optimize file sizes
  • 7Professional media workflow automation for content creators managing large video libraries

Prerequisites

  • Minimum 4GB RAM per transcoding node, with 8GB recommended for 4K content processing
  • Sufficient storage space for transcoding cache, typically 2-3x the size of largest video files
  • Available ports 8265 (web UI) and 8266 (server communication) not conflicting with other services
  • Understanding of video codecs, containers, and transcoding concepts for effective plugin configuration
  • Fast storage or SSD recommended for temporary transcoding files to avoid I/O bottlenecks
  • Basic knowledge of FFmpeg parameters and video encoding settings for custom workflows

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  tdarr: 
3    image: ghcr.io/haveagitgat/tdarr:latest
4    container_name: tdarr
5    environment: 
6      - PUID=1000
7      - PGID=1000
8      - TZ=${TZ}
9      - serverIP=0.0.0.0
10      - serverPort=8266
11      - webUIPort=8265
12      - internalNode=true
13      - inContainer=true
14    volumes: 
15      - tdarr_server:/app/server
16      - tdarr_configs:/app/configs
17      - tdarr_logs:/app/logs
18      - /path/to/media:/media
19      - /path/to/transcode_cache:/temp
20    ports: 
21      - "8265:8265"
22      - "8266:8266"
23    networks: 
24      - tdarr-network
25
26  tdarr-node: 
27    image: ghcr.io/haveagitgat/tdarr_node:latest
28    container_name: tdarr-node
29    environment: 
30      - PUID=1000
31      - PGID=1000
32      - TZ=${TZ}
33      - serverIP=tdarr
34      - serverPort=8266
35      - inContainer=true
36    volumes: 
37      - tdarr_configs:/app/configs
38      - tdarr_logs:/app/logs
39      - /path/to/media:/media
40      - /path/to/transcode_cache:/temp
41    networks: 
42      - tdarr-network
43
44volumes: 
45  tdarr_server: 
46  tdarr_configs: 
47  tdarr_logs: 
48
49networks: 
50  tdarr-network: 
51    driver: bridge

.env Template

.env
1# Tdarr
2TZ=UTC

Usage Notes

  1. 1Web UI at http://localhost:8265
  2. 2Add libraries and configure
  3. 3Create processing plugins
  4. 4Scale with additional nodes
  5. 5GPU transcoding supported

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

tdarr
tdarr:
  image: ghcr.io/haveagitgat/tdarr:latest
  container_name: tdarr
  environment:
    - PUID=1000
    - PGID=1000
    - TZ=${TZ}
    - serverIP=0.0.0.0
    - serverPort=8266
    - webUIPort=8265
    - internalNode=true
    - inContainer=true
  volumes:
    - tdarr_server:/app/server
    - tdarr_configs:/app/configs
    - tdarr_logs:/app/logs
    - /path/to/media:/media
    - /path/to/transcode_cache:/temp
  ports:
    - "8265:8265"
    - "8266:8266"
  networks:
    - tdarr-network
tdarr-node
tdarr-node:
  image: ghcr.io/haveagitgat/tdarr_node:latest
  container_name: tdarr-node
  environment:
    - PUID=1000
    - PGID=1000
    - TZ=${TZ}
    - serverIP=tdarr
    - serverPort=8266
    - inContainer=true
  volumes:
    - tdarr_configs:/app/configs
    - tdarr_logs:/app/logs
    - /path/to/media:/media
    - /path/to/transcode_cache:/temp
  networks:
    - tdarr-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  tdarr:
5    image: ghcr.io/haveagitgat/tdarr:latest
6    container_name: tdarr
7    environment:
8      - PUID=1000
9      - PGID=1000
10      - TZ=${TZ}
11      - serverIP=0.0.0.0
12      - serverPort=8266
13      - webUIPort=8265
14      - internalNode=true
15      - inContainer=true
16    volumes:
17      - tdarr_server:/app/server
18      - tdarr_configs:/app/configs
19      - tdarr_logs:/app/logs
20      - /path/to/media:/media
21      - /path/to/transcode_cache:/temp
22    ports:
23      - "8265:8265"
24      - "8266:8266"
25    networks:
26      - tdarr-network
27
28  tdarr-node:
29    image: ghcr.io/haveagitgat/tdarr_node:latest
30    container_name: tdarr-node
31    environment:
32      - PUID=1000
33      - PGID=1000
34      - TZ=${TZ}
35      - serverIP=tdarr
36      - serverPort=8266
37      - inContainer=true
38    volumes:
39      - tdarr_configs:/app/configs
40      - tdarr_logs:/app/logs
41      - /path/to/media:/media
42      - /path/to/transcode_cache:/temp
43    networks:
44      - tdarr-network
45
46volumes:
47  tdarr_server:
48  tdarr_configs:
49  tdarr_logs:
50
51networks:
52  tdarr-network:
53    driver: bridge
54EOF
55
56# 2. Create the .env file
57cat > .env << 'EOF'
58# Tdarr
59TZ=UTC
60EOF
61
62# 3. Start the services
63docker compose up -d
64
65# 4. View logs
66docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/tdarr-transcode/run | bash

Troubleshooting

  • Node shows as offline in web UI: Verify serverIP environment variable matches tdarr service name and network connectivity between containers
  • Transcoding jobs fail with 'file not found' errors: Ensure media volume mounts are identical between tdarr-server and tdarr-node containers
  • High memory usage during transcoding: Reduce concurrent transcoding jobs in node settings or increase available RAM allocation
  • GPU transcoding not working: Install nvidia-docker runtime and add device mappings for GPU access to transcoding nodes
  • Files stuck in processing queue: Check transcoding cache volume has sufficient free space and proper write permissions
  • Web UI shows 'server connection lost': Verify tdarr-server container is running and port 8266 is accessible within the docker network

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

tdarr-servertdarr-node

Tags

#tdarr#transcoding#ffmpeg#handbrake#media

Category

Media & Entertainment

Related Recipes

Ad Space