application.integrations.subsonic package#

Subpackages#

Submodules#

application.integrations.subsonic.exceptions module#

exception application.integrations.subsonic.exceptions.ConnectionError(message)#

Bases: SessionError

Exception raised for errors occurring during a connection attempt in a session.

This exception is a subclass of SessionError and is used to indicate issues related to establishing or maintaining a connection.

None#
exception application.integrations.subsonic.exceptions.ResponseError(message)#

Bases: SessionError

Exception raised for errors in the response during a session.

Inherits from:

SessionError

Use this exception to indicate that an error occurred while processing a response in a session.

exception application.integrations.subsonic.exceptions.SessionError(message)#

Bases: Exception

Exception raised for errors related to Subsonic sessions.

Parameters:

message (str) – Description of the error.

Example

raise SessionError(“Invalid session token”)

application.integrations.subsonic.subsonic_client module#

Subsonic API client implementation.

class application.integrations.subsonic.subsonic_client.SubsonicClient(host, username, password, *, client='subsonic-py', version='1.15.0')#

Bases: object

SubsonicClient provides an interface to interact with a Subsonic music server via its REST API.

Parameters:

  • host (str) – The base URI of the Subsonic server.

  • username (str) – The username for authentication.

  • password (str) – The password or MD5 hash, depending on server configuration.

  • client (str, optional) – The client identifier. Defaults to ‘subsonic-py’.

  • version (str, optional) – The Subsonic API version. Defaults to ‘1.15.0’.

rest_params#

The REST API authentication and client parameters.

Type:

str

connection_uri#

The base URI for API requests.

Type:

str

query(action, parameters={}, process=True) → str | dict#

Executes a generic Subsonic API query.

ping() → dict#

Checks connectivity to the Subsonic server.

search(

text, artist_count=None, artist_offset=None, album_count=None, album_offset=None, song_count=None, song_offset=None, music_folder_id=None

) -> SearchResults

Searches for artists, albums, and songs matching the query text.

playlists -> list[Playlist]

Returns a list of available playlists.

playlist(name) → Playlist | None#

Retrieves a playlist by name.

license -> str

Returns the license information for the Subsonic server.

folders -> dict[str, str]

Returns a mapping of music folder names to their IDs.

albums(folder, page, count=40) → list#

Retrieves a paginated list of albums from a specified music folder.

album_songs(album_id) → list[Song]#

Retrieves the list of songs in a specified album.

cover_art(cover_art_id) → str#

Retrieves the cover art for a given ID, encoded as a base64 string.

album_songs(album_id)#

Retrieves a list of songs from a specified album.

Parameters:

album_id (str) – The unique identifier of the album.

Returns:

A list of Song objects representing the tracks in the album.

Return type:

list[Song]

albums(folder, page, count=40)#

Retrieves a paginated list of albums from a specified music folder.

Parameters:

  • folder (str) – The name of the music folder to retrieve albums from.

  • page (int) – The page number (zero-based) to retrieve.

  • count (int, optional) – The number of albums per page. Defaults to 40.

Returns:

A list of Album objects for the specified folder and page.

Return type:

list

Raises:

ResponseError – If the specified folder does not exist.

cover_art(cover_art_id)#

Retrieves the cover art image for the specified cover art ID, encodes it in base64, and returns it as a string.

Parameters:

cover_art_id (str) – The unique identifier for the cover art to retrieve.

Returns:

The base64-encoded cover art image.

Return type:

str

Raises:

Any exceptions raised by the query method or during base64 encoding. –

property folders: dict[str, str]#

Retrieves a dictionary mapping music folder names to their corresponding IDs.

Returns:

A dictionary where the keys are folder names

and the values are folder IDs.

Return type:

dict[str, str]

property license: str#

Retrieves the license information from the Subsonic server.

Returns:

The license string if available, otherwise an empty string.

Return type:

str

ping()#

Sends a ‘ping’ request to the Subsonic server to check connectivity.

Returns:

An instance of Ping containing the server’s response data.

If a ConnectionError occurs, returns a Ping object with status ‘failed’ and unknown version and server values.

Return type:

Ping

playlist(name)#

Retrieves a playlist by its name.

Parameters:

name (str) – The name of the playlist to retrieve.

Returns:

The playlist object with the specified name if found, otherwise None.

Return type:

Playlist | None

property playlists: list[Playlist]#

Retrieves a list of playlists from the Subsonic server.

Returns:

A list of Playlist objects, each initialized with data from the server response and helper functions for querying and streaming.

Return type:

list[Playlist]

The method sends a ‘getPlaylists’ query to the server, extracts the playlist data, and constructs Playlist instances with appropriate query and stream functions.

query(action, parameters=None, *, process=True)#

Executes a query against the Subsonic API. :type action: str :param action: The API action to perform. :type action: str :type parameters: dict | None :param parameters: Parameters to include in the query. Defaults to None. :type parameters: dict, optional :type process: bool :param process: Whether to process the response. Defaults to True. :type process: bool, optional

Returns:

The response from the API, either as a raw string or a processed dictionary.

Return type:

str | dict

search(text, *, artist_count=None, artist_offset=None, album_count=None, album_offset=None, song_count=None, song_offset=None, music_folder_id=None)#

Searches for artists, albums, and songs matching the given text query.

Parameters:

  • text (str) – The search query string.

  • artist_count (int | None, optional) – Maximum number of artists to return.

  • artist_offset (int | None, optional) – Offset for artist results (for pagination).

  • album_count (int | None, optional) – Maximum number of albums to return.

  • album_offset (int | None, optional) – Offset for album results (for pagination).

  • song_count (int | None, optional) – Maximum number of songs to return.

  • song_offset (int | None, optional) – Offset for song results (for pagination).

  • music_folder_id (int | None, optional) – ID of the music folder to restrict the search.

Returns:

An object containing the search results for artists, albums, and songs, along with helper functions for querying and streaming.

Return type:

SearchResults

Module contents#