Transcode Doctor for Jellyfin

Jellyfin does not detect your graphics card by itself: the acceleration method and the codecs are chosen by hand, and a wrong choice or a missing permission sends transcoding back to the processor without any warning. Transcode Doctor tests what your server can really do, tells you what is missing and applies the settings that work.

What it does

• Hardware acceleration diagnosis: checks ffmpeg, the NVIDIA card and the /dev/dri devices (with the permissions of the Jellyfin process), then runs short test transcodes on the server with each method — NVIDIA NVENC, Intel QuickSync and VA-API (Intel / AMD). Each method is tested at decoding H.264, HEVC, HEVC 10-bit, MPEG-2 (TV), VP9 and AV1 and at encoding H.264 and HEVC, with the measured speed. The test clips are generated by ffmpeg in Jellyfin's cache folder; your media is not touched.
• Problems with the exact fix: for example "Jellyfin cannot access /dev/dri/renderD128 — sudo usermod -aG render jellyfin, then restart Jellyfin", an NVIDIA card whose driver does not respond, or ffmpeg missing at the configured path.
• Recommendation and one-click apply: the method that works best, the decoding codecs that passed, hardware encoding and an estimate of how many 1080p transcodes can run at the same time. Apply the settings writes them into Jellyfin's transcoding settings; nothing changes until you click it.
• One-click restore: before applying, the plugin saves your previous transcoding settings; Restore the previous settings puts them back exactly.
• Why it transcodes: the recent transcoded playbacks, each with Jellyfin's reasons explained in plain words and what can be done (for example burned-in PGS subtitles, HDR on an SDR screen, the app's bitrate limit). Up to 500 playbacks are kept.
• CPU fallback alert: an entry in Jellyfin's activity log when a video transcode runs on the processor although hardware acceleration is configured.
• In English and Romanian.

What it changes in Jellyfin

Only when you click Apply the settings, and only in Dashboard → Playback → Transcoding: the hardware acceleration method, the hardware decoding codecs (the ones that passed; VC-1, VP8 and MPEG-4, which cannot be tested, stay as you set them), HEVC 10-bit decoding, hardware encoding and the VA-API / QuickSync device. HEVC encoding is turned off if it failed the test; the plugin never turns it on. The restore puts back the settings from before the last apply.

Requirements

• Jellyfin Server 12.2 or newer, with jellyfin-ffmpeg (the ffmpeg build that comes with Jellyfin).
• An NVIDIA, Intel or AMD graphics card with its driver: for NVIDIA, the driver with nvidia-smi; for Intel and AMD, a /dev/dri render device the Jellyfin user can open (usually through the render group). In Docker, the device must be passed into the container.

Frequently asked

Why does Jellyfin transcode on the CPU even though my server has a GPU? Usually the acceleration method or the codecs are set wrong, or the Jellyfin user has no access to the GPU. Transcode Doctor finds which one and fixes the settings. See the guide.

Can it break my transcoding? It only applies settings that passed the tests on your server, after you click, and keeps the previous ones for a one-click restore.

What it sends where

• No external contact besides the licensing client. It downloads no test files: sample clips (H.264, HEVC, HEVC 10-bit, MPEG-2, VP9, AV1) are generated locally with jellyfin-ffmpeg, in the server's cache folder (transcode-doctor/). Your media files are not touched.
• Local processes: jellyfin-ffmpeg, nvidia-smi (only if an NVIDIA card exists), an access check on /dev/dri/renderD*.
• The diagnosis runs only when you click the button. Session watching (every 15 s, licensed only) reads the transcoding info of active playbacks; the "fell back to CPU" alert (on by default) only writes to the local activity log.
• "Apply" (one click, admin-initiated only) saves the recommended hardware-acceleration settings, after saving the old ones to state/encoding-before.json; "Revert" restores them.
• Plus the licensing client, the same in every plugin: see Licensing and privacy in our plugins.

Stored locally (state/ in the plugin data folder): report.json (last diagnosis: ffmpeg path, GPU, results), history.json (last 500 transcoded playbacks: time, user, app, device, title, transcode reasons, hardware/CPU), synthetic clips in cache.

Never sent: none of the above leaves the server.

Client compatibility

• Watching and alerts are server-side: 🟢 works with any client that triggers a transcode.
• UI: admin page only — Jellyfin Web / medialab Server ✅ (checked visually; no automated end-to-end test).
• Hardware tested: NVIDIA (NVENC) on a real Quadro M2000 ✅. Intel QSV / VA-API: detected and tested by the plugin, ❔ not tested on real hardware. AMD AMF, Apple VideoToolbox, Rockchip: not supported.
• Checks are Linux-oriented (/dev/dri, nvidia-smi, render group); Windows/macOS: ❔ not tested.

Legend: ✅ verified (end-to-end or on-device test) · 🟢 server-side, works with any client (by design, no client-specific test) · ➖ not applicable · ❔ not tested.

Licensing

The plugin is open source (GPL-3.0). The ready-to-install builds are public, like the source code. What you buy is the subscription: the license to use the plugin on one Jellyfin server, the updates your plan includes, and support: every update while the subscription is active, through your private plugin repository, and help when something does not work. The plugin checks the subscription key once a day; without a valid subscription it stops until you renew (nothing is deleted). Monthly, yearly or lifetime (lifetime includes one year of updates), or included in the Jellyfin bundle. 30-day free trial.

Source code. For every release, the complete corresponding source code is public, next to the build, in the changelog, and also in your account (Account → Licenses, Source code); each archive contains the full GPL-3.0 text (LICENSE). If you need the source of a version you can no longer download, ask us and we send it. See section 10 of the EULA.

Transcode Doctor is our own code, written by MediaLab Works for Jellyfin; it contains no third-party code.