media.jellyfin

media.jellyfin#

Description#

Plugin to interact with a Jellyfin media server.

Note: As of February 2022, this plugin also works with Emby media server instances. Future back-compatibility if the two APIs diverge, however, is not guaranteed.

Note: At the current state, it is advised to use API keys retrieved from the frontend rather than the server-generated API keys (open Developer Tools in your browser while logged in to Jellyfin, go to the Network tab, select any request, and grab the Token from the Authorization header).

This is because of known limitations in the user session management in the Jellyfin API - see this discussion and this issue.

Configuration#

media.jellyfin:
  # [Required]
  # Jellyfin base server URL (including ``http://`` or ``https://``).
  server:   # type=str

  # [Required]
  # Server API key. You can generate one from
  # ``http(s)://your-server/web/index.html#!/apikeys.html``.
  api_key:   # type=str

  # [Optional]
  # Customize results for the specified user
  # (default: user associated to the API token if it's a user token, or the first created
  # user on the platform).
  # username:   # type=Optional[str]

Actions#

Module reference#

class platypush.plugins.media.jellyfin.MediaJellyfinPlugin(server: str, api_key: str, username: str | None = None, **kwargs)[source]#

Bases: Plugin

Plugin to interact with a Jellyfin media server.

Note: As of February 2022, this plugin also works with Emby media server instances. Future back-compatibility if the two APIs diverge, however, is not guaranteed.

Note: At the current state, it is advised to use API keys retrieved from the frontend rather than the server-generated API keys (open Developer Tools in your browser while logged in to Jellyfin, go to the Network tab, select any request, and grab the Token from the Authorization header).

This is because of known limitations in the user session management in the Jellyfin API - see this discussion and this issue.

__init__(server: str, api_key: str, username: str | None = None, **kwargs)[source]#
Parameters:

  • server – Jellyfin base server URL (including http:// or https://).

  • api_key – Server API key. You can generate one from http(s)://your-server/web/index.html#!/apikeys.html.

  • username – Customize results for the specified user (default: user associated to the API token if it’s a user token, or the first created user on the platform).

add_to_playlist(playlist_id: str, item_ids: Collection[str]) → dict[source]#

Add items to a playlist.

Parameters:

  • playlist_id – ID of the playlist.

  • item_ids – List of item IDs to add to the playlist.

create_playlist(name: str, public: bool = True, item_ids: Collection[str] | None = None) → dict[source]#

Create a new playlist.

Parameters:

  • name – Name of the playlist.

  • public – Whether the playlist should be visible to any logged-in user.

  • item_ids – List of item IDs to add to the playlist.

delete_item(item_id: str) → dict[source]#

Delete an item from the server.

Parameters:

item_id – ID of the item to delete.

get_artists(limit: int | None = 100, offset: int = 0, query: str | None = None, is_played: bool | None = None, is_favourite: bool | None = None, is_liked: bool | None = None, genres: Iterable[str] | None = None, tags: Iterable[str] | None = None, years: Iterable[int] | None = None) → Iterable[dict][source]#

Get a list of artists on the server.

Parameters:

  • limit – Maximum number of items to return (default: 100).

  • offset – Return results starting from this (0-based) index (default: 0).

  • query – Filter items by this term.

  • is_played – Return only played items (or unplayed if set to False).

  • is_liked – Return only liked items (or not liked if set to False).

  • is_favourite – Return only favourite items (or not favourite if set to False).

  • genres – Filter results by (a list of) genres.

  • tags – Filter results by (a list of) tags.

  • years – Filter results by (a list of) years.

Returns:

[
  {
    "can_delete": true,
    "collection_type": "constant",
    "created_at": "2020-01-01T00:00:00+00:00",
    "id": "Artist ID",
    "image": "Artist main image (URL)",
    "item_type": "constant",
    "name": "Artist name",
    "path": "Path to collection",
    "type": "constant"
  }
]

get_collections(parent_id: str | None = None, recursive: bool = False) → Iterable[dict][source]#

Get the list of collections associated to the user on the server (Movies, Series, Channels etc.)

Parameters:

  • parent_id – Filter collections under the specified parent ID.

  • recursive – If true, return all the collections recursively under the parent.

Returns:

[
  {
    "can_delete": false,
    "collection_type": "string",
    "created_at": "2020-01-01T00:00:00+00:00",
    "id": "Collection ID",
    "image": "string",
    "item_type": "constant",
    "name": "Collection name",
    "path": "Path to collection",
    "type": "constant"
  }
]

get_items(parent_id: str, recursive: bool = False, limit: int | None = 100) → Iterable[dict][source]#

Get all the items under the specified parent ID.

Parameters:

  • parent_id – ID of the parent item.

  • recursive – If true, return all the items recursively under the parent.

  • limit – Maximum number of items to return (default: 100).

get_playlist_items(playlist_id: str, limit: int | None = 10000) → Iterable[dict][source]#

Get the items in a playlist.

Parameters:

  • playlist_id – ID of the playlist.

  • limit – Maximum number of items to return (default: 10000).

get_playlists() → Iterable[dict][source]#

Get the list of playlists associated to the user on the server.

Returns:

[
  {
    "can_delete": true,
    "collection_type": "constant",
    "created_at": "2020-01-01T00:00:00+00:00",
    "duration": 76,
    "genres": [
      "string"
    ],
    "id": "string",
    "image": "string",
    "item_type": "constant",
    "n_items": 8,
    "name": "string",
    "path": "Path to collection",
    "public": false,
    "tags": [
      "string"
    ],
    "type": "constant"
  }
]

info(item_id: str) → dict[source]#

Get the metadata for a specific item.

Parameters:

parent_id – ID of the parent item.

playlist_move(playlist_id: str, *_, from_pos: int | None = None, to_pos: int, item_id: str | None = None, **__)[source]#

Move items in a playlist.

Either from_pos or item must be specified.

Parameters:

  • playlist_id – ID of the playlist.

  • from_pos – Starting position of the item to move (0-based).

  • to_pos – New position of the item (0-based).

  • item_id – Playlist ID of the item to move, as returned by get_playlist_items(). Note: This is the playlist_item_id on the response, not the id.

remove_from_playlist(playlist_id: str, item_ids: Collection[str]) → dict[source]#

Remove items from a playlist.

Parameters:

  • playlist_id – ID of the playlist.

  • item_ids – List of item IDs to remove from the playlist. Note: These are the playlist_item_id on the response of get_playlist_items(), not the id.

search(limit: int | None = 100, offset: int = 0, sort_desc: bool | None = None, query: str | None = None, collection: str | None = None, parent_id: str | None = None, has_subtitles: bool | None = None, minimum_community_rating: int | None = None, minimum_critic_rating: int | None = None, is_played: bool | None = None, is_favourite: bool | None = None, is_liked: bool | None = None, genres: Iterable[str] | None = None, tags: Iterable[str] | None = None, years: Iterable[int] | None = None) → Iterable[dict][source]#

Perform a search on the server.

Parameters:

  • limit – Maximum number of items to return (default: 100).

  • offset – Return results starting from this (0-based) index (default: 0).

  • sort_desc – Return results in descending order if true, ascending if false.

  • query – Filter items by this term.

  • collection – ID/name of the collection to search (Movies, TV, Channels etc.)

  • parent_id – Filter items under the specified parent ID.

  • has_subtitles – Filter items with/without subtitles.

  • minimum_community_rating – Filter by minimum community rating.

  • minimum_critic_rating – Filter by minimum critic rating.

  • is_played – Return only played items (or unplayed if set to False).

  • is_liked – Return only liked items (or not liked if set to False).

  • is_favourite – Return only favourite items (or not favourite if set to False).

  • genres – Filter results by (a list of) genres.

  • tags – Filter results by (a list of) tags.

  • years – Filter results by (a list of) years.

Returns:

The list of matching results.

Schema for artists:
{
  "can_delete": false,
  "collection_type": "constant",
  "created_at": "2020-01-01T00:00:00+00:00",
  "id": "Artist ID",
  "image": "Artist main image (URL)",
  "item_type": "constant",
  "name": "Artist name",
  "path": "Path to collection",
  "type": "constant"
}
Schema for collections:
{
  "can_delete": false,
  "collection_type": "string",
  "created_at": "2020-01-01T00:00:00+00:00",
  "id": "Collection ID",
  "image": "string",
  "item_type": "constant",
  "name": "Collection name",
  "path": "Path to collection",
  "type": "constant"
}
Schema for movies:
{
  "can_delete": true,
  "community_rating": 74,
  "container": "mp4",
  "created_at": "2020-01-01T00:00:00+00:00",
  "critic_rating": 8,
  "duration": 66,
  "file": "string",
  "genres": [
    "string"
  ],
  "has_subtitles": false,
  "id": "string",
  "image": "https://example.org",
  "imdb_url": "https://www.imdb.com/title/tt1234567/",
  "item_type": "constant",
  "overview": "string",
  "path": "string",
  "tags": [
    "string"
  ],
  "title": "string",
  "trailer_url": "https://example.org",
  "type": "constant",
  "url": "https://example.org",
  "year": 33
}
Schema for episodes:
{
  "can_delete": false,
  "community_rating": 6,
  "container": "mp4",
  "created_at": "2020-01-01T00:00:00+00:00",
  "critic_rating": 58,
  "duration": 78,
  "file": "string",
  "genres": [
    "string"
  ],
  "has_subtitles": true,
  "id": "string",
  "image": "https://example.org",
  "imdb_url": "https://www.imdb.com/title/tt1234567/",
  "item_type": "constant",
  "overview": "string",
  "path": "string",
  "tags": [
    "string"
  ],
  "title": "string",
  "trailer_url": "https://example.org",
  "type": "constant",
  "url": "https://example.org",
  "year": 38
}