Tdarr: Transcoding Your Media Library to Claw Back Terabytes
Batch re-encoding a whole library with GPU acceleration, and the mistakes that ruin a library while you're doing it

Contents
A library built up over a few years of automated grabs ends up an inconsistent mess of codecs — some H.264, some H.265, some ancient MPEG-2 remuxes from a batch of older films nobody’s re-downloaded since — and the size difference between H.264 and H.265 encodes of the same content is routinely 30-50% for equivalent visual quality. Tdarr exists to batch that re-encode across an entire library using whatever hardware you throw at it, GPU included, without you manually queuing individual ffmpeg commands one file at a time. It’s also the single easiest tool in this whole ecosystem to use to quietly destroy a library if you skip the one step everyone skips: testing on a small sample before pointing it at everything you own.
I want to be upfront that this isn’t a tool to run casually. Transcoding is lossy by nature, re-encoding is slow even with hardware acceleration, and a misconfigured job can chew through your entire library before you notice the output looks worse than the source. Read the health-check section before running anything against real files.
Why re-encode at all
H.265 (HEVC) delivers materially smaller files than H.264 at comparable perceived quality, largely because it does a better job of exploiting redundancy between frames and within them using more sophisticated prediction than H.264’s older toolset allows. For a library heavy on older H.264 grabs, or worse, ancient MPEG-2 or VC-1 remuxes from early automated setups, re-encoding to H.265 at a sensible bitrate target can reclaim a genuinely large fraction of total storage — I’ve seen a few terabytes come back from a library that hadn’t been touched since it was first assembled. The trade-off is CPU or GPU time: transcoding a library of any real size on CPU alone can take weeks of continuous processing, which is the entire reason hardware-accelerated transcoding (via Intel Quick Sync, an Nvidia GPU with NVENC, or similar) is the only realistic way to run this against a library rather than a handful of files.

Setup: server and node architecture
Tdarr splits into two roles: a server that holds the library scan, job queue, and web UI, and one or more “nodes” that actually perform the transcoding work. This split matters because nodes can run on different machines — a beefy desktop with a GPU, a NAS, a spare machine that’s otherwise idle overnight — all pulling from the same central queue, which is genuinely useful if your always-on server doesn’t have a GPU but you’ve got other hardware in the house that does.
| |
internalNode=true runs a node inside the same container as the server, which is fine for a first setup or a single-machine deployment, but separating them onto dedicated node containers (or dedicated machines) is worth doing once you’re relying on this for anything beyond experimentation, since a transcoding job pegging every core doesn’t leave much headroom for the server’s own web UI and queue management to stay responsive.
The /dev/dri device passthrough is what exposes Intel’s Quick Sync hardware encoder to the container, and it needs the host’s GPU drivers actually installed and working outside Docker first — Tdarr can’t accelerate anything it doesn’t have driver access to, and a container that starts fine without this device mapping will simply fall back to CPU-only transcoding with no obvious error, just noticeably slower job throughput than you were expecting.
The transcode cache path matters
The /temp mount (mapped to ./tdarr/transcode-cache above) is where Tdarr writes in-progress transcodes before replacing the original file, and it’s worth putting this on fast local storage — an SSD, ideally — rather than the same slow bulk-storage volume the library itself lives on. Every file being processed gets written here in full before the swap happens, so this path sees continuous write load for as long as jobs are running, and slow storage here becomes the actual bottleneck on throughput regardless of how fast your GPU can encode.
Health checks: the step that actually protects your library
Tdarr includes a health-check stage that verifies a transcoded file plays back correctly (checking for corruption, verifying stream integrity) before it’s allowed to replace the original. This is not optional in any setup where the library matters to you, and it’s the single most important setting in the entire tool: without it enabled, a job that produces a subtly corrupted or truncated file will still replace your only copy of that source, and you won’t find out until you try to actually watch it, at which point the process may have already deleted or overwritten the original.
Run health checks with deleteOriginalFileAfterTranscode disabled for at least your first batch of real jobs, keeping both the original and transcoded output side by side until you’ve manually verified a sample plays back correctly. Only flip the delete-original setting on once you trust the pipeline against your specific combination of source files, hardware encoder, and target settings — a combination that hasn’t been validated against your actual library is exactly the situation where a silent corruption slips through unnoticed.
Plugins hold the actual transcode logic
Tdarr’s core app handles scanning, queuing, and node coordination, but the actual decision about what to transcode and how is defined by “plugins” — JavaScript snippets, community-maintained or self-written, that inspect each file’s metadata and decide whether it needs processing and with what settings. This separation is deliberate: the same core Tdarr install can run a completely different transcoding strategy for TV versus film, or skip files that are already H.265 while re-encoding everything still on H.264, purely by changing which plugins are attached to a given library’s stack, without touching the underlying job engine at all.
The stock plugin library covers the common cases — “transcode to HEVC if not already HEVC,” “remux audio to a specific format,” “skip files below a certain size where the encode wouldn’t meaningfully help” — well enough that most people never need to write their own. Where it’s worth spending time is chaining a stack of plugins in the right order for your library rather than relying on a single one: checking container format, then codec, then bitrate, in sequence, so a file that’s already efficiently encoded gets skipped early rather than needlessly re-processed and potentially made larger by a second lossy pass over already-compressed content.
Targeted transcoding beats a blanket library-wide job
Running a single job configuration against an entire library, sight unseen, is how people end up re-encoding files that didn’t need it and, worse, re-encoding files more than once as jobs get reconfigured and re-run against the same library. A more deliberate approach: filter the initial job to a specific folder or a specific source codec (older MPEG-2 remuxes, for instance, which benefit the most and are usually the smallest fraction of a library), verify the output on that narrow set first, and only widen the scope once you’ve confirmed quality, timing, and storage savings actually match what you expected. This is slower to get started than pointing Tdarr at /media and walking away, but it’s the difference between a controlled, reversible process and finding out three days into an unattended run that a plugin setting was subtly wrong for an entire category of your library.
This pairs naturally with how a library gets structured in the first place if you’re running the rest of the automation stack — media organised by Sonarr and Radarr into consistent folder layouts makes it much easier to scope a Tdarr job to “just the older stuff” rather than needing to inspect every file’s codec individually to know what to target.
Troubleshooting
Jobs run but never use the GPU. Confirm /dev/dri (or the equivalent Nvidia device mappings) is actually passed through, and separately confirm the transcode plugin/library selected inside Tdarr’s job configuration is actually requesting hardware acceleration — some default flows quietly fall back to software encoding (libx265) if the hardware-accelerated option wasn’t explicitly selected when the transcode was configured.
Output files look visibly worse than the source. Check the target bitrate or CRF value configured for the job — hardware encoders in particular can produce noticeably worse quality than software encoding at the same nominal bitrate, and a setting copied from a software-encoding guide often needs a meaningfully higher target when using a hardware encoder to hit comparable visual quality.
Library scan never finishes, or keeps re-scanning the same files. This is almost always a path mapping issue similar to the *arr apps — Tdarr needs a consistent view of the library path across every node involved, and a node running on a different machine with a different local mount point for the same network share will treat files as new or missing depending on how paths resolve on that particular node.
A job fails partway through and leaves a partial file behind. Check the /temp cache path first — a partial transcode failing mid-write shouldn’t touch the original file if health checks and delete-on-complete are configured correctly, but a stray partial file in the cache directory from an interrupted job is normal and safe to clear manually.
Playback compatibility is worth checking before committing to HEVC everywhere
H.265 support isn’t universal across every client that might play from your library — most modern smart TVs, Jellyfin clients, and recent phones handle it natively, but older devices, some browsers without the right codec licensing, and a handful of budget streaming sticks either don’t support it at all or fall back to software decoding that struggles with anything beyond 1080p. If your household plays media on a genuinely mixed fleet of devices, it’s worth confirming HEVC playback actually works smoothly on the oldest device you still use regularly before committing an entire library to it — the storage savings are real, but they’re not worth a library that plays back stuttering on the one device a family member actually uses most.
Is it worth running
If your library is large enough that storage is a real constraint, and it’s carrying a meaningful fraction of older or inefficiently encoded files, yes — the storage reclaimed is often dramatic, and hardware acceleration makes the time cost tolerable rather than a multi-week ordeal. If your library is already mostly efficient H.265 or storage genuinely isn’t a constraint, this is a lot of processing time and risk to a library you already have working fine, for a benefit you don’t actually need. And regardless of library size: do not skip the health-check and keep-originals step on your first real batch. A tool that batch-modifies every file in your library is the one place in this whole ecosystem where a misconfiguration doesn’t just waste time, it can cost you content you can’t easily get back.




