API Reference

ListenBrainz client

The ListenBrainz class is the main interface provided by liblistenbrainz. It can be used to interact with the ListenBrainz API.

class liblistenbrainz.client.ListenBrainz

Bases: object

delete_listen(listen)

Delete a particular listen from a user’s listen history.

The listen is not deleted immediately, but is scheduled for deletion, which usually happens shortly after the hour.

Requires that the auth token for the user whose data is being submitted has been set.

Parameters:

listen (liblistenbrainz.Listen) – the listen to be deleted. The listen must have a listened_at and recording_msid attribute

Raises:
get_listens(username, max_ts=None, min_ts=None, count=None)

Get listens for user username

If none of the optional arguments are given, this function will return the 25 most recent listens. The optional max_ts and min_ts UNIX epoch timestamps control at which point in time to start returning listens. You may specify max_ts or min_ts, but not both in one call.

Parameters:

  • username (str) – the username of the user whose data is to be fetched

  • max_ts (int, optional) – If you specify a max_ts timestamp, listens with listened_at less than (but not including) this value will be returned.

  • min_ts (int, optional) – If you specify a min_ts timestamp, listens with listened_at greater than (but not including) this value will be returned.

  • count (int, optional) – the number of listens to return. Defaults to 25, maximum is 100.

Returns:

A list of listens for the user username

Return type:

List[liblistenbrainz.Listen]

Raises:

ListenBrainzAPIException – if the ListenBrainz API returns a non 2xx return code

get_playing_now(username)

Get the listen being played right now for user username.

Parameters:

username (str) – the username of the user whose data is to be fetched

Returns:

A single listen if the user is playing something currently, else None

Return type:

liblistenbrainz.Listen or None

Raises:

ListenBrainzAPIException – if the ListenBrainz API returns a non 2xx return code

get_user_artists(username, count=25, offset=0, time_range='all_time')

Get artists for user ‘username’, sorted in descending order of listen count.

Parameters:

  • username (str) – the username of the user whose artists are to be fetched.

  • count (int, optional) – the number of artists to fetch, defaults to 25, maximum is 100.

  • offset (int, optional) – the number of artists to skip from the beginning, for pagination, defaults to 0.

  • time_range (str) – the time range, can be ‘all_time’, ‘month’, ‘week’ or ‘year’

Returns:

the artists listened to by the user in the time range with listen counts and other data in the same format as the API response

Return type:

dict

get_user_feedback(username, score, metadata, count=100, offset=0)

Get feedback given by user

Parameters:

  • username (str) – The user to get the feedbacks from

  • count (int, optional) – Optional, number of feedback items to return. Default 100.

  • offset (int, optional) – Optional, number of feedback items to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 feedback will be skipped, defaults to 0.

  • score (int, optional) – Optional, If 1 then returns the loved recordings, if -1 returns hated recordings.

  • metadata (bool, optional) – Optional, boolean if this call should return the metadata for the feedback.

get_user_listen_count(username)

Get total number of listens for user

Parameters:

username (str) – The username of the user whose listens are to be fetched

Returns:

Number of listens returned by the Listenbrainz API

Return type:

int

get_user_recommendation_recordings(username, artist_type='top', count=25, offset=0)

Get recommended recordings for a user.

Parameters:

  • username (str) – the username of the user whose recommended tracks are to be fetched.

  • artist_type (str) – The type of filtering applied to the recommended tracks. ‘top’ for filtering by top artists or ‘similar’ for filtering by similar artists ‘raw’ for no filtering

  • count (int, optional) – the number of recordings to fetch, defaults to 25, maximum is 100.

  • offset (int, optional) – the number of releases to skip from the beginning, for pagination, defaults to 0.

Returns:

the recommended recordings as other data returned by the API

Return type:

dict

get_user_recordings(username, count=25, offset=0, time_range='all_time')

Get recordings for user ‘username’, sorted in descending order of listen count.

Parameters:

  • username (str) – the username of the user whose artists are to be fetched.

  • count (int, optional) – the number of recordings to fetch, defaults to 25, maximum is 100.

  • offset (int, optional) – the number of recordings to skip from the beginning, for pagination, defaults to 0.

  • time_range (str) – the time range, can be ‘all_time’, ‘month’, ‘week’ or ‘year’

Returns:

the recordings listened to by the user in the time range with listen counts and other data, in the same format as the API response

Return type:

dict

get_user_releases(username, count=25, offset=0, time_range='all_time')

Get releases for user ‘username’, sorted in descending order of listen count.

Parameters:

  • username (str) – the username of the user whose releases are to be fetched.

  • count (int, optional) – the number of releases to fetch, defaults to 25, maximum is 100.

  • offset (int, optional) – the number of releases to skip from the beginning, for pagination, defaults to 0.

  • time_range (str) – the time range, can be ‘all_time’, ‘month’, ‘week’ or ‘year’

Returns:

the releases listened to by the user in the time range with listen counts and other data

Return type:

dict

is_token_valid(token)

Check if the specified ListenBrainz auth token is valid using the /1/validate-token endpoint.

Parameters:

token (str) – the auth token that needs to be checked for validity

Raises:

ListenBrainzAPIException – if the ListenBrainz API returns a non 2xx return code

set_auth_token(auth_token, check_validity=True)

Give the client an auth_token to use for future requests. This is required if the client wishes to submit listens. Each user has a unique auth token and the auth token is used to identify the user whose data is being submitted.

Parameters:

  • auth_token (str) – auth token

  • check_validity (bool, optional) – specify whether we should check the validity of the auth token by making a request to ListenBrainz before setting it (defaults to True)

Raises:
submit_multiple_listens(listens)

Submit a list of listens to ListenBrainz.

Requires that the auth token for the user whose listens are being submitted has been set.

Parameters:

listens (List[liblistenbrainz.Listen]) – the list of listens to be submitted

Raises:
submit_playing_now(listen)

Submit a playing now notification to ListenBrainz.

Requires that the auth token for the user whose data is being submitted has been set.

Parameters:

listen (liblistenbrainz.Listen) – the listen to be submitted, the listen should NOT have a listened_at attribute

Raises:
submit_single_listen(listen)

Submit a single listen to ListenBrainz.

Requires that the auth token for the user whose data is being submitted has been set.

Parameters:

listen (liblistenbrainz.Listen) – the listen to be submitted

Raises:
submit_user_feedback(feedback, recording_mbid)

Submit a feedback to Listenbrainz

Requires that the auth token for the user whose data is being submitted has been set.

:param feedback The type of feedback 1 = loved, -1 = hated, 0 = delete feedback if any :param recording_mbid The recording Musicbrainz Id of the track being anotated

class Listen

The Listen class represents a Listen from ListenBrainz.

class liblistenbrainz.Listen(track_name, artist_name, listened_at=None, release_name=None, recording_mbid=None, artist_mbids=None, release_mbid=None, tags=None, release_group_mbid=None, work_mbids=None, tracknumber=None, spotify_id=None, listening_from=None, isrc=None, additional_info=None, username=None, recording_msid=None)

Bases: object

__init__(track_name, artist_name, listened_at=None, release_name=None, recording_mbid=None, artist_mbids=None, release_mbid=None, tags=None, release_group_mbid=None, work_mbids=None, tracknumber=None, spotify_id=None, listening_from=None, isrc=None, additional_info=None, username=None, recording_msid=None)

Creates a Listen.

Needs at least a track name and an artist name.

Parameters:

  • track_name (str) – the name of the track

  • artist_name (str) – the name of the artist

  • listened_at (int, optional) – the unix timestamp at which the user listened to this listen

  • release_name (str, optional) – the name of the MusicBrainz release the track is a part of

  • recording_mbid (str, optional) – the MusicBrainz ID of this listen’s recording

  • artist_mbids (List[str], optional) – the MusicBrainz IDs of this listen’s artists

  • release_mbid (str, optional) – the MusicBrainz ID of this listen’s release

  • tags (List[str], optional) – a list of user defined tags for this recording, each listen can only have at most 50 tags and each tag must be shorter than 64 characters.

  • release_group_mbid (str, optional) – A MusicBrainz Release Group ID of the release group this recording was played from.

  • work_mbids (List[str], optional) – A list of MusicBrainz Work IDs that may be associated with this recording.

  • tracknumber (int, optional) – The tracknumber of the recording. This first recording on a release is tracknumber 1.

  • spotify_id (str, optional) – The Spotify track URL associated with this recording. e.g.: http://open.spotify.com/track/1rrgWMXGCGHru5bIRxGFV0

  • listening_from (str, optional) – the source of the listen, for example: ‘spotify’ or ‘vlc’,

  • isrc (str, optional) – The ISRC code associated with the recording.

  • additional_info (dict, optional) – a dict containing any additional fields that should be submitted with the listen.

  • username (str, optional) – the username of the user to whom this listen belongs

  • recording_msid (str, optional) – the MSID of this listen’s recording

Returns:

A listen object with the passed properties

Return type:

Listen

Statistics (beta)

ListenBrainz has started exposing statistics endpoints. The following classes are related to those endpoints.