Self-hosted service
HaveAGitGat/Tdarr avatar
HaveAGitGat/Tdarr

Tdarr V2: conditional plugin stacks over FFmpeg and HandBrake

Tdarr - Distributed transcode automation using FFmpeg/HandBrake + Audio/Video library analytics + video health checking (Windows, macOS, Linux & Docker)

4,399 stars125 forksMakefileNOASSERTION

At a glance

What is it?
Tdarr rewrites a media library you already own by running files through conditional plugin stacks on FFmpeg or HandBrake, with a server handing work to nodes on other machines. The machinery is real and the target is narrow: your own files, decided by rules you write.
Who is it for?
Adopt Tdarr if you own a large library spread across machines with spare CPU or GPU and want codec normalisation running on a schedule without sitting at the machine. Do not adopt it if you want one-click desktop batch conversion, where the README points you to HBBatchBeast instead.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Makefile, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • HaveAGitGat/Tdarr4,399 ★ · +69
Star history
Repository2026-09-232026-11-15
HaveAGitGat/Tdarr4.3k4.4k

69 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Conditional filters decide whether a file is touched at all

Tdarr V2 is built around a question the owner of a media library keeps asking: which files do not match the standard you want? Answer that as a stack of conditional rules and the library is normalised without anyone opening a folder of MP4s by hand. The README gives the common case as converting h264 to hevc (h265), which it says saves 40%-50% in size. That saving is why people arrive. The mechanism that matters is the condition deciding whether a file gets rewritten at all, not the codec named inside it.

Every library you add carries its own transcode settings, filters and schedule, so two libraries on the same server can run different stacks without interfering. That separation is the design centre of the project. A single server can hold a 4K library that stays untouched and a smaller library that gets re-encoded weekly, and neither rule leaks into the other.

The payoff is unattended maintenance. A scheduler runs on a seven day, 24 hour cycle, and a folder watcher picks up new arrivals so a file does not sit unprocessed until the next scheduled window. The README also claims testing on a 1,000,000 file dummy library, and it lists a property explorer and library stats alongside the search interface, which is the direction of travel: manage the collection as a database rather than as a pile of files.

Tdarr_Server and Tdarr_Node split the queue from the work

The application splits into two components. Tdarr_Server is the central process that every node connects to, and Tdarr_Node is a process on the same machine or another one that collects tasks from that server. The split is the reason spare hardware in a cupboard can be counted: put a node on the machine with the idle CPU or the spare GPU and the server treats it as capacity rather than as a machine you must sit in front of.

Nodes exist for Windows, Linux including arm and arm64, and macOS, with Docker and Flatpak directories in the repository and hardware transcoding supported through a container with the Nvidia plugin on unRAID or the Nvidia runtime container on Ubuntu. The README names Sonarr and Radarr as applications it is designed to sit alongside, which tells you the intended entry point is a library already managed by other tools.

Workers come in four types: transcode CPU, transcode GPU, health check CPU and health check GPU. Limits on how many run at once are set by the scheduler or by hand. Load balancing spreads work across libraries and drives, and a worker stall detector exists for the case where a job hangs. That detector matters more than it sounds: a transcode that never exits will otherwise hold a slot forever, and on a four-worker node one hung job is a quarter of your throughput.

Plugin stacks live under Tdarr/Documents and are written in JavaScript

The stack is the unit of configuration. The README walks through a typical one: transcode non hevc files into hevc, remove subs, remove metadata if title, add aac stereo audio if none with eng preferred, and remove closed captions. Four of those are community plugins available immediately, while the add-audio one is built in the plugin creator and appears as a local plugin.

Each plugin is conditional, so it only runs when needed. That is the whole safety story in one sentence, and it is also the whole configuration burden: you write the conditions, and a badly written filter silently matches nothing or silently matches everything. Plugins sit in the Tdarr/Documents directory and are written in JavaScript, so anyone with coding experience can modify one or write a new one, with steps kept in the separate Tdarr_Plugins repository.

The plugin creator splits into filters and actions, where filters encapsulate the actions so the action only fires when the condition is met. Listed filters cover codec, medium, age, resolution and size. Listed actions cover HandBrake basic options, HandBrake or FFmpeg custom arguments, standardising audio stream codecs, adding an audio stream, keeping one audio stream, and remuxing the container.

No install command anywhere, only a download page and a builds index

The README points to download and setup pages rather than an install command. The README links to home.tdarr.io/download and to a setup page at docs.tdarr.io/docs/installation/windows-linux-macos, and describes the result as a click-to-run web app rather than something you invoke from a shell. Docker users are pointed at the builds index at docs.tdarr.io/docs/releases/changing-version for the image list. If you script your infrastructure, plan on fetching images or binaries rather than running a package manager step.

A detail worth catching before you expect a Node application. The repository's package.json names index.js as its main entry and declares a single dependency, babel-eslint at ^10.1.0, which is a linting parser rather than a runtime library. The primary language of the repository is recorded as Makefile. Together those say the manifest is not the install surface, and that packaging happens through the updater directory, the Docker directory and the Flatpak directory rather than through npm. Trying to npm install this repository would not get you a running Tdarr.

First use is therefore a web UI problem, not a shell problem. Once Tdarr_Server is up, the sequence is: add a library path, choose FFmpeg or HandBrake, attach a plugin stack to that library, confirm a node reports in, and run the first job against a small directory before pointing the scheduler at everything. Plan around that limit: the repository is not archived and the last push was on 2026-10-27, yet the newest GitHub release is v1.2066-Beta from 2020-09-18, so there is no V2 release tag to pin, and licence handling is equally indirect because package.json defers to LICENSE.md rather than naming one.

Extra streams break direct play, and rewrites have no documented way back

The README is unusually clear about why normalisation earns its keep. Subtitles and closed captions are different things, and closed caption data can sit embedded inside the h264 video stream rather than as its own track. Streams you do not need cause direct play and sync problems, and in players such as VLC or Kodi subtitle and caption handling can cause playback delays and stutter when jumping around in a file. Extra streams also cost space, and the README warns of files carrying 15 or more audio, commentary and subtitle tracks that can add a gigabyte or more each.

That is a genuine failure mode, and the plugins address it directly. The README describes a job report, a worker verdict history and a property explorer, which tell you what happened, not that you can reverse it.

There is a second sharp edge in the plugin model. Because plugins run in order and each is conditional on the state left by the one before it, an ordering mistake produces a plausible-looking result rather than an error. Transcoding first and then removing metadata produces different output from removing metadata first.

HBBatchBeast is the alternative the README itself names

For a desktop application with similar functionality the README points to HBBatchBeast, from the same author. That is the comparison to make, not a general transcoder, because the difference in approach is structural rather than a matter of quality.

Tdarr is a distributed system. Work is queued centrally on Tdarr_Server, pulled by Tdarr_Node processes on other machines, and governed by a scheduler with worker limits and load balancing across drives. Configuration lives in a browser UI as plugin stacks of conditional filters and actions, and the unit of management is the library with its own settings, filters and schedule. You are operating infrastructure.

A desktop application puts the same kind of work in front of one machine and one operator, with no server to keep running and no nodes to register. The cost of Tdarr's model is the part that shows up on a weekend: when a library job misbehaves, you are debugging a two-process setup across your LAN rather than a single window. The gain is the part that shows up every night: idle hardware elsewhere in the house keeps normalising the library while the machine you sit at does nothing.

Whichever you pick, the decision turns on whether your library is large enough to need machines you are not sitting at.

Keep one audio stream and its 16 outcomes mark where configuration stops being obvious

One action in the list deserves to be pulled out, because it is where a user meets the project's real learning curve. Keep one audio stream is described as having 16 different outcomes as it tries to determine the best stream to keep based on the codec, language and channel count you specify.

Sixteen is not a marketing number, it is a decision table. A file with an English stereo track, a German surround track and a mono commentary track is not a binary choice, and the plugin resolves it by rules you supply and the shape of the file. The README notes that some actions have become quite complicated and so take a bit more time.

That candour is worth crediting, and it is also a warning. Compare a couple of files by hand before you let the action touch a library, because a mis-picked commentary track is not obvious later when the credits come out in the wrong language.

Editorial conclusion

Adopt Tdarr if you own a large library spread across machines with spare CPU or GPU and want codec normalisation running on a schedule without sitting at the machine. Do not adopt it if you want one-click desktop batch conversion, where the README points you to HBBatchBeast instead. Verify first that your stack includes a remux to a container your players handle directly, then run it against a handful of files and compare them before you point the scheduler at the whole library.

Frequently asked questions

What is Tdarr for?

Tdarr V2 is a cross-platform conditional transcoding application for automating transcode and remux management of media libraries you already own, wrapping FFmpeg or HandBrake. The README's common example is converting h264 to hevc (h265), which it says saves 40%-50% in size.

Does Tdarr need a GPU?

No. Workers come in four types, transcode CPU and GPU plus health check CPU and GPU, so encoding can run on CPU alone. GPU workers and a hardware transcoding container are options, with the Nvidia plugin on unRAID or the Nvidia runtime container on Ubuntu.

how to install tdarr

The README links to home.tdarr.io/download and to the setup page at docs.tdarr.io/docs/installation/windows-linux-macos, and the application is described as a click-to-run web app, with images listed on the builds index at docs.tdarr.io/docs/releases/changing-version.

how to setup tdarr node

Tdarr_Node processes run on the same device or others and collect tasks from Tdarr_Server. Nodes exist for Windows, Linux including arm and arm64, and macOS, and workers come in transcode and health check types on CPU or GPU.

how to use tdarr plugins

Plugins form an ordered stack of conditional steps, each running only when its filter matches the file. They live in the Tdarr/Documents directory, are written in JavaScript, and community ones come from the Tdarr_Plugins repository, while the plugin creator builds local plugins from filters and actions.

Official sources

  1. HaveAGitGat/Tdarr on GitHub
  2. Issues
  3. README
  4. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/haveagitgat-tdarr.svg)](https://hysenlabs.com/projects/haveagitgat-tdarr)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/haveagitgat-tdarr.svg)](https://hysenlabs.com/projects/haveagitgat-tdarr)

Was this useful?