jellyfin-kodi: a Jellyfin client that writes into Kodi's own database

Two projects that normally do not meet

The Jellyfin for Kodi add-on is described as a whole new way to manage and view your media library, and the pitch is a combination of two things that are usually in tension.

On the Kodi side: ultra smooth navigation, beautiful user interfaces and playback of any file under the sun. On the Jellyfin side: the most powerful open source multi-client media metadata indexer and server. The add-on joins them, and the argument for it is the line about retiring your MySQL setup in favour of a more flexible setup.

That sentence is aimed at a specific history. The pitch is aimed at setups that run a MySQL database they have to maintain, and the plugin offers a more flexible arrangement in its place. The plugin's answer is to synchronise your media on the Jellyfin server into the native Kodi database, so you browse at full speed with the tools Kodi already has, while keeping the ability to use other Kodi add-ons and any Kodi skin you like.

So the design goal is not to be another Jellyfin client. It is to make Jellyfin's library look and feel like a native Kodi library while keeping Jellyfin as the source of truth. Everything else in the plugin follows from that decision, including the two limitations the project documents.

The hybrid sync, and what ends up in the native database

The add-on supports a hybrid approach, and the README explains it in one sentence: you can decide which Jellyfin libraries to sync to the Kodi database, and the other libraries and features are accessible dynamically as a plugin listing.

The list of library types that can be synchronised covers movies and sets, TV shows, music videos, and music. The features that are not synchronised but remain reachable through the plugin include Simple Live TV presentation, Home Videos and photos, playlists, and theme media.

That split is the trade. A synchronised library is fast because the metadata is in Kodi's own database and Kodi's native library queries are answering, with no network round trip per browse. An unsynchronised library is a remote view, which is slower and which depends on the server being up.

Playback itself supports direct play and transcode, so the plugin is not restricted to formats the client can decode, and the skins work as they always do because the synchronised content is ordinary Kodi content.

The mode of operation also matters, because the known limitations attach to it. The plugin has a native playback mode and a plugin mode, and which one you are in decides whether some things work at all.

Two way state, remote control, and the small touches

The feature list has a few items that are about the relationship between the server and the client rather than about the library itself.

There is a two way watched and resume state between the server and Kodi, and the README calls it a near instant feature. That is the item people notice first, because it is the one that changes daily behaviour: you stop watching something on the television and pick it up on a phone, or the other way round, without a manual mark as watched.

You can also remote control your Kodi and send play commands from the Jellyfin web client or the Jellyfin mobile apps, which turns the television into a playback target you can drive from a phone, and it is the feature that makes the plugin more than a library browser.

The smaller entries are what separate this from a minimal client. Extrafanart, rotating backgrounds, for skins that support it. An offer to delete content after playback, which is a small feature that some people care about a lot. And the ability to back up your Jellyfin Kodi profile, with a link to the older create and restore from backup guide, which matters because the synchronised library is a local copy and a local copy can be rebuilt but only if you know how.

The supported list also ends with and more, which is an honest way to end a feature list in a project that has been iterated for years.

The two limitations, and the setting that decides them

The known limitations section is short and both entries point at the same thing.

Chapter images are missing unless native playback mode is used. And certain add-ons that depend on seeing where your content is located will not work unless native playback mode is selected.

The second one is the more consequential. Some Kodi add-ons are path aware, in the sense that they look at the file on disk to do something, whether that is reading a subtitle from beside the video or working out what is playing. When the content is being served from Jellyfin rather than read from a local file, there is no local path for them to see, and they stop working.

So native playback mode is not a preference, it is the setting that determines whether the add-on behaves like a native Kodi library or like a remote browser. If your setup depends on path aware add-ons, that is a hard constraint. If you need chapter artwork, it is another one.

The workaround in both cases is the same, and it is worth understanding why it exists. Native playback mode plays the file the way Kodi normally plays a local file, which means the paths are real, and the trade is the one the hybrid model makes throughout: the more native the behaviour, the more you are relying on the local database and the local file layout rather than on the server being the single source of truth.

Kodi support follows a current release plus one policy

The support target is stated in one line at the top of the README: the informal Kodi support target is the current release plus or minus one, which at the time of writing translates to Nexus as the old release, Omega as the current one and Piers as the next.

The next line is the one that matters for planning. The next release is a moving target, has a relatively low priority, and is unlikely to receive active work before the release candidate stage.

That is a candid statement of how the plugin handles the bleeding edge of Kodi. Kodi's addon architecture changes between major versions often enough that supporting a new one is real work, and the project prefers to do that work after the release candidate is out, when the shape of the release is settled. The cost is that on the newest Kodi you may be running a plugin that is not being actively fixed for that version yet.

The practical approach for an install is to stay on the current release if you can, and to read the release notes before moving to a new major version of Kodi, because the plugin's own version numbering moves in step and the jump is where behaviour changes land.

The contribution policy on generated code is unusually firm

The contributing section has an AI and LLM subsection that is worth quoting, because it is stricter than most projects are about it and it is written plainly.

Any pull request, issue or comment that is primarily LLM generated will be rejected outright on principle. Machine translation as a communication aid is allowed, but requires disclosure and that you also include the original language text. LLM generated code has a high probability of getting rejected. Relatively low effort AI contributions put an unsustainable and unproportional extra burden on project maintainers, which during the review process need to understand the suggested changes and evaluate whether they are good changes and whether there are better alternatives.

The reasoning is given too. LLM can be a decent tool to get up to speed and learn the code base, but is highly likely to generate subpar code, and it is fine for debugging, research and proof of concept, but not currently suitable for production code.

For a contributor, the practical effect is that you have to write the change yourself and be able to explain why it is the right change, and the machine translation allowance is a useful contrast because it is a case where the tool is allowed with disclosure and the original text kept. The project also points at Jellyfin's official LLM policy page, so the rule is part of the wider project rather than a local invention.

The rest of the development setup is visible in the repository: black for formatting, mypy with a mypy.ini, tox.ini, separate requirements-dev.txt and requirements-test.txt files, a pre-commit configuration, a devcontainer and a dev-tools/ directory, and a .build/ directory for packaging.

Editorial conclusion

jellyfin-kodi fits a household that runs Jellyfin as its library and Kodi on the television, and that wants the Kodi experience of skins, local add-ons and instant browsing rather than the Jellyfin web client projected to a screen. It does not fit a setup where every library must be browsable at full speed at once, because you choose what is synchronised and the rest is a plugin listing, and it does not fit a user who needs chapter artwork or add-ons that resolve file locations. Verify three things before you commit: which Kodi versions you are targeting against the current release plus one policy, whether your skins and add-ons need native playback mode, because that setting decides whether chapter images and location aware add-ons work at all, and how the two way watched and resume state behaves for you, since it is the feature most likely to surprise people who have two different viewing habits across devices.

Frequently asked questions

Official sources

1. jellyfin/jellyfin-kodi on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases