Transcode Doctor for Jellyfin — guide

Installation

You need Jellyfin Server 12.2 or newer and a MediaLab Works account with a license that covers the plugin (an active subscription, a lifetime license within its update window, the Jellyfin bundle or the free 30-day trial).

From your plugin repository (recommended). Jellyfin then installs and updates the plugin by itself.

In your MediaLab Works account open Licenses → Jellyfin plugin repository and click Create address. Copy it: it is private (it contains a token), so do not share it; you can regenerate or revoke it at any time.
In Jellyfin open Dashboard → Plugins → Repositories, click +, give it a name (for example MediaLab Works), paste the address and save.
In Dashboard → Plugins → Catalog find Transcode Doctor by MediaLab, click Install, then restart Jellyfin.

The repository lists only the plugins your licenses cover, and only the versions they allow. Its download links are signed and expire after a few hours, so Jellyfin always reads a fresh list.

From the public catalog. https://medialab.works/jellyfin/manifest.json lists every released MediaLab Works plugin with its public build; medialab Server adds it by itself. You can add it the same way to install a plugin before you have a key: the plugin then asks for the license, or starts the trial, on its License page. With a lifetime license whose update window has ended, keep to your private repository, which offers only the versions your license allows.

Manually, from a zip file.

In Account → Licenses download jf-transcodedoctor_x.y.z.zip (the SHA-256 of the file is shown next to the button).
Extract it into a new folder Transcode Doctor by MediaLab_x.y.z.0 inside the Jellyfin plugins folder:
- Linux (package): /var/lib/jellyfin/plugins/
- Docker (official image): /config/plugins/ in the config volume
- Windows: %ProgramData%\Jellyfin\Server\plugins\
Restart Jellyfin.

License activation

Open the plugin page in Dashboard → Plugins → Transcode Doctor by MediaLab and click License.
Paste your license key and click Activate with key. The plugin contacts the license server, binds the key to this Jellyfin server and shows the license as Active.
No key yet? On the same page enter your e-mail and start the 30-day free trial (card needed, nothing to pay today) or buy a license; the plugin activates itself when the payment is done.

The license is checked once a day and at every Jellyfin start. Without internet the plugin keeps working for 7 days after the last successful check. Without a valid license the plugin stops its work and only its License page keeps working (trial, key, renewal); nothing is deleted, and everything resumes as soon as the license is valid again. Move license (release this server) on the same page frees the key for another server.

Updates and rollback

From the repository: Jellyfin shows new versions in Dashboard → Plugins and can update the plugin automatically; restart Jellyfin to load the new version.
From the plugin's License page: with a valid license, Install update installs the newest version your license allows and Roll back to x.y.z goes back to the previous version (for example if something stopped working after an update). Restart Jellyfin after either. Both packages are checked against the checksum published by the license server.
A lifetime license receives the versions released during its update window; after it, the plugin keeps working on the last version it may use.
After Roll back to x.y.z, Jellyfin's automatic update for that plugin is turned off until the next Install update on the License page, so the scheduled task Update Plugins (at start-up and daily) does not bring the newer version back.
Lifetime license and automatic updates. The public Jellyfin catalog (https://medialab.works/jellyfin/manifest.json) always offers the newest version. When the update window of a lifetime license has ended, versions released after it are not licensed: if Jellyfin's automatic plugin updates install one, the plugin stops with "version not licensed" until you go back with Roll back to x.y.z on its License page or buy an update pass. To avoid it, don't let Jellyfin update this plugin automatically: add your private plugin repository, which offers only the versions your license allows, instead of the public catalog, or remove the triggers of the scheduled task Update Plugins in Dashboard → Scheduled Tasks (this stops automatic updates for every plugin).

Source code

The GPL-3.0 source code of each version is in Account → Licenses (Source code), next to the download, as a .tar.gz archive made from the exact commit of that version.

Configuration

Open Transcode Doctor in the Jellyfin dashboard menu.

Hardware acceleration diagnosis: click Run the tests. The plugin checks ffmpeg, the NVIDIA card and the /dev/dri devices, creates a few short test clips with ffmpeg in Jellyfin's cache folder, then tries each method (NVIDIA NVENC, Intel QuickSync, VA-API) at decoding H.264, HEVC, HEVC 10-bit, MPEG-2, VP9 and AV1 and at encoding H.264 and HEVC. Each test takes at most a minute; the table shows what works and how fast.
Problems: if something blocks acceleration, the page says what and how to fix it. The most common one is Jellyfin without access to /dev/dri/renderD128: run the command shown (it adds the Jellyfin user to the render group), restart Jellyfin and run the tests again. In Docker, pass the GPU device into the container.
Recommendation: the method that passed the most tests, the decoding codecs, hardware encoding and about how many 1080p transcodes can run at once, next to your current settings.
Apply the settings writes the recommendation into Dashboard → Playback → Transcoding: the acceleration method, the hardware decoding codecs, HEVC 10-bit decoding, hardware encoding and the VA-API / QuickSync device. VC-1, VP8 and MPEG-4 decoding, which cannot be tested, stay as you set them; HEVC encoding is turned off if it failed and is never turned on by the plugin.
Restore the previous settings puts back the transcoding settings saved just before the last apply. You can always change them by hand in Jellyfin as well.

Daily use

Why it transcodes lists the recent transcoded playbacks: when, who, what, the reasons in plain words with what can be done, and whether the GPU or the CPU did the work. "CPU (GPU not used)" for a playback while acceleration is configured means the card was not used.
When a video transcode runs on the CPU although acceleration is configured, the plugin writes an entry in Jellyfin's activity log.
Run the tests again after a driver, Jellyfin or hardware change.

Troubleshooting

The diagnosis failed: ffmpeg not found: install jellyfin-ffmpeg and set its path in Dashboard → Playback → Transcoding.
Every VA-API / QuickSync test fails: check the problems list; usually the Jellyfin user is missing from the render group or the device is not passed into the Docker container.
Every NVENC test fails: the NVIDIA driver is missing or nvidia-smi does not respond.
No hardware method passed the tests: transcoding stays on the CPU; nothing is applied.