# Tdarr Media Transcoding

> Tdarr distributed transcoding system for media libraries.

- Category: Media & Entertainment
- Difficulty: intermediate
- Components: tdarr-server, tdarr-node
- Tags: tdarr, transcoding, ffmpeg, handbrake, media
- Source: https://docker.recipes/media/tdarr-transcode

## 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.

## 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

## Use cases

- Home media server optimization to reduce Plex or Jellyfin storage requirements
- Content preparation for streaming services requiring specific codec and resolution standards
- Legacy video archive modernization to convert old formats to contemporary codecs
- Multi-location media processing across home lab environments with distributed compute resources
- Automated video optimization for mobile device compatibility and bandwidth constraints
- Batch processing of recorded TV content to remove commercials and optimize file sizes
- Professional 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

## docker-compose.yml

```yaml
services:
  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:
    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

volumes:
  tdarr_server:
  tdarr_configs:
  tdarr_logs:

networks:
  tdarr-network:
    driver: bridge
```

## .env

```bash
# Tdarr
TZ=UTC
```

## Usage notes

- Web UI at http://localhost:8265
- Add libraries and configure
- Create processing plugins
- Scale with additional nodes
- GPU transcoding supported

## 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

