Auto-detect GPU/iGPU/APU/NPU and automatically configure hardware acceleration, codecs and subtitle handling

[ford220102]

Summary

Jellyfin should automatically detect available GPU hardware on startup
and configure hardware acceleration, supported codecs, and subtitle
delivery without requiring manual setup by the user.

Problem

Currently every user must manually:

• Select the correct acceleration method (AMF/VAAPI/NVENC/QSV)
• Enable/disable each codec individually (H264, HEVC, AV1, VP9...)
• Configure subtitle burn-in per client type

This leads to broken setups, unnecessary CPU transcoding, and
silent failures with no guidance. Non-technical users have no way
to know which settings are correct for their hardware.

Real-world examples:

• AMD RX 580 with AMF enabled causes silent transcoding failures;
  user must manually revert to CPU with no error message
• Enabling AV1 on GCN-era AMD GPU (which has no AV1 support)
  silently breaks transcoding
• ASS/SSA subtitles force full video transcoding on Android TV
  because burn-in is not auto-configured for the client
• FFmpeg embedded album art extraction times out with no fallback

Proposed solution

On first run and on each startup, Jellyfin should:

1. Detect available GPU/iGPU/APU/NPU via FFmpeg or system API
   (D3D11VA/DXVA on Windows, /dev/dri on Linux)
2. Automatically select correct acceleration method:
   • AMD on Windows → AMF
   • AMD/Intel on Linux → VAAPI
   • Intel on Windows → QSV
   • NVIDIA → NVENC/NVDEC
3. Query FFmpeg to detect which codecs are actually supported
   by the detected hardware and enable only those
4. Fall back to CPU automatically if GPU acceleration fails,
   and log the reason clearly
5. Detect per-session what subtitle formats the client supports
   and automatically choose: direct / extract / burn-in
6. Display detected hardware info in Dashboard > Playback
   so the user can verify the automatic configuration

Expected result

• User installs Jellyfin
• Jellyfin detects hardware and configures itself correctly
• Playback works with hardware acceleration out of the box
• Subtitles work correctly on all clients without manual setup
• No expert knowledge required

Current result

• Default is "None" (CPU only) with no detection or suggestion
• Wrong manual settings cause silent failures
• Subtitle handling requires manual configuration per client type
• RAM and CPU overloaded when GPU could handle the workload

Environment where this was observed

• OS: Windows 11
• GPU: AMD Radeon RX 580 2048SP (GCN / Polaris)
• Client: Jellyfin for Android TV
• Jellyfin: 10.11.11
• FFmpeg: jellyfin-ffmpeg 7.1.4-3

Additional notes

Plex performs basic hardware auto-detection out of the box.
Jellyfin should offer the same baseline experience for
non-technical users. This would also significantly reduce
repeated support requests in the community.

[gnattu]

This is planned but no ETA yet due to the complexity of current transcoding pipeline. Adding this would eventually requiring a refactor of current transcoders.

[MDeveloping]

Question:
Does every user really have to enable GPU acceleration? I thought this was configured for everyone by the server administrator under Administration → Playback → Transcoding.

[gnattu]

Does every user really have to enable GPU acceleration?

No. Without GPU acceleration the server would also work.

[MDeveloping]

Yes, I know, but with GPU acceleration it's better, so the question is, if this is a global option which is configured by administrator or have every user to configure it?

[gnattu]

It is global and an admin only option.

[absidue]

@MDeveloping In the original post where it says user it actually means the admin, it looks like LLM output (or at least is formatted like it), so problems with the text are probably to be expected.

[ford220102]

I used AI to help me translate and understand this issue, as I am a Polish speaker. I am not a native English speaker, so I apologize for any confusion.

[all3f0r1]

As @gnattu already noted, this is a large undertaking rather than a single fix. Having looked through the server code, I wanted to lay out the concrete scope so it's clear why this can't land as one PR, and what would actually be involved in closing it.

This request bundles six largely independent workstreams, and roughly half of them live outside jellyfin (the server) in jellyfin-web.

What already exists today (reusable building blocks)

• FFmpeg capability probing — ffmpeg -hwaccels/-encoders/-decoders in EncoderValidator.cs.
• VAAPI driver detection (AMD Mesa / Intel iHD / i965) via ffmpeg -init_hw_device, run at startup in MediaEncoder.SetFFmpegPath() but only when a HW type is already selected in EncodingOptions.
• macOS VideoToolbox AV1 capability check.
• A generic config API (ConfigurationController) and encoding.xml persistence.

What is missing and would have to be built

1. Hardware type auto-detection. There is currently no logic that identifies the vendor/path (NVIDIA→NVENC, AMD→AMF/VAAPI, Intel→QSV, NPU) or enumerates devices (/dev/dri on Linux, D3D11VA/DXVA on Windows). The accel type is a manual choice.
2. Codec capability gating per device. Probing exists, but mapping "this specific GPU supports/does not support AV1/HEVC/VP9" into the enabled-codec set (the RX 580 / GCN AV1 example in the issue) is new logic.
3. Automatic CPU fallback on failure. This is the big one. Today the entire decision is made statically at command-build time in EncodingHelper (~8k lines), and TranscodeManager runs a single pass. If a HW encoder fails at runtime, the transcode just fails. Real auto-fallback needs a "first attempt → detect failure → retry on CPU → log reason" path that does not exist yet.
4. Per-session subtitle method auto-selection (direct / extract / burn-in). The decision tree lives in StreamBuilder.GetSubtitleProfile() and EncodingHelper.ShouldEncodeSubtitle() (checked in ~17 places), driven by per-client DeviceProfile. Changing the heuristics means auditing those paths carefully.
5. A recommendation/validation layer that turns detection results into a suggested config and warns on impossible combinations.
6. Dashboard UI to surface detected hardware and the auto-config — this is in jellyfin-web, not here.

Why it is invasive

EncodingHelper.cs is a ~8,000-line monolith with 30+ direct references to EncodingOptions and ~100+ build-time capability probes; StreamBuilder.cs is ~2,500 lines. There is no separation between capability detection and command building, and no runtime fallback layer, which is exactly the "refactor of current transcoders" already mentioned.

Suggested path forward

If this is to make progress incrementally, the only piece that is cleanly isolatable without touching the transcode core is #1 + #5 as a read-only "detect & recommend" endpoint: scan the hardware, surface what is detected, and suggest (not apply) a configuration. The automatic fallback (#3) and subtitle auto-selection (#4) genuinely require the pipeline refactor and should probably be tracked as their own issues so this one does not become a permanent catch-all.

[MDeveloping]

What do you think about adding a test button instead of auto-detection, so the server administrator can verify whether the selected options are working correctly and gpu acceleration is active?

This would at least be a good intermediate step and would require less effort.

[goinsandrew]

I agree, Rather than rebuild the wheel, I see it as something like a printer dialog with tray configuration.

• Go to Transcoding settings
• click "Query Hardware" and get a response with what the hardware lists.
• Click a button to enable suggested settings with a warning that settings are not guaranteed to work.
• Have a "Test transcode" button that allows you to select a existing media item, and it will attempt to play it with various transcoding settings, prompting the user after each test to confirm it worked.

[ford220102]

Thanks @all3f0r1 for breaking this down so clearly — that's exactly the kind of scope that isn't visible from a user's perspective.
The phased approach makes sense as a starting point, but I'd like to stress that the end goal should really be a full, proper fix in the transcoding pipeline itself — not just a "detect & recommend" endpoint plus manual test buttons as a permanent solution. Those are reasonable first steps, but they're still workarounds that shift the burden back to the user. The real fix is the refactor @all3f0r1 described: automatic detection, automatic codec gating, and automatic CPU fallback built into the code, so this stops being something users (or admins) have to manage or troubleshoot manually at all.
I get that this is a big undertaking, but I'd rather see this tracked as a real end goal (even if delivered in stages) than have the incremental fixes become the final state by default.

[all3f0r1]

@ford220102 Fully agree on the end goal, and having dug deeper since my last comment, I want to be honest about what "a full, proper fix" actually implies.

The transcoding pipeline is only the visible part of the problem. When I traced how far the coupling goes, it doesn't stop at EncodingHelper.cs: nearly everything funnels through two god classes, BaseItem (~3,000 lines) and LibraryManager (~3,600 lines). Media source resolution, stream selection, playback info, metadata, user data: every code path a capability-aware pipeline would need to touch runs through them, with static state and circular dependencies layered on top. You can't cleanly carve out "detect capabilities, gate codecs, build the command, fall back at runtime" while those layers stay entangled.

We may be able to figure out a way to work around those, but the ideal fix isn't a refactor of the encoding code alone. It starts with dismantling BaseItem and LibraryManager into proper, separately testable services. That's an enormous ask for any upstream contributor, and I didn't expect anyone to volunteer for it given the scale, so I've been exploring it myself in a private exploratory project.

Happy to share findings with anyone who wants to tackle pieces of it upstream.

[ford220102]

I agree that the problem goes much deeper than just the transcoding layer. A proper capability-aware pipeline needs clean separation between media discovery, stream selection, playback decisions and encoding, otherwise every fix becomes another workaround.

Breaking down BaseItem and LibraryManager would definitely be a huge task, but I think it could be approached incrementally instead of trying to rewrite everything at once. Creating new services around existing logic and gradually moving responsibilities out could reduce the risk.

I would be interested in seeing your findings from the exploratory project. Even partial architectural ideas or dependency maps could help identify smaller pieces that could be improved upstream.

[all3f0r1]

@ford220102 Gladly. Here are a few findings that I think are directly actionable upstream, kept at the architectural level. Your intuition about "creating new services around existing logic and gradually moving responsibilities out" matches exactly what worked; the details below are mostly about where the safe boundaries are.

1. The static coupling is not one problem, it's about seven. Auditing the static BaseItem.LibraryManager usage across the entity classes, the call sites split into distinct ownership categories: lookup and parent resolution, query/listing, collection folders and library options, mutation and registration, alternate-version maintenance, images/extras, and legacy sort fallbacks. Rough counts in the entities folder alone: ~35 uses in BaseItem.cs, ~30 in Video.cs, ~27 in Folder.cs. The practical consequence: "remove the statics" is not one refactor but a sequence, and the only safe first slice is read-only lookup and parent resolution (GetParent(), Episode.Series, Season.Series, etc.). Everything else pairs repository writes with cache and item-registration side effects, so mutations and alternate-version repair must never be bundled into the same change as lookup. Also worth knowing before touching it: GetItemById is not a simple facade, it participates in cache, retrieval, registration and visibility semantics that differ per call site.

2. The DI cycle is much thinner than it looks. LibraryManager and UserViewManager form a two-node constructor cycle, held together today by the Lazy<IUserViewManager> inside LibraryManager. The decisive observation: the consumers that actually close the loop only ever call one method, GetUserViews. Nothing in the cycle needs GetUserSubView or GetLatestItems. So you don't have to break up IUserViewManager wholesale; extracting a one-method IUserViewCatalog port, implemented against leaf services (item lookup, user root folder, sorting) with no ILibraryManager reference, removes the Lazy entirely and the cycle with it. I'd bet other apparent cycles in the codebase have the same shape: a wide interface hiding a single-method dependency. Mapping which methods each edge of a cycle actually uses is cheap and very high value.

3. Parity can be proven instead of hoped for. The technique that made the extractions safe: characterization tests on the legacy behavior first, then a shadow mode that dual-runs the legacy path and the new implementation on sampled real traffic, with a time budget and aggregated mismatch metrics. This caught ordering and null-handling divergences that unit tests missed. Any upstream extraction of query/listing logic would benefit from the same harness; it costs far less than debugging behavioral regressions after release.

And to tie it back to this discussion: once the query/lookup side is decoupled, modeling hardware capabilities as its own layer (what the hardware can decode vs. what we should encode to, as separate concepts) becomes straightforward. So the phased plan holds: detection and recommendation can be built as an isolated component early, while automatic runtime fallback genuinely waits on the pipeline untangling.

[ford220102]

Thanks for taking the time to write this up. This is exactly the kind of architectural insight I was hoping for.

The point about treating the static coupling as several independent refactors rather than one large change makes a lot of sense, especially separating read-only lookup from mutation paths. The observation about GetItemById carrying cache and registration semantics is also something that's easy to underestimate.

The IUserViewCatalog extraction is particularly interesting. Breaking the cycle by introducing a narrow interface instead of splitting IUserViewManager entirely seems like a pragmatic first step.

I also like the characterization test + shadow mode approach. Having measurable parity before switching implementations would make upstream reviews much easier and reduce the risk of subtle regressions.

Thanks again for sharing these findings. If you continue documenting the dependency boundaries or identify other safe extraction points, I'd be very interested in reading them.

[sevenrats]

Please remember that according to our rules that the use of AI for any form of direct communication will result in a ban. The single exception exists for foreign language speakers who wish to use LLM's to translate, but this must be disclosed in advance. If we were to suspect that a person were using AI in their communications with this organization, we would respond by removing that person.

[ford220102]

I'm sorry, but I needed help with translation and understanding the language because I'm not very good at it and I know they can confuse English with understanding people, and it's true what I replied about the help with translation, I'm still sorry, can I leave this matter?

[albarago]

Hello all, I've been working on figuring out a seamless solution for this issue which can be easily integrated into JF core. I would love for y'all to check out my proposal, and hopefully test it and provide feedback. Thank you!! (Would love to hear from @gnattu on what you think of the approach I'm proposing)

jellyfin/jellyfin-meta#163