jellyfin-sdk 0.2.0

A Possible Official Python SDK for Jellyfin.

Jellyfin SDK for Python

---

A High-level Wrapper for OpenAPI Generated Bindings for Jellyfin API.

Warning: API changes will occur only in the final classes, bindings and legacy don't change

The main goal of this project is to be a wrapper for the API but with high level of abstraction using the power of OpenAPI Specs bindings and good patterns such as Inversion of Control, Method Chaining, JSONPath, and more.

Main unique features:

• Enables targeting a specific Jellyfin server version to ensure compatibility and prevent breaking changes.
• Supports accessing multiple servers, each potentially running different Jellyfin versions.
• Allows reducing the level of abstraction to access advanced or unavailable options through lower-level interfaces.
• Works like AWS CDK Constructs Level, more abstraction, more simple.

How modules work together

There is a thin layer that builds the high-level abstraction (green box/jellyfin) consuming only the bindings that already contain dataclasses and api built using the OpenAPI Generator (blue box/generated), which in turn also allows use only if the user requests jellyfin_apiclient_python (purple box/legacy) to allow for refactoring and incremental development. Both legacy and generated have classes that allow low-level access, being practically just an envelope method for requests that must communicate with the actual jellyfin API (lilac box).

This project is mainly inspired by good python library like these:

• tmdbsimple
• plexapi
• tensorflow

Install

pip install jellyfin-sdk

or

uv add jellyfin-sdk

Usage

Drop-in replacement for jellyfin-apiclient-python

This library includes the old legacy client (which is almost unmaintained) to help with migration:

pip uninstall jellyfin-apiclient-python
pip install jellyfin-sdk[legacy]

# change from
from jellyfin_apiclient_python import JellyfinClient
from jellyfin_apiclient_python.api import API

# to this
from jellyfin.legacy import JellyfinClient
from jellyfin.legacy.api import API

List of current problems in legacy project already fixed here:

• Fixed missing exception when user id is missing#70

import jellyfin

jellyfin.api(os.getenv("URL"), os.getenv("API_KEY")).users.libraries

ValueError: User ID is not set. Use the 'of(user_id)' method to set the user context.

• Fixed Info and Configuration missmatch #69

import jellyfin

jellyfin.api(os.getenv("URL"), os.getenv("API_KEY")).system.info

• Add Playlist endpoints#64

import jellyfin
from jellyfin.items import ItemCollection, Item
from jellyfin.generated import PlaylistsApi, BaseItemKind

api = jellyfin.api(os.getenv("URL"), os.getenv("API_KEY"))
api.user = 'justin'
playlist = api.items.search.add('include_item_types', [BaseItemKind.PLAYLIST]).recursive().all.first
playlist

<Item
  name="Editor's Choice",
  original_title=None,
  server_id='REDACTED',
  id=UUID('ec0770d5-bde0-794c-bc1e-c5e8ff0588ca'),
  etag=None,
  source_type=None,
  playlist_item_id=None,
  date_created=None,
  date_last_media_added=None,
  extra_type=None
  ...
]>

# no high level abstraction, let's use bindings for playlist
ItemCollection(Item(
    PlaylistsApi().get_playlist_items(playlist.id, api.user.id)
))

Easy to debug

Debug is a missing peace in every implementation I look at, even the jellyfin team have a hard time to see what happen. To help to remove the SDK of equation and for code more complex we have a feature to allow show a curl command of every request in the server.

import jellyfin
from jellyfin.items import ItemCollection
from jellyfin.generated import PlaylistsApi, BaseItemKind

api = jellyfin.api(os.getenv("URL"), os.getenv("API_KEY"))
api.debug = True

playlist = api.items.search.add('include_item_types', [BaseItemKind.PLAYLIST]).recursive().all.first

The api.debug enable the client to print all requests in curl in prompt. Never use this in production!

curl '-X' GET \n
    '-H' 'Accept: application/json' \n
    '-H' 'User-Agent: OpenAPI-Generator/10.10/python' \n
    '-H' 'Authorization: MediaBrowser Token="API_KEY"' \n
    URL/Items?recursive=true&includeItemTypes=Playlist

Lots of problems happens in the api server or behavior not in documentation, in this way you have data to open a issue in jellyfin.

Login

import os

os.environ["URL"] = "https://jellyfin.example.com"
os.environ["API_KEY"] = "MY_TOKEN"

Using SDK

import jellyfin

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

print(
    api.system.info.version,
    api.system.info.server_name
)

Direct with Generated Bindings

from jellyfin.generated.api_10_10 import Configuration, ApiClient, SystemApi

configuration = Configuration(
    host = os.getenv("URL"),
    api_key={'CustomAuthentication': f'Token="{os.getenv("API_KEY")}"'}, 
    api_key_prefix={'CustomAuthentication': 'MediaBrowser'}
)

client = ApiClient(configuration)
system = SystemApi(client)

print(
    system.get_system_info().version, 
    system.get_system_info().server_name
)

It's possible use the proxy direct, this always will point to current stable

# specific
from jellyfin.generated.api_10_10 import Configuration, ApiClient, SystemApi

# current stable
from jellyfin.generated import Configuration, ApiClient, SystemApi

# current unstable
from jellyfin.generated.api_10_11 import BackupApi

# inject from high level abstraction
import jellyfin

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

# module loader
api.generated

<module 'jellyfin.generated.api_10_10' from '/code/jellyfin-sdk-python/src/jellyfin/generated/api_10_10/__init__.py'>

# injected from bindings
client = api.generated.ApiClient

<class 'jellyfin.generated.api_10_10.api_client.ApiClient'>

Legacy

from jellyfin.legacy import JellyfinClient
client = JellyfinClient()
client.authenticate(
    {"Servers": [{
        "AccessToken": os.getenv("API_KEY"), 
        "address": os.getenv("URL")
    }]}, 
    discover=False
)
system_info = client.jellyfin.get_system_info()

print(
    system_info.get("Version"), 
    system_info.get("ServerName")
)

Jellyfin Server API Version

This is important because when a new API version is released, breaking changes can affect the entire project. To avoid this, you can set an API target version, similar to how it's done in Android development:

from jellyfin.api import Version
import jellyfin

# By default will use the lastest stable
jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

# now let's test the new API (version 10.11) for breaking changes in same endpoint
jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY"), 
    Version.V10_11
)

# but str is allow to: 10.10, 10.11 and etc
jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY"), 
    '10.11'
)

# let's test a wrong version
jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY"), 
    '99'
)

ValueError: Unsupported version: 99. Supported versions are: ['10.10', '10.11']

List all libraries of an user

When using API_KEY some endpoints need the user_id (don't me ask why!), almost all issues with jellyfin is around this. To help to identify this not-so-much-edge-cases we raise a exception to help with that:

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

api.users.libraries

ValueError: User ID is not set. Use the 'of(user_id)' method to set the user context.


api.users.of('f674245b84ea4d3ea9cf11').libraries

# works also with the user name
api.users.of('niels').libraries

# when using 'of' the attribute of dataclasses
# user and user_view can be accessed directly
api.users.of('niels').id

List all items

Item can be any object in the server, in fact that's how works, one huge table recursive linked.

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

api.items.all

# Same command but without shorthand
search = api.items.search
search

<ItemSearch (no filters set)>

search.paginate(1000)

<ItemSearch filters={
  start_index=0,
  limit=1000,
  enable_total_record_count=True
}>

search.recursive()

<ItemSearch filters={
  start_index=0,
  limit=1000,
  enable_total_record_count=True,
  recursive=True
}>

All filter options is available here.

The pagination uses a Iterator:

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

for item in api.items.search.paginate(100).recursive().all:
    print(item.name)

Let's get the User ID by name or ID

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

uuid = api.user.by_name('joshua').id

api.user.by_id(uuid).name

Get item by ID

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

api.items.by_id('ID')

This is just a shorthand for:

api.items.search.add('ids', ['ID']).all.first

Upload a Primary Image for a Item

import jellyfin
from jellyfin.generated import ImageType

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

api.image.upload_from_url(
    'ID', 
    ImageType.PRIMARY,
    'https://upload.wikimedia.org/wikipedia/commons/6/6a/Jellyfin_v10.6.0_movie_detail%2C_web_client.png'
)

Add tags in a collection

Edit item require the user_id, but we make this easy:

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)

item = api.items.edit('ID', 'joshua')
item.tags = ['branding']
item.save()

item = api.items.edit('ID', 'niels')
item.tags = ['rules']
item.save()

If you want to set a global user:

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)
api.user = 'niels'

item = api.items.edit('ID')
item.tags = ['branding']
item.save()

item = api.items.edit('OTHER_ID')
item.tags = ['rules']
item.save()

The user on edit method has precedence over global

Register as a client

If necessary register a client to identify ourselves to the server

api = jellyfin.api(
    os.getenv("URL"), 
    os.getenv("API_KEY")
)
api.register_client()

<Api
 url='https://jellyfin.example.com',
 version='10.10',
 auth='Token="***",
       Client="4b8caf670ca1",
       Device="Linux Ubuntu 24.04.3 LTS (noble)",
       DeviceId="a7-17-23-d8-b9-b8",
       Version="24.04.3"'
>

If you need customize the client information:

api.register_client('test')

<Api
 url='https://jellyfin.example.com',
 version='10.10',
 auth='Token="***",
       Client="test",
       Device="Linux Ubuntu 24.04.3 LTS (noble)",
       DeviceId="a7-17-23-d8-b9-b8",
       Version="24.04.3"'
>

For more detail look the docs.

Documentation

• SDK Reference
• Jellyfin API 10.10 (Stable)
• Jellyfin API 10.11 (Release Candidate)

Supported Jellyfin Versions

SDK Version	Jellyfin API Target
0.1.x	10.10.x-10.11.x