Table of Contents

• Table of Contents
• jellyfin
  • jellyfin.api
• jellyfin.api
• jellyfin.api.Api Objects
  • __init__
  • __repr__
  • __str__
  • user
  • user
  • configuration
  • client
  • register_client
  • libraries
• jellyfin.base
• jellyfin.base.Pagination Objects
• jellyfin.base.Model Objects
  • model
  • __str__
  • __repr__
  • summary
• jellyfin.base.Collection Objects
  • __iter__
  • model
  • data
  • __len__
• jellyfin.items
• jellyfin.items.Item Objects
  • save
• jellyfin.items.ItemSearch Objects
  • __setattr__
  • __getattr__
  • __delattr__
  • add
  • remove
  • next_page
  • paginate
  • all
  • recursive
  • name_starts_with
  • only_library
• jellyfin.items.Items Objects
  • __init__
  • all
  • by_id
  • edit
  • search
• jellyfin.image
• jellyfin.image.Image Objects
  • __init__
  • upload_from_url
  • upload_from_file
  • get_image_tmp
• jellyfin.system
• jellyfin.system.System Objects
  • __init__
  • info
• jellyfin.users
• jellyfin.users.Users Objects
  • __init__
  • of
  • by_id
  • by_name
  • all
  • libraries
  • views
  • __repr__
  • __getattr__

jellyfin

Entrypoint module for the Jellyfin SDK.

jellyfin.api

def api(url: str, api_key: str, version: Version = Version.V10_10) -> Api

Create an instance of the Jellyfin API client.

Arguments:

• url str - The base URL of the Jellyfin server.
• api_key str - The API key for authentication.
• version Version - The API version to use (default is Version.V10_10).

Returns:

• Api - An instance of the Api class.

jellyfin.api

Module api - High-level interface for ApiClient and Configuration.

jellyfin.api.Api Objects

class Api()

__init__

def __init__(url: str, api_key: str, version: Version = Version.V10_10)

Initializes the Jellyfin API client.

Arguments:

• url str - The base URL of the Jellyfin server.
• api_key str - The API key for authentication.
• version Version - The API version to use (default is Version.V10_10).

Raises:

• ValueError - If an unsupported version is provided.

Returns:

• Api - An instance of the Api class.

__repr__

def __repr__()

Official string representation of the Api instance.

__str__

def __str__()

String representation of the Api instance.

user

@property
def user() -> User | None

Returns the user context for the API requests.

user

@user.setter
def user(value: str | uuid.UUID)

Sets the user context for the API requests.

Arguments:

• value str | uuid.UUID - The user to set, either as a username or UUID.

configuration

@property
def configuration() -> Configuration

Returns the Configuration instance.

client

@property
def client() -> ApiClient

Returns the ApiClient instance.

register_client

def register_client(client_name: str = None,
                    device_name: str = None,
                    device_id: str = None,
                    device_version: str = None) -> Self

Just register this as a client with the server.

Arguments:

• client_name str, optional - The name of the client application. Defaults to the hostname if not provided.
• device_name str, optional - The name of the device. Defaults to the OS name if not provided.
• device_id str, optional - The unique identifier for the device. Defaults to the MAC address if not provided.
• device_version str, optional - The version of the client application. Defaults to the OS version if not provided.

Returns:

• Api - The current instance of the Api class.

libraries

@property
def libraries() -> ItemCollection

Alias for items of type COLLECTIONFOLDER.

Returns:

• ItemCollection - A collection of all libraries.

jellyfin.base

jellyfin.base.Pagination Objects

class Pagination(Protocol)

Protocol for paginated responses.

jellyfin.base.Model Objects

class Model()

model

@property
def model() -> BaseModel

Returns the generated model

__str__

def __str__() -> str

Returns the string representation of the model.

__repr__

def __repr__() -> str

Returns a detailed string representation of the Item object, with each attribute on a new line.

summary

def summary(empty: bool = False, size: int = 80, limit: int = 100) -> None

Prints the simple representation of the model.

Arguments:

• empty bool - If True, includes all values. If False, omits empty values (None, "", 0, [], {}).

jellyfin.base.Collection Objects

class Collection(Sequence)

__iter__

def __iter__()

Returns an iterator for the collection.

Usage: collection = ItemCollection(...) for item in collection: print(collection.current) # Always shows the current item

model

@property
def model() -> Model

Returns the reference model.

data

@property
def data() -> List[BaseModel]

Returns the reference list of items inside model.

__len__

def __len__()

Returns the total number of records in the collection.

Returns:

• int - The total number of records.

jellyfin.items

Module items - High-level interface for ItemsApi.

jellyfin.items.Item Objects

class Item(Model)

save

def save() -> Item

Save changes made to the item.

Returns:

• Item - The updated item.

jellyfin.items.ItemSearch Objects

class ItemSearch()

Based on DataFrame Builder pattern

Usage: search = api.items.search search.is_movie = False search.user_id = "abc" result = search.all()

api.items.search.add(is_movie=False).all()
api.items.search.filter({
    "is_movie": False, 
    "user_id": "abc"
}).all()

__setattr__

def __setattr__(name, value)

Set a filter using 'search.attr = value'

Arguments:

• name str - The name of the attribute to set.
• value Any - The value to set the attribute to.

__getattr__

def __getattr__(name)

Get a filter using 'search.attr'

Arguments:

• name str - The name of the attribute to retrieve.

Returns:

• Any - The value of the specified attribute, or None if not found.

__delattr__

def __delattr__(name)

Remove a filter using 'del search.attr'

Arguments:

• name str - The name of the attribute to remove.

add

def add(key: str, value: Any) -> Self

Add multiple filters at once using 'search.add(attr=value, ...)'

Arguments:

• key str - The name of the attribute to add.
• value Any - The value to set the attribute to.

Returns:

• ItemSearch - The current ItemSearch instance (for chaining).

remove

def remove(key: str) -> Self

Remove multiple filters at once using 'search.remove(attr, ...)'

Arguments:

• key str - The name of the attribute to remove.

Returns:

• ItemSearch - The current ItemSearch instance (for chaining).

next_page

def next_page() -> ItemCollection

Move to the next page of results based on the current pagination settings.

Returns:

• ItemCollection - A collection of items for the next page.

paginate

def paginate(size: int = 100) -> Self

Enable pagination.

Arguments:

• size int - The maximum number of results to return per page. Defaults to 100. Zero turns off pagination.

Returns:

• ItemSearch - The current ItemSearch instance (for chaining).

all

@property
def all() -> ItemCollection

Execute the search and return all results as an ItemCollection

Returns:

• ItemCollection - A collection of items matching the search criteria.

recursive

def recursive(flag: bool = True) -> Self

Shortcut to enable recursive search

name_starts_with

def name_starts_with(prefix: str) -> Self

Shortcut to filter by name prefix

only_library

def only_library() -> Self

Shortcut to filter only libraries (collections)

jellyfin.items.Items Objects

class Items()

__init__

def __init__(api: Api)

Initializes the Items API wrapper.

Arguments:

• api Api - An instance of the Api class.

all

@property
def all() -> ItemCollection

Returns all items as an ItemCollection.

Returns:

• ItemCollection - A collection of all items.

by_id

def by_id(item_id: str | UUID) -> Item

Returns an item by its ID.

Returns:

• Item - The item with the specified ID.

edit

def edit(item: Item | str | UUID, user: str | UUID = None) -> Item

Edits an item.

Arguments:

• item Item | str | UUID - The item to edit, either as an Item instance or its ID.
• user str | UUID - The user context for the edit, either as a username or UUID.

Returns:

• Item - The edited item.

search

@property
def search() -> ItemSearch

Returns an ItemSearch instance for building search queries.

Returns:

• ItemSearch - An instance of ItemSearch for building search queries.

jellyfin.image

Module image - High-level interface for ImageApi.

jellyfin.image.Image Objects

class Image()

__init__

def __init__(api: Api)

Initializes the Image API wrapper.

Arguments:

• api Api - An instance of the Api class.

upload_from_url

def upload_from_url(item: Item | str | uuid.UUID, image_type: ImageType,
                    uri: str) -> bool

Uploads an image for a given item.

Arguments:

• item Item | str | uuid.UUID - The item to upload the image for.
• image_type ImageType - The type of the image (e.g., "Primary", "Backdrop").
• uri str - The URI of the image file.

Returns:

• bool - True if the upload was successful, False otherwise.

upload_from_file

def upload_from_file(item: Item | str | uuid.UUID, image_type: ImageType,
                     file_path: str) -> bool

Uploads an image for a given item from a local file.

Arguments:

• item Item | str | uuid.UUID - The item to upload the image for.
• image_type ImageType - The type of the image (e.g., "Primary", "Backdrop").
• file_path str - The path to the local image file.

Returns:

• bool - True if the upload was successful, False otherwise.

get_image_tmp

def get_image_tmp(uri: str) -> str

Downloads an image from a URI to a temporary file.

Arguments:

• uri str - The URI of the image to download.

Returns:

• str - The path to the temporary file containing the downloaded image.

jellyfin.system

Module system - High-level interface for SystemAPI.

jellyfin.system.System Objects

class System()

__init__

def __init__(api: Api)

Initializes the System API wrapper.

Arguments:

• api Api - An instance of the Api class.

info

@property
def info() -> SystemInfo

Returns system information.

Returns:

• SystemInfo - System information.

jellyfin.users

Module user - High-level interface for UserApi and UserViewsApi.

jellyfin.users.Users Objects

class Users()

__init__

def __init__(api: Api)

Initializes the User API wrapper.

Arguments:

• api Api - An instance of the Api class.

of

def of(user_name_or_uuid: str | uuid.UUID) -> Self

Set user context

Arguments:

• user_name_or_uuid str | uuid.UUID - The UUID or name of the user.

Raises:

• ValueError - If the provided user_name_or_uuid is not a valid UUID or name.

Returns:

• User - The current User instance with the user context set.

by_id

def by_id(user_id: uuid.UUID) -> User

Get user by ID

Arguments:

• user_id uuid.UUID - The UUID of the user.

Returns:

• User - The user object if found.

by_name

def by_name(user_name: str) -> User | None

Get user by name

Arguments:

• user_name str - The name of the user.

Returns:

User | None: The user object if found, otherwise None.

all

@property
def all() -> UserCollection

Get all users.

Returns:

• UserCollection - A list of all users.

libraries

@property
def libraries() -> ItemCollection

Get libraries for the current user context.

Returns:

• ItemCollection - A list of libraries.

views

@property
def views() -> ItemCollection

Get views for the current user context.

Raises:

• ValueError - If user ID is not set.

Returns:

• ItemCollection - A list of libraries.

__repr__

def __repr__()

String representation of the Users instance.

__getattr__

def __getattr__(name)

Delegate attribute access to user_api, user_views_api, or the current user object.