kelin/EZ-Homelab

Fork 0

Files

kelinfoxy 08b184aea7 Standardize Compose Files

2026-01-24 23:11:05 -05:00

15 KiB

Raw Blame History

Tdarr - Transcoding Automation

Overview
What is Tdarr?
Why Use Tdarr?
How It Works
Configuration in AI-Homelab
Official Resources
Educational Resources
Docker Configuration
Initial Setup
Advanced Topics
Troubleshooting

Overview

Category: Media Transcoding
Docker Image: ghcr.io/haveagitgat/tdarr
Default Stack: transcoders.yml
Web UI: https://tdarr.${DOMAIN} or http://SERVER_IP:8265
Server Port: 8266
Authentication: Built-in
Ports: 8265 (WebUI), 8266 (Server)

What is Tdarr?

Tdarr is a distributed transcoding system for automating media library transcoding/remuxing management. It can convert your entire media library to specific codecs (like H.265/HEVC), formats, or remove unwanted audio/subtitle tracks - all automatically. It uses a plugin system with hundreds of pre-made plugins for common tasks, supports hardware acceleration, and can run transcoding across multiple nodes.

Key Features

Distributed Transcoding: Multiple worker nodes
Plugin System: 500+ pre-made plugins
Hardware Acceleration: NVIDIA, Intel QSV, AMD
Health Checks: Identify corrupted files
Codec Conversion: H.264 → H.265, VP9, AV1
Audio/Subtitle Management: Remove unwanted tracks
Container Remux: MKV → MP4, etc.
Scheduling: Transcode during specific hours
Library Statistics: Codec breakdown, space usage
Web UI: Modern interface with dark mode

Why Use Tdarr?

Space Savings: H.265 saves 30-50% vs H.264
Standardization: Consistent codec across library
Compatibility: Convert to Plex/Jellyfin-friendly formats
Cleanup: Remove unwanted audio/subtitle tracks
Quality Control: Health checks detect corruption
Automation: Set it and forget it
Hardware Acceleration: Fast transcoding with GPU
Distributed: Use multiple machines
Free & Open Source: No cost
Flexible: Plugin system for any workflow

How It Works

Tdarr Scans Media Library
        ↓
Analyzes Each File
(Codec, resolution, audio tracks, etc.)
        ↓
Compares Against Rules/Plugins
        ↓
Files Needing Transcoding → Queue
        ↓
Worker Nodes Process Queue
(Using CPU or GPU)
        ↓
Transcoded File Created
        ↓
Replaces Original (or saves alongside)
        ↓
Library Updated

Architecture

Tdarr Server:

Central management
Web UI
Library scanning
Queue management

Tdarr Node:

Worker process
Performs transcoding
Can run on same or different machine
Multiple nodes supported

Configuration in AI-Homelab

Directory Structure

/opt/stacks/media-management/tdarr/
├── server/              # Tdarr server data
├── config/              # Configuration
├── logs/                # Logs
└── temp/                # Temporary transcoding files

/mnt/media/              # Media libraries (shared)
├── movies/
└── tv/

Environment Variables

# Server
serverIP=0.0.0.0
serverPort=8266
webUIPort=8265

# User permissions
PUID=1000
PGID=1000

# Timezone
TZ=America/New_York

# Hardware acceleration (optional)
# NVIDIA_VISIBLE_DEVICES=all

Official Resources

Website: https://tdarr.io
Documentation: https://docs.tdarr.io
GitHub: https://github.com/HaveAGitGat/Tdarr
Discord: https://discord.gg/GF8Chh3
Forum: https://www.reddit.com/r/Tdarr
Plugins: https://github.com/HaveAGitGat/Tdarr_Plugins

Educational Resources

Videos

Articles & Guides

Concepts to Learn

Transcoding: Converting video codecs
Remuxing: Changing container without re-encoding
H.265/HEVC: Modern codec, better compression
Hardware Encoding: GPU-accelerated transcoding
Bitrate: Video quality measurement
CRF: Constant Rate Factor (quality setting)
Streams: Video, audio, subtitle tracks

Docker Configuration

Complete Service Definition

tdarr:
  image: ghcr.io/haveagitgat/tdarr:latest
  container_name: tdarr
  restart: unless-stopped
  networks:
    - traefik-network
  ports:
    - "8265:8265"  # WebUI
    - "8266:8266"  # Server
  environment:
    - serverIP=0.0.0.0
    - serverPort=8266
    - webUIPort=8265
    - PUID=1000
    - PGID=1000
    - TZ=America/New_York
  volumes:
    - /opt/stacks/media-management/tdarr/server:/app/server
    - /opt/stacks/media-management/tdarr/config:/app/configs
    - /opt/stacks/media-management/tdarr/logs:/app/logs
    - /opt/stacks/media-management/tdarr/temp:/temp
    - /mnt/media:/media
  devices:
    - /dev/dri:/dev/dri  # Intel QuickSync
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.tdarr.rule=Host(`tdarr.${DOMAIN}`)"
    - "traefik.http.routers.tdarr.entrypoints=websecure"
    - "traefik.http.routers.tdarr.tls.certresolver=letsencrypt"
    - "traefik.http.routers.tdarr.middlewares=authelia@docker"
    - "traefik.http.services.tdarr.loadbalancer.server.port=8265"

With NVIDIA GPU

tdarr:
  image: ghcr.io/haveagitgat/tdarr:latest
  container_name: tdarr
  runtime: nvidia
  environment:
    - NVIDIA_VISIBLE_DEVICES=all
    - NVIDIA_DRIVER_CAPABILITIES=compute,video,utility
  # ... rest of config

Tdarr Node (Worker)

tdarr-node:
  image: ghcr.io/haveagitgat/tdarr_node:latest
  container_name: tdarr-node
  restart: unless-stopped
  network_mode: service:tdarr
  environment:
    - nodeName=MainNode
    - serverIP=0.0.0.0
    - serverPort=8266
    - PUID=1000
    - PGID=1000
  volumes:
    - /opt/stacks/media-management/tdarr/config:/app/configs
    - /opt/stacks/media-management/tdarr/logs:/app/logs
    - /opt/stacks/media-management/tdarr/temp:/temp
    - /mnt/media:/media
  devices:
    - /dev/dri:/dev/dri

Initial Setup

First Access

Start Containers:
```
docker compose up -d tdarr tdarr-node
```
Access Web UI:
- Local: http://SERVER_IP:8265
- Domain: https://tdarr.yourdomain.com
Initial Configuration:
- Add libraries
- Configure node
- Install plugins
- Create flows

Add Library

Libraries Tab → Add Library:

Name: Movies
Source: /media/movies
Folder watch: ✓ Enable
Priority: Normal
Schedule: Always (or specific hours)
Save

Repeat for TV Shows:

Name: TV Shows
Source: /media/tv

Configure Node

Nodes Tab:

Built-in Node:

Should appear automatically
Named "MainNode" (from docker config)
Shows as "Online"

Node Settings:

Transcode GPU: 1 (if GPU available)
Transcode CPU: 2-4 (CPU threads)
Health Check GPU: 0
Health Check CPU: 1

Hardware Acceleration:

CPU Only: Use CPU workers
NVIDIA: Select "NVENC" codec in plugins
Intel QSV: Select "QSV" codec
Prioritize GPU for best performance

Install Plugins

Plugins Tab → Community:

Essential Plugins:

Migz-Transcode using Nvidia GPU & FFMPEG
- NVIDIA hardware transcoding
- H.264 → H.265
Migz-Transcode using CPU & FFMPEG
- CPU-based transcoding
- Fallback for non-GPU
Remux Container to MKV
- Convert to MKV without re-encoding
Remove All Subtitle Streams
- Clean unwanted subtitles
Remove Non-English Audio Streams
- Keep only English audio

Install:

Click "+" to install plugin
Shows in "Local" tab when installed

Create Flow

Flows Tab → Add Flow:

Example: Convert to H.265

Flow Name: H.265 Conversion
Add Step:
- Plugin: Migz-Transcode using Nvidia GPU & FFMPEG
- Target Codec: hevc (H.265)
- CRF: 23 (quality)
- Resolution: Keep original
- Audio: Copy (no transcode)
- Subtitles: Copy
Save Flow

Assign to Library:

Libraries → Movies → Transcode Options
Flow: H.265 Conversion
Save

Start Processing

Dashboard:

View queue
Processing status
Completed/Failed counts
Library statistics

Start Transcoding:

Automatically starts based on schedule
Monitor progress in real-time

Advanced Topics

Custom Plugins

Create Custom Plugin:

Plugins Tab → Local → Create Plugin:

function details() {
  return {
    id: "Custom_H265",
    Stage: "Pre-processing",
    Name: "Custom H.265 Conversion",
    Type: "Video",
    Operation: "Transcode",
    Description: "Custom H.265 conversion with specific settings",
    Version: "1.0",
    Tags: "video,h265,nvenc",
  };
}

function plugin(file, librarySettings, inputs, otherArguments) {
  var response = {
    processFile: false,
    preset: "",
    handBrakeMode: false,
    FFmpegMode: true,
    reQueueAfter: true,
    infoLog: "",
  };

  if (file.video_codec_name === "hevc") {
    response.infoLog += "File already H.265 ☑\n";
    response.processFile = false;
    return response;
  }

  response.processFile = true;
  response.preset = "-c:v hevc_nvenc -crf 23 -c:a copy -c:s copy";
  response.infoLog += "Transcoding to H.265 with NVENC\n";
  
  return response;
}

module.exports.details = details;
module.exports.plugin = plugin;

Use Cases:

Specific quality settings
Custom audio handling
Conditional transcoding
Advanced workflows

Flow Conditions

Add Conditions to Flows:

Example: Only transcode if > 1080p

Add condition: Resolution > 1920x1080
Then: Transcode to 1080p
Else: Skip

Example: Only if file size > 5GB

Condition: File size check
Large files get transcoded
Small files skipped

Scheduling

Library Settings → Schedule:

Transcode Schedule:

All day: 24/7 transcoding
Night only: 10PM - 6AM
Custom hours: Define specific times

Use Cases:

Transcode during off-hours
Avoid peak usage times
Save electricity costs

Health Checks

Detect Corrupted Files:

Libraries → Settings → Health Check:

✓ Enable health check
Check for: Video errors, audio errors
Workers: 1-2 CPU workers

Health Check Flow:

Scans files for corruption
Marks unhealthy files
Option to quarantine or delete

Statistics

Dashboard → Statistics:

Library Stats:

Total files
Codec breakdown (H.264 vs H.265)
Total size
Space savings potential

Processing Stats:

Files processed
Success rate
Average processing time
Queue size

Multiple Libraries

Separate libraries for:

Movies
TV Shows
4K Content
Different quality tiers

Benefits:

Different flows per library
Prioritization
Separate schedules

Troubleshooting

Tdarr Not Transcoding

# Check node status
# Nodes tab → Should show "Online"

# Check queue
# Dashboard → Should show items

# Check workers
# Nodes → Workers should be > 0

# Check logs
docker logs tdarr
docker logs tdarr-node

# Common issues:
# - No workers configured
# - Library not assigned to flow
# - Schedule disabled
# - Temp directory full

Transcoding Fails

# Check logs
docker logs tdarr-node | tail -50

# Check temp directory space
df -h /opt/stacks/media-management/tdarr/temp/

# Check FFmpeg
docker exec tdarr-node ffmpeg -version

# Check hardware acceleration
# GPU not detected → use CPU plugins

# Check file permissions
ls -la /mnt/media/movies/

High CPU/GPU Usage

# Check worker count
# Nodes → Reduce workers if too high

# Monitor resources
docker stats tdarr tdarr-node

# Limit workers:
# - GPU: 1-2
# - CPU: 2-4 (depending on cores)

# Schedule during off-hours
# Libraries → Schedule → Night only

Slow Transcoding

# Enable hardware acceleration
# Use NVENC/QSV plugins instead of CPU

# Reduce quality
# CRF 28 faster than CRF 18

# Increase workers (if resources available)

# Use faster preset
# Plugin settings → Preset: fast/faster

# Check disk I/O
# Fast NVMe for temp directory improves speed

Files Not Replacing Originals

# Check flow settings
# Flow → Output → Replace original: ✓

# Check permissions
ls -la /mnt/media/

# Check temp directory
ls -la /opt/stacks/media-management/tdarr/temp/

# Check logs for errors
docker logs tdarr-node | grep -i error

Performance Optimization

Hardware Acceleration

Best Performance:

NVIDIA GPU (NVENC)
Intel QuickSync (QSV)
AMD GPU
CPU (slowest)

Settings:

GPU workers: 1-2
Quality: CRF 23-28
Preset: medium/fast

Temp Directory

Use Fast Storage:

volumes:
  - /path/to/fast/nvme:/temp

Or RAM disk:

volumes:
  - /dev/shm:/temp