Skip to main content

Python API client for Jellyfin

Project description

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)

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

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.

Project details


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.10.0.tar.gz (61.1 kB view details)

Uploaded Source

Built Distribution

jellyfin_apiclient_python-1.10.0-py3-none-any.whl (50.2 kB view details)

Uploaded Python 3

File details

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

File metadata

File hashes

Hashes for jellyfin_apiclient_python-1.10.0.tar.gz
Algorithm Hash digest
SHA256 e6589f2e8b6600bb967e0b58a0f065cf45618235e65980a67b57b237657f217e
MD5 3bfa1c6a4c7b12484a29d963d790fe8a
BLAKE2b-256 288036494795ce450d8ff4c9aab5042db953fde21bd6105ddcb02b9681fed053

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for jellyfin_apiclient_python-1.10.0-py3-none-any.whl
Algorithm Hash digest
SHA256 db7d1d2cce1261909a690420d93c346b296e3ecfc17ccf2ffc33f5880d408840
MD5 c6aad10ba17473c206659a14d7c03d3e
BLAKE2b-256 95c88d8ed75cb0e829056e778c2ef942becbc6b11f5029ebb88ff7dd528eebeb

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page