Browsing

Browsing(api, subsonic)

Class that contains all the methods needed to interact with the browsing endpoints in the Subsonic API.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def __init__(self, api: Api, subsonic: "Subsonic") -> None:
    self.api = api
    self.subsonic = subsonic

get_album(album_id)

Get all the info about an album.

Parameters:

Name	Type	Description	Default
album_id	str	The ID of the album to get its info.	required

Returns:

Type	Description
Album	An object that contains all the info about the requested album.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_album(self, album_id: str) -> Album:
    """Get all the info about an album.

    Args:
        album_id: The ID of the album to get its info.

    Returns:
        An object that contains all the info about
            the requested album.
    """

    response = self.api.json_request("getAlbum", {"id": album_id})["album"]

    return Album(self.subsonic, **response)

get_album_info(album_id)

Get all the extra info about an album.

Parameters:

Name	Type	Description	Default
album_id	str	The ID of the album to get its extra info.	required

Returns:

Type	Description
AlbumInfo	An object that contains all the extra info about the requested album.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_album_info(self, album_id: str) -> AlbumInfo:
    """Get all the extra info about an album.

    Args:
        album_id: The ID of the album to get its extra info.

    Returns:
        An object that contains all the extra info about
            the requested album.
    """

    response = self.api.json_request("getAlbumInfo2", {"id": album_id})["albumInfo"]

    return AlbumInfo(self.subsonic, album_id, **response)

get_album_info_non_id3(album_id)

Get all the extra info about an album. Not organized according ID3 tags.

Parameters:

Name	Type	Description	Default
album_id	str	The ID of the album to get its extra info.	required

Returns:

Type	Description
AlbumInfo	An object that contains all the extra info about the requested album.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_album_info_non_id3(self, album_id: str) -> AlbumInfo:
    """Get all the extra info about an album. Not organized according
    ID3 tags.

    Args:
        album_id: The ID of the album to get its extra info.

    Returns:
        An object that contains all the extra info about
            the requested album.
    """

    response = self.api.json_request("getAlbumInfo", {"id": album_id})["albumInfo"]

    return AlbumInfo(self.subsonic, album_id, **response)

get_artist(artist_id)

Get all the info about an artist.

Parameters:

Name	Type	Description	Default
artist_id	str	The ID of the artist to get its info.	required

Returns:

Type	Description
Artist	An object that contains all the info about the requested artist.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_artist(self, artist_id: str) -> Artist:
    """Get all the info about an artist.

    Args:
        artist_id: The ID of the artist to get its info.

    Returns:
        An object that contains all the info about
            the requested artist.
    """

    response = self.api.json_request("getArtist", {"id": artist_id})["artist"]

    return Artist(self.subsonic, **response)

get_artist_info(artist_id, max_similar_artists=None, include_similar_artists_not_present=None)

Get all the extra info about an artist.

Parameters:

Name	Type	Description	Default
artist_id	str	The ID of the artist to get its extra info.	required
max_similar_artists	int | None	The max number of similar artists to return.	None
include_similar_artists_not_present	bool | None	Include similar artists that are not present in any the media library.	None

Returns:

Type	Description
ArtistInfo	An object that contains all the extra info about the requested artist.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_artist_info(
    self,
    artist_id: str,
    max_similar_artists: int | None = None,
    include_similar_artists_not_present: bool | None = None,
) -> ArtistInfo:
    """Get all the extra info about an artist.

    Args:
        artist_id: The ID of the artist to get its extra info.
        max_similar_artists: The max number of similar artists to
            return.
        include_similar_artists_not_present: Include similar artists
            that are not present in any the media library.

    Returns:
        An object that contains all the extra info about
            the requested artist.
    """

    response = self.api.json_request(
        "getArtistInfo2",
        {
            "id": artist_id,
            "count": max_similar_artists,
            "includeNotPresent": include_similar_artists_not_present,
        },
    )["artistInfo2"]

    return ArtistInfo(self.subsonic, artist_id, **response)

get_artist_info_non_id3(artist_id, max_similar_artists=None, include_similar_artists_not_present=None)

Get all the extra info about an artist. Not organized according ID3 tags.

Parameters:

Name	Type	Description	Default
artist_id	str	The ID of the artist to get its extra info.	required
max_similar_artists	int | None	The max number of similar artists to return.	None
include_similar_artists_not_present	bool | None	Include similar artists that are not present in any the media library.	None

Returns:

Type	Description
ArtistInfo	An object that contains all the extra info about the requested artist.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_artist_info_non_id3(
    self,
    artist_id: str,
    max_similar_artists: int | None = None,
    include_similar_artists_not_present: bool | None = None,
) -> ArtistInfo:
    """Get all the extra info about an artist. Not organized according
    ID3 tags.

    Args:
        artist_id: The ID of the artist to get its extra info.
        max_similar_artists: The max number of similar artists to
            return.
        include_similar_artists_not_present: Include similar artists
            that are not present in any the media library.

    Returns:
        An object that contains all the extra info about
            the requested artist.
    """

    response = self.api.json_request(
        "getArtistInfo",
        {
            "id": artist_id,
            "count": max_similar_artists,
            "includeNotPresent": include_similar_artists_not_present,
        },
    )["artistInfo"]

    return ArtistInfo(self.subsonic, artist_id, **response)

get_artists(music_folder_id=None)

Get all the registered artists in the server.

Parameters:

Name	Type	Description	Default
music_folder_id	str | None	A music folder ID to reduce the scope of the artists to return.	None

Returns:

Type	Description
list[Artist]	A list with all the info about all the received artists.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_artists(self, music_folder_id: str | None = None) -> list[Artist]:
    """Get all the registered artists in the server.

    Args:
        music_folder_id: A music folder ID to reduce the scope of the
            artists to return.

    Returns:
        A list with all the info about all the received artists.
    """

    response = self.api.json_request(
        "getArtists", {"musicFolderId": music_folder_id}
    )["artists"]["index"]

    artists: list[Artist] = []

    for index in response:
        for artist_data in index["artist"]:
            artist = Artist(self.subsonic, **artist_data)
            artists.append(artist)

    return artists

get_artists_indexed(music_folder_id, modified_since)

Get all the registered artist indexed alphabetically.

Parameters:

Name	Type	Description	Default
music_folder_id	str	A music folder ID to reduce the scope where the artist should be from.	required
modified_since	int	Time in milliseconds since the artist have changed its collection.	required

Returns:

Type	Description
ArtistIndex	An object containt all the artist alphabetically indexed.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_artists_indexed(
    self, music_folder_id: str, modified_since: int
) -> ArtistIndex:
    """Get all the registered artist indexed alphabetically.

    Args:
        music_folder_id: A music folder ID to reduce the scope
            where the artist should be from.
        modified_since: Time in milliseconds since the artist have changed
            its collection.

    Returns:
        An object containt all the artist alphabetically indexed.
    """

    response = self.api.json_request(
        "getIndexes",
        {"musicFolderId": music_folder_id, "ifModifiedSince": modified_since},
    )["indexes"]

    return ArtistIndex(subsonic=self.subsonic, **response)

get_genre(genre_name)

Get all the info of a genre.

Parameters:

Name	Type	Description	Default
genre_name	str	The name of the genre to get its info.	required

Returns:

Type	Description
Genre | None	An object that contains all the info about the requested genre.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_genre(self, genre_name: str) -> Genre | None:
    """Get all the info of a genre.

    Args:
        genre_name: The name of the genre to get its info.

    Returns:
        An object that contains all the info
            about the requested genre.
    """

    genres = self.get_genres()

    for genre in genres:
        if genre.value == genre_name:
            return genre

    return None

get_genres()

Get all the available genres in the server.

Returns:

Type	Description
list[Genre]	A list with all the registered genres in the server.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_genres(self) -> list[Genre]:
    """Get all the available genres in the server.

    Returns:
        A list with all the registered genres in the server.
    """

    response = self.api.json_request("getGenres")["genres"]["genre"]

    return [Genre(self.subsonic, **genre) for genre in response]

get_music_directory(music_directory_id)

Get the info of a music directory.

Parameters:

Name	Type	Description	Default
music_directory_id	str	The ID of the music directory to get its info.	required

Returns:

Type	Description
MusicDirectory	An object that holds all the info about the requested music directory.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_music_directory(self, music_directory_id: str) -> MusicDirectory:
    """Get the info of a music directory.

    Args:
        music_directory_id: The ID of the music directory to get its info.

    Returns:
        An object that holds all the info about the requested music
            directory.
    """

    response = self.api.json_request(
        "getMusicDirectory", {"id": music_directory_id}
    )["directory"]

    return MusicDirectory(subsonic=self.subsonic, **response)

get_music_folder(music_folder_id)

Get the info of a music folder.

Parameters:

Name	Type	Description	Default
music_folder_id	str	The ID of the music folder to get.	required

Returns:

Type	Description
MusicFolder | None	An object that contains all the info about the requested music folder, or None if it wasn't found.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_music_folder(self, music_folder_id: str) -> MusicFolder | None:
    """Get the info of a music folder.

    Args:
        music_folder_id: The ID of the music folder to get.

    Returns:
        An object that contains all the info about the
            requested music folder, or None if it wasn't found.
    """

    music_folders = self.get_music_folders()

    for music_folder in music_folders:
        if music_folder.id == music_folder_id:
            return music_folder

    return None

get_music_folders()

Get all the top level music folders.

Returns:

Type	Description
list[MusicFolder]	A list that contains all the info about all the available music folders.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_music_folders(self) -> list[MusicFolder]:
    """Get all the top level music folders.

    Returns:
        A list that contains all the info about all the available
            music folders.
    """

    response = self.api.json_request("getMusicFolders")["musicFolders"][
        "musicFolder"
    ]

    return [MusicFolder(self.subsonic, **music_folder) for music_folder in response]

get_similar_songs(song_id, song_count=None)

Get similar songs to the given one.

Parameters:

Name	Type	Description	Default
song_id	str	The ID of the song to get similar songs.	required
song_count	int | None	The number of songs to return.	None

Returns:

Type	Description
list[Song]	A list that contains all the songs that are similar to the given one.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_similar_songs(
    self, song_id: str, song_count: int | None = None
) -> list[Song]:
    """Get similar songs to the given one.

    Args:
        song_id: The ID of the song to get similar songs.
        song_count: The number of songs to return.

    Returns:
        A list that contains all the songs that are similar
            to the given one.
    """

    response = self.api.json_request(
        "getSimilarSongs2", {"id": song_id, "count": song_count}
    )["similarSongs2"]["song"]

    return [Song(subsonic=self.subsonic, **song) for song in response]

get_similar_songs_non_id3(song_id, song_count=None)

Get similar songs to the given one. Not organized according ID3 tags.

Parameters:

Name	Type	Description	Default
song_id	str	The ID of the song to get similar songs.	required
song_count	int | None	The number of songs to return.	None

Returns:

Type	Description
list[Song]	A list that contains all the songs that are similar to the given one.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_similar_songs_non_id3(
    self, song_id: str, song_count: int | None = None
) -> list[Song]:
    """Get similar songs to the given one. Not organized according
    ID3 tags.

    Args:
        song_id: The ID of the song to get similar songs.
        song_count: The number of songs to return.

    Returns:
        A list that contains all the songs that are similar
            to the given one.
    """

    response = self.api.json_request(
        "getSimilarSongs", {"id": song_id, "count": song_count}
    )["similarSongs"]["song"]

    return [Song(subsonic=self.subsonic, **song) for song in response]

get_song(song_id)

Get all the info about a song.

Parameters:

Name	Type	Description	Default
song_id	str	The ID of the song to get its info.	required

Returns:

Type	Description
Song	An object that contains all the info about the requested song.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_song(self, song_id: str) -> Song:
    """Get all the info about a song.

    Args:
        song_id: The ID of the song to get its info.

    Returns:
        An object that contains all the info
            about the requested song.
    """

    response = self.api.json_request("getSong", {"id": song_id})["song"]

    return Song(self.subsonic, **response)

get_top_songs(artist_name, max_num_of_songs)

Get the top rated songs in the server.

Parameters:

Name	Type	Description	Default
artist_name	str	Limit the ranked songs to the ones created by the given artist.	required
max_num_of_songs	int	The max number of songs to return.	required

Returns:

Type	Description
list[Song]	A list that contains the top rated songs of the server.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_top_songs(self, artist_name: str, max_num_of_songs: int) -> list[Song]:
    """Get the top rated songs in the server.

    Args:
        artist_name: Limit the ranked songs to the ones created by the
            given artist.
        max_num_of_songs: The max number of songs to return.

    Returns:
        A list that contains the top rated songs of the server.
    """

    response = self.api.json_request(
        "getTopSongs", {"artist": artist_name, "count": max_num_of_songs}
    )["topSongs"]["song"]

    return [Song(subsonic=self.subsonic, **song) for song in response]

get_video(video_id)

Get all the info about a video.

Parameters:

Name	Type	Description	Default
video_id	str	The ID of the video to get its info.	required

Returns:

Type	Description
Video | None	An object that contains all the info about the requested video.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_video(self, video_id: str) -> Video | None:
    """Get all the info about a video.

    Args:
        video_id: The ID of the video to get its info.

    Returns:
        An object that contains all the info about
            the requested video.
    """

    videos = self.get_videos()

    for video in videos:
        if video.id == video_id:
            return video

    return None

get_video_info(video_id)

Get all the extra info about a video.

Parameters:

Name	Type	Description	Default
video_id	str	The ID of the video to get its extra info.	required

Returns:

Type	Description
VideoInfo	An object that holds all the extra info about the requested video.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_video_info(self, video_id: str) -> VideoInfo:
    """Get all the extra info about a video.

    Args:
        video_id: The ID of the video to get its extra info.

    Returns:
        An object that holds all the extra info about
            the requested video.
    """

    response = self.api.json_request("getVideoInfo", {"id": video_id})["videoInfo"]

    return VideoInfo(self.subsonic, video_id=video_id, **response)

get_videos()

Get all the registered videos in the server.

Returns:

Type	Description
list[Video]	A list with all the info about al the videos available in the server.

Source code in .venv/lib/python3.11/site-packages/knuckles/_browsing.py

def get_videos(self) -> list[Video]:
    """Get all the registered videos in the server.

    Returns:
        A list with all the info about al the videos
            available in the server.
    """

    response = self.api.json_request("getVideos")["videos"]["video"]

    return [Video(self.subsonic, **video) for video in response]