Skip to main content

Jellyfin ApiClient Python

This is the API client from Jellyfin Kodi extracted as a python package so that other users may use the API without maintaining a fork of the API client. Please note that this API client is not complete. You may have to add API calls to perform certain tasks. Please see Contributing below.

Usage

This client can be installed with pip3 install jellyfin-apiclient-python and imported with import jellyfin_apiclient_python.

Creating a client

from jellyfin_apiclient_python import JellyfinClient
client = JellyfinClient()

You need to set some configuration values before you can connect a server:

client.config.app('your_brilliant_app', '0.0.1', 'machine_name', 'unique_id')
client.config.data["auth.ssl"] = True

Authenticating to a server

If you do not have a token, you will need to connect via username and password:

client.auth.connect_to_address('server_url')
client.auth.login('server_url', 'username', 'password')

You can then generate a token:

credentials = client.auth.credentials.get_credentials()
server = credentials["Servers"][0]
server["username"] = 'username'
json.dumps(server)

And if you wish then use that token to authenticate in future:

json.loads(credentials)
client.authenticate({"Servers": [credentials]}, discover=False)

You can also authenticate using an API key, which is generated on the server. This is different to a device AccessToken, and is set by not configuring a device name, or a device id:

client.config.data["app.name"] = 'your_brilliant_app'
client.config.data["app.version"] = '0.0.1'
client.authenticate({"Servers": [{"AccessToken": '<API key here>', "address": '<Server Address>'}]}, discover=False)

# Some endpoint require a user context event using API Key.

client.config.data["auth.user_id"] = '<UserID here>'
client.authenticate({"Servers": [{"AccessToken": '<API key here>', "address": '<Server Address>'}]}, discover=False)

API

The API is accessed via the jellyfin attribute of the client. Return values are a dictionary with 3 members, "Items", "TotalRecordCount" and "StartIndex"

The easiest way to fetch media objects is by calling search_media_items, like so:

client.jellyfin.search_media_items(term="And Now for Something Completely Different", media="Videos")

For details on what the individual API calls do or how to do a certain task, you will probably find the Jellyfin MPV Shim and Jellyfin Kodi repositories useful.

Running the tests

The test suite is run via tox, and you can install it from PyPi.

  • To run the linter: tox -elint
  • To run the test suite, for Python 3.9: tox -epy39
  • You can run multiple environments, if you wish: tox -elint,py311

Changes from Jellyfin Kodi

  • Removal of websocket.py (now a dependency to websocket_client).
  • Removal of dependencies on helper (from Jellyfin Kodi) and kodi_six.
  • Add has_attribute directly to __init__.py.
  • Add API calls:
    • get_season for fetching season metadata.
    • get_audio_stream to read an audio stream into a file
    • search_media_items to search for media items
    • audio_url to return the URL to an audio file
  • Add parameters aid=None, sid=None, start_time_ticks=None, is_playback=True to API call get_play_info.
  • Add timesync manager and SyncPlay API methods.
  • Remove usage of six module.
  • Add group of remote_ API calls to remote control another session
  • Configurable item refreshes allowing custom refresh logic (can also iterate through a list of items)
  • Add support for authenticating via an API key
  • Add support for the optional 'date played' parameter in the item_played API method
  • Add API calls get_userdata_for_item and update_userdata_for_item
  • Add API call get_playlist_items for fetching a playlist's contents in order
  • Add support for the backup API introduced in Jellyfin 10.11.0
  • Extend the (currently) experimental identify API call to include all parameters supported by Jellyfin
  • Fix close_live_stream sending the stream id as a JSON body; the server binds it from the query string, so the call always failed and leaked the tuner
  • Add API call get_user_items, a named-argument form of the general item query (GET Users/{UserId}/Items) that browse UIs otherwise had to build by hand
  • Add browse API calls get_resume_items, get_random_items, get_items_by_person, get_album_tracks, get_artist_albums, get_artist_songs, get_genre_songs and get_playlists
  • Add Live TV API calls get_programs and get_recommended_programs, and add paging/field/add_current_program parameters to get_channels, which was previously unbounded (note that LiveTv/Channels has no way to skip the total record count, unlike the item endpoints)
  • Add API calls get_endpoint_info (System/Endpoint) and update_user_settings, the write side of get_user_settings
  • Add API calls get_chapter_image and get_trickplay_tile for downloading chapter thumbnails and scrubbing-preview tiles
  • Add parameters fields, enable_image_types, image_type_limit and enable_total_record_count to get_recently_added, fields to get_items, and paging/sorting parameters to get_collections, get_artists and get_album_artists
  • Add parameters timeout and retry to sessions, so a health check can fail fast instead of waiting out the client-wide defaults
  • Add parameter include_segment_types to get_media_segments

Contributing

When contributing, please maintain backward compatibility with existing calls in the API. Adding parameters is fine, but please make sure that they have default options to prevent existing software from breaking. Please also add your changes to the Changes from Jellyfin Kodi section.

If you would like to produce documentation for this API, I would also be interested in accepting pull requests for documentation.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jellyfin_apiclient_python-1.18.0.tar.gz (85.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

jellyfin_apiclient_python-1.18.0-py3-none-any.whl (69.1 kB view details)

Uploaded Python 3

File details

Details for the file jellyfin_apiclient_python-1.18.0.tar.gz.

File metadata

File hashes

Hashes for jellyfin_apiclient_python-1.18.0.tar.gz
Algorithm Hash digest
SHA256 8a3d77111f748e3c5396f7651bd9a26c1bc7d7342cc57899ac59c14cf8bcbbab
MD5 7bcf41ae4c9bd6c9b88477f50d569c87
BLAKE2b-256 c76011c0fa95d235146e33317294bb0c8df90e3f2ee8bfbf20437767aae5ee8e

See more details on using hashes here.

File details

Details for the file jellyfin_apiclient_python-1.18.0-py3-none-any.whl.

File metadata

File hashes

Hashes for jellyfin_apiclient_python-1.18.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f459c0c785eb08e40f90fd51f09312f58f8d7807dbf64688467640f5cca3d326
MD5 386aea56e9c7b49af72b37931da9cd1f
BLAKE2b-256 7399bc0555653d8598d14e25661a308cb1817a94d60efde02acc7216b79a62f6

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.18.0 This release

2 files

1.17.0

2 files

1.16.0

2 files

1.15.0

2 files

1.14.0

2 files

1.13.0

2 files

1.12.0

2 files

1.11.0

2 files

1.10.0

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.1

2 files

1.8.0

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.1

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.0

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page