diff --git a/.gitignore b/.gitignore index a95b3b8c..f38c71ca 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,11 @@ .ruff_cache/ _examples/ dist/ +docs/build/ +docs/jupyter_execute/ +docs/source/api/ jupyter_execute/ src/minim.egg-info -.coverage \ No newline at end of file +.coverage +tests/data/previews/spektrem_shine.mp3 +tests/data/previews/tobu_back_to_you_copy.flac \ No newline at end of file diff --git a/docs/api/minim.audio.Audio.html b/docs/api/minim.audio.Audio.html deleted file mode 100644 index 138b2d1e..00000000 --- a/docs/api/minim.audio.Audio.html +++ /dev/null @@ -1,701 +0,0 @@ - - - - - - - - - Audio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

Audio#

-
-
-class minim.audio.Audio(*args, **kwargs)[source]#
-

Bases: object

-

Generic audio file handler.

-

Subclasses for specific audio containers or formats include

-
    -

  • FLACAudio for audio encoded using the Free -Lossless Audio Codec (FLAC),

    • -

  • MP3Audio for audio encoded and stored in the MPEG Audio -Layer III (MP3) format,

    • -

  • MP4Audio for audio encoded in the Advanced -Audio Coding (AAC) format, encoded using the Apple Lossless -Audio Codec (ALAC), or stored in a MPEG-4 Part 14 (MP4, M4A) -container,

    • -

  • OggAudio for Opus or Vorbis audio stored in an Ogg file, -and

    • -

  • WAVEAudio for audio encoded using linear pulse-code -modulation (LPCM) and in the Waveform Audio File Format (WAVE).

    • -
-
-

Note

-

This class can instantiate a specific file handler from the list -above for an audio file by examining its file extension. However, -there may be instances when this detection fails, especially when -the audio codec and format combination is rarely seen. As such, -it is always best to directly use one of the subclasses above to -create a file handler for your audio file when its audio codec -and format are known.

-
-
-
Parameters:
-
-
filestr or pathlib.Path

Audio filename or path.

-
-
patterntuple, keyword-only, optional

Regular expression search pattern and the corresponding metadata -field(s).

-
-

Valid values:

-

The supported metadata fields are

-
    -

  • "artist" for the track artist,

    • -

  • "title" for the track title, and

    • -

  • "track_number" for the track number.

    • -
-

Examples:

-
    -

  • ("(.*) - (.*)", ("artist", "title")) matches -filenames like “Taylor Swift - Cruel Summer.flac”.

    • -

  • ("(\d*) - (.*)", ("track_number", "title")) matches -filenames like “04 - The Man.m4a”.

    • -

  • ("(\d*) (.*)", ("track_number", "title")) matches -filenames like “13 You Need to Calm Down.mp3”.

    • -
-
-
-
multivaluebool

Determines whether multivalue tags are supported. If -False, the items in value are concatenated using the -separator(s) specified in sep.

-
-
sepstr or tuple, keyword-only, default: (", ", " & ")

Separator(s) to use to concatenate multivalue tags. If a -str is provided, it is used to concatenate all values. -If a tuple is provided, the first str is used to -concatenate the first \(n - 1\) values, and the second -str is used to append the final value.

-
-
-
-
Attributes:
-
-
albumstr

Album title.

-
-
album_artiststr or list

Album artist(s).

-
-
artiststr or list

Artist(s).

-
-
artworkbytes or str

Byte-representation of, URL leading to, or filename of file -containing the cover artwork.

-
-
bit_depthint

Bits per sample.

-
-
bitrateint

Bitrate in bytes per second (B/s).

-
-
channel_countint

Number of audio channels.

-
-
codecstr

Audio codec.

-
-
commentstr

Comment(s).

-
-
compilationbool

Whether the album is a compilation of songs by various artists.

-
-
composerstr or list

Composers, lyrics, and/or writers.

-
-
copyrightstr

Copyright information.

-
-
datestr

Release date.

-
-
disc_numberint

Disc number.

-
-
disc_countint

Total number of discs.

-
-
genrestr or list

Genre.

-
-
isrcstr

International Standard Recording Code (ISRC).

-
-
lyricsstr

Lyrics.

-
-
sample_rateint

Sample rate in Hz.

-
-
tempoint

Tempo in beats per minute (bpm).

-
-
titlestr

Track title.

-
-
track_numberint

Track number.

-
-
track_countint

Total number of tracks.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - -

convert

Convert the current audio file to another format.

set_metadata_using_itunes

Populate tags using data retrieved from the iTunes Search API.

set_metadata_using_qobuz

Populate tags using data retrieved from the Qobuz API.

set_metadata_using_spotify

Populate tags using data retrieved from the Spotify Web API and Spotify Lyrics service.

set_metadata_using_tidal

Populate tags using data retrieved from the TIDAL API.

-
-
-
-convert(codec: str, container: str = None, options: str = None, *, filename: str = None, preserve: bool = True) → None[source]#
-

Convert the current audio file to another format.

-
-

Software dependency

-

Requires FFmpeg.

-
-
-

Note

-

The audio file handler is automatically updated to reflect -the new audio file format. For example, converting a FLAC -audio file to an ALAC audio file will change the file handler -from a FLACAudio object to an MP4Audio -object.

-
-
-
Parameters:
-
-
codecstr

New audio codec or coding format.

-
-

Valid values:

-
    -

  • "aac", "m4a", "mp4", or -"mp4a" for lossy AAC audio.

    • -

  • "alac" for lossless ALAC audio.

    • -

  • "flac" for lossless FLAC audio.

    • -

  • "mp3" for lossy MP3 audio.

    • -

  • "ogg" or "opus" for lossy Opus audio

    • -

  • "vorbis" for lossy Vorbis audio.

    • -

  • "lpcm", "wav", or "wave" for -lossless LPCM audio.

    • -
-
-
-
containerstr, optional

New audio file container. If not specified, the best -container is determined based on codec.

-
-

Valid values:

-
    -

  • "flac" for a FLAC audio container, which only -supports FLAC audio.

    • -

  • "m4a", "mp4", or "mp4a" for -a MP4 audio container, which supports AAC and ALAC -audio.

    • -

  • "mp3" for a MP3 audio container, which only -supports MP3 audio.

    • -

  • "ogg" for an Ogg audio container, which -supports FLAC, Opus, and Vorbis audio.

    • -

  • "wav" or "wave" for an WAVE audio -container, which only supports LPCM audio.

    • -
-
-
-
optionsstr, optional

FFmpeg command-line options, excluding the input and output -files, the -y flag (to overwrite files), and the --c:v copy argument (to preserve cover art for -containers that support it).

-
-

Defaults:

-
    -

  • AAC audio: "-c:a aac -b:a 256k" (or -"-c:a libfdk_aac -b:a 256k" if FFmpeg was -compiled with --enable-libfdk-aac)

    • -

  • ALAC audio: "-c:a alac"

    • -

  • FLAC audio: "-c:a flac"

    • -

  • MP3 audio: "-c:a libmp3lame -q:a 0"

    • -

  • Opus audio: "-c:a libopus -b:a 256k -vn"

    • -

  • Vorbis audio: -"-c:a vorbis -strict experimental -vn" (or -"-c:a libvorbis -vn" if FFmpeg was compiled -with --enable-libvorbis)

    • -

  • WAVE audio: "-c:a pcm_s16le" or -"-c:a pcm_s24le", depending on the bit depth of -the original audio file.

    • -
-
-
-
filenamestr, keyword-only, optional

Filename of the converted audio file. If not provided, the -filename of the original audio file, but with the -appropriate new extension appended, is used.

-
-
preservebool, keyword-only, default: True

Determines whether the original audio file is kept.

-
-
-
-
-
- -
-
-set_metadata_using_itunes(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int | str = 1400, artwork_format: str = 'jpg', overwrite: bool = False) → None[source]#
-

Populate tags using data retrieved from the iTunes Search API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup(). If not provided, -album artist and copyright information is unavailable.

-
-
artwork_sizeint or str, keyword-only, default: 1400

Resized artwork size in pixels. If -artwork_size="raw", the uncompressed high-resolution -image is retrieved, regardless of size.

-
-
artwork_formatstr, keyword-only, {"jpg", "png"}

Artwork file format. If artwork_size="raw", the file -format of the uncompressed high-resolution image takes -precedence.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_qobuz(data: dict[str, Any], *, artwork_size: str = 'large', comment: str = None, overwrite: bool = False) → None[source]#
-

Populate tags using data retrieved from the Qobuz API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Qobuz API via minim.qobuz.PrivateAPI.get_track() -or minim.qobuz.PrivateAPI.search().

-
-
artwork_sizestr, keyword-only, default: "large"

Artwork size.

-

Valid values: "large", "small", or -"thumbnail".

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_spotify(data: dict[str, Any], *, audio_features: dict[str, Any] = None, lyrics: str | dict[str, Any] = None, overwrite: bool = False) → None[source]#
-

Populate tags using data retrieved from the Spotify Web API -and Spotify Lyrics service.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track().

-
-
audio_featuresdict, keyword-only, optional

Information about the track’s audio features obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track_audio_features(). -If not provided, tempo information is unavailable.

-
-
lyricsstr or dict, keyword-only

Information about the track’s formatted or time-synced -lyrics obtained using the Spotify Lyrics service via -minim.spotify.PrivateLyricsService.get_lyrics(). If not -provided, lyrics are unavailable.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_tidal(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int = 1280, composers: str | list[str] | dict[str, Any] = None, lyrics: dict[str, Any] = None, comment: str = None, overwrite: bool = False) → None[source]#
-

Populate tags using data retrieved from the TIDAL API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the TIDAL API via minim.tidal.API.get_track(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_track(), or -minim.tidal.PrivateAPI.search().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the TIDAL API via minim.tidal.API.get_album(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_album(), or -minim.tidal.PrivateAPI.search(). If not provided, -album artist and disc and track numbering information is -unavailable.

-
-
artwork_sizeint, keyword-only, default: 1280

Maximum artwork size in pixels.

-

Valid values: artwork_size should be between -80 and 1280.

-
-
composersstr, list, or dict, keyword-only, optional

Information about the track’s composers in a formatted -str, a list, or a dict obtained using the TIDAL API -via minim.tidal.PrivateAPI.get_track_composers(), -minim.tidal.PrivateAPI.get_track_contributors(), or -minim.tidal.PrivateAPI.get_track_credits(). If not -provided, songwriting credits are unavailable.

-
-
lyricsstr or dict, keyword-only, optional

The track’s lyrics obtained using the TIDAL API via -minim.tidal.PrivateAPI.get_track_lyrics().

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.audio.FLACAudio.html b/docs/api/minim.audio.FLACAudio.html deleted file mode 100644 index 1433cf1b..00000000 --- a/docs/api/minim.audio.FLACAudio.html +++ /dev/null @@ -1,640 +0,0 @@ - - - - - - - - - FLACAudio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

FLACAudio#

-
-
-class minim.audio.FLACAudio(*args, **kwargs)[source]#
-

Bases: Audio, _VorbisComment

-

FLAC audio file handler.

-
-

See also

-

For a full list of attributes and their descriptions, see -Audio.

-
-
-
Parameters:
-
-
filestr or pathlib.Path

FLAC audio filename or path.

-
-
patterntuple, keyword-only, optional

Regular expression search pattern and the corresponding metadata -field(s).

-
-

Valid values:

-

The supported metadata fields are

-
    -

  • "artist" for the track artist,

    • -

  • "title" for the track title, and

    • -

  • "track_number" for the track number.

    • -
-

Examples:

-
    -

  • ("(.*) - (.*)", ("artist", "title")) matches -filenames like “Taylor Swift - Fearless.flac”.

    • -

  • ("(\d*) - (.*)", ("track_number", "title")) matches -filenames like “03 - Love Story.flac”.

    • -

  • ("(\d*) (.*)", ("track_number", "title")) matches -filenames like “06 You Belong with Me.flac”.

    • -
-
-
-
multivaluebool

Determines whether multivalue tags are supported. If -False, the items in value are concatenated using the -separator(s) specified in sep.

-
-
sepstr or tuple, keyword-only, default: (", ", " & ")

Separator(s) to use to concatenate multivalue tags. If a -str is provided, it is used to concatenate all values. -If a tuple is provided, the first str is used to -concatenate the first \(n - 1\) values, and the second -str is used to append the final value.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - -

convert

Convert the current audio file to another format.

set_metadata_using_itunes

Populate tags using data retrieved from the iTunes Search API.

set_metadata_using_qobuz

Populate tags using data retrieved from the Qobuz API.

set_metadata_using_spotify

Populate tags using data retrieved from the Spotify Web API and Spotify Lyrics service.

set_metadata_using_tidal

Populate tags using data retrieved from the TIDAL API.

write_metadata

Write metadata to file.

-
-
-
-convert(codec: str, container: str = None, options: str = None, *, filename: str = None, preserve: bool = True) → None#
-

Convert the current audio file to another format.

-
-

Software dependency

-

Requires FFmpeg.

-
-
-

Note

-

The audio file handler is automatically updated to reflect -the new audio file format. For example, converting a FLAC -audio file to an ALAC audio file will change the file handler -from a FLACAudio object to an MP4Audio -object.

-
-
-
Parameters:
-
-
codecstr

New audio codec or coding format.

-
-

Valid values:

-
    -

  • "aac", "m4a", "mp4", or -"mp4a" for lossy AAC audio.

    • -

  • "alac" for lossless ALAC audio.

    • -

  • "flac" for lossless FLAC audio.

    • -

  • "mp3" for lossy MP3 audio.

    • -

  • "ogg" or "opus" for lossy Opus audio

    • -

  • "vorbis" for lossy Vorbis audio.

    • -

  • "lpcm", "wav", or "wave" for -lossless LPCM audio.

    • -
-
-
-
containerstr, optional

New audio file container. If not specified, the best -container is determined based on codec.

-
-

Valid values:

-
    -

  • "flac" for a FLAC audio container, which only -supports FLAC audio.

    • -

  • "m4a", "mp4", or "mp4a" for -a MP4 audio container, which supports AAC and ALAC -audio.

    • -

  • "mp3" for a MP3 audio container, which only -supports MP3 audio.

    • -

  • "ogg" for an Ogg audio container, which -supports FLAC, Opus, and Vorbis audio.

    • -

  • "wav" or "wave" for an WAVE audio -container, which only supports LPCM audio.

    • -
-
-
-
optionsstr, optional

FFmpeg command-line options, excluding the input and output -files, the -y flag (to overwrite files), and the --c:v copy argument (to preserve cover art for -containers that support it).

-
-

Defaults:

-
    -

  • AAC audio: "-c:a aac -b:a 256k" (or -"-c:a libfdk_aac -b:a 256k" if FFmpeg was -compiled with --enable-libfdk-aac)

    • -

  • ALAC audio: "-c:a alac"

    • -

  • FLAC audio: "-c:a flac"

    • -

  • MP3 audio: "-c:a libmp3lame -q:a 0"

    • -

  • Opus audio: "-c:a libopus -b:a 256k -vn"

    • -

  • Vorbis audio: -"-c:a vorbis -strict experimental -vn" (or -"-c:a libvorbis -vn" if FFmpeg was compiled -with --enable-libvorbis)

    • -

  • WAVE audio: "-c:a pcm_s16le" or -"-c:a pcm_s24le", depending on the bit depth of -the original audio file.

    • -
-
-
-
filenamestr, keyword-only, optional

Filename of the converted audio file. If not provided, the -filename of the original audio file, but with the -appropriate new extension appended, is used.

-
-
preservebool, keyword-only, default: True

Determines whether the original audio file is kept.

-
-
-
-
-
- -
-
-set_metadata_using_itunes(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int | str = 1400, artwork_format: str = 'jpg', overwrite: bool = False) → None#
-

Populate tags using data retrieved from the iTunes Search API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup(). If not provided, -album artist and copyright information is unavailable.

-
-
artwork_sizeint or str, keyword-only, default: 1400

Resized artwork size in pixels. If -artwork_size="raw", the uncompressed high-resolution -image is retrieved, regardless of size.

-
-
artwork_formatstr, keyword-only, {"jpg", "png"}

Artwork file format. If artwork_size="raw", the file -format of the uncompressed high-resolution image takes -precedence.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_qobuz(data: dict[str, Any], *, artwork_size: str = 'large', comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Qobuz API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Qobuz API via minim.qobuz.PrivateAPI.get_track() -or minim.qobuz.PrivateAPI.search().

-
-
artwork_sizestr, keyword-only, default: "large"

Artwork size.

-

Valid values: "large", "small", or -"thumbnail".

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_spotify(data: dict[str, Any], *, audio_features: dict[str, Any] = None, lyrics: str | dict[str, Any] = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Spotify Web API -and Spotify Lyrics service.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track().

-
-
audio_featuresdict, keyword-only, optional

Information about the track’s audio features obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track_audio_features(). -If not provided, tempo information is unavailable.

-
-
lyricsstr or dict, keyword-only

Information about the track’s formatted or time-synced -lyrics obtained using the Spotify Lyrics service via -minim.spotify.PrivateLyricsService.get_lyrics(). If not -provided, lyrics are unavailable.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_tidal(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int = 1280, composers: str | list[str] | dict[str, Any] = None, lyrics: dict[str, Any] = None, comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the TIDAL API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the TIDAL API via minim.tidal.API.get_track(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_track(), or -minim.tidal.PrivateAPI.search().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the TIDAL API via minim.tidal.API.get_album(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_album(), or -minim.tidal.PrivateAPI.search(). If not provided, -album artist and disc and track numbering information is -unavailable.

-
-
artwork_sizeint, keyword-only, default: 1280

Maximum artwork size in pixels.

-

Valid values: artwork_size should be between -80 and 1280.

-
-
composersstr, list, or dict, keyword-only, optional

Information about the track’s composers in a formatted -str, a list, or a dict obtained using the TIDAL API -via minim.tidal.PrivateAPI.get_track_composers(), -minim.tidal.PrivateAPI.get_track_contributors(), or -minim.tidal.PrivateAPI.get_track_credits(). If not -provided, songwriting credits are unavailable.

-
-
lyricsstr or dict, keyword-only, optional

The track’s lyrics obtained using the TIDAL API via -minim.tidal.PrivateAPI.get_track_lyrics().

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-write_metadata() → None#
-

Write metadata to file.

-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.audio.MP3Audio.html b/docs/api/minim.audio.MP3Audio.html deleted file mode 100644 index 71d84272..00000000 --- a/docs/api/minim.audio.MP3Audio.html +++ /dev/null @@ -1,640 +0,0 @@ - - - - - - - - - MP3Audio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

MP3Audio#

-
-
-class minim.audio.MP3Audio(*args, **kwargs)[source]#
-

Bases: Audio, _ID3

-

MP3 audio file handler.

-
-

See also

-

For a full list of attributes and their descriptions, see -Audio.

-
-
-
Parameters:
-
-
filestr or pathlib.Path

MP3 audio filename or path.

-
-
patterntuple, keyword-only, optional

Regular expression search pattern and the corresponding metadata -field(s).

-
-

Valid values:

-

The supported metadata fields are

-
    -

  • "artist" for the track artist,

    • -

  • "title" for the track title, and

    • -

  • "track_number" for the track number.

    • -
-

Examples:

-
    -

  • ("(.*) - (.*)", ("artist", "title")) matches -filenames like “Taylor Swift - Red.mp3”.

    • -

  • ("(\d*) - (.*)", ("track_number", "title")) matches -filenames like “04 - I Knew You Were Trouble.mp3”.

    • -

  • ("(\d*) (.*)", ("track_number", "title")) matches -filenames like “06 22.mp3”.

    • -
-
-
-
multivaluebool

Determines whether multivalue tags are supported. If -False, the items in value are concatenated using the -separator(s) specified in sep.

-
-
sepstr or tuple, keyword-only, default: (", ", " & ")

Separator(s) to use to concatenate multivalue tags. If a -str is provided, it is used to concatenate all values. -If a tuple is provided, the first str is used to -concatenate the first \(n - 1\) values, and the second -str is used to append the final value.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - -

convert

Convert the current audio file to another format.

set_metadata_using_itunes

Populate tags using data retrieved from the iTunes Search API.

set_metadata_using_qobuz

Populate tags using data retrieved from the Qobuz API.

set_metadata_using_spotify

Populate tags using data retrieved from the Spotify Web API and Spotify Lyrics service.

set_metadata_using_tidal

Populate tags using data retrieved from the TIDAL API.

write_metadata

Write metadata to file.

-
-
-
-convert(codec: str, container: str = None, options: str = None, *, filename: str = None, preserve: bool = True) → None#
-

Convert the current audio file to another format.

-
-

Software dependency

-

Requires FFmpeg.

-
-
-

Note

-

The audio file handler is automatically updated to reflect -the new audio file format. For example, converting a FLAC -audio file to an ALAC audio file will change the file handler -from a FLACAudio object to an MP4Audio -object.

-
-
-
Parameters:
-
-
codecstr

New audio codec or coding format.

-
-

Valid values:

-
    -

  • "aac", "m4a", "mp4", or -"mp4a" for lossy AAC audio.

    • -

  • "alac" for lossless ALAC audio.

    • -

  • "flac" for lossless FLAC audio.

    • -

  • "mp3" for lossy MP3 audio.

    • -

  • "ogg" or "opus" for lossy Opus audio

    • -

  • "vorbis" for lossy Vorbis audio.

    • -

  • "lpcm", "wav", or "wave" for -lossless LPCM audio.

    • -
-
-
-
containerstr, optional

New audio file container. If not specified, the best -container is determined based on codec.

-
-

Valid values:

-
    -

  • "flac" for a FLAC audio container, which only -supports FLAC audio.

    • -

  • "m4a", "mp4", or "mp4a" for -a MP4 audio container, which supports AAC and ALAC -audio.

    • -

  • "mp3" for a MP3 audio container, which only -supports MP3 audio.

    • -

  • "ogg" for an Ogg audio container, which -supports FLAC, Opus, and Vorbis audio.

    • -

  • "wav" or "wave" for an WAVE audio -container, which only supports LPCM audio.

    • -
-
-
-
optionsstr, optional

FFmpeg command-line options, excluding the input and output -files, the -y flag (to overwrite files), and the --c:v copy argument (to preserve cover art for -containers that support it).

-
-

Defaults:

-
    -

  • AAC audio: "-c:a aac -b:a 256k" (or -"-c:a libfdk_aac -b:a 256k" if FFmpeg was -compiled with --enable-libfdk-aac)

    • -

  • ALAC audio: "-c:a alac"

    • -

  • FLAC audio: "-c:a flac"

    • -

  • MP3 audio: "-c:a libmp3lame -q:a 0"

    • -

  • Opus audio: "-c:a libopus -b:a 256k -vn"

    • -

  • Vorbis audio: -"-c:a vorbis -strict experimental -vn" (or -"-c:a libvorbis -vn" if FFmpeg was compiled -with --enable-libvorbis)

    • -

  • WAVE audio: "-c:a pcm_s16le" or -"-c:a pcm_s24le", depending on the bit depth of -the original audio file.

    • -
-
-
-
filenamestr, keyword-only, optional

Filename of the converted audio file. If not provided, the -filename of the original audio file, but with the -appropriate new extension appended, is used.

-
-
preservebool, keyword-only, default: True

Determines whether the original audio file is kept.

-
-
-
-
-
- -
-
-set_metadata_using_itunes(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int | str = 1400, artwork_format: str = 'jpg', overwrite: bool = False) → None#
-

Populate tags using data retrieved from the iTunes Search API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup(). If not provided, -album artist and copyright information is unavailable.

-
-
artwork_sizeint or str, keyword-only, default: 1400

Resized artwork size in pixels. If -artwork_size="raw", the uncompressed high-resolution -image is retrieved, regardless of size.

-
-
artwork_formatstr, keyword-only, {"jpg", "png"}

Artwork file format. If artwork_size="raw", the file -format of the uncompressed high-resolution image takes -precedence.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_qobuz(data: dict[str, Any], *, artwork_size: str = 'large', comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Qobuz API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Qobuz API via minim.qobuz.PrivateAPI.get_track() -or minim.qobuz.PrivateAPI.search().

-
-
artwork_sizestr, keyword-only, default: "large"

Artwork size.

-

Valid values: "large", "small", or -"thumbnail".

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_spotify(data: dict[str, Any], *, audio_features: dict[str, Any] = None, lyrics: str | dict[str, Any] = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Spotify Web API -and Spotify Lyrics service.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track().

-
-
audio_featuresdict, keyword-only, optional

Information about the track’s audio features obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track_audio_features(). -If not provided, tempo information is unavailable.

-
-
lyricsstr or dict, keyword-only

Information about the track’s formatted or time-synced -lyrics obtained using the Spotify Lyrics service via -minim.spotify.PrivateLyricsService.get_lyrics(). If not -provided, lyrics are unavailable.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_tidal(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int = 1280, composers: str | list[str] | dict[str, Any] = None, lyrics: dict[str, Any] = None, comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the TIDAL API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the TIDAL API via minim.tidal.API.get_track(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_track(), or -minim.tidal.PrivateAPI.search().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the TIDAL API via minim.tidal.API.get_album(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_album(), or -minim.tidal.PrivateAPI.search(). If not provided, -album artist and disc and track numbering information is -unavailable.

-
-
artwork_sizeint, keyword-only, default: 1280

Maximum artwork size in pixels.

-

Valid values: artwork_size should be between -80 and 1280.

-
-
composersstr, list, or dict, keyword-only, optional

Information about the track’s composers in a formatted -str, a list, or a dict obtained using the TIDAL API -via minim.tidal.PrivateAPI.get_track_composers(), -minim.tidal.PrivateAPI.get_track_contributors(), or -minim.tidal.PrivateAPI.get_track_credits(). If not -provided, songwriting credits are unavailable.

-
-
lyricsstr or dict, keyword-only, optional

The track’s lyrics obtained using the TIDAL API via -minim.tidal.PrivateAPI.get_track_lyrics().

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-write_metadata() → None#
-

Write metadata to file.

-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.audio.MP4Audio.html b/docs/api/minim.audio.MP4Audio.html deleted file mode 100644 index fd432057..00000000 --- a/docs/api/minim.audio.MP4Audio.html +++ /dev/null @@ -1,640 +0,0 @@ - - - - - - - - - MP4Audio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

MP4Audio#

-
-
-class minim.audio.MP4Audio(*args, **kwargs)[source]#
-

Bases: Audio

-

MP4 audio file handler.

-
-

See also

-

For a full list of attributes and their descriptions, see -Audio.

-
-
-
Parameters:
-
-
filestr or pathlib.Path

MP4 audio filename or path.

-
-
patterntuple, keyword-only, optional

Regular expression search pattern and the corresponding metadata -field(s).

-
-

Valid values:

-

The supported metadata fields are

-
    -

  • "artist" for the track artist,

    • -

  • "title" for the track title, and

    • -

  • "track_number" for the track number.

    • -
-

Examples:

-
    -

  • ("(.*) - (.*)", ("artist", "title")) matches -filenames like “Taylor Swift - Mine.m4a”.

    • -

  • ("(\d*) - (.*)", ("track_number", "title")) matches -filenames like “04 - Speak Now.m4a”.

    • -

  • ("(\d*) (.*)", ("track_number", "title")) matches -filenames like “07 The Story of Us.m4a”.

    • -
-
-
-
multivaluebool

Determines whether multivalue tags are supported. If -False, the items in value are concatenated using the -separator(s) specified in sep.

-
-
sepstr or tuple, keyword-only, default: (", ", " & ")

Separator(s) to use to concatenate multivalue tags. If a -str is provided, it is used to concatenate all values. -If a tuple is provided, the first str is used to -concatenate the first \(n - 1\) values, and the second -str is used to append the final value.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - -

convert

Convert the current audio file to another format.

set_metadata_using_itunes

Populate tags using data retrieved from the iTunes Search API.

set_metadata_using_qobuz

Populate tags using data retrieved from the Qobuz API.

set_metadata_using_spotify

Populate tags using data retrieved from the Spotify Web API and Spotify Lyrics service.

set_metadata_using_tidal

Populate tags using data retrieved from the TIDAL API.

write_metadata

Write metadata to file.

-
-
-
-convert(codec: str, container: str = None, options: str = None, *, filename: str = None, preserve: bool = True) → None#
-

Convert the current audio file to another format.

-
-

Software dependency

-

Requires FFmpeg.

-
-
-

Note

-

The audio file handler is automatically updated to reflect -the new audio file format. For example, converting a FLAC -audio file to an ALAC audio file will change the file handler -from a FLACAudio object to an MP4Audio -object.

-
-
-
Parameters:
-
-
codecstr

New audio codec or coding format.

-
-

Valid values:

-
    -

  • "aac", "m4a", "mp4", or -"mp4a" for lossy AAC audio.

    • -

  • "alac" for lossless ALAC audio.

    • -

  • "flac" for lossless FLAC audio.

    • -

  • "mp3" for lossy MP3 audio.

    • -

  • "ogg" or "opus" for lossy Opus audio

    • -

  • "vorbis" for lossy Vorbis audio.

    • -

  • "lpcm", "wav", or "wave" for -lossless LPCM audio.

    • -
-
-
-
containerstr, optional

New audio file container. If not specified, the best -container is determined based on codec.

-
-

Valid values:

-
    -

  • "flac" for a FLAC audio container, which only -supports FLAC audio.

    • -

  • "m4a", "mp4", or "mp4a" for -a MP4 audio container, which supports AAC and ALAC -audio.

    • -

  • "mp3" for a MP3 audio container, which only -supports MP3 audio.

    • -

  • "ogg" for an Ogg audio container, which -supports FLAC, Opus, and Vorbis audio.

    • -

  • "wav" or "wave" for an WAVE audio -container, which only supports LPCM audio.

    • -
-
-
-
optionsstr, optional

FFmpeg command-line options, excluding the input and output -files, the -y flag (to overwrite files), and the --c:v copy argument (to preserve cover art for -containers that support it).

-
-

Defaults:

-
    -

  • AAC audio: "-c:a aac -b:a 256k" (or -"-c:a libfdk_aac -b:a 256k" if FFmpeg was -compiled with --enable-libfdk-aac)

    • -

  • ALAC audio: "-c:a alac"

    • -

  • FLAC audio: "-c:a flac"

    • -

  • MP3 audio: "-c:a libmp3lame -q:a 0"

    • -

  • Opus audio: "-c:a libopus -b:a 256k -vn"

    • -

  • Vorbis audio: -"-c:a vorbis -strict experimental -vn" (or -"-c:a libvorbis -vn" if FFmpeg was compiled -with --enable-libvorbis)

    • -

  • WAVE audio: "-c:a pcm_s16le" or -"-c:a pcm_s24le", depending on the bit depth of -the original audio file.

    • -
-
-
-
filenamestr, keyword-only, optional

Filename of the converted audio file. If not provided, the -filename of the original audio file, but with the -appropriate new extension appended, is used.

-
-
preservebool, keyword-only, default: True

Determines whether the original audio file is kept.

-
-
-
-
-
- -
-
-set_metadata_using_itunes(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int | str = 1400, artwork_format: str = 'jpg', overwrite: bool = False) → None#
-

Populate tags using data retrieved from the iTunes Search API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup(). If not provided, -album artist and copyright information is unavailable.

-
-
artwork_sizeint or str, keyword-only, default: 1400

Resized artwork size in pixels. If -artwork_size="raw", the uncompressed high-resolution -image is retrieved, regardless of size.

-
-
artwork_formatstr, keyword-only, {"jpg", "png"}

Artwork file format. If artwork_size="raw", the file -format of the uncompressed high-resolution image takes -precedence.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_qobuz(data: dict[str, Any], *, artwork_size: str = 'large', comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Qobuz API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Qobuz API via minim.qobuz.PrivateAPI.get_track() -or minim.qobuz.PrivateAPI.search().

-
-
artwork_sizestr, keyword-only, default: "large"

Artwork size.

-

Valid values: "large", "small", or -"thumbnail".

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_spotify(data: dict[str, Any], *, audio_features: dict[str, Any] = None, lyrics: str | dict[str, Any] = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Spotify Web API -and Spotify Lyrics service.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track().

-
-
audio_featuresdict, keyword-only, optional

Information about the track’s audio features obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track_audio_features(). -If not provided, tempo information is unavailable.

-
-
lyricsstr or dict, keyword-only

Information about the track’s formatted or time-synced -lyrics obtained using the Spotify Lyrics service via -minim.spotify.PrivateLyricsService.get_lyrics(). If not -provided, lyrics are unavailable.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_tidal(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int = 1280, composers: str | list[str] | dict[str, Any] = None, lyrics: dict[str, Any] = None, comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the TIDAL API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the TIDAL API via minim.tidal.API.get_track(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_track(), or -minim.tidal.PrivateAPI.search().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the TIDAL API via minim.tidal.API.get_album(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_album(), or -minim.tidal.PrivateAPI.search(). If not provided, -album artist and disc and track numbering information is -unavailable.

-
-
artwork_sizeint, keyword-only, default: 1280

Maximum artwork size in pixels.

-

Valid values: artwork_size should be between -80 and 1280.

-
-
composersstr, list, or dict, keyword-only, optional

Information about the track’s composers in a formatted -str, a list, or a dict obtained using the TIDAL API -via minim.tidal.PrivateAPI.get_track_composers(), -minim.tidal.PrivateAPI.get_track_contributors(), or -minim.tidal.PrivateAPI.get_track_credits(). If not -provided, songwriting credits are unavailable.

-
-
lyricsstr or dict, keyword-only, optional

The track’s lyrics obtained using the TIDAL API via -minim.tidal.PrivateAPI.get_track_lyrics().

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-write_metadata() → None[source]#
-

Write metadata to file.

-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.audio.OGGAudio.html b/docs/api/minim.audio.OGGAudio.html deleted file mode 100644 index 9d464ad9..00000000 --- a/docs/api/minim.audio.OGGAudio.html +++ /dev/null @@ -1,645 +0,0 @@ - - - - - - - - - OggAudio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

OggAudio#

-
-
-class minim.audio.OggAudio(*args, **kwargs)[source]#
-

Bases: Audio, _VorbisComment

-

Ogg audio file handler.

-
-

See also

-

For a full list of attributes and their descriptions, see -Audio.

-
-
-
Parameters:
-
-
filestr or pathlib.Path

Ogg audio filename or path.

-
-
codecstr, optional

Audio codec. If not specified, it will be determined -automatically.

-

Valid values: "flac", "opus", or -"vorbis".

-
-
patterntuple, keyword-only, optional

Regular expression search pattern and the corresponding metadata -field(s).

-
-

Valid values:

-

The supported metadata fields are

-
    -

  • "artist" for the track artist,

    • -

  • "title" for the track title, and

    • -

  • "track_number" for the track number.

    • -
-

Examples:

-
    -

  • ("(.*) - (.*)", ("artist", "title")) matches -filenames like “Taylor Swift - Blank Space.ogg”.

    • -

  • ("(\d*) - (.*)", ("track_number", "title")) matches -filenames like “03 - Style.ogg”.

    • -

  • ("(\d*) (.*)", ("track_number", "title")) matches -filenames like “06 Shake It Off.ogg”.

    • -
-
-
-
multivaluebool

Determines whether multivalue tags are supported. If -False, the items in value are concatenated using the -separator(s) specified in sep.

-
-
sepstr or tuple, keyword-only, default: (", ", " & ")

Separator(s) to use to concatenate multivalue tags. If a -str is provided, it is used to concatenate all values. -If a tuple is provided, the first str is used to -concatenate the first \(n - 1\) values, and the second -str is used to append the final value.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - -

convert

Convert the current audio file to another format.

set_metadata_using_itunes

Populate tags using data retrieved from the iTunes Search API.

set_metadata_using_qobuz

Populate tags using data retrieved from the Qobuz API.

set_metadata_using_spotify

Populate tags using data retrieved from the Spotify Web API and Spotify Lyrics service.

set_metadata_using_tidal

Populate tags using data retrieved from the TIDAL API.

write_metadata

Write metadata to file.

-
-
-
-convert(codec: str, container: str = None, options: str = None, *, filename: str = None, preserve: bool = True) → None#
-

Convert the current audio file to another format.

-
-

Software dependency

-

Requires FFmpeg.

-
-
-

Note

-

The audio file handler is automatically updated to reflect -the new audio file format. For example, converting a FLAC -audio file to an ALAC audio file will change the file handler -from a FLACAudio object to an MP4Audio -object.

-
-
-
Parameters:
-
-
codecstr

New audio codec or coding format.

-
-

Valid values:

-
    -

  • "aac", "m4a", "mp4", or -"mp4a" for lossy AAC audio.

    • -

  • "alac" for lossless ALAC audio.

    • -

  • "flac" for lossless FLAC audio.

    • -

  • "mp3" for lossy MP3 audio.

    • -

  • "ogg" or "opus" for lossy Opus audio

    • -

  • "vorbis" for lossy Vorbis audio.

    • -

  • "lpcm", "wav", or "wave" for -lossless LPCM audio.

    • -
-
-
-
containerstr, optional

New audio file container. If not specified, the best -container is determined based on codec.

-
-

Valid values:

-
    -

  • "flac" for a FLAC audio container, which only -supports FLAC audio.

    • -

  • "m4a", "mp4", or "mp4a" for -a MP4 audio container, which supports AAC and ALAC -audio.

    • -

  • "mp3" for a MP3 audio container, which only -supports MP3 audio.

    • -

  • "ogg" for an Ogg audio container, which -supports FLAC, Opus, and Vorbis audio.

    • -

  • "wav" or "wave" for an WAVE audio -container, which only supports LPCM audio.

    • -
-
-
-
optionsstr, optional

FFmpeg command-line options, excluding the input and output -files, the -y flag (to overwrite files), and the --c:v copy argument (to preserve cover art for -containers that support it).

-
-

Defaults:

-
    -

  • AAC audio: "-c:a aac -b:a 256k" (or -"-c:a libfdk_aac -b:a 256k" if FFmpeg was -compiled with --enable-libfdk-aac)

    • -

  • ALAC audio: "-c:a alac"

    • -

  • FLAC audio: "-c:a flac"

    • -

  • MP3 audio: "-c:a libmp3lame -q:a 0"

    • -

  • Opus audio: "-c:a libopus -b:a 256k -vn"

    • -

  • Vorbis audio: -"-c:a vorbis -strict experimental -vn" (or -"-c:a libvorbis -vn" if FFmpeg was compiled -with --enable-libvorbis)

    • -

  • WAVE audio: "-c:a pcm_s16le" or -"-c:a pcm_s24le", depending on the bit depth of -the original audio file.

    • -
-
-
-
filenamestr, keyword-only, optional

Filename of the converted audio file. If not provided, the -filename of the original audio file, but with the -appropriate new extension appended, is used.

-
-
preservebool, keyword-only, default: True

Determines whether the original audio file is kept.

-
-
-
-
-
- -
-
-set_metadata_using_itunes(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int | str = 1400, artwork_format: str = 'jpg', overwrite: bool = False) → None#
-

Populate tags using data retrieved from the iTunes Search API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup(). If not provided, -album artist and copyright information is unavailable.

-
-
artwork_sizeint or str, keyword-only, default: 1400

Resized artwork size in pixels. If -artwork_size="raw", the uncompressed high-resolution -image is retrieved, regardless of size.

-
-
artwork_formatstr, keyword-only, {"jpg", "png"}

Artwork file format. If artwork_size="raw", the file -format of the uncompressed high-resolution image takes -precedence.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_qobuz(data: dict[str, Any], *, artwork_size: str = 'large', comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Qobuz API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Qobuz API via minim.qobuz.PrivateAPI.get_track() -or minim.qobuz.PrivateAPI.search().

-
-
artwork_sizestr, keyword-only, default: "large"

Artwork size.

-

Valid values: "large", "small", or -"thumbnail".

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_spotify(data: dict[str, Any], *, audio_features: dict[str, Any] = None, lyrics: str | dict[str, Any] = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Spotify Web API -and Spotify Lyrics service.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track().

-
-
audio_featuresdict, keyword-only, optional

Information about the track’s audio features obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track_audio_features(). -If not provided, tempo information is unavailable.

-
-
lyricsstr or dict, keyword-only

Information about the track’s formatted or time-synced -lyrics obtained using the Spotify Lyrics service via -minim.spotify.PrivateLyricsService.get_lyrics(). If not -provided, lyrics are unavailable.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_tidal(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int = 1280, composers: str | list[str] | dict[str, Any] = None, lyrics: dict[str, Any] = None, comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the TIDAL API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the TIDAL API via minim.tidal.API.get_track(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_track(), or -minim.tidal.PrivateAPI.search().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the TIDAL API via minim.tidal.API.get_album(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_album(), or -minim.tidal.PrivateAPI.search(). If not provided, -album artist and disc and track numbering information is -unavailable.

-
-
artwork_sizeint, keyword-only, default: 1280

Maximum artwork size in pixels.

-

Valid values: artwork_size should be between -80 and 1280.

-
-
composersstr, list, or dict, keyword-only, optional

Information about the track’s composers in a formatted -str, a list, or a dict obtained using the TIDAL API -via minim.tidal.PrivateAPI.get_track_composers(), -minim.tidal.PrivateAPI.get_track_contributors(), or -minim.tidal.PrivateAPI.get_track_credits(). If not -provided, songwriting credits are unavailable.

-
-
lyricsstr or dict, keyword-only, optional

The track’s lyrics obtained using the TIDAL API via -minim.tidal.PrivateAPI.get_track_lyrics().

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-write_metadata() → None#
-

Write metadata to file.

-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.audio.WAVEAudio.html b/docs/api/minim.audio.WAVEAudio.html deleted file mode 100644 index 77bfbed4..00000000 --- a/docs/api/minim.audio.WAVEAudio.html +++ /dev/null @@ -1,640 +0,0 @@ - - - - - - - - - WAVEAudio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

WAVEAudio#

-
-
-class minim.audio.WAVEAudio(*args, **kwargs)[source]#
-

Bases: Audio, _ID3

-

WAVE audio file handler.

-
-

See also

-

For a full list of attributes and their descriptions, see -Audio.

-
-
-
Parameters:
-
-
filestr or pathlib.Path

WAVE audio filename or path.

-
-
patterntuple, keyword-only, optional

Regular expression search pattern and the corresponding metadata -field(s).

-
-

Valid values:

-

The supported metadata fields are

-
    -

  • "artist" for the track artist,

    • -

  • "title" for the track title, and

    • -

  • "track_number" for the track number.

    • -
-

Examples:

-
    -

  • ("(.*) - (.*)", ("artist", "title")) matches -filenames like “Taylor Swift - Don’t Blame Me.wav”.

    • -

  • ("(\d*) - (.*)", ("track_number", "title")) matches -filenames like “05 - Delicate.wav”.

    • -

  • ("(\d*) (.*)", ("track_number", "title")) matches -filenames like “06 Look What You Made Me Do.wav”.

    • -
-
-
-
multivaluebool

Determines whether multivalue tags are supported. If -False, the items in value are concatenated using the -separator(s) specified in sep.

-
-
sepstr or tuple, keyword-only, default: (", ", " & ")

Separator(s) to use to concatenate multivalue tags. If a -str is provided, it is used to concatenate all values. -If a tuple is provided, the first str is used to -concatenate the first \(n - 1\) values, and the second -str is used to append the final value.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - -

convert

Convert the current audio file to another format.

set_metadata_using_itunes

Populate tags using data retrieved from the iTunes Search API.

set_metadata_using_qobuz

Populate tags using data retrieved from the Qobuz API.

set_metadata_using_spotify

Populate tags using data retrieved from the Spotify Web API and Spotify Lyrics service.

set_metadata_using_tidal

Populate tags using data retrieved from the TIDAL API.

write_metadata

Write metadata to file.

-
-
-
-convert(codec: str, container: str = None, options: str = None, *, filename: str = None, preserve: bool = True) → None#
-

Convert the current audio file to another format.

-
-

Software dependency

-

Requires FFmpeg.

-
-
-

Note

-

The audio file handler is automatically updated to reflect -the new audio file format. For example, converting a FLAC -audio file to an ALAC audio file will change the file handler -from a FLACAudio object to an MP4Audio -object.

-
-
-
Parameters:
-
-
codecstr

New audio codec or coding format.

-
-

Valid values:

-
    -

  • "aac", "m4a", "mp4", or -"mp4a" for lossy AAC audio.

    • -

  • "alac" for lossless ALAC audio.

    • -

  • "flac" for lossless FLAC audio.

    • -

  • "mp3" for lossy MP3 audio.

    • -

  • "ogg" or "opus" for lossy Opus audio

    • -

  • "vorbis" for lossy Vorbis audio.

    • -

  • "lpcm", "wav", or "wave" for -lossless LPCM audio.

    • -
-
-
-
containerstr, optional

New audio file container. If not specified, the best -container is determined based on codec.

-
-

Valid values:

-
    -

  • "flac" for a FLAC audio container, which only -supports FLAC audio.

    • -

  • "m4a", "mp4", or "mp4a" for -a MP4 audio container, which supports AAC and ALAC -audio.

    • -

  • "mp3" for a MP3 audio container, which only -supports MP3 audio.

    • -

  • "ogg" for an Ogg audio container, which -supports FLAC, Opus, and Vorbis audio.

    • -

  • "wav" or "wave" for an WAVE audio -container, which only supports LPCM audio.

    • -
-
-
-
optionsstr, optional

FFmpeg command-line options, excluding the input and output -files, the -y flag (to overwrite files), and the --c:v copy argument (to preserve cover art for -containers that support it).

-
-

Defaults:

-
    -

  • AAC audio: "-c:a aac -b:a 256k" (or -"-c:a libfdk_aac -b:a 256k" if FFmpeg was -compiled with --enable-libfdk-aac)

    • -

  • ALAC audio: "-c:a alac"

    • -

  • FLAC audio: "-c:a flac"

    • -

  • MP3 audio: "-c:a libmp3lame -q:a 0"

    • -

  • Opus audio: "-c:a libopus -b:a 256k -vn"

    • -

  • Vorbis audio: -"-c:a vorbis -strict experimental -vn" (or -"-c:a libvorbis -vn" if FFmpeg was compiled -with --enable-libvorbis)

    • -

  • WAVE audio: "-c:a pcm_s16le" or -"-c:a pcm_s24le", depending on the bit depth of -the original audio file.

    • -
-
-
-
filenamestr, keyword-only, optional

Filename of the converted audio file. If not provided, the -filename of the original audio file, but with the -appropriate new extension appended, is used.

-
-
preservebool, keyword-only, default: True

Determines whether the original audio file is kept.

-
-
-
-
-
- -
-
-set_metadata_using_itunes(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int | str = 1400, artwork_format: str = 'jpg', overwrite: bool = False) → None#
-

Populate tags using data retrieved from the iTunes Search API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the iTunes Search API via -minim.itunes.SearchAPI.search() or -minim.itunes.SearchAPI.lookup(). If not provided, -album artist and copyright information is unavailable.

-
-
artwork_sizeint or str, keyword-only, default: 1400

Resized artwork size in pixels. If -artwork_size="raw", the uncompressed high-resolution -image is retrieved, regardless of size.

-
-
artwork_formatstr, keyword-only, {"jpg", "png"}

Artwork file format. If artwork_size="raw", the file -format of the uncompressed high-resolution image takes -precedence.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_qobuz(data: dict[str, Any], *, artwork_size: str = 'large', comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Qobuz API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Qobuz API via minim.qobuz.PrivateAPI.get_track() -or minim.qobuz.PrivateAPI.search().

-
-
artwork_sizestr, keyword-only, default: "large"

Artwork size.

-

Valid values: "large", "small", or -"thumbnail".

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_spotify(data: dict[str, Any], *, audio_features: dict[str, Any] = None, lyrics: str | dict[str, Any] = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the Spotify Web API -and Spotify Lyrics service.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track().

-
-
audio_featuresdict, keyword-only, optional

Information about the track’s audio features obtained using -the Spotify Web API via -minim.spotify.WebAPI.get_track_audio_features(). -If not provided, tempo information is unavailable.

-
-
lyricsstr or dict, keyword-only

Information about the track’s formatted or time-synced -lyrics obtained using the Spotify Lyrics service via -minim.spotify.PrivateLyricsService.get_lyrics(). If not -provided, lyrics are unavailable.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-set_metadata_using_tidal(data: dict[str, Any], *, album_data: dict[str, Any] = None, artwork_size: int = 1280, composers: str | list[str] | dict[str, Any] = None, lyrics: dict[str, Any] = None, comment: str = None, overwrite: bool = False) → None#
-

Populate tags using data retrieved from the TIDAL API.

-
-
Parameters:
-
-
datadict

Information about the track in JSON format obtained using -the TIDAL API via minim.tidal.API.get_track(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_track(), or -minim.tidal.PrivateAPI.search().

-
-
album_datadict, keyword-only, optional

Information about the track’s album in JSON format obtained -using the TIDAL API via minim.tidal.API.get_album(), -minim.tidal.API.search(), -minim.tidal.PrivateAPI.get_album(), or -minim.tidal.PrivateAPI.search(). If not provided, -album artist and disc and track numbering information is -unavailable.

-
-
artwork_sizeint, keyword-only, default: 1280

Maximum artwork size in pixels.

-

Valid values: artwork_size should be between -80 and 1280.

-
-
composersstr, list, or dict, keyword-only, optional

Information about the track’s composers in a formatted -str, a list, or a dict obtained using the TIDAL API -via minim.tidal.PrivateAPI.get_track_composers(), -minim.tidal.PrivateAPI.get_track_contributors(), or -minim.tidal.PrivateAPI.get_track_credits(). If not -provided, songwriting credits are unavailable.

-
-
lyricsstr or dict, keyword-only, optional

The track’s lyrics obtained using the TIDAL API via -minim.tidal.PrivateAPI.get_track_lyrics().

-
-
commentstr, keyword-only, optional

Comment or description.

-
-
overwritebool, keyword-only, default: False

Determines whether existing metadata should be overwritten.

-
-
-
-
-
- -
-
-write_metadata() → None#
-

Write metadata to file.

-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.audio.html b/docs/api/minim.audio.html deleted file mode 100644 index ba571871..00000000 --- a/docs/api/minim.audio.html +++ /dev/null @@ -1,360 +0,0 @@ - - - - - - - - - audio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

audio#

-
-

Audio file objects#

-

This module provides convenient Python objects to keep track of audio -file handles and metadata, and convert between different audio formats.

-
-

Classes

-
- - - - - - - - - - - - - - - - - - - - - -

Audio

Generic audio file handler.

FLACAudio

FLAC audio file handler.

MP3Audio

MP3 audio file handler.

MP4Audio

MP4 audio file handler.

OggAudio

Ogg audio file handler.

WAVEAudio

WAVE audio file handler.

-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.discogs.API.html b/docs/api/minim.discogs.API.html deleted file mode 100644 index 64cea398..00000000 --- a/docs/api/minim.discogs.API.html +++ /dev/null @@ -1,3911 +0,0 @@ - - - - - - - - - API - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

API#

-
-
-class minim.discogs.API(*, consumer_key: str = None, consumer_secret: str = None, flow: str = None, browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, access_token: str = None, access_token_secret: str = None, overwrite: bool = False, save: bool = True)[source]#
-

Bases: object

-

Discogs API client.

-

The Discogs API lets developers build their own Discogs-powered -applications for the web, desktop, and mobile devices. It is a -RESTful interface to Discogs data and enables accessing JSON- -formatted information about artists, releases, and labels, -managing user collections and wantlists, creating marketplace -listings, and more.

-
-

See also

-

For more information, see the Discogs API home page.

-
-

The Discogs API can be accessed with or without authentication. -(client credentials, personal access token, or OAuth access token -and access token secret). However, it is recommended that users at -least provide client credentials to enjoy higher rate limits and -access to image URLs. The consumer key and consumer secret can -either be provided to this class’s constructor as keyword arguments -or be stored as DISCOGS_CONSUMER_KEY and -DISCOGS_CONSUMER_SECRET in the operating system’s -environment variables.

-
-

See also

-

To get client credentials, see the Registration section of the -Authentication page of the Discogs API website. To take -advantage of Minim’s automatic access token retrieval -functionality for the OAuth 1.0a flow, the redirect URI should be -in the form http://localhost:{port}/callback, where -{port} is an open port on localhost.

-
-

To view and make changes to account information and resources, users -must either provide a personal access token to this class’s -constructor as a keyword argument or undergo the OAuth 1.0a flow, -which require valid client credentials, using Minim. If an existing -OAuth access token/secret pair is available, it can be provided to -this class’s constructor as keyword arguments to bypass the access -token retrieval process.

-
-

Tip

-

The authorization flow and access token can be changed or updated -at any time using set_flow() and set_access_token(), -respectively.

-
-

Minim also stores and manages access tokens and their properties. -When the OAuth 1.0a flow is used to acquire an access token/secret -pair, it is automatically saved to the Minim configuration file to -be loaded on the next instantiation of this class. This behavior can -be disabled if there are any security concerns, like if the computer -being used is a shared device.

-
-
Parameters:
-
-
consumer_keystr, keyword-only, optional

Consumer key. Required for the OAuth 1.0a flow, and can be used -in the Discogs authorization flow alongside a consumer secret. -If it is not stored as DISCOGS_CONSUMER_KEY in the -operating system’s environment variables or found in the Minim -configuration file, it can be provided here.

-
-
consumer_secretstr, keyword-only, optional

Consumer secret. Required for the OAuth 1.0a flow, and can be -used in the Discogs authorization flow alongside a consumer key. -If it is not stored as DISCOGS_CONSUMER_SECRET in the -operating system’s environment variables or found in the Minim -configuration file, it can be provided here.

-
-
flowstr, keyword-only, optional

Authorization flow. If None and no access token is -provided, no user authentication will be performed and client -credentials will not be attached to requests, even if found or -provided.

-
-

Valid values:

-
    -

  • None for no user authentication.

    • -

  • "discogs" for the Discogs authentication flow.

    • -

  • "oauth" for the OAuth 1.0a flow.

    • -
-
-
-
browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for the -OAuth 1.0a flow. If False, users will have to manually -open the authorization URL and provide the full callback URI via -the terminal.

-
-
web_frameworkstr, keyword-only, optional

Determines which web framework to use for the OAuth 1.0a flow.

-
-

Valid values:

-
    -

  • "http.server" for the built-in implementation of -HTTP servers.

    • -

  • "flask" for the Flask framework.

    • -

  • "playwright" for the Playwright framework by -Microsoft.

    • -
-
-
-
portint or str, keyword-only, default: 8888

Port on localhost to use for the OAuth 1.0a flow with -the http.server and Flask frameworks. Only used if -redirect_uri is not specified.

-
-
redirect_uristr, keyword-only, optional

Redirect URI for the OAuth 1.0a flow. If not on -localhost, the automatic request access token retrieval -functionality is not available.

-
-
access_tokenstr, keyword-only, optional

Personal or OAuth access token. If provided here or found in the -Minim configuration file, the authentication process is -bypassed.

-
-
access_token_secretstr, keyword-only, optional

OAuth access token secret accompanying access_token.

-
-
overwritebool, keyword-only, default: False

Determines whether to overwrite an existing access token in the -Minim configuration file.

-
-
savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their -associated properties are stored to the Minim configuration -file.

-
-
-
-
Attributes:
-
-
API_URLstr

Base URL for the Discogs API.

-
-
ACCESS_TOKEN_URLstr

URL for the OAuth 1.0a access token endpoint.

-
-
AUTH_URLstr

URL for the OAuth 1.0a authorization endpoint.

-
-
REQUEST_TOKEN_URLstr

URL for the OAuth 1.0a request token endpoint.

-
-
sessionrequests.Session

Session used to send requests to the Discogs API.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

add_collection_folder_release

User Collection > Add To Collection Folder: Add a release to a folder in a user's collection.

add_order_message

Marketplace > List Order Messages > Add New Message: Adds a new message to the order's message log.

create_collection_folder

User Collection > Collection > Create Folder: Create a new folder in a user's collection.

create_listing

Marketplace > New Listing: Create a marketplace listing.

delete_collection_folder

User Collection > Collection Folder > Delete Folder: Delete a folder from a user's collection.

delete_collection_folder_release

User Collection > Delete Instance From Folder: Remove an instance of a release from a user's collection folder.

delete_listing

Marketplace > Listing > Delete Listing: Permanently remove a listing from the marketplace.

delete_user_release_rating

Database > Release Rating By User > Delete Release Rating By User: Deletes the release's rating for a given user.

download_inventory_export

Inventory Export > Download An Export: Download the results of an inventory export.

edit_collection_folder_release

User Collection > Change Rating Of Release: Change the rating on a release and/or move the instance to another folder.

edit_collection_release_field

User Collection > Edit Fields Instance: Change the value of a notes field on a particular instance.

edit_listing

Marketplace > Listing > Edit Listing: Edit the data associated with a listing.

edit_order

Marketplace > Order > Edit Order: Edit the data associated with an order.

edit_profile

User Identity > Profile > Edit Profile: Edit a user's profile data.

export_inventory

Inventory Export > Export Your Inventory: Request an export of your inventory as a CSV.

get_artist

Database > Artist: Get an artist.

get_artist_releases

Database > Artist Releases: Get an artist's releases and masters.

get_collection_fields

User Collection > Collection Fields: Retrieve a list of user-defined collection notes fields.

get_collection_folder

User Collection > Collection Folder > Get Folders: Retrieve metadata about a folder in a user's collection.

get_collection_folder_releases

User Collection > Collection Items By Folder: Returns the items in a folder in a user's collection.

get_collection_folders

User Collection > Collection > Get Collection Folders: Retrieve a list of folders in a user's collection.

get_collection_folders_by_release

User Collection > Collection Items By Release: View the user's collection folders which contain a specified release.

get_collection_value

User Collection > Collection Value: Returns the minimum, median, and maximum value of a user's collection.

get_community_release_rating

Database > Community Release Rating: Retrieves the community release rating average and count.

get_fee

Marketplace > Fee with currency: Calculates the fee for selling an item on the marketplace given a particular currency.

get_identity

User Identity > Identity: Retrieve basic information about the authenticated user.

get_inventory

Marketplace > Inventory: Get a seller's inventory.

get_inventory_export

Inventory Export > Get An Export: Get details about the status of an inventory export.

get_inventory_exports

Inventory Export > Get Recent Exports: Get all recent exports of your inventory.

get_label

Database > Label: Get a label, company, recording studio, locxation, or other entity involved with artists and releases.

get_label_releases

Database > Label Releases: Get a list of releases associated with the label.

get_listing

Marketplace > Listing: View marketplace listings.

get_master_release

Database > Master Release: Get a master release.

get_master_release_versions

Database > Master Release Versions: Retrieves a list of all releases that are versions of this master.

get_order

Marketplace > Order > Get Order: View the data associated with an order.

get_order_messages

Marketplace > List Order Messages > List Order Messages: Returns a list of the order's messages with the most recent first.

get_price_suggestions

Marketplace > Price Suggestions: Retrieve price suggestions in the user's selling currency for the provided release ID.

get_profile

User Identity > Profile > Get Profile: Retrieve a user by username.

get_release

Database > Release: Get a release (physical or digital object released by one or more artists).

get_release_marketplace_stats

Marketplace > Release Statistics: Retrieve marketplace statistics for the provided release ID.

get_release_stats

Database > Release Stats: Retrieves the release's "have" and "want" counts.

get_user_contributions

User Identity > User Contributions: Retrieve a user's contributions (releases, labels, artists) by username.

get_user_orders

Marketplace > List Orders: Returns a list of the authenticated user's orders.

get_user_release_rating

Database > Release Rating By User > Get Release Rating By User: Retrieves the release's rating for a given user.

get_user_submissions

User Identity > User Submissions: Retrieve a user's submissions (edits made to releases, labels, and artists) by username.

rename_collection_folder

User Collection > Collection Folder > Edit Folder: Rename a folder.

search

Database > Search: Issue a search query to the Discogs database.

set_access_token

Set the Discogs API personal or OAuth access token (and secret).

set_flow

Set the authorization flow.

update_user_release_rating

Database > Release Rating By User > Update Release Rating By User: Updates the release's rating for a given user.

-
-
-
-add_collection_folder_release(folder_id: int, release_id: int, *, username: str = None) → dict[str, int | str][source]#
-

User Collection > Add To Collection Folder: Add a release -to a folder in a user’s collection.

-

The folder_id must be non-zero. You can use 1 for -“Uncategorized”.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
folder_idint

The ID of the folder to modify.

-

Example: 3.

-
-
release_idint

The ID of the release you are adding.

-

Example: 130076.

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
Returns:
-
-
folderdict

Information about the folder.

-
-

Sample

-
{
-  "instance_id": <int>,
-  "resource_url": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-add_order_message(order_id: str, message: str = None, status: str = None) → dict[str, Any][source]#
-

Marketplace > List Order Messages > Add New Message: -Adds a new message to the order’s message log.

-

When posting a new message, you can simultaneously change the -order status. IF you do, the message will automatically be -prepended with:

-
-

Seller changed status from […] to […]

-
-

While message and status are each optional, one or both -must be present.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
order_idstr

The ID of the order you are fetching.

-

Example: 1-1.

-
-
messagestr, optional

The message you are posting.

-

Example: "hello world"

-
-
statusstr, optional

The status of the order you are updating.

-

Valid values: "New Order", -"Buyer Contacted", "Invoice Sent", -"Payment Pending", "Payment Received", -"In Progress", "Shipped", -"Refund Sent", "Cancelled (Non-Paying Buyer)", -"Cancelled (Item Unavailable)", and -"Cancelled (Per Buyer's Request)".

-
-
-
-
Returns:
-
-
messagedict

The order’s message.

-
-

Sample

-
{
-  "from": {
-    "username": <str>,
-    "resource_url": <str>
-  },
-  "message": <str>,
-  "order": {
-    "resource_url": <str>,
-    "id": <str>
-  },
-  "timestamp": <str>,
-  "subject": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-create_collection_folder(name: str) → dict[str, int | str][source]#
-

User Collection > Collection > Create Folder: Create a new folder in a -user’s collection.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
namestr

The name of the newly-created folder.

-

Example: "My favorites".

-
-
-
-
Returns:
-
-
folderdict

Information about the newly-created folder.

-
-

Sample

-
{
-  "id": <int>,
-  "name": <str>,
-  "count": <int>,
-  "resource_url": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-create_listing(release_id: int | str, condition: str, price: float, status: str = 'For Sale', *, sleeve_condition: str = None, comments: str = None, allow_offers: bool = None, external_id: str = None, location: str = None, weight: float = None, format_quantity: int = None) → dict[str, Any][source]#
-

Marketplace > New Listing: Create a -marketplace listing.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
release_idint or str

The ID of the release you are posting.

-

Example: 249504.

-
-
conditionstr

The condition of the release you are posting.

-

Valid values: "Mint (M)", -"Near Mint (NM or M-)", -"Very Good Plus (VG+)", -"Very Good (VG)", "Good Plus (G+)", -"Good (G)", "Fair (F)", and -"Poor (P)".

-
-
pricefloat

The price of the item (in the seller’s currency).

-

Example: 10.00.

-
-
statusstr, default: "For Sale"

The status of the listing.

-

Valid values: "For Sale" (the listing is ready -to be shwon on the marketplace) and "Draft" (the -listing is not ready for public display).

-
-
sleeve_conditionstr, optional

The condition of the sleeve of the item you are posting.

-

Valid values: "Mint (M)", -"Near Mint (NM or M-)", -"Very Good Plus (VG+)", -"Very Good (VG)", "Good Plus (G+)", -"Good (G)", "Fair (F)", and -"Poor (P)".

-
-
commentsstr, optional

Any remarks about the item that will be displated to buyers.

-
-
allow_offersbool, optional

Whether or not to allow buyers to make offers on the item.

-

Default: False.

-
-
external_idstr, optional

A freeform field that can be used for the seller’s own -reference. Information stored here will not be displayed to -anyone other than the seller. This field is called “Private -Comments” on the Discogs website.

-
-
locationstr, optional

A freeform field that is intended to help identify an item’s -physical storage location. Information stored here will not -be displayed to anyone other than the seller. This field -will be visible on the inventory management page and will be -available in inventory exports via the website.

-
-
weightfloat, optional

The weight, in grams, of this listing, for the purpose of -calculating shipping. Set this field to "auto" to -have the weight automatically estimated for you.

-
-
format_quantityint, optional

The number of items this listing counts as, for the purpose -of calculating shipping. This field is called “Counts As” on -the Discogs website. Set this field to "auto" to -have the quantity automatically estimated for you.

-
-
-
-
-
- -
-
-delete_collection_folder(folder_id: int, *, username: str = None) → None[source]#
-

User Collection > Collection Folder > Delete Folder: Delete a folder -from a user’s collection.

-

A folder must be empty before it can be deleted.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
folder_idint

The ID of the folder to delete.

-

Example: 3.

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to delete. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
-
- -
-
-delete_collection_folder_release(folder_id: int, release_id: int, instance_id: int, *, username: str = None) → None[source]#
-

User Collection > Delete Instance From Folder: Remove an -instance of a release from a user’s collection folder.

-

To move the release to the “Uncategorized” folder instead, use -the edit_collection_folder_release() method.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
folder_idint

The ID of the folder to modify.

-

Example: 3.

-
-
release_idint

The ID of the release you are modifying.

-

Example: 130076.

-
-
instance_idint

The ID of the instance.

-

Example: 1.

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
-
- -
-
-delete_listing(listing_id: int | str) → None[source]#
-

Marketplace > Listing > Delete Listing: Permanently remove a listing -from the marketplace.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
listing_idint or str

The ID of the listing you are fetching.

-

Example: 172723812.

-
-
-
-
-
- -
-
-delete_user_release_rating(release_id: int | str, username: str = None) → None[source]#
-

Database > Release Rating By User > Delete Release Rating By -User: -Deletes the release’s rating for a given user.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
release_idint or str

The release ID.

-

Example: 249504.

-
-
usernamestr, optional

The username of the user whose rating you are requesting. If -not specified, the username of the authenticated user is -used.

-

Example: "memory".

-
-
-
-
-
- -
-
-download_inventory_export(export_id: int, *, filename: str = None, path: str = None) → str[source]#
-

Inventory Export > Download An Export: Download the -results of an inventory export.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
export_idint

ID of the export.

-
-
filenamestr, optional

Filename of the exported CSV file. A .csv extension -will be appended if not present. If not specified, the CSV -file is saved as -<username>-inventory-<date>-<number>.csv.

-
-
pathstr, optional

Path to save the exported CSV file. If not specified, the -file is saved in the current working directory.

-
-
-
-
Returns:
-
-
pathstr

Full path to the exported CSV file.

-
-
-
-
-
- -
-
-edit_collection_folder_release(folder_id: int, release_id: int, instance_id: int, *, username: str = None, new_folder_id: int, rating: int = None) → None[source]#
-

User Collection > Change Rating Of Release: Change the -rating on a release and/or move the instance to another folder.

-

This endpoint potentially takes two folder ID parameters: -folder_id (which is the folder you are requesting, and is -required), and new_folder_id (representing the folder you want -to move the instance to, which is optional).

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
folder_idint

The ID of the folder to modify.

-

Example: 3.

-
-
release_idint

The ID of the release you are modifying.

-

Example: 130076.

-
-
instance_idint

The ID of the instance.

-

Example: 1.

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
new_folder_idint

The ID of the folder to move the instance to.

-

Example: 4.

-
-
ratingint, keyword-only, optional

The rating of the instance you are supplying.

-

Example: 5.

-
-
-
-
-
- -
-
-edit_collection_release_field(folder_id: int, release_id: int, instance_id: int, field_id: int, value: str, *, username: str = None) → None[source]#
-

User Collection > Edit Fields Instance: Change the value -of a notes field on a particular instance.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
folder_idint

The ID of the folder to modify.

-

Example: 3.

-
-
release_idint

The ID of the release you are modifying.

-

Example: 130076.

-
-
instance_idint

The ID of the instance.

-

Example: 1.

-
-
field_idint

The ID of the field you are modifying.

-

Example: 1.

-
-
valuestr

The new value of the field. If the field’s type is -"dropdown", value must match one of the values in -the field’s list of options.

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
-
- -
-
-edit_listing(listing_id: int | str, release_id: int | str, condition: str, price: float, status: str = 'For Sale', *, sleeve_condition: str = None, comments: str = None, allow_offers: bool = None, external_id: str = None, location: str = None, weight: float = None, format_quantity: int = None) → None[source]#
-

Marketplace > Listing > Edit Listing: -Edit the data associated with a listing.

-

If the listing’s status is not "For Sale", -"Draft", or "Expired", it cannot be -modified—only deleted. To re-list a "Sold" listing, a -new listing must be created.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
listing_idint or str

The ID of the listing you are fetching.

-

Example: 172723812.

-
-
release_idint or str

The ID of the release you are posting.

-

Example: 249504.

-
-
conditionstr

The condition of the release you are posting.

-

Valid values: "Mint (M)", -"Near Mint (NM or M-)", -"Very Good Plus (VG+)", -"Very Good (VG)", "Good Plus (G+)", -"Good (G)", "Fair (F)", and -"Poor (P)".

-
-
pricefloat

The price of the item (in the seller’s currency).

-

Example: 10.00.

-
-
statusstr, default: "For Sale"

The status of the listing.

-

Valid values: "For Sale" (the listing is ready -to be shwon on the marketplace) and "Draft" (the -listing is not ready for public display).

-
-
sleeve_conditionstr, optional

The condition of the sleeve of the item you are posting.

-

Valid values: "Mint (M)", -"Near Mint (NM or M-)", -"Very Good Plus (VG+)", -"Very Good (VG)", "Good Plus (G+)", -"Good (G)", "Fair (F)", and -"Poor (P)".

-
-
commentsstr, optional

Any remarks about the item that will be displated to buyers.

-
-
allow_offersbool, optional

Whether or not to allow buyers to make offers on the item.

-

Default: False.

-
-
external_idstr, optional

A freeform field that can be used for the seller’s own -reference. Information stored here will not be displayed to -anyone other than the seller. This field is called “Private -Comments” on the Discogs website.

-
-
locationstr, optional

A freeform field that is intended to help identify an item’s -physical storage location. Information stored here will not -be displayed to anyone other than the seller. This field -will be visible on the inventory management page and will be -available in inventory exports via the website.

-
-
weightfloat, optional

The weight, in grams, of this listing, for the purpose of -calculating shipping. Set this field to "auto" to -have the weight automatically estimated for you.

-
-
format_quantityint, optional

The number of items this listing counts as, for the purpose -of calculating shipping. This field is called “Counts As” on -the Discogs website. Set this field to "auto" to -have the quantity automatically estimated for you.

-
-
-
-
-
- -
-
-edit_order(order_id: str, status: str, *, shipping: float = None) → dict[str, Any][source]#
-

Marketplace > Order > Edit Order: Edit the data -associated with an order.

-

The response contains a "next_status" key—an array of -valid next statuses for this order.

-

Changing the order status using this resource will always message -the buyer with

-
-

Seller changed status from […] to […]

-
-

and does not provide a facility for including a custom message -along with the change. For more fine-grained control, use the -add_order_message() method, which allows you to -simultaneously add a message and change the order status. If the -order status is not "Cancelled", -"Payment Received", or "Shipped", you can change -the shipping. Doing so will send an invoice to the buyer and set -the order status to "Invoice Sent". (For that reason, -you cannot set the shipping and the order status in the same -request.)

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
order_idstr

The ID of the order you are fetching.

-

Example: 1-1.

-
-
statusstr

The status of the order you are updating. The new status must -be present in the order’s "next_status" list.

-

Valid values: "New Order", -"Buyer Contacted", "Invoice Sent", -"Payment Pending", "Payment Received", -"In Progress", "Shipped", -"Refund Sent", "Cancelled (Non-Paying Buyer)", -"Cancelled (Item Unavailable)", and -"Cancelled (Per Buyer's Request)".

-
-
shippingfloat, optional

The order shipping amount. As a side effect of setting this -value, the buyer is invoiced and the order status is set to -"Invoice Sent".

-

Example: 5.00.

-
-
-
-
Returns:
-
-
orderdict

The marketplace order.

-
-

Sample

-
{
-  "id": <str>,
-  "resource_url": <str>,
-  "messages_url": <str>,
-  "uri": <str>,
-  "status": <str>,
-  "next_status": [<str>],
-  "fee": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "created": <str>,
-  "items": [
-    {
-      "release": {
-        "id": <int>,
-        "description": <str>,
-      },
-      "price": {
-        "currency": <str>,
-        "value": <int>
-      },
-      "media_condition": <str>,
-      "sleeve_condition": <str>,
-      "id": <int>
-    }
-  ],
-  "shipping": {
-    "currency": <str>,
-    "method": <str>,
-    "value": <int>
-  },
-  "shipping_address": <str>,
-  "additional_instructions": <str>,
-  "archived": <bool>,
-  "seller": {
-    "resource_url": <str>,
-    "username": <str>,
-    "id": <int>
-  },
-  "last_activity": <str>,
-  "buyer": {
-    "resource_url": <str>,
-    "username": <str>,
-    "id": <int>
-  },
-  "total": {
-    "currency": <str>,
-    "value": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-edit_profile(*, name: str = None, home_page: str = None, location: str = None, profile: str = None, curr_abbr: str = None) → dict[str, Any][source]#
-

User Identity > Profile > Edit Profile: -Edit a user’s profile data.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
namestr, keyword-only, optional

The real name of the user.

-

Example: "Nicolas Cage".

-
-
home_pagestr, keyword-only, optional

The user’s website.

-

Example: "www.discogs.com".

-
-
locationstr, keyword-only, optional

The geographical location of the user.

-

Example: "Portland".

-
-
profilestr, keyword-only, optional

Biological information about the user.

-

Example: "I am a Discogs user!".

-
-
curr_abbrstr, keyword-only, optional

Currency abbreviation for marketplace data.

-

Valid values: "USD", "GBP", -"EUR", "CAD", "AUD", "JPY", -"CHF", "MXN", "BRL", "NZD", -"SEK", and "ZAR".

-
-
-
-
Returns:
-
-
profiledict

Updated profile.

-
-

Sample

-
{
-  "id": <int><int>,
-  "username": <str>,
-  "name": <str>,
-  "email": <str>,
-  "resource_url": <str>,
-  "inventory_url": <str>,
-  "collection_folders_url": <str>,
-  "collection_fields_url": <str>,
-  "wantlist_url": <str>,
-  "uri": <str>,
-  "profile": <str>,
-  "home_page": <str>,
-  "location": <str>,
-  "registered": <str>,
-  "num_lists": <int>,
-  "num_for_sale": <int>,
-  "num_collection": <int>,
-  "num_wantlist": <int>,
-  "num_pending": <int>,
-  "releases_contributed": <int>,
-  "rank": <int>,
-  "releases_rated": <int>,
-  "rating_avg": <float>
-}
-
-
-
-
-
-
-
-
- -
-
-export_inventory(*, download: bool = True, filename: str = None, path: str = None) → str[source]#
-

Inventory Export > Export Your Inventory: Request an -export of your inventory as a CSV.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
downloadbool, keyword-only, default: True

Specifies whether to download the CSV file. If -False, the export ID is returned.

-
-
filenamestr, optional

Filename of the exported CSV file. A .csv extension -will be appended if not present. If not specified, the CSV -file is saved as -<username>-inventory-<date>-<number>.csv.

-
-
pathstr, optional

Path to save the exported CSV file. If not specified, the -file is saved in the current working directory.

-
-
-
-
Returns:
-
-
path_or_idstr

Full path to the exported CSV file (download=True) -or the export ID (download=False).

-
-
-
-
-
- -
-
-get_artist(artist_id: int | str) → dict[str, Any][source]#
-

Database > Artist: Get an artist.

-
-
Parameters:
-
-
artist_idint or str

The artist ID.

-

Example: 108713.

-
-
-
-
Returns:
-
-
artistdict

Discogs database information for a single artist.

-
-

Sample

-
{
-  "namevariations": [<str>],
-  "profile": <str>,
-  "releases_url": <str>,
-  "resource_url": <str>,
-  "uri": <str>,
-  "urls": [<str>],
-  "data_quality": <str>,
-  "id": <int>,
-  "images": [
-    {
-      "height": <int>,
-      "resource_url": <str>,
-      "type": <str>,
-      "uri": <str>,
-      "uri150": <str>,
-      "width": <int>
-    }
-  ],
-  "members": [
-    {
-      "active": <bool>,
-      "id": <int>,
-      "name": <str>,
-      "resource_url": <str>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_releases(artist_id: int | str, *, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#
-

Database > Artist Releases: Get an -artist’s releases and masters.

-
-
Parameters:
-
-
artist_idint or str

The artist ID.

-

Example: 108713.

-
-
pageint or str, keyword-only, optional

Page of results to fetch.

-
-
per_pageint or str, keyword-only, optional

Number of results per page.

-
-
sortstr, keyword-only, optional

Sort results by this field.

-

Valid values: "year", "title", and -"format".

-
-
sort_orderstr, keyword-only, optional

Sort results in a particular order.

-

Valid values: "asc" and "desc".

-
-
-
-
Returns:
-
-
releasesdict

Discogs database information for all releases by the -specified artist.

-
-

Sample

-
{
-  "pagination": {
-    "items": <int>,
-    "page": <int>,
-    "pages": <int>,
-    "per_page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    }
-  },
-  "releases": [
-    {
-      "artist": <str>,
-      "id": <int>,
-      "main_release": <int>,
-      "resource_url": <str>,
-      "role": <str>,
-      "thumb": <str>,
-      "title": <str>,
-      "type": <str>,
-      "year": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_collection_fields(username: str = None) → list[dict[str, Any]][source]#
-

User Collection > Collection Fields: Retrieve a list of -user-defined collection notes fields.

-

These fields are available on every release in the collection.

-
-

User authentication

-

If the collection has been made private by its owner, -authentication as the collection owner is required.

-

If you are not authenticated as the collection owner, only -fields with public set to true will be visible.

-
-
-
Parameters:
-
-
usernamestr, optional

The username of the collection you are trying to fetch. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
Returns:
-
-
fieldslist

A list of user-defined collection fields.

-
-

Sample

-
[
-  {
-    "id": <int>,
-    "name": <str>,
-    "options": [<str>],
-    "public": <bool>,
-    "position": <int>,
-    "type": "dropdown"
-  },
-  {
-    "id": <int>,
-    "name": <str>,
-    "lines": <int>,
-    "public": <bool>,
-    "position": <int>,
-    "type": "textarea"
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_collection_folder(folder_id: int, *, username: str = None) → dict[str, int | str][source]#
-

User Collection > Collection Folder > Get Folders: Retrieve metadata -about a folder in a user’s collection.

-
-

User authentication

-

If folder_id is not 0, authentication as the -collection owner is required.

-
-
-
Parameters:
-
-
folder_idint

The ID of the folder to request.

-

Example: 3.

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to request. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
Returns:
-
-
folderdict

Metadata about the folder.

-
-

Sample

-
{
-  "id": <int>,
-  "name": <str>,
-  "count": <int>,
-  "resource_url": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_collection_folder_releases(folder_id: int, *, username: str = None, page: int = None, per_page: int = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#
-

User Collection > Collection Items By Folder: Returns the items -in a folder in a user’s collection.

-

Basic information about each release is provided, suitable for -display in a list. For detailed information, make another call -to fetch the corresponding release.

-
-

User authentication

-

If folder_id is not 0 or the collection has been -made private by its owner, authentication as the collection -owner is required.

-

If you are not authenticated as the collection owner, only -the public notes fields will be visible.

-
-
-
Parameters:
-
-
folder_idint

The ID of the folder to request.

-

Example: 3.

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to request. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
pageint, keyword-only, optional

Page of results to fetch.

-
-
per_pageint, keyword-only, optional

Number of results per page.

-
-
sortstr, keyword-only, optional

Sort items by this field.

-

Valid values: "label", "artist", -"title", "catno", "format", -"rating", "year", and "added".

-
-
sort_orderstr, keyword-only, optional

Sort items in a particular order.

-

Valid values: "asc" and "desc".

-
-
-
-
Returns:
-
-
itemsdict

Items in the folder.

-
-

Sample

-
{
-  "pagination": {
-    "per_page": <int>,
-    "items": <int>,
-    "page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    },
-    "pages": <int>
-  },
-  "releases": [
-    {
-      "instance_id": <int>,
-      "rating": <int>,
-      "basic_information": {
-        "labels": [
-          {
-            "name": <str>,
-            "entity_type": <str>,
-            "catno": <str>,
-            "resource_url": <str>,
-            "id": <int>,
-            "entity_type_name": <str>
-          }
-        ],
-        "formats": [
-          {
-            "descriptions": [<str>],
-            "name": <str>,
-            "qty": <str>
-          }
-        ],
-        "thumb": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "join": <str>,
-            "name": <str>,
-            "anv": <str>,
-            "tracks": <str>,
-            "role": <str>,
-            "resource_url": <str>,
-            "id": <int>
-          }
-        ],
-        "resource_url": <str>,
-        "year": <int>,
-        "id": <int>,
-      },
-      "folder_id": <int>,
-      "date_added": <str>,
-      "id": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_collection_folders(username: str = None) → list[dict[str, Any]][source]#
-

User Collection > Collection > Get Collection Folders: Retrieve a list of folders -in a user’s collection.

-
-

User authentication

-

If the collection has been made private by its owner, -authentication as the collection owner is required. If you -are not authenticated as the collection owner, only folder ID -0 (the “All” folder) will be visible (if the -requested user’s collection is public).

-
-
-
Parameters:
-
-
usernamestr, optional

The username of the collection you are trying to fetch. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
Returns:
-
-
folderslist

A list of folders in the user’s collection.

-
-

Sample

-
[
-  {
-    "id": <int>,
-    "name": <str>,
-    "count": <int>,
-    "resource_url": <str>
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_collection_folders_by_release(release_id: int | str, *, username: str = None) → dict[str, Any][source]#
-

User Collection > Collection Items By Release: View the -user’s collection folders which contain a specified release. -This will also show information about each release instance.

-
-
Parameters:
-
-
release_idint or str

The ID of the release to request.

-

Example: 7781525.

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to view. If -not specified, the username of the authenticated user is -used.

-

Example: "susan.salkeld".

-
-
-
-
Returns:
-
-
releaseslist

A list of releases and their folders.

-
-

Sample

-
{
-  "pagination": {
-    "per_page": <int>,
-    "items": <int>,
-    "page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    },
-    "pages": <int>
-  },
-  "releases": [
-    {
-      "instance_id": <int>,
-      "rating": <int>,
-      "basic_information": {
-        "labels": [
-          {
-            "name": <str>,
-            "entity_type": <str>,
-            "catno": <str>,
-            "resource_url": <str>,
-            "id": <int>,
-            "entity_type_name": <str>
-          }
-        ],
-        "formats": [
-          {
-            "descriptions": [<str>],
-            "name": <str>,
-            "qty": <str>
-          }
-        ],
-        "thumb": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "join": <str>,
-            "name": <str>,
-            "anv": <str>,
-            "tracks": <str>,
-            "role": <str>,
-            "resource_url": <str>,
-            "id": <int>
-          }
-        ],
-        "resource_url": <str>,
-        "year": <int>,
-        "id": <int>,
-      },
-      "folder_id": <int>,
-      "date_added": <str>,
-      "id": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_collection_value(username: str = None) → dict[str, Any][source]#
-

User Collection > Collection Value: Returns the minimum, -median, and maximum value of a user’s collection.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
usernamestr, optional

The username of the collection you are trying to fetch. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
Returns:
-
-
valuedict

The total minimum value of the user’s collection.

-
-

Sample

-
{
-  "maximum": <str>,
-  "median": <str>,
-  "minimum": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_community_release_rating(release_id: int | str) → dict[str, Any][source]#
-

Database > Community Release Rating: Retrieves the -community release rating average and count.

-
-
Parameters:
-
-
release_idint or str

The release ID.

-

Example: 249504.

-
-
-
-
Returns:
-
-
ratingdict

Community release rating average and count.

-
-

Sample

-
{
-  "rating": {
-      "count": <int>,
-      "average": <float>
-  },
-  "release_id": <int>
-}
-
-
-
-
-
-
-
-
- -
-
-get_fee(price: float, *, currency: str = 'USD') → dict[str, Any][source]#
-

Marketplace > Fee with currency: Calculates the fee for -selling an item on the marketplace given a particular currency.

-
-
Parameters:
-
-
pricefloat

The price of the item (in the seller’s currency).

-

Example: 10.00.

-
-
currencystr, keyword-only, default: "USD"

The currency abbreviation for the fee calculation.

-

Valid values: "USD", "GBP", "EUR", -"CAD", "AUD", "JPY", "CHF", -"MXN", "BRL", "NZD", "SEK", -and "ZAR".

-
-
-
-
Returns:
-
-
feedict

The fee for selling an item on the marketplace.

-
-

Sample

-
{
-  "value": <float>,
-  "currency": <str>,
-}
-
-
-
-
-
-
-
-
- -
-
-get_identity() → dict[str, Any][source]#
-

User Identity > Identity: -Retrieve basic information about the authenticated user.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-

You can use this resource to find out who you’re authenticated -as, and it also doubles as a good sanity check to ensure that -you’re using OAuth correctly.

-

For more detailed information, make another request for the -user’s profile using get_profile().

-
-
Returns:
-
-
identitydict

Basic information about the authenticated user.

-
-

Sample

-
{
-  "id": <int>,
-  "username": <str>,
-  "resource_url": <str>,
-  "consumer_name": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_inventory(username: str = None, *, status: str = None, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#
-

Marketplace > Inventory: -Get a seller’s inventory.

-
-

User authentication

-

If you are authenticated as the inventory owner, additional -fields will be returned in the response, such as -"weight", "format_quantity", -"external_id", "location", and -"quantity".

-
-
-
Parameters:
-
-
usernamestr

The username of the inventory owner. If not specified, the -username of the authenticated user is used.

-

Example: "360vinyl".

-
-
statusstr, keyword-only, optional

The status of the listings to return.

-

Valid values: "For Sale", "Draft", -"Expired", "Sold", and "Deleted".

-
-
pageint or str, keyword-only, optional

The page you want to request.

-

Example: 3.

-
-
per_pageint or str, keyword-only, optional

The number of items per page.

-

Example: 25.

-
-
sortstr, keyword-only, optional

Sort items by this field.

-

Valid values: "listed", "price", -"item", "artist", "label", -"catno", "audio", "status", and -"location".

-
-
sort_orderstr, keyword-only, optional

Sort items in a particular order.

-

Valid values: "asc" and "desc".

-
-
-
-
Returns:
-
-
inventorydict

The seller’s inventory.

-
-

Sample

-
{
-  "pagination": {
-    "page": <int>,
-    "pages": <int>,
-    "per_page": <int>,
-    "items": <int>,
-    "urls": {}
-  },
-  "listings": [
-    {
-      "status": <str>,
-      "price": {
-        "currency": <str>,
-        "value": <float>
-      },
-      "allow_offers": <bool>,
-      "sleeve_condition": <str>,
-      "id": <int>,
-      "condition": <str>,
-      "posted": <str>,
-      "ships_from": <str>,
-      "uri": <str>,
-      "comments": <str>,
-      "seller": {
-        "username": <str>,
-        "resource_url": <str>,
-        "id": <int>
-      },
-      "release": {
-        "catalog_number": <str>,
-        "resource_url": <str>,
-        "year": <int>,
-        "id": <int>,
-        "description": <str>,
-        "artist": <str>,
-        "title": <str>,
-        "format": <str>,
-        "thumbnail": <str>
-      },
-      "resource_url": <str>,
-      "audio": <bool>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_inventory_export(export_id: int) → dict[str, int | str][source]#
-

Inventory Export > Get An Export: Get details about the -status of an inventory export.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
export_idint

ID of the export.

-
-
-
-
Returns:
-
-
exportdict

Details about the status of the inventory export.

-
-

Sample

-
{
-  "status": <str>,
-  "created_ts": <str>,
-  "url": <str>,
-  "finished_ts": <str>,
-  "download_url": <str>,
-  "filename": <str>,
-  "id": <int>
-}
-
-
-
-
-
-
-
-
- -
-
-get_inventory_exports(*, page: int = None, per_page: int = None) → dict[str, Any][source]#
-

Inventory Export > Get Recent Exports: Get all recent -exports of your inventory.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
pageint, keyword-only, optional

The page you want to request.

-

Example: 3.

-
-
per_pageint, keyword-only, optional

The number of items per page.

-

Example: 25.

-
-
-
-
Returns:
-
-
exportsdict

The authenticated user’s inventory exports.

-
-

Sample

-
{
-  "items": [
-    {
-      "status": <str>,
-      "created_ts": <str>,
-      "url": <str>,
-      "finished_ts": <str>,
-      "download_url": <str>,
-      "filename": <str>,
-      "id": <int>
-    }
-  ],
-  "pagination": {
-    "per_page": <int>,
-    "items": <int>,
-    "page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    },
-    "pages": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_label(label_id: int | str) → dict[str, Any][source]#
-

Database > Label: Get a label, -company, recording studio, locxation, or other entity involved -with artists and releases.

-
-
Parameters:
-
-
label_idint or str

The label ID.

-

Example: 1.

-
-
-
-
Returns:
-
-
labeldict

Discogs database information for a single label.

-
-

Sample

-
{
-  "profile": <str>,
-  "releases_url": <str>,
-  "name": <str>,
-  "contact_info": <str>,
-  "uri": <str>,
-  "sublabels": [
-    {
-      "resource_url": <str>,
-      "id": <int>,
-      "name": <str>
-    }
-  ],
-  "urls": [<str>],
-  "images": [
-    {
-      "height": <int>,
-      "resource_url": <str>,
-      "type": <str>,
-      "uri": <str>,
-      "uri150": <str>,
-      "width": <int>
-    }
-  ],
-  "resource_url": <str>,
-  "id": <int>,
-  "data_quality": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_label_releases(label_id: int | str, *, page: int | str = None, per_page: int | str = None) → dict[str, Any][source]#
-

Database > Label Releases: Get a -list of releases associated with the label.

-
-
Parameters:
-
-
label_idint or str

The label ID.

-

Example: 1.

-
-
pageint or str, keyword-only, optional

Page of results to fetch.

-
-
per_pageint or str, keyword-only, optional

Number of results per page.

-
-
-
-
Returns:
-
-
releasesdict

Discogs database information for all releases by the -specified label.

-
-

Sample

-
{
-  "pagination": {
-    "items": <int>,
-    "page": <int>,
-    "pages": <int>,
-    "per_page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    }
-  },
-  "releases": [
-    {
-      "artist": <str>,
-      "catno": <str>,
-      "format": <str>,
-      "id": <int>,
-      "resource_url": <str>,
-      "status": <str>,
-      "thumb": <str>,
-      "title": <str>,
-      "year": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_listing(listing_id: int | str, *, curr_abbr: str = None) → dict[str, Any][source]#
-

Marketplace > Listing: View -marketplace listings.

-
-
Parameters:
-
-
listing_idint or str

The ID of the listing you are fetching.

-

Example: 172723812.

-
-
curr_abbrstr, keyword-only, optional

Currency abbreviation for marketplace listings. Defaults to -the authenticated user’s currency.

-

Valid values: "USD", "GBP", "EUR", -"CAD", "AUD", "JPY", "CHF", -"MXN", "BRL", "NZD", "SEK", -and "ZAR".

-
-
-
-
Returns:
-
-
listingdict

The marketplace listing.

-
-

Sample

-
{
-  "status": <str>,
-  "price": {
-    "currency": <str>,
-    "value": <int>
-  },
-  "original_price": {
-    "curr_abbr": <str>,
-    "curr_id": <int>,
-    "formatted": <str>,
-    "value": <float>
-  },
-  "allow_offers": <bool>,
-  "sleeve_condition": <str>,
-  "id": <int>,
-  "condition": <str>,
-  "posted": <str>,
-  "ships_from": <str>,
-  "uri": <str>,
-  "comments": <str>,
-  "seller": {
-    "username": <str>,
-    "avatar_url": <str>,
-    "resource_url": <str>,
-    "url": <str>,
-    "id": <int>,
-    "shipping": <str>,
-    "payment": <str>,
-    "stats": {
-      "rating": <str>,
-      "stars": <float>,
-      "total": <int>
-    }
-  },
-  "shipping_price": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "original_shipping_price": {
-    "curr_abbr": <str>,
-    "curr_id": <int>,
-    "formatted": <str>,
-    "value": <float>
-  },
-  "release": {
-    "catalog_number": <str>,
-    "resource_url": <str>,
-    "year": <int>,
-    "id": <int>,
-    "description": <str>,
-    "thumbnail": <str>,
-  },
-  "resource_url": <str>,
-  "audio": <bool>
-}
-
-
-
-
-
-
-
-
- -
-
-get_master_release(master_id: int | str) → dict[str, Any][source]#
-

Database > Master Release: Get a -master release.

-
-
Parameters:
-
-
master_idint or str

The master release ID.

-

Example: 1000.

-
-
-
-
Returns:
-
-
master_releasedict

Discogs database information for a single master release.

-
-

Sample

-
{
-  "styles": [<str>],
-  "genres": [<str>],
-  "videos": [
-    {
-      "duration": <int>,
-      "description": <str>,
-      "embed": <bool>,
-      "uri": <str>,
-      "title": <str>
-    }
-  ],
-  "title": <str>,
-  "main_release": <int>,
-  "main_release_url": <str>,
-  "uri": <str>,
-  "artists": [
-    {
-      "join": <str>,
-      "name": <str>,
-      "anv": <str>,
-      "tracks": <str>,
-      "role": <str>,
-      "resource_url": <str>,
-      "id": <int>
-    }
-  ],
-  "versions_url": <str>,
-  "year": <int>,
-  "images": [
-    {
-      "height": <int>,
-      "resource_url": <str>,
-      "type": <str>,
-      "uri": <str>,
-      "uri150": <str>,
-      "width": <int>
-    }
-  ],
-  "resource_url": <str>,
-  "tracklist": [
-    {
-      "duration": <str>,
-      "position": <str>,
-      "type_": <str>,
-      "extraartists": [
-        {
-          "join": <str>,
-          "name": <str>,
-          "anv": <str>,
-          "tracks": <str>,
-          "role": <str>,
-          "resource_url": <str>,
-          "id": <int>
-        }
-      ],
-      "title": <str>
-    }
-  ],
-  "id": <int>,
-  "num_for_sale": <int>,
-  "lowest_price": <float>,
-  "data_quality": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_master_release_versions(master_id: int | str, *, country: str = None, format: str = None, label: str = None, released: str = None, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#
-

Database > Master Release Versions: Retrieves a list of -all releases that are versions of this master.

-
-
Parameters:
-
-
master_idint or str

The master release ID.

-

Example: 1000.

-
-
countrystr, keyword-only, optional

The country to filter for.

-

Example: "Belgium".

-
-
formatstr, keyword-only, optional

The format to filter for.

-

Example: "Vinyl".

-
-
labelstr, keyword-only, optional

The label to filter for.

-

Example: "Scorpio Music".

-
-
releasedstr, keyword-only, optional

The release year to filter for.

-

Example: "1992".

-
-
pageint or str, keyword-only, optional

The page you want to request.

-

Example: 3.

-
-
per_pageint or str, keyword-only, optional

The number of items per page.

-

Example: 25.

-
-
sortstr, keyword-only, optional

Sort items by this field.

-

Valid values: "released", "title", -"format", "label", "catno", -and "country".

-
-
sort_orderstr, keyword-only, optional

Sort items in a particular order.

-

Valid values: "asc" and "desc".

-
-
-
-
Returns:
-
-
versionsdict

Discogs database information for all releases that are -versions of the specified master.

-
-

Sample

-
{
-  "pagination": {
-    "items": <int>,
-    "page": <int>,
-    "pages": <int>,
-    "per_page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    }
-  },
-  "versions": [
-    {
-      "status": <str>,
-      "stats": {
-        "user": {
-          "in_collection": <int>,
-          "in_wantlist": <int>
-        },
-        "community": {
-          "in_collection": <int>,
-          "in_wantlist": <int>
-        }
-      },
-      "thumb": <str>,
-      "format": <str>,
-      "country": <str>,
-      "title": <str>,
-      "label": <str>,
-      "released": <str>,
-      "major_formats": [<str>],
-      "catno": <str>,
-      "resource_url": <str>,
-      "id": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_order(order_id: str) → dict[str, Any][source]#
-

Marketplace > Order > Get Order: View the data -associated with an order.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
order_idstr

The ID of the order you are fetching.

-

Example: 1-1.

-
-
-
-
Returns:
-
-
orderdict

The marketplace order.

-
-

Sample

-
{
-  "id": <str>,
-  "resource_url": <str>,
-  "messages_url": <str>,
-  "uri": <str>,
-  "status": <str>,
-  "next_status": [<str>],
-  "fee": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "created": <str>,
-  "items": [
-    {
-      "release": {
-        "id": <int>,
-        "description": <str>,
-      },
-      "price": {
-        "currency": <str>,
-        "value": <int>
-      },
-      "media_condition": <str>,
-      "sleeve_condition": <str>,
-      "id": <int>
-    }
-  ],
-  "shipping": {
-    "currency": <str>,
-    "method": <str>,
-    "value": <int>
-  },
-  "shipping_address": <str>,
-  "additional_instructions": <str>,
-  "archived": <bool>,
-  "seller": {
-    "resource_url": <str>,
-    "username": <str>,
-    "id": <int>
-  },
-  "last_activity": <str>,
-  "buyer": {
-    "resource_url": <str>,
-    "username": <str>,
-    "id": <int>
-  },
-  "total": {
-    "currency": <str>,
-    "value": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_order_messages(order_id: str, *, page: int | str = None, per_page: int | str = None) → dict[str, Any][source]#
-

Marketplace > List Order Messages > List Order Messages: -Returns a list of the order’s messages with the most recent -first.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
order_idstr

The ID of the order you are fetching.

-

Example: 1-1.

-
-
pageint or str, keyword-only, optional

The page you want to request.

-

Example: 3.

-
-
per_pageint or str, keyword-only, optional

The number of items per page.

-

Example: 25.

-
-
-
-
Returns:
-
-
messagesdict

The order’s messages.

-
-

Sample

-
{
-  "pagination": {
-    "per_page": <int>,
-    "items": <int>,
-    "page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    },
-    "pages": <int>
-  },
-  "messages": [
-    {
-      "refund": {
-        "amount": <int>,
-        "order": {
-          "resource_url": <str>,
-          "id": <str>
-        }
-      },
-      "timestamp": <str>,
-      "message": <str>,
-      "type": <str>,
-      "order": {
-        "resource_url": <str>,
-        "id": <str>,
-      },
-      "subject": <str>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_price_suggestions(release_id: int | str) → dict[str, Any][source]#
-

Marketplace > Price Suggestions: Retrieve price suggestions in -the user’s selling currency for the provided release ID.

-

If no suggestions are available, an empty object will be -returned.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
release_idint or str

The ID of the release you are fetching.

-

Example: 249504.

-
-
-
-
Returns:
-
-
pricesdict

The price suggestions for the release.

-
-

Sample

-
{
-  "Very Good (VG)": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "Good Plus (G+)": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "Near Mint (NM or M-)": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "Good (G)": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "Very Good Plus (VG+)": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "Mint (M)": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "Fair (F)": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "Poor (P)": {
-    "currency": <str>,
-    "value": <float>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_profile(username: str = None) → dict[str, Any][source]#
-

User Identity > Profile > Get Profile: -Retrieve a user by username.

-
-

User authentication

-

If authenticated as the requested user, the "email" -key will be visible, and the "num_lists" count will -include the user’s private lists.

-

If authenticated as the requested user or the user’s -collection/wantlist is public, the -"num_collection"/"num_wantlist" keys will be -visible.

-
-
-
Parameters:
-
-
usernamestr, optional

The username of whose profile you are requesting. If not -specified, the username of the authenticated user is used.

-

Example: "rodneyfool".

-
-
-
-
Returns:
-
-
profiledict

Detailed information about the user.

-
-

Sample

-
{
-  "profile": <str>,
-  "wantlist_url": <str>,
-  "rank": <int>,
-  "num_pending": <int>,
-  "id": <int>,
-  "num_for_sale": <int>,
-  "home_page": <str>,
-  "location": <str>,
-  "collection_folders_url": <str>,
-  "username": <str>,
-  "collection_fields_url": <str>,
-  "releases_contributed": <int>,
-  "registered": <str>,
-  "rating_avg": <float>,
-  "num_collection": <int>,
-  "releases_rated": <int>,
-  "num_lists": <int>,
-  "name": <str>,
-  "num_wantlist": <int>,
-  "inventory_url": <str>,
-  "avatar_url": <str>,
-  "banner_url": <str>,
-  "uri": <str>,
-  "resource_url": <str>,
-  "buyer_rating": <float>,
-  "buyer_rating_stars": <int>,
-  "buyer_num_ratings": <int>,
-  "seller_rating": <float>,
-  "seller_rating_stars": <int>,
-  "seller_num_ratings": <int>,
-  "curr_abbr": <str>,
-}
-
-
-
-
-
-
-
-
- -
-
-get_release(release_id: int | str, *, curr_abbr: str = None) → dict[str, Any][source]#
-

Database > Release: -Get a release (physical or digital object released by one or -more artists).

-
-
Parameters:
-
-
release_idint or str

The release ID.

-

Example: 249504.

-
-
curr_abbrstr, keyword-only, optional

Currency abbreviation for marketplace data. Defaults to the -authenticated user’s currency.

-

Valid values: "USD", "GBP", -"EUR", "CAD", "AUD", "JPY", -"CHF", "MXN", "BRL", "NZD", -"SEK", and "ZAR".

-
-
-
-
Returns:
-
-
releasedict

Discogs database information for a single release.

-
-

Sample

-
{
-  "title": <str>,
-  "id": <int>,
-  "artists": [
-    {
-      "anv": <str>,
-      "id": <int>,
-      "join": <str>,
-      "name": <str>,
-      "resource_url": <str>,
-      "role": <str>,
-      "tracks": <str>
-    }
-  ],
-  "data_quality": <str>,
-  "thumb": <str>,
-  "community": {
-    "contributors": [
-      {
-        "resource_url": <str>,
-        "username": <str>
-      }
-    ],
-    "data_quality": <str>,
-    "have": <int>,
-    "rating": {
-      "average": <float>,
-      "count": <int>
-    },
-    "status": <str>,
-    "submitter": {
-      "resource_url": <str>,
-      "username": <str>
-    },
-    "want": <int>
-  },
-  "companies": [
-    {
-      "catno": <str>,
-      "entity_type": <str>,
-      "entity_type_name": <str>,
-      "id": <int>,
-      "name": <str>,
-      "resource_url": <str>
-    }
-  ],
-  "country": <str>,
-  "date_added": <str>,
-  "date_changed": <str>,
-  "estimated_weight": <int>,
-  "extraartists": [
-    {
-      "anv": <str>,
-      "id": <int>,
-      "join": <str>,
-      "name": <str>,
-      "resource_url": <str>,
-      "role": <str>,
-      "tracks": <str>
-    }
-  ],
-  "format_quantity": <int>,
-  "formats": [
-    {
-      "descriptions": [<str>],
-      "name": <str>,
-      "qty": <str>
-    }
-  ],
-  "genres": [<str>],
-  "identifiers": [
-    {
-      "type": <str>,
-      "value": <str>
-    },
-  ],
-  "images": [
-    {
-      "height": <int>,
-      "resource_url": <str>,
-      "type": <str>,
-      "uri": <str>,
-      "uri150": <str>,
-      "width": <int>
-    }
-  ],
-  "labels": [
-    {
-      "catno": <str>,
-      "entity_type": <str>,
-      "id": <int>,
-      "name": <str>,
-      "resource_url": <str>
-    }
-  ],
-  "lowest_price": <float>,
-  "master_id": <int>,
-  "master_url": <str>,
-  "notes": <str>,
-  "num_for_sale": <int>,
-  "released": <str>,
-  "released_formatted": <str>,
-  "resource_url": <str>,
-  "series": [],
-  "status": <str>,
-  "styles": [<str>],
-  "tracklist": [
-    {
-      "duration": <str>,
-      "position": <str>,
-      "title": <str>,
-      "type_": <str>
-    }
-  ],
-  "uri": <str>,
-  "videos": [
-    {
-      "description": <str>,
-      "duration": <int>,
-      "embed": <bool>,
-      "title": <str>,
-      "uri": <str>
-    },
-  ],
-  "year": <int>
-}
-
-
-
-
-
-
-
-
- -
-
-get_release_marketplace_stats(release_id: int | str, *, curr_abbr: str = None) → dict[str, Any][source]#
-

Marketplace > Release Statistics: Retrieve marketplace -statistics for the provided release ID.

-

These statistics reflect the state of the release in the -marketplace currently, and include the number of items currently -for sale, lowest listed price of any item for sale, and whether -the item is blocked for sale in the marketplace.

-

Releases that have no items or are blocked for sale in the -marketplace will return a body with null data in the -"lowest_price" and "num_for_sale" keys.

-
-

User authentication

-

Authentication is optional. Authenticated users will by -default have the lowest currency expressed in their own buyer -currency, configurable in buyer settings, in the absence of -the curr_abbr query parameter to specify the currency. -Unauthenticated users will have the price expressed in US -Dollars, if no curr_abbr is provided.

-
-
-
Parameters:
-
-
release_idint or str

The ID of the release you are fetching.

-

Example: 249504.

-
-
curr_abbrstr, keyword-only, optional

Currency abbreviation for marketplace data.

-

Valid values: "USD", "GBP", -"EUR", "CAD", "AUD", "JPY", -"CHF", "MXN", "BRL", "NZD", -"SEK", and "ZAR".

-
-
-
-
Returns:
-
-
statsdict

The marketplace statistics for the release.

-
-

Sample

-
{
-  "lowest_price": {
-    "currency": <str>,
-    "value": <float>
-  },
-  "num_for_sale": <int>,
-  "blocked_from_sale": <bool>
-}
-
-
-
-
-
-
-
-
- -
-
-get_release_stats(release_id: int | str) → dict[str, Any][source]#
-

Database > Release Stats: Retrieves -the release’s “have” and “want” counts.

-
-

Attention

-

This endpoint does not appear to be working correctly. -Currently, the response will be of the form

-
{
-  "is_offense": <bool>
-}
-
-
-
-
-
Parameters:
-
-
release_idint or str

The release ID.

-

Example: 249504.

-
-
-
-
Returns:
-
-
statsdict

Release “have” and “want” counts.

-
-

Sample

-
{
-  "num_have": <int>,
-  "num_want": <int>
-}
-
-
-
-
-
-
-
-
- -
-
-get_user_contributions(username: str = None, *, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#
-

User Identity > User Contributions: Retrieve a user’s -contributions (releases, labels, artists) by username.

-
-
Parameters:
-
-
usernamestr, optional

The username of the contributions you are trying to fetch. -If not specified, the username of the authenticated user is -used.

-

Example: "shooezgirl".

-
-
pageint or str, keyword-only, optional

Page of results to fetch.

-
-
per_pageint or str, keyword-only, optional

Number of results per page.

-
-
sortstr, keyword-only, optional

Sort items by this field.

-

Valid values: "label", "artist", -"title", "catno", "format", -"rating", "year", and "added".

-
-
sort_orderstr, keyword-only, optional

Sort items in a particular order.

-

Valid values: "asc" and "desc".

-
-
-
-
Returns:
-
-
contributionsdict

Contributions made by the user.

-
-

Sample

-
{
-  "pagination": {
-    "items": <int>,
-    "page": <int>,
-    "pages": <int>,
-    "per_page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    }
-  },
-  "contributions": [
-    {
-      "artists": [
-        {
-          "anv": <str>,
-          "id": <int>,
-          "join": <str>,
-          "name": <str>,
-          "resource_url": <str>,
-          "role": <str>,
-          "tracks": <str>
-        }
-      ],
-      "community": {
-        "contributors": [
-          {
-            "resource_url": <str>,
-            "username": <str>
-          }
-        ],
-        "data_quality": <str>,
-        "have": <int>,
-        "rating": {
-          "average": <int>,
-          "count": <int>
-        },
-        "status": <str>,
-        "submitter": {
-          "resource_url": <str>,
-          "username": <str>
-        },
-        "want": <int>
-      },
-      "companies": [],
-      "country": <str>,
-      "data_quality": <str>,
-      "date_added": <str>,
-      "date_changed": <str>,
-      "estimated_weight": <int>,
-      "format_quantity": <int>,
-      "formats": [
-        {
-          "descriptions": [<str>],
-          "name": <str>,
-          "qty": <str>
-        }
-      ],
-      "genres": [<str>],
-      "id": <int>,
-      "images": [
-        {
-          "height": <int>,
-          "resource_url": <str>,
-          "type": <str>,
-          "uri": <str>,
-          "uri150": <str>,
-          "width": <int>
-        }
-      ],
-      "labels": [
-        {
-          "catno": <str>,
-          "entity_type": <str>,
-          "id": <int>,
-          "name": <str>,
-          "resource_url": <str>
-        }
-      ],
-      "master_id": <int>,
-      "master_url": <str>,
-      "notes": <str>,
-      "released": <str>,
-      "released_formatted": <str>,
-      "resource_url": <str>,
-      "series": [],
-      "status": <str>,
-      "styles": [<str>],
-      "thumb": <str>,
-      "title": <str>,
-      "uri": <str>,
-      "videos": [
-        {
-          "description": <str>,
-          "duration": <int>,
-          "embed": <bool>,
-          "title": <str>,
-          "uri": <str>
-        }
-      ],
-      "year": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_user_orders(*, status: str = None, created_after: str = None, created_before: str = None, archived: bool = None, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#
-

Marketplace > List Orders: -Returns a list of the authenticated user’s orders.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
statusstr, keyword-only, optional

Only show orders with this status.

-

Valid values: "All", "New Order", -"Buyer Contacted", "Invoice Sent", -"Payment Pending", "Payment Received", -"In Progress", "Shipped", -"Merged", "Order Changed", -"Refund Sent", "Cancelled", -"Cancelled (Non-Paying Buyer)", -"Cancelled (Item Unavailable)", -"Cancelled (Per Buyer's Request)", and -"Cancelled (Refund Received)".

-
-
created_afterstr, keyword-only, optional

Only show orders created after this ISO 8601 timestamp.

-

Example: "2019-06-24T20:58:58Z".

-
-
created_beforestr, keyword-only, optional

Only show orders created before this ISO 8601 timestamp.

-

Example: "2019-06-24T20:58:58Z".

-
-
archivedbool, keyword-only, optional

Only show orders with a specific archived status. If no key -is provided, both statuses are returned.

-
-
pageint or str, keyword-only, optional

The page you want to request.

-

Example: 3.

-
-
per_pageint, keyword-only, optional

The number of items per page.

-

Example: 25.

-
-
sortstr, keyword-only, optional

Sort items by this field.

-

Valid values: "id", "buyer", -"created", "status", and -"last_activity".

-
-
sort_orderstr, keyword-only, optional

Sort items in a particular order.

-

Valid values: "asc" and "desc".

-
-
-
-
Returns:
-
-
ordersdict

The authenticated user’s orders.

-
-

Sample

-
{
-  "pagination": {
-    "page": <int>,
-    "pages": <int>,
-    "per_page": <int>,
-    "items": <int>,
-    "urls": {}
-  },
-  "orders": [
-    {
-      "id": <str>,
-      "resource_url": <str>,
-      "messages_url": <str>,
-      "uri": <str>,
-      "status": <str>,
-      "next_status": [<str>],
-      "fee": {
-        "currency": <str>,
-        "value": <float>
-      },
-      "created": <str>,
-      "items": [
-        {
-          "release": {
-            "id": <int>,
-            "description": <str>,
-          },
-          "price": {
-            "currency": <str>,
-            "value": <int>
-          },
-          "media_condition": <str>,
-          "sleeve_condition": <str>,
-          "id": <int>
-        }
-      ],
-      "shipping": {
-        "currency": <str>,
-        "method": <str>,
-        "value": <int>
-      },
-      "shipping_address": <str>,
-      "additional_instructions": <str>,
-      "archived": <bool>,
-      "seller": {
-        "resource_url": <str>,
-        "username": <str>,
-        "id": <int>
-      },
-      "last_activity": <str>,
-      "buyer": {
-        "resource_url": <str>,
-        "username": <str>,
-        "id": <int>
-      },
-      "total": {
-        "currency": <str>,
-        "value": <int>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_user_release_rating(release_id: int | str, username: str = None) → dict[str, Any][source]#
-

Database > Release Rating By User > Get Release Rating By User: Retrieves the -release’s rating for a given user.

-
-
Parameters:
-
-
release_idint or str

The release ID.

-

Example: 249504.

-
-
usernamestr, optional

The username of the user whose rating you are requesting. If -not specified, the username of the authenticated user is -used.

-

Example: "memory".

-
-
-
-
Returns:
-
-
ratingdict

Rating for the release by the given user.

-
-

Sample

-
{
-  "username": <str>,
-  "release_id": <int>,
-  "rating": <int>
-}
-
-
-
-
-
-
-
-
- -
-
-get_user_submissions(username: str = None, *, page: int | str = None, per_page: int | str = None) → dict[str, Any][source]#
-

User Identity > User Submissions: Retrieve a user’s -submissions (edits made to releases, labels, and artists) by -username.

-
-
Parameters:
-
-
usernamestr, optional

The username of the submissions you are trying to fetch. If -not specified, the username of the authenticated user is -used.

-

Example: "shooezgirl".

-
-
pageint or str, keyword-only, optional

Page of results to fetch.

-
-
per_pageint or str, keyword-only, optional

Number of results per page.

-
-
-
-
Returns:
-
-
submissionsdict

Submissions made by the user.

-
-

Sample

-
{
-  "pagination": {
-    "items": <int>,
-    "page": <int>,
-    "pages": <int>,
-    "per_page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    }
-  },
-  "submissions": {
-    "artists": [
-      {
-        "data_quality": <str>,
-        "id": <int>,
-        "name": <str>,
-        "namevariations": [<str>],
-        "releases_url": <str>,
-        "resource_url": <str>,
-        "uri": <str>
-      }
-    ],
-    "labels": [],
-    "releases": [
-      {
-        "artists": [
-          {
-            "anv": <str>,
-            "id": <int>,
-            "join": <str>,
-            "name": <str>,
-            "resource_url": <str>,
-            "role": <str>,
-            "tracks": <str>
-          }
-        ],
-        "community": {
-          "contributors": [
-            {
-              "resource_url": <str>,
-              "username": <str>
-            }
-          ],
-          "data_quality": <str>,
-          "have": <int>,
-          "rating": {
-            "average": <int>,
-            "count": <int>
-          },
-          "status": <str>,
-          "submitter": {
-            "resource_url": <str>,
-            "username": <str>
-          },
-          "want": <int>
-        },
-        "companies": [],
-        "country": <str>,
-        "data_quality": <str>,
-        "date_added": <str>,
-        "date_changed": <str>,
-        "estimated_weight": <int>,
-        "format_quantity": <int>,
-        "formats": [
-          {
-            "descriptions": [<str>],
-            "name": <str>,
-            "qty": <str>
-          }
-        ],
-        "genres": [<str>],
-        "id": <int>,
-        "images": [
-          {
-            "height": <int>,
-            "resource_url": <str>,
-            "type": <str>,
-            "uri": <str>,
-            "uri150": <str>,
-            "width": <int>
-          }
-        ],
-        "labels": [
-          {
-            "catno": <str>,
-            "entity_type": <str>,
-            "id": <int>,
-            "name": <str>,
-            "resource_url": <str>
-          }
-        ],
-        "master_id": <int>,
-        "master_url": <str>,
-        "notes": <str>,
-        "released": <str>,
-        "released_formatted": <str>,
-        "resource_url": <str>,
-        "series": [],
-        "status": <str>,
-        "styles": [<str>],
-        "thumb": <str>,
-        "title": <str>,
-        "uri": <str>,
-        "videos": [
-          {
-            "description": <str>,
-            "duration": <int>,
-            "embed": <bool>,
-            "title": <str>,
-            "uri": <str>
-          }
-        ],
-        "year": <int>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-rename_collection_folder(folder_id: int, name: str, *, username: str = None) → dict[str, int | str][source]#
-

User Collection > Collection Folder > Edit Folder: Rename a folder.

-

Folders 0 and 1 cannot be renamed.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
folder_idint

The ID of the folder to modify.

-

Example: 3.

-
-
namestr

The new name of the folder.

-

Example: "My favorites".

-
-
usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If -not specified, the username of the authenticated user is -used.

-

Example: "rodneyfool".

-
-
-
-
Returns:
-
-
folderdict

Information about the edited folder.

-
-

Sample

-
{
-  "id": <int>,
-  "name": <str>,
-  "count": <int>,
-  "resource_url": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-search(query: str = None, *, type: str = None, title: str = None, release_title: str = None, credit: str = None, artist: str = None, anv: str = None, label: str = None, genre: str = None, style: str = None, country: str = None, year: str = None, format: str = None, catno: str = None, barcode: str = None, track: str = None, submitter: str = None, contributor: str = None) → dict[str, Any][source]#
-

Database > Search: Issue a search -query to the Discogs database.

-
-

Authentication

-

Requires authentication with consumer credentials, with a -personal access token, or via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
querystr, optional

The search query.

-

Example: "Nirvana".

-
-
typestr, keyword-only, optional

The type of item to search for.

-

Valid values: "release", "master", -"artist", and "label".

-
-
titlestr, keyword-only, optional

Search by combined "<artist name> - <release title>" -title field.

-

Example: "Nirvana - Nevermind".

-
-
release_titlestr, keyword-only, optional

Search release titles.

-

Example: "Nevermind".

-
-
creditstr, keyword-only, optional

Search release credits.

-

Example: "Kurt".

-
-
artiststr, keyword-only, optional

Search artist names.

-

Example: "Nirvana".

-
-
anvstr, keyword-only, optional

Search artist name variations (ANV).

-

Example: "Nirvana".

-
-
labelstr, keyword-only, optional

Search labels.

-

Example: "DGC".

-
-
genrestr, keyword-only, optional

Search genres.

-

Example: "Rock".

-
-
stylestr, keyword-only, optional

Search styles.

-

Example: "Grunge".

-
-
countrystr, keyword-only, optional

Search release country.

-

Example: "Canada".

-
-
yearstr, keyword-only, optional

Search release year.

-

Example: "1991".

-
-
formatstr, keyword-only, optional

Search formats.

-

Example: "Album".

-
-
catnostr, keyword-only, optional

Search catalog number.

-

Example: "DGCD-24425".

-
-
barcodestr, keyword-only, optional

Search barcode.

-

Example: "720642442524".

-
-
trackstr, keyword-only, optional

Search track.

-

Example: "Smells Like Teen Spirit".

-
-
submitterstr, keyword-only, optional

Search submitter username.

-

Example: "milKt".

-
-
contributorstr, keyword-only, optional

Search contributor username.

-

Example: "jerome99".

-
-
-
-
Returns:
-
-
resultsdict

Search results.

-
-

Sample

-
{
-  "pagination": {
-    "items": <int>,
-    "page": <int>,
-    "pages": <int>,
-    "per_page": <int>,
-    "urls": {
-      "last": <str>,
-      "next": <str>
-    }
-  },
-  "results": [
-    {
-      "style": [<str>],
-      "thumb": <str>,
-      "title": <str>,
-      "country": <str>,
-      "format": [<str>],
-      "uri": <str>,
-      "community": {
-        "want": <int>,
-        "have": <int>
-      },
-      "label": [<str>],
-      "catno": <str>,
-      "year": <str>,
-      "genre": [<str>],
-      "resource_url": <str>,
-      "type": <str>,
-      "id": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-set_access_token(access_token: str = None, access_token_secret: str = None) → None[source]#
-

Set the Discogs API personal or OAuth access token (and secret).

-
-
Parameters:
-
-
access_tokenstr, optional

Personal or OAuth access token.

-
-
access_token_secretstr, optional

OAuth access token secret.

-
-
-
-
-
- -
-
-set_flow(flow: str, *, consumer_key: str = None, consumer_secret: str = None, browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, save: bool = True) → None[source]#
-

Set the authorization flow.

-
-
Parameters:
-
-
flowstr

Authorization flow. If None, no user authentication -will be performed and client credentials will not be -attached to requests, even if found or provided.

-
-

Valid values:

-
    -

  • None for no user authentication.

    • -

  • "discogs" for the Discogs authentication flow.

    • -

  • "oauth" for the OAuth 1.0a flow.

    • -
-
-
-
consumer_keystr, keyword-only, optional

Consumer key. Required for the OAuth 1.0a flow, and can be -used in the Discogs authorization flow alongside a consumer -secret. If it is not stored as DISCOGS_CONSUMER_KEY -in the operating system’s environment variables or found in -the Minim configuration file, it can be provided here.

-
-
consumer_secretstr, keyword-only, optional

Consumer secret. Required for the OAuth 1.0a flow, and can -be used in the Discogs authorization flow alongside a -consumer key. If it is not stored as -DISCOGS_CONSUMER_SECRET in the operating system’s -environment variables or found in the Minim configuration -file, it can be provided here.

-
-
browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for -the OAuth 1.0a flow. If False, users will have to -manually open the authorization URL and provide the full -callback URI via the terminal.

-
-
web_frameworkstr, keyword-only, optional

Determines which web framework to use for the OAuth 1.0a -flow.

-
-

Valid values:

-
    -

  • "http.server" for the built-in implementation -of HTTP servers.

    • -

  • "flask" for the Flask framework.

    • -

  • "playwright" for the Playwright framework by -Microsoft.

    • -
-
-
-
portint or str, keyword-only, default: 8888

Port on localhost to use for the OAuth 1.0a flow -with the http.server and Flask frameworks. Only used -if redirect_uri is not specified.

-
-
redirect_uristr, keyword-only, optional

Redirect URI for the OAuth 1.0a flow. If not on -localhost, the automatic request access token -retrieval functionality is not available.

-
-
savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their -associated properties are stored to the Minim configuration -file.

-
-
-
-
-
- -
-
-update_user_release_rating(release_id: int | str, rating: int, username: str = None) → dict[str, Any][source]#
-

Database > Release Rating By User > Update Release Rating By -User: -Updates the release’s rating for a given user.

-
-

User authentication

-

Requires user authentication with a personal access token or -via the OAuth 1.0a flow.

-
-
-
Parameters:
-
-
release_idint or str

The release ID.

-

Example: 249504.

-
-
ratingint

The new rating for a release between \(1\) and \(5\).

-
-
usernamestr, optional

The username of the user whose rating you are requesting. If -not specified, the username of the authenticated user is -used.

-

Example: "memory".

-
-
-
-
Returns:
-
-
ratingdict

Updated rating for the release by the given user.

-
-

Sample

-
{
-  "username": <str>,
-  "release_id": <int>,
-  "rating": <int>
-}
-
-
-
-
-
-
-
-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.discogs.html b/docs/api/minim.discogs.html deleted file mode 100644 index d42a5a79..00000000 --- a/docs/api/minim.discogs.html +++ /dev/null @@ -1,344 +0,0 @@ - - - - - - - - - discogs - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

discogs#

-
-

Discogs#

-

This module contains a complete implementation of the Discogs API.

-
-

Classes

-
- - - - - - -

API

Discogs API client.

-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.html b/docs/api/minim.html deleted file mode 100644 index 600972e5..00000000 --- a/docs/api/minim.html +++ /dev/null @@ -1,338 +0,0 @@ - - - - - - - - - minim - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
- -
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.itunes.SearchAPI.html b/docs/api/minim.itunes.SearchAPI.html deleted file mode 100644 index 8ab34c34..00000000 --- a/docs/api/minim.itunes.SearchAPI.html +++ /dev/null @@ -1,700 +0,0 @@ - - - - - - - - - SearchAPI - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

SearchAPI#

-
-
-class minim.itunes.SearchAPI[source]#
-

Bases: object

-

iTunes Search API client.

-

The iTunes Search API allows searching for a variety of content, -including apps, iBooks, movies, podcasts, music, music videos, -audiobooks, and TV shows within the iTunes Store, App Store, -iBooks Store and Mac App Store. It also supports ID-based lookup -requests to create mappings between your content library and the -digital catalog.

-
-

See also

-

For more information, see the iTunes Search API -documentation.

-
-
-
Attributes:
-
-
API_URLstr

Base URL for the iTunes Search API.

-
-
-
-
-

Methods

-
- - - - - - - - - -

lookup

Search for content based on iTunes IDs, AMG IDs, UPCs/EANs, or ISBNs.

search

Search for content using the iTunes Search API.

-
-
-
-lookup(id: int | str | list[int | str] = None, *, amg_artist_id: int | str | list[int | str] = None, amg_album_id: int | str | list[int | str] = None, amg_video_id: int | str | list[int | str] = None, bundle_id: str | list[str] = None, upc: int | str | list[int | str] = None, isbn: int | str | list[int | str] = None, entity: str | list[str] = None, limit: int | str = None, sort: str = None) → dict[str, Any][source]#
-

Search for content based on iTunes IDs, AMG IDs, UPCs/EANs, or -ISBNs. ID-based lookups are faster and contain fewer -false-positive results.

-
-
Parameters:
-
-
idint, str, or list, optional

The iTunes ID(s) to lookup.

-
-
amg_artist_idint, str, or list, keyword-only, optional

The AMG artist ID(s) to lookup.

-
-
amg_album_idint, str, or list, keyword-only, optional

The AMG album ID(s) to lookup.

-
-
amg_video_idint, str, or list, keyword-only, optional

The AMG video ID(s) to lookup.

-
-
bundle_idstr or list, keyword-only, optional

The Apple bundle ID(s) to lookup.

-
-
upcint, str, or list, keyword-only, optional

The UPC(s) to lookup.

-
-
isbnint, str, or list, keyword-only, optional

The 13-digit ISBN(s) to lookup.

-
-
entitystr or list, keyword-only, optional

The type(s) of results you want returned.

-
-

See also

-

For a list of available entities, see the iTunes Store -API Table 2-1.

-
-

Default: The track entity associated with the specified -media type.

-
-
limitint or str, keyword-only, optional

The number of search results you want the iTunes Store to -return.

-

Valid values: limit must be between 1 and 200.

-

Default: 50.

-
-
sortstr, keyword-only, optional

The sort applied to the search results.

-

Allowed value: "recent".

-
-
-
-
Returns:
-
-
resultsdict

The lookup results.

-
-

Sample response

-
{
-  "resultCount": <int>,
-  "results": [
-    {
-      "wrapperType": <str>,
-      "kind": <str>,
-      "artistId": <int>,
-      "collectionId": <int>,
-      "trackId": <int>,
-      "artistName": <str>,
-      "collectionName": <str>,
-      "trackName": <str>,
-      "collectionCensoredName": <str>,
-      "trackCensoredName": <str>,
-      "collectionArtistId": <int>,
-      "collectionArtistName": <str>,
-      "artistViewUrl": <str>,
-      "collectionViewUrl": <str>,
-      "trackViewUrl": <str>,
-      "previewUrl": <str>,
-      "artworkUrl30": <str>,
-      "artworkUrl60": <str>,
-      "artworkUrl100": <str>,
-      "collectionPrice": <float>,
-      "trackPrice": <float>,
-      "releaseDate": <str>,
-      "collectionExplicitness": <str>,
-      "trackExplicitness": <str>,
-      "discCount": <int>,
-      "discNumber": <int>,
-      "trackCount": <int>,
-      "trackNumber": <int>,
-      "trackTimeMillis": <int>,
-      "country": <str>,
-      "currency": <str>,
-      "primaryGenreName": <str>,
-      "isStreamable": <bool>
-    }
-  ]
-}
-
-
-
-
-
-
-
-

Examples

-

Look up Jack Johnson by iTunes artist ID:

-
>>> itunes.lookup(909253)
-
-
-

Look up the Yelp application by iTunes ID:

-
>>> itunes.lookup(284910350)
-
-
-

Look up Jack Johnson by AMG artist ID:

-
>>> itunes.lookup(amg_artist_id=468749)
-
-
-

Look up multiple artists by their AMG artist IDs:

-
>>> itunes.lookup(amg_artist_id=[468749, 5723])
-
-
-

Look up all albums for Jack Johnson:

-
>>> itunes.lookup(909253, entity="album")
-
-
-

Look up multiple artists by their AMG artist IDs and get each -artist’s top 5 albums:

-
>>> itunes.lookup(amg_artist_id=[468749, 5723], entity="album",
-...               limit=5)
-
-
-

Look up multiple artists by their AMG artist IDs and get each -artist’s 5 most recent songs:

-
>>> itunes.lookup(amg_artist_id=[468749, 5723], entity="song",
-...               limit=5, sort="recent")
-
-
-

Look up an album or video by its UPC:

-
>>> itunes.lookup(upc=720642462928)
-
-
-

Look up an album by its UPC, including the tracks on that album:

-
>>> itunes.lookup(upc=720642462928, entity="song")
-
-
-

Look up an album by its AMG Album ID:

-
>>> itunes.lookup(amg_album_id=[15175, 15176, 15177, 15178,
-...                             15183, 15184, 15187, 15190,
-...                             15191, 15195, 15197, 15198])
-
-
-

Look up a Movie by AMG Video ID:

-
>>> itunes.lookup(amg_video_id=17120)
-
-
-

Look up a book by its 13-digit ISBN:

-
>>> itunes.lookup(isbn=9780316069359)
-
-
-

Look up the Yelp application by iTunes bundle ID:

-
>>> itunes.lookup(bundle_id="com.yelp.yelpiphone")
-
-
-
- -
-
-search(term: str, *, country: str = None, media: str = None, entity: str | list[str] = None, attribute: str = None, limit: int | str = None, lang: str = None, version: int | str = None, explicit: bool | str = None) → dict[str, Any][source]#
-

Search for content using the iTunes Search API.

-
-
Parameters:
-
-
termstr

The text string to search for.

-
-

Note

-

URL encoding replaces spaces with the plus (+) -character, and all characters except letters, numbers, -periods (.), dashes (-), underscores -(_), and asterisks (*) are encoded.

-
-

Example: "jack+johnson".

-
-
countrystr, keyword-only, optional

The two-letter country code for the store you want to search. -The search uses the default store front for the specified -country.

-
-

See also

-

For a list of ISO country codes, see the -ISO OBP.

-
-

Default: "US".

-
-
mediastr, keyword-only, optional

The media type you want to search for.

-
-

Valid values: "movie", "podcast", -"music", "musicVideo", "audioBook", -"shortFilm", "tvShow", "software", -and "ebook".

-
-

Default: "all".

-
-
entitystr or list, keyword-only, optional

The type(s) of results you want returned, relative to the -specified media type in media.

-
-

See also

-

For a list of available -entities, see the iTunes Store API Table 2-1.

-
-

Default: The track entity associated with the specified -media type.

-

Example: "movieArtist" for a movie media type -search.

-
-
attributestr, keyword-only, optional

The attribute you want to search for in the stores, relative -to the specified media type (media).

-
-

See also

-

For a list of available -attributes, see the iTunes Store API Table 2-2.

-
-

Default: All attributes associated with the specified -media type.

-

Example: If you want to search for an artist by name, -specify entity="allArtist" and -attribute="allArtistTerm". Then, if you search for -term="maroon", iTunes returns “Maroon 5” in the -search results, instead of all artists who have ever -recorded a song with the word “maroon” in the title.

-
-
limitint or str, keyword-only, optional

The number of search results you want the iTunes Store to -return.

-

Valid values: limit must be between 1 and 200.

-

Default: 50.

-
-
langstr, keyword-only, optional

The language, English or Japanese, you want to use when -returning search results. Specify the language using the -five-letter codename.

-
-

Valid values:

-
    -

  • "en_us" for English.

    • -

  • "ja_jp" for Japanese.

    • -
-
-

Default: "en_us".

-
-
versionint or str, keyword-only, optional

The search result key version you want to receive back from -your search.

-

Valid values: 1 and 2.

-

Default: 2.

-
-
explicitbool or str, keyword-only, optional

A flag indicating whether or not you want to include -explicit content in your search results.

-

Default: "Yes".

-
-
-
-
Returns:
-
-
resultsdict

The search results.

-
-

Sample response

-
{
-  "resultCount": <int>,
-  "results": [
-    {
-      "wrapperType": <str>,
-      "kind": <str>,
-      "artistId": <int>,
-      "collectionId": <int>,
-      "trackId": <int>,
-      "artistName": <str>,
-      "collectionName": <str>,
-      "trackName": <str>,
-      "collectionCensoredName": <str>,
-      "trackCensoredName": <str>,
-      "collectionArtistId": <int>,
-      "collectionArtistName": <str>,
-      "artistViewUrl": <str>,
-      "collectionViewUrl": <str>,
-      "trackViewUrl": <str>,
-      "previewUrl": <str>,
-      "artworkUrl30": <str>,
-      "artworkUrl60": <str>,
-      "artworkUrl100": <str>,
-      "collectionPrice": <float>,
-      "trackPrice": <float>,
-      "releaseDate": <str>,
-      "collectionExplicitness": <str>,
-      "trackExplicitness": <str>,
-      "discCount": <int>,
-      "discNumber": <int>,
-      "trackCount": <int>,
-      "trackNumber": <int>,
-      "trackTimeMillis": <int>,
-      "country": <str>,
-      "currency": <str>,
-      "primaryGenreName": <str>,
-      "isStreamable": <bool>
-    }
-  ]
-}
-
-
-
-
-
-
-
-

Examples

-

To search for all Jack Johnson audio and video content (movies, -podcasts, music, music videos, audiobooks, short films, and TV -shows),

-
>>> itunes.search("jack johnson")
-
-
-

To search for all Jack Johnson audio and video content and -return only the first 25 items,

-
>>> itunes.search("jack johnson", limit=25)
-
-
-

To search for only Jack Johnson music videos,

-
>>> itunes.search("jack johnson", entity="musicVideo")
-
-
-

To search for all Jim Jones audio and video content and return -only the results from the Canada iTunes Store,

-
>>> itunes.search("jack johnson", country="ca")
-
-
-

To search for applications titled “Yelp” and return only the -results from the United States iTunes Store,

-
>>> itunes.search("yelp", country="us", entity="software")
-
-
-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.itunes.html b/docs/api/minim.itunes.html deleted file mode 100644 index 062c5358..00000000 --- a/docs/api/minim.itunes.html +++ /dev/null @@ -1,345 +0,0 @@ - - - - - - - - - itunes - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

itunes#

-
-

iTunes#

-

This module contains a complete implementation of all iTunes Search API -endpoints.

-
-

Classes

-
- - - - - - -

SearchAPI

iTunes Search API client.

-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.qobuz.PrivateAPI.html b/docs/api/minim.qobuz.PrivateAPI.html deleted file mode 100644 index 33b1525a..00000000 --- a/docs/api/minim.qobuz.PrivateAPI.html +++ /dev/null @@ -1,2823 +0,0 @@ - - - - - - - - - PrivateAPI - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

PrivateAPI#

-
-
-class minim.qobuz.PrivateAPI(*, app_id: str = None, app_secret: str = None, flow: str = None, browser: bool = False, user_agent: str = None, email: str = None, password: str = None, auth_token: str = None, overwrite: bool = False, save: bool = True)[source]#
-

Bases: object

-

Private Qobuz API client.

-

The private TIDAL API allows songs, collections (albums, playlists), -and performers to be queried, and information about them to be -retrieved. As there is no available official documentation for the -private Qobuz API, its endpoints have been determined by watching -HTTP network traffic.

-
-

Attention

-

As the private Qobuz API is not designed to be publicly -accessible, this class can be disabled or removed at any time to -ensure compliance with the Qobuz API Terms of Use.

-
-

While authentication is not necessary to search for and retrieve -data from public content, it is required to access personal content -and stream media (with an active Qobuz subscription). In the latter -case, requests to the private Qobuz API endpoints must be -accompanied by a valid user authentication token in the header.

-

Minim can obtain user authentication tokens via the password grant, -but it is an inherently unsafe method of authentication since it has -no mechanisms for multifactor authentication or brute force attack -detection. As such, it is highly encouraged that you obtain a user -authentication token yourself through the Qobuz Web Player or the -Android, iOS, macOS, and Windows applications, and then provide it -and its accompanying app ID and secret to this class’s constructor -as keyword arguments. The app credentials can also be stored as -QOBUZ_PRIVATE_APP_ID and QOBUZ_PRIVATE_APP_SECRET -in the operating system’s environment variables, and they will -automatically be retrieved.

-
-

Tip

-

The app credentials and user authentication token can be changed -or updated at any time using set_flow() and -set_auth_token(), respectively.

-
-

Minim also stores and manages user authentication tokens and their -properties. When the password grant is used to acquire a user -authentication token, it is automatically saved to the Minim -configuration file to be loaded on the next instantiation of this -class. This behavior can be disabled if there are any security -concerns, like if the computer being used is a shared device.

-
-
Parameters:
-
-
app_idstr, keyword-only, optional

App ID. Required if an user authentication token is provided in -auth_token.

-
-
app_secretstr, keyword-only, optional

App secret. Required if an user authentication token is provided -in auth_token.

-
-
flowstr, keyword-only, optional

Authorization flow.

-
-

Valid values:

-
    -

  • "password" for the password flow.

    • -

  • None for no authentication.

    • -
-
-
-
browserbool, keyword-only, default: False

Determines whether a web browser is opened with the Qobuz login -page using the Playwright framework by Microsoft to complete the -password flow. If False, the account email and password -must be provided in email and password, respectively.

-
-
user_agentstr, keyword-only, optional

User agent information to send in the header of HTTP requests.

-
-
emailstr, keyword-only, optional

Account email address. Required if an user authentication token -is not provided in auth_token and browser=False.

-
-
passwordstr, keyword-only, optional

Account password. Required if an user authentication token is -not provided in auth_token and browser=False.

-
-
auth_tokenstr, keyword-only, optional

User authentication token. If provided here or found in the -Minim configuration file, the authentication process is -bypassed.

-
-
overwritebool, keyword-only, default: False

Determines whether to overwrite an existing user authentication -token in the Minim configuration file.

-
-
savebool, keyword-only, default: True

Determines whether newly obtained user authentication tokens and -their associated properties are stored to the Minim -configuration file.

-
-
-
-
Attributes:
-
-
API_URLstr

URL for the Qobuz API.

-
-
WEB_URLstr

URL for the Qobuz Web Player.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

add_playlist_tracks

Add tracks to a user playlist.

create_playlist

Create a user playlist.

delete_playlist

Delete a user playlist.

delete_playlist_tracks

Delete tracks from a user playlist.

favorite_items

Favorite albums, artists, and/or tracks.

favorite_playlist

Subscribe to a playlist.

get_album

Get Qobuz catalog information for a single album.

get_artist

Get Qobuz catalog information for a single artist.

get_collection_streams

Get audio stream data for all tracks in an album or a playlist.

get_curated_tracks

Get weekly curated tracks for the user.

get_favorites

Get the current user's favorite albums, artists, and tracks.

get_featured_albums

Get Qobuz catalog information for featured albums.

get_featured_playlists

Get Qobuz catalog information for featured playlists.

get_label

Get Qobuz catalog information for a record label.

get_playlist

Get Qobuz catalog information for a playlist.

get_profile

Get the current user's profile information.

get_purchases

Get the current user's purchases.

get_track

Get Qobuz catalog information for a track.

get_track_file_url

Get the file URL for a track.

get_track_performers

Get credits for a track.

get_track_stream

Get the audio stream data for a track.

get_user_playlists

Get the current user's custom and favorite playlists.

move_playlist_tracks

Move tracks in a user playlist.

search

Search Qobuz for media and performers.

set_auth_token

Set the private Qobuz API user authentication token.

set_flow

Set the authorization flow.

unfavorite_items

Unfavorite albums, artists, and/or tracks.

unfavorite_playlist

Unsubscribe from a playlist.

update_playlist

Update the title, description, and/or privacy of a playlist owned by the current user.

update_playlist_position

Organize a user's playlists.

-
-
-
-add_playlist_tracks(playlist_id: int | str, track_ids: int | str | list[int | str], *, duplicate: bool = False) → dict[str, Any][source]#
-

Add tracks to a user playlist.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
playlist_idint or str

Qobuz user playlist ID.

-

Example: 17737508.

-
-
track_idsint, str, or list

Qobuz track ID(s).

-

Examples: "24393122,24393138" or -[24393122, 24393138].

-
-
duplicatebool, keyword-only, default: False

Determines whether duplicate tracks should be added to the -playlist.

-
-
-
-
Returns:
-
-
playliststr

Qobuz catalog information for the updated playlist.

-
-

Sample response

-
{
-  "id": <int>,
-  "name": <str>,
-  "description": <str>,
-  "tracks_count": <int>,
-  "users_count": <int>,
-  "duration": <int>,
-  "public_at": <int>,
-  "created_at": <int>,
-  "updated_at": <int>,
-  "is_public": <bool>,
-  "is_collaborative": <bool>,
-  "owner": {
-    "id": <int>,
-    "name": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-create_playlist(name: str, *, description: str = None, public: bool = True, collaborative: bool = False) → dict[str, Any][source]#
-

Create a user playlist.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
namestr

Qobuz playlist name.

-
-
descriptionstr, keyword-only, optional

Brief playlist description.

-
-
publicbool, keyword-only, default: True

Determines whether the playlist is public (True) or -private (False).

-
-
collaborativebool, keyword-only, default: False

Determines whether the playlist is collaborative.

-
-
-
-
Returns:
-
-
playliststr

Qobuz catalog information for the newly created playlist.

-
-

Sample response

-
{
-  "id": <int>,
-  "name": <str>,
-  "description": <str>,
-  "tracks_count": <int>,
-  "users_count": <int>,
-  "duration": <int>,
-  "public_at": <int>,
-  "created_at": <int>,
-  "updated_at": <int>,
-  "is_public": <bool>,
-  "is_collaborative": <bool>,
-  "owner": {
-    "id": <int>,
-    "name": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-delete_playlist(playlist_id: int | str) → None[source]#
-

Delete a user playlist.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
playlist_idint or str

Qobuz user playlist ID.

-

Example: 17737508.

-
-
-
-
-
- -
-
-delete_playlist_tracks(playlist_id: int | str, playlist_track_ids: int | str | list[int | str]) → dict[str, Any][source]#
-

Delete tracks from a user playlist.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
playlist_idint or str

Qobuz user playlist ID.

-

Example: 17737508.

-
-
playlist_track_idsint, str, or list

Qobuz playlist track ID(s).

-
-

Note

-

Playlist track IDs are not the same as track IDs. To get -playlist track IDs, use get_playlist().

-
-
-
-
-
Returns:
-
-
playliststr

Qobuz catalog information for the updated playlist.

-
-

Sample response

-
{
-  "id": <int>,
-  "name": <str>,
-  "description": <str>,
-  "tracks_count": <int>,
-  "users_count": <int>,
-  "duration": <int>,
-  "public_at": <int>,
-  "created_at": <int>,
-  "updated_at": <int>,
-  "is_public": <bool>,
-  "is_collaborative": <bool>,
-  "owner": {
-    "id": <int>,
-    "name": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-favorite_items(*, album_ids: str | list[str] = None, artist_ids: int | str | list[int | str] = None, track_ids: int | str | list[int | str] = None) → None[source]#
-

Favorite albums, artists, and/or tracks.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-

See also

-

For playlists, use favorite_playlist().

-
-
-
Parameters:
-
-
album_idsstr or list, keyword-only, optional

Qobuz album ID(s).

-
-
artist_idsint, str, or list, keyword-only, optional

Qobuz artist ID(s).

-
-
track_idsint, str, or list, keyword-only, optional

Qobuz track ID(s).

-
-
-
-
-
- -
-
-favorite_playlist(playlist_id: int | str) → None[source]#
-

Subscribe to a playlist.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
playlist_idint or str

Qobuz playlist ID.

-

Example: 15732665.

-
-
-
-
-
- -
-
-get_album(album_id: str) → dict[str, Any][source]#
-

Get Qobuz catalog information for a single album.

-
-
Parameters:
-
-
album_idstr

Qobuz album ID.

-

Example: "0060254735180".

-
-
-
-
Returns:
-
-
albumdict

Qobuz catalog information for a single album.

-
-

Sample response

-
{
-  "maximum_bit_depth": <int>,
-  "image": {
-    "small": <str>,
-    "thumbnail": <str>,
-    "large": <str>,
-    "back": <str>
-  },
-  "media_count": <str>,
-  "artist": {
-    "image": <str>,
-    "name": <str>,
-    "id": <int>,
-    "albums_count": <int>,
-    "slug": <str>,
-    "picture": <str>
-  },
-  "artists": [
-    {
-      "id": <int>,
-      "name": <str>,
-      "roles": [<str>]
-    }
-  ],
-  "upc": <str>,
-  "released_at": <int>,
-  "label": {
-    "name": <str>,
-    "id": <int>,
-    "albums_count": <int>,
-    "supplier_id": <int>,
-    "slug": <str>
-  },
-  "title": <str>,
-  "qobuz_id": <int>,
-  "version": <str>,
-  "url": <str>,
-  "duration": <int>,
-  "parental_warning": <bool>,
-  "popularity": <int>,
-  "tracks_count": <int>,
-  "genre": {
-    "path": [<int>],
-    "color": <str>,
-    "name": <str>,
-    "id": <int>,
-    "slug": <str>
-  },
-  "maximum_channel_count": <int>,
-  "id": <str>,
-  "maximum_sampling_rate": <int>,
-  "articles": <list>,
-  "release_date_original": <str>,
-  "release_date_download": <str>,
-  "release_date_stream": <str>,
-  "purchasable": <bool>,
-  "streamable": <bool>,
-  "previewable": <bool>,
-  "sampleable": <bool>,
-  "downloadable": <bool>,
-  "displayable": <bool>,
-  "purchasable_at": <int>,
-  "streamable_at": <int>,
-  "hires": <bool>,
-  "hires_streamable": <bool>,
-  "awards": <list>,
-  "description": <str>,
-  "description_language": <str>,
-  "goodies": <list>,
-  "area": <str>,
-  "catchline": <str>,
-  "composer": {
-    "id": <int>,
-    "name": <str>,
-    "slug": <str>,
-    "albums_count": <int>,
-    "picture": <str>,
-    "image": <str>
-  },
-  "created_at": <int>,
-  "genres_list": [<str>],
-  "period": <str>,
-  "copyright": <str>,
-  "is_official": <bool>,
-  "maximum_technical_specifications": <str>,
-  "product_sales_factors_monthly": <int>,
-  "product_sales_factors_weekly": <int>,
-  "product_sales_factors_yearly": <int>,
-  "product_type": <str>,
-  "product_url": <str>,
-  "recording_information": <str>,
-  "relative_url": <str>,
-  "release_tags": <list>,
-  "release_type": <str>,
-  "slug": <str>,
-  "subtitle": <str>,
-  "tracks": {
-    "offset": <int>,
-    "limit": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "maximum_bit_depth": <int>,
-        "copyright": <str>,
-        "performers": <str>,
-        "audio_info": {
-          "replaygain_track_peak": <float>,
-          "replaygain_track_gain": <float>
-        },
-        "performer": {
-          "name": <str>,
-          "id": <int>
-        },
-        "work": <str>,
-        "composer": {
-          "name": <str>,
-          "id": <int>
-        },
-        "isrc": <str>,
-        "title": <str>,
-        "version": <str>,
-        "duration": <int>,
-        "parental_warning": <bool>,
-        "track_number": <int>,
-        "maximum_channel_count": <int>,
-        "id": <int>,
-        "media_number": <int>,
-        "maximum_sampling_rate": <int>,
-        "release_date_original": <str>,
-        "release_date_download": <str>,
-        "release_date_stream": <str>,
-        "release_date_purchase": <str>,
-        "purchasable": <bool>,
-        "streamable": <bool>,
-        "previewable": <bool>,
-        "sampleable": <bool>,
-        "downloadable": <bool>,
-        "displayable": <bool>,
-        "purchasable_at": <int>,
-        "streamable_at": <int>,
-        "hires": <bool>,
-        "hires_streamable": <bool>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist(artist_id: int | str, *, extras: str | list[str] = None, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get Qobuz catalog information for a single artist.

-
-
Parameters:
-
-
artist_idint or str

Qobuz artist ID.

-
-
extrasstr or list, keyword-only, optional

Specifies extra information about the artist to return.

-

Valid values: "albums", "tracks", -"playlists", "tracks_appears_on", and -"albums_with_last_release".

-
-
limitint, keyword-only, optional

The maximum number of extra items to return. Has no effect -if extras=None.

-

Default: 25.

-
-
offsetint, keyword-only, optional

The index of the first extra item to return. Use with -limit to get the next page of extra items. Has no effect -if extras=None.

-

Default: 0.

-
-
-
-
Returns:
-
-
artistdict

Qobuz catalog information for a single artist.

-
-

Sample response

-
{
-  "id": <int>,
-  "name": <str>,
-  "albums_as_primary_artist_count": <int>,
-  "albums_as_primary_composer_count": <int>,
-  "albums_count": <int>,
-  "slug": <str>,
-  "picture": <str>,
-  "image": {
-    "small": <str>,
-    "medium": <str>,
-    "large": <str>,
-    "extralarge": <str>,
-    "mega": <str>
-  },
-  "similar_artist_ids": [<int>],
-  "information": <str>,
-  "biography": {
-    "summary": <str>,
-    "content": <str>,
-    "source": <str>,
-    "language": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_collection_streams(id: int | str, type: str, *, format_id: int | str = 27) → list[tuple[bytes, str]][source]#
-

Get audio stream data for all tracks in an album or a playlist.

-
-

Subscription

-

Full track playback information and lossless and Hi-Res audio -is only available with an active Qobuz subscription.

-
-
-

Note

-

This method is provided for convenience and is not a private -Qobuz API endpoint.

-
-
-
Parameters:
-
-
idint or str

Qobuz collection ID.

-
-
typestr

Collection type.

-

Valid values: "album" and "playlist".

-
-
format_idint, default: 27

Audio format ID that determines the maximum audio quality.

-
-

Valid values:

-
    -

  • 5 for constant bitrate (320 kbps) MP3.

    • -

  • 6 for CD-quality (16-bit, 44.1 kHz) FLAC.

    • -

  • 7 for up to 24-bit, 96 kHz Hi-Res FLAC.

    • -

  • 27 for up to 24-bit, 192 kHz Hi-Res FLAC.

    • -
-
-
-
-
-
Returns:
-
-
streamslist

Audio stream data.

-
-
-
-
-
- -
-
-get_curated_tracks() → list[dict[str, Any]][source]#
-

Get weekly curated tracks for the user.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of tracks to return.

-

Default: 50.

-
-
offsetint, keyword-only, optional

The index of the first track to return. Use with limit -to get the next page of tracks.

-

Default: 0.

-
-
-
-
Returns:
-
-
trackslist

Qobuz catalog information for the curated tracks.

-
-

Sample response

-
{
-  "title": <str>,
-  "baseline": <str>,
-  "description": <str>,
-  "type": "weekly",
-  "step_pagination": <int>,
-  "images": {
-    "small": <str>,
-    "large": <str>
-  },
-  "graphics": {
-    "background": <str>,
-    "foreground": <str>
-  },
-  "duration": <int>,
-  "generated_at": <int>,
-  "expires_on": <int>,
-  "track_count": <int>,
-  "tracks": {
-    "offset": <int>,
-    "limit": <int>,
-    "items": [
-      {
-        "maximum_bit_depth": <int>,
-        "copyright": <str>,
-        "performers": <str>,
-        "audio_info": {
-          "replaygain_track_peak": <float>,
-          "replaygain_track_gain": <float>
-        },
-        "performer": {
-          "name": <str>,
-          "id": <int>
-        },
-        "album": {
-          "image": {
-            "small": <str>,
-            "thumbnail": <str>,
-            "large": <str>
-          },
-          "maximum_bit_depth": <int>,
-          "media_count": <int>,
-          "artist": {
-            "image": <str>,
-            "name": <str>,
-            "id": <int>,
-            "albums_count": <int>,
-            "slug":<str>,
-            "picture": <str>
-          },
-          "upc": <str>,
-          "released_at": <int>,
-          "label": {
-            "name": <str>,
-            "id": <int>,
-            "albums_count": <int>,
-            "supplier_id": <int>,
-            "slug": <str>
-          },
-          "title": <str>,
-          "qobuz_id": <int>,
-          "version": <str>,
-          "duration": <int>,
-          "parental_warning": <bool>,
-          "tracks_count": <int>,
-          "popularity": <int>,
-          "genre": {
-            "path": [<int>],
-            "color": <str>,
-            "name": <str>,
-            "id": <int>,
-            "slug": <str>
-          },
-          "maximum_channel_count": <int>,
-          "id": <str>,
-          "maximum_sampling_rate": <int>,
-          "previewable": <bool>,
-          "sampleable": <bool>,
-          "displayable": <bool>,
-          "streamable": <bool>,
-          "streamable_at": <int>,
-          "downloadable": <bool>,
-          "purchasable_at": <int>,
-          "purchasable": <bool>,
-          "release_date_original": <str>,
-          "release_date_download": <str>,
-          "release_date_stream": <str>,
-          "release_date_purchase": <str>,
-          "hires": <bool>,
-          "hires_streamable": <bool>
-        },
-        "work": <str>,
-        "composer": {
-          "name": <str>,
-          "id": <int>
-        },
-        "isrc": <str>,
-        "title": <str>,
-        "version": <str>,
-        "duration": <int>,
-        "parental_warning": <bool>,
-        "track_number": <int>,
-        "maximum_channel_count": <int>,
-        "id": <int>,
-        "media_number": <int>,
-        "maximum_sampling_rate": <int>,
-        "release_date_original": <str>,
-        "release_date_download": <str>,
-        "release_date_stream": <str>,
-        "release_date_purchase": <str>,
-        "purchasable": <bool>,
-        "streamable": <bool>,
-        "previewable": <bool>,
-        "sampleable": <bool>,
-        "downloadable": <bool>,
-        "displayable": <bool>,
-        "purchasable_at": <int>,
-        "streamable_at": <int>,
-        "hires": <bool>,
-        "hires_streamable": <bool>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_favorites(type: str = None, *, limit: int = None, offset: int = None) → dict[str, dict][source]#
-

Get the current user’s favorite albums, artists, and tracks.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
typestr

Media type to return. If not specified, all of the user’s -favorite items are returned.

-
-

Valid values: "albums", "artists", -and "tracks".

-
-
-
limitint, keyword-only, optional

The maximum number of favorited items to return.

-

Default: 50.

-
-
offsetint, keyword-only, optional

The index of the first favorited item to return. Use with -limit to get the next page of favorited items.

-

Default: 0.

-
-
-
-
Returns:
-
-
favoritesdict

A dictionary containing Qobuz catalog information for the -current user’s favorite items and the user’s ID and email.

-
-

Sample response

-
{
-  "albums": {
-    "offset": <int>,
-    "limit": <int>,
-    "total": <int>,
-    "items": <list>
-  },
-  "user": {
-    "id": <int>,
-    "login": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
- -

Get Qobuz catalog information for featured albums.

-
-
Parameters:
-
-
typestr, default: "new-releases"

Feature type.

-

Valid values: "best-sellers", -"editor-picks", "ideal-discography", -"most-featured", "most-streamed", -"new-releases", "new-releases-full", -"press-awards", "recent-releases", -"qobuzissims", "harmonia-mundi", -"universal-classic", "universal-jazz", -"universal-jeunesse", and -"universal-chanson".

-
-
limitint, keyword-only, optional

The maximum number of albums to return.

-

Default: 50.

-
-
offsetint, keyword-only, optional

The index of the first album to return. Use with limit to -get the next page of albums.

-

Default: 0.

-
-
-
-
Returns:
-
-
albumsdict

Qobuz catalog information for the albums.

-
-

Sample response

-
{
-  "albums": {
-    "total": <int>,
-    "limit": <int>,
-    "offset": <int>,
-    "items": [
-      {
-        "maximum_bit_depth": <int>,
-        "image": {
-          "small": <str>,
-          "thumbnail": <str>,
-          "large": <str>,
-          "back": <str>
-        },
-        "media_count": <str>,
-        "artist": {
-          "image": <str>,
-          "name": <str>,
-          "id": <int>,
-          "albums_count": <int>,
-          "slug": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "roles": [<str>]
-          }
-        ],
-        "upc": <str>,
-        "released_at": <int>,
-        "label": {
-          "name": <str>,
-          "id": <int>,
-          "albums_count": <int>,
-          "supplier_id": <int>,
-          "slug": <str>
-        },
-        "title": <str>,
-        "qobuz_id": <int>,
-        "version": <str>,
-        "url": <str>,
-        "duration": <int>,
-        "parental_warning": <bool>,
-        "popularity": <int>,
-        "tracks_count": <int>,
-        "genre": {
-          "path": [<int>],
-          "color": <str>,
-          "name": <str>,
-          "id": <int>,
-          "slug": <str>
-        },
-        "maximum_channel_count": <int>,
-        "id": <str>,
-        "maximum_sampling_rate": <int>,
-        "articles": <list>,
-        "release_date_original": <str>,
-        "release_date_download": <str>,
-        "release_date_stream": <str>,
-        "purchasable": <bool>,
-        "streamable": <bool>,
-        "previewable": <bool>,
-        "sampleable": <bool>,
-        "downloadable": <bool>,
-        "displayable": <bool>,
-        "purchasable_at": <int>,
-        "streamable_at": <int>,
-        "hires": <bool>,
-        "hires_streamable": <bool>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
- -

Get Qobuz catalog information for featured playlists.

-
-
Parameters:
-
-
typestr, default: "editor-picks"

Feature type.

-

Valid values: "editor-picks" and -"last-created".

-
-
limitint, keyword-only, optional

The maximum number of playlists to return.

-

Default: 50.

-
-
offsetint, keyword-only, optional

The index of the first playlist to return. Use with limit -to get the next page of playlists.

-

Default: 0.

-
-
-
-
Returns:
-
-
playlistsdict

Qobuz catalog information for the playlists.

-
-

Sample response

-
{
-  "offset": <int>,
-  "limit": <int>,
-  "total": <int>,
-  "items": [
-    {
-      "owner": {
-        "name": <str>,
-        "id": <int>
-      },
-      "image_rectangle_mini": [<str>],
-      "users_count": <int>,
-      "images150": [<str>],
-      "images": [<str>],
-      "featured_artists": <list>,
-      "is_collaborative": <bool>,
-      "stores": [<str>],
-      "description": <str>,
-      "created_at": <int>,
-      "images300": [<str>],
-      "tags": [
-        {
-          "color": <str>,
-          "is_discover": <bool>,
-          "featured_tag_id": <str>,
-          "name_json": <str>,
-          "slug": <str>,
-          "genre_tag": <str>
-        }
-      ],
-      "duration": <int>,
-      "updated_at": <int>,
-      "genres": [
-        {
-          "path": [<int>],
-          "color": <str>,
-          "name": <str>,
-          "id": <int>,
-          "percent": <float>,
-          "slug": <str>
-        }
-      ],
-      "image_rectangle": [<str>],
-      "tracks_count": <int>,
-      "public_at": <int>,
-      "name": <str>,
-      "is_public": <bool>,
-      "id": <int>,
-      "slug": <str>,
-      "is_featured": <bool>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_label(label_id: int | str, *, albums: bool = False, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get Qobuz catalog information for a record label.

-
-
Parameters:
-
-
label_idint or str

Qobuz record label ID.

-

Example: 1153.

-
-
albumsbool, keyword-only, default: False

Specifies whether information on the albums released by the -record label is returned.

-
-
limitint, keyword-only, optional

The maximum number of albums to return. Has no effect if -albums=False.

-

Default: 25.

-
-
offsetint, keyword-only, optional

The index of the first album to return. Use with limit to -get the next page of albums. Has no effect if -albums=False.

-

Default: 0.

-
-
-
-
Returns:
-
-
labeldict

Qobuz catalog information for the record label.

-
-

Sample response

-
{
-  "id": <int>,
-  "name": <str>,
-  "slug": <str>,
-  "supplier_id": <int>,
-  "albums_count": <int>,
-  "image": <str>,
-  "description": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_playlist(playlist_id: int | str, *, tracks: bool = True, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get Qobuz catalog information for a playlist.

-
-
Parameters:
-
-
playlist_idint or str

Qobuz playlist ID.

-

Example: 15732665.

-
-
tracksbool, keyword-only, default: True

Specifies whether information on the tracks in the playlist -is returned.

-
-
limitint, keyword-only, optional

The maximum number of tracks to return. Has no effect if -tracks=False.

-

Default: 50.

-
-
offsetint, keyword-only, optional

The index of the first track to return. Use with limit to -get the next page of tracks. Has no effect if -tracks=False.

-

Default: 0.

-
-
-
-
Returns:
-
-
playlistdict

Qobuz catalog information for the playlist.

-
-

Sample response

-
{
-  "image_rectangle_mini": [<str>],
-  "featured_artists": <list>,
-  "description": <str>,
-  "created_at": <int>,
-  "timestamp_position": <int>,
-  "images300": [<str>],
-  "duration": <int>,
-  "updated_at": <int>,
-  "genres": [
-    {
-      "id": <int>,
-      "color": <str>,
-      "name": <str>,
-      "path": [<int>],
-      "slug": <str>,
-      "percent": <float>
-    }
-  ],
-  "image_rectangle": [<str>],
-  "id": <int>,
-  "slug": <str>,
-  "owner": {
-    "id": <int>,
-    "name": <str>
-  },
-  "users_count": <int>,
-  "images150": [<str>],
-  "images": [<str>],
-  "is_collaborative": <bool>,
-  "stores": [<str>],
-  "tags": [
-    {
-      "featured_tag_id": <str>,
-      "name_json": <str>,
-      "slug": <str>,
-      "color": <str>,
-      "genre_tag": <str>,
-      "is_discover": <bool>
-    }
-  ],
-  "tracks_count": <int>,
-  "public_at": <int>,
-  "name": <str>,
-  "is_public": <bool>,
-  "is_featured": <bool>,
-  "tracks": {
-    "offset": <int>,
-    "limit": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "maximum_bit_depth": <int>,
-        "copyright": <str>,
-        "performers": <str>,
-        "audio_info": {
-          "replaygain_track_peak": <float>,
-          "replaygain_track_gain": <float>
-        },
-        "performer": {
-          "name": <str>,
-          "id": <int>
-        },
-        "album": {
-          "image": {
-            "small": <str>,
-            "thumbnail": <str>,
-            "large": <str>
-          },
-          "maximum_bit_depth": <int>,
-          "media_count": <int>,
-          "artist": {
-            "image": <str>,
-            "name": <str>,
-            "id": <int>,
-            "albums_count": <int>,
-            "slug": <str>,
-            "picture": <str>
-          },
-          "upc": <str>,
-          "released_at": <int>,
-          "label": {
-            "name": <str>,
-            "id": <int>,
-            "albums_count": <int>,
-            "supplier_id": <int>,
-            "slug": <str>
-          },
-          "title": <str>,
-          "qobuz_id": <int>,
-          "version": <str>,
-          "duration": <int>,
-          "parental_warning": <bool>,
-          "tracks_count": <int>,
-          "popularity": <int>,
-          "genre": {
-            "path": [<int>],
-            "color": <str>,
-            "name": <str>,
-            "id": <int>,
-            "slug": <str>
-          },
-          "maximum_channel_count": <int>,
-          "id": <str>,
-          "maximum_sampling_rate": <int>,
-          "previewable": <bool>,
-          "sampleable": <bool>,
-          "displayable": <bool>,
-          "streamable": <bool>,
-          "streamable_at": <int>,
-          "downloadable": <bool>,
-          "purchasable_at": <int>,
-          "purchasable": <bool>,
-          "release_date_original": <str>,
-          "release_date_download": <str>,
-          "release_date_stream": <str>,
-          "release_date_purchase": <str>,
-          "hires": <bool>,
-          "hires_streamable": <bool>
-        },
-        "work": <str>,
-        "isrc": <str>,
-        "title": <str>,
-        "version": null,
-        "duration": <int>,
-        "parental_warning": <bool>,
-        "track_number": <int>,
-        "maximum_channel_count": <int>,
-        "id": <int>,
-        "media_number": <int>,
-        "maximum_sampling_rate": <int>,
-        "release_date_original": <str>,
-        "release_date_download": <str>,
-        "release_date_stream": <str>,
-        "release_date_purchase": <str>,
-        "purchasable": <bool>,
-        "streamable": <bool>,
-        "previewable": <bool>,
-        "sampleable": <bool>,
-        "downloadable": <bool>,
-        "displayable": <bool>,
-        "purchasable_at": <int>,
-        "streamable_at": <int>,
-        "hires": <bool>,
-        "hires_streamable": <bool>,
-        "position": <int>,
-        "created_at": <int>,
-        "playlist_track_id": <int>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_profile() → dict[str, Any][source]#
-

Get the current user’s profile information.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Returns:
-
-
profiledict

A dictionary containing the current user’s profile -information.

-
-

Sample response

-
{
-  "id": <int>,
-  "publicId": <str>,
-  "email": <str>,
-  "login": <str>,
-  "firstname": <str>,
-  "lastname": <str>,
-  "display_name": <str>,
-  "country_code": <str>,
-  "language_code": <str>,
-  "zone": <str>,
-  "store": <str>,
-  "country": <str>,
-  "avatar": <str>,
-  "genre": <str>,
-  "age": <int>,
-  "creation_date": <str>,
-  "subscription": {
-    "offer": <str>,
-    "periodicity": <str>,
-    "start_date": <str>,
-    "end_date": <str>,
-    "is_canceled": <bool>,
-    "household_size_max": <int>
-  },
-  "credential": {
-    "id": <int>,
-    "label": <str>,
-    "description": <str>,
-    "parameters": {
-      "lossy_streaming": <bool>,
-      "lossless_streaming": <bool>,
-      "hires_streaming": <bool>,
-      "hires_purchases_streaming": <bool>,
-      "mobile_streaming": <bool>,
-      "offline_streaming": <bool>,
-      "hfp_purchase": <bool>,
-      "included_format_group_ids": [<int>],
-      "color_scheme": {
-        "logo": <str>
-      },
-      "label": <str>,
-      "short_label": <str>,
-      "source": <str>
-    }
-  },
-  "last_update": {
-    "favorite": <int>,
-    "favorite_album": <int>,
-    "favorite_artist": <int>,
-    "favorite_track": <int>,
-    "playlist": <int>,
-    "purchase": <int>
-  },
-  "store_features": {
-    "download": <bool>,
-    "streaming": <bool>,
-    "editorial": <bool>,
-    "club": <bool>,
-    "wallet": <bool>,
-    "weeklyq": <bool>,
-    "autoplay": <bool>,
-    "inapp_purchase_subscripton": <bool>,
-    "opt_in": <bool>,
-    "music_import": <bool>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_purchases(type: str = 'albums', *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get the current user’s purchases.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
typestr, default: "albums"

Media type.

-

Valid values: "albums" and "tracks".

-
-
limitint, keyword-only, optional

The maximum number of albums or tracks to return.

-

Default: 50.

-
-
offsetint, keyword-only, optional

The index of the first album or track to return. Use with -limit to get the next page of albums or tracks.

-

Default: 0.

-
-
-
-
Returns:
-
-
purchasesdict

A dictionary containing Qobuz catalog information for the -current user’s purchases.

-
-

Sample response

-
{
-  "offset": <int>,
-  "limit": <int>,
-  "total": <int>,
-  "items": <list>
-}
-
-
-
-
-
-
-
-
- -
-
-get_track(track_id: int | str) → dict[str, Any][source]#
-

Get Qobuz catalog information for a track.

-
-
Parameters:
-
-
track_idint or str

Qobuz track ID.

-

Example: 24393138.

-
-
-
-
Returns:
-
-
trackdict

Qobuz catalog information for the track.

-
-

Sample response

-
{
-  "maximum_bit_depth": <int>,
-  "copyright": <str>,
-  "performers": <str>,
-  "audio_info": {
-    "replaygain_track_gain": <float>,
-    "replaygain_track_peak": <float>
-  },
-  "performer": {
-    "id": <int>,
-    "name": <str>
-  },
-  "album": {
-    "maximum_bit_depth": <int>,
-    "image": {
-      "small": <str>,
-      "thumbnail": <str>,
-      "large": <str>,
-      "back": <str>
-    },
-    "media_count": <int>,
-    "artist": {
-      "image": <str>,
-      "name": <str>,
-      "id": <int>,
-      "albums_count": <int>,
-      "slug": <str>,
-      "picture": <str>
-    },
-    "artists": [
-      {
-        "id": <int>,
-        "name": <str>,
-        "roles": [<str>]
-      }
-    ],
-    "upc": <str>,
-    "released_at": <int>,
-    "label": {
-      "name": <str>,
-      "id": <int>,
-      "albums_count": <int>,
-      "supplier_id": <int>,
-      "slug": <str>
-    },
-    "title": <str>,
-    "qobuz_id": <int>,
-    "version": <str>,
-    "url": <str>,
-    "duration": <int>,
-    "parental_warning": <bool>,
-    "popularity": <int>,
-    "tracks_count": <int>,
-    "genre": {
-      "path": [<int>],
-      "color": <str>,
-      "name": <str>,
-      "id": <int>,
-      "slug": <str>
-    },
-    "maximum_channel_count": <int>,
-    "id": <str>,
-    "maximum_sampling_rate": <int>,
-    "articles": <list>,
-    "release_date_original": <str>,
-    "release_date_download": <str>,
-    "release_date_stream": <str>,
-    "purchasable": <bool>,
-    "streamable": <bool>,
-    "previewable": <bool>,
-    "sampleable": <bool>,
-    "downloadable": <bool>,
-    "displayable": <bool>,
-    "purchasable_at": <int>,
-    "streamable_at": <int>,
-    "hires": <bool>,
-    "hires_streamable": <bool>,
-    "awards": <list>,
-    "description": <str>,
-    "description_language": <str>,
-    "goodies": <list>,
-    "area": null,
-    "catchline": <str>,
-    "composer": {
-      "id": <int>,
-      "name": <str>,
-      "slug": <str>,
-      "albums_count": <int>,
-      "picture": <str>,
-      "image": <str>
-    },
-    "created_at": <int>,
-    "genres_list": [<str>],
-    "period": <str>,
-    "copyright": <str>,
-    "is_official": <bool>,
-    "maximum_technical_specifications": <str>,
-    "product_sales_factors_monthly": <int>,
-    "product_sales_factors_weekly": <int>,
-    "product_sales_factors_yearly": <int>,
-    "product_type": <str>,
-    "product_url": <str>,
-    "recording_information": <str>,
-    "relative_url": <str>,
-    "release_tags": <list>,
-    "release_type": <str>,
-    "slug": <str>,
-    "subtitle": <str>
-  },
-  "work": <str>,
-  "composer": {
-    "id": <int>,
-    "name": <str>
-  },
-  "isrc": <str>,
-  "title": <str>,
-  "version": <str>,
-  "duration": <int>,
-  "parental_warning": <bool>,
-  "track_number": <int>,
-  "maximum_channel_count": <int>,
-  "id": <int>,
-  "media_number": <int>,
-  "maximum_sampling_rate": <int>,
-  "articles": <list>,
-  "release_date_original": <str>,
-  "release_date_download": <str>,
-  "release_date_stream": <str>,
-  "release_date_purchase": <str>,
-  "purchasable": <bool>,
-  "streamable": <bool>,
-  "previewable": <bool>,
-  "sampleable": <bool>,
-  "downloadable": <bool>,
-  "displayable": <bool>,
-  "purchasable_at": <int>,
-  "streamable_at": <int>,
-  "hires": <bool>,
-  "hires_streamable": <bool>
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_file_url(track_id: int | str, format_id: int | str = 27) → dict[str, Any][source]#
-

Get the file URL for a track.

-
-

Subscription

-

Full track playback information and lossless and Hi-Res audio -is only available with an active Qobuz subscription.

-
-
-
Parameters:
-
-
track_idint or str

Qobuz track ID.

-

Example: 24393138.

-
-
format_idint or str, default: 27

Audio format ID that determines the maximum audio quality.

-
-

Valid values:

-
    -

  • 5 for constant bitrate (320 kbps) MP3.

    • -

  • 6 for CD-quality (16-bit, 44.1 kHz) FLAC.

    • -

  • 7 for up to 24-bit, 96 kHz Hi-Res FLAC.

    • -

  • 27 for up to 24-bit, 192 kHz Hi-Res FLAC.

    • -
-
-
-
-
-
Returns:
-
-
urldict

A dictionary containing the URL and track information, such -as the audio format, bit depth, etc.

-
-

Sample response

-
{
-  "track_id": <int>,
-  "duration": <int>,
-  "url": <str>,
-  "format_id": <int>,
-  "mime_type": <str>,
-  "restrictions": [
-    {
-      "code": <str>
-    }
-  ],
-  "sampling_rate": <int>,
-  "bit_depth": <int>
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_performers(track_id: int | str = None, *, performers: str = None, roles: list[str] | set[str] = None) → dict[str, list][source]#
-

Get credits for a track.

-
-

Note

-

This method is provided for convenience and is not a private -Qobuz API endpoint.

-
-
-
Parameters:
-
-
track_idint or str, optional

Qobuz track ID. Required if performers is not provided.

-

Example: 24393138.

-
-
performersstr, keyword-only, optional

An unformatted string containing the track credits obtained -from calling get_track().

-
-
roleslist or set, keyword-only, optional

Role filter. The special "Composers" filter will -combine the "Composer", "ComposerLyricist", -"Lyricist", and "Writer" roles.

-

Valid values: "MainArtist", -"FeaturedArtist", "Producer", -"Co-Producer", "Mixer", -"Composers" ("Composer", -"ComposerLyricist", "Lyricist", -"Writer"), "MusicPublisher", etc.

-
-
-
-
Returns:
-
-
creditsdict

A dictionary containing the track contributors, with their -roles (in snake case) being the keys.

-
-
-
-
-
- -
-
-get_track_stream(track_id: int | str, *, format_id: int | str = 27) → tuple[bytes, str][source]#
-

Get the audio stream data for a track.

-
-

Subscription

-

Full track playback information and lossless and Hi-Res audio -is only available with an active Qobuz subscription.

-
-
-

Note

-

This method is provided for convenience and is not a private -Qobuz API endpoint.

-
-
-
Parameters:
-
-
track_idint or str

Qobuz track ID.

-

Example: 24393138.

-
-
format_idint, default: 27

Audio format ID that determines the maximum audio quality.

-
-

Valid values:

-
    -

  • 5 for constant bitrate (320 kbps) MP3.

    • -

  • 6 for CD-quality (16-bit, 44.1 kHz) FLAC.

    • -

  • 7 for up to 24-bit, 96 kHz Hi-Res FLAC.

    • -

  • 27 for up to 24-bit, 192 kHz Hi-Res FLAC.

    • -
-
-
-
-
-
Returns:
-
-
streambytes

Audio stream data.

-
-
mime_typestr

Audio stream MIME type.

-
-
-
-
-
- -
-
-get_user_playlists(*, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get the current user’s custom and favorite playlists.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of playlists to return.

-

Default: 500.

-
-
offsetint, keyword-only, optional

The index of the first playlist to return. Use with limit -to get the next page of playlists.

-

Default: 0.

-
-
-
-
Returns:
-
-
playlistsdict

Qobuz catalog information for the current user’s custom and -favorite playlists.

-
-

Sample response

-
{
-  "offset": <int>,
-  "limit": <int>,
-  "total": <int>,
-  "items": [
-    {
-      "image_rectangle_mini": [<str>],
-      "is_published": <bool>,
-      "featured_artists": <list>,
-      "description": <str>,
-      "created_at": <int>,
-      "timestamp_position": <int>,
-      "images300": [<str>],
-      "duration": <int>,
-      "updated_at": <int>,
-      "published_to": <int>,
-      "genres": <list>,
-      "image_rectangle": [<str>],
-      "id": <int>,
-      "slug": <str>,
-      "owner": {
-        "id": <int>,
-        "name": <str>
-      },
-      "users_count": <int>,
-      "images150": [<str>],
-      "images": [<str>],
-      "is_collaborative": <bool>.
-      "stores": [<str>],
-      "tracks_count": <int>,
-      "public_at": <int>,
-      "name": "Welcome to Qobuz",
-      "is_public": <bool>,
-      "published_from": <int>,
-      "is_featured": <bool>,
-      "position": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-move_playlist_tracks(playlist_id: int | str, playlist_track_ids: int | str | list[int | str], insert_before: int) → dict[str, Any][source]#
-

Move tracks in a user playlist.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
playlist_idint or str

Qobuz user playlist ID.

-

Example: 17737508.

-
-
playlist_track_idsint, str, or list

Qobuz playlist track ID(s).

-
-

Note

-

Playlist track IDs are not the same as track IDs. To get -playlist track IDs, use get_playlist().

-
-
-
insert_beforeint

Position to which to move the tracks specified in -track_ids.

-
-
-
-
Returns:
-
-
playliststr

Qobuz catalog information for the updated playlist.

-
-

Sample response

-
{
-  "id": <int>,
-  "name": <str>,
-  "description": <str>,
-  "tracks_count": <int>,
-  "users_count": <int>,
-  "duration": <int>,
-  "public_at": <int>,
-  "created_at": <int>,
-  "updated_at": <int>,
-  "is_public": <bool>,
-  "is_collaborative": <bool>,
-  "owner": {
-    "id": <int>,
-    "name": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-search(query: str, type: str = None, *, hi_res: bool = False, new_release: bool = False, strict: bool = False, limit: int = 10, offset: int = 0) → dict[str, Any][source]#
-

Search Qobuz for media and performers.

-
-
Parameters:
-
-
querystr

Search query.

-
-
typestr, keyword-only, optional

Category to search in. If specified, only matching releases -and tracks will be returned.

-

Valid values: "MainArtist", "Composer", -"Performer", "ReleaseName", and -"Label".

-
-
hi_resbool, keyword-only, False

High-resolution audio only.

-
-
new_releasebool, keyword-only, False

New releases only.

-
-
strictbool, keyword-only, False

Enable exact word or phrase matching.

-
-
limitint, keyword-only, default: 10

Maximum number of results to return.

-
-
offsetint, keyword-only, default: 0

Index of the first result to return. Use with limit to get -the next page of search results.

-
-
-
-
Returns:
-
-
resultsdict

Search results.

-
-

Sample response

-
{
-  "query": <str>,
-  "albums": {
-    "limit": <int>,
-    "offset": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "maximum_bit_depth": <int>,
-        "image": {
-          "small": <str>,
-          "thumbnail": <str>,
-          "large": <str>,
-          "back": <str>,
-        },
-        "media_count": <int>,
-        "artist": {
-          "image": <str>,
-          "name": <str>,
-          "id": <int>,
-          "albums_count": <int>,
-          "slug": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "roles": [<str>]
-          }
-        ],
-        "upc": <str>,
-        "released_at": <int>,
-        "label": {
-          "name": <str>,
-          "id": <int>,
-          "albums_count": <int>,
-          "supplier_id": <int>,
-          "slug": <str>
-        },
-        "title": <str>,
-        "qobuz_id": <int>,
-        "version": <str>,
-        "url": <str>,
-        "duration": <int>,
-        "parental_warning": <bool>,
-        "popularity": <int>,
-        "tracks_count": <int>,
-        "genre": {
-          "path": [<int>],
-          "color": <str>,
-          "name": <str>,
-          "id": <int>,
-          "slug": <str>
-        },
-        "maximum_channel_count": <int>,
-        "id": <str>,
-        "maximum_sampling_rate": <int>,
-        "articles": <list>,
-        "release_date_original": <str>,
-        "release_date_download": <str>,
-        "release_date_stream": <str>,
-        "purchasable": <bool>,
-        "streamable": <bool>,
-        "previewable": <bool>,
-        "sampleable": <bool>,
-        "downloadable": <bool>,
-        "displayable": <bool>,
-        "purchasable_at": <int>,
-        "streamable_at": <int>,
-        "hires": <bool>,
-        "hires_streamable": <bool>
-      }
-    ]
-  },
-  "tracks": {
-    "limit": <int>,
-    "offset": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "maximum_bit_depth": <int>,
-        "copyright": <str>,
-        "performers": <str>,
-        "audio_info": {
-          "replaygain_track_peak": <float>,
-          "replaygain_track_gain": <float>
-        },
-        "performer": {
-          "name": <str>,
-          "id": <int>
-        },
-        "album": {
-          "image": {
-            "small": <str>,
-            "thumbnail": <str>,
-            "large": <str>
-          },
-          "maximum_bit_depth": <int>,
-          "media_count": <int>,
-          "artist": {
-            "image": <str>,
-            "name": <str>,
-            "id": <int>,
-            "albums_count": <int>,
-            "slug":<str>,
-            "picture": <str>
-          },
-          "upc": <str>,
-          "released_at": <int>,
-          "label": {
-            "name": <str>,
-            "id": <int>,
-            "albums_count": <int>,
-            "supplier_id": <int>,
-            "slug": <str>
-          },
-          "title": <str>,
-          "qobuz_id": <int>,
-          "version": <str>,
-          "duration": <int>,
-          "parental_warning": <bool>,
-          "tracks_count": <int>,
-          "popularity": <int>,
-          "genre": {
-            "path": [<int>],
-            "color": <str>,
-            "name": <str>,
-            "id": <int>,
-            "slug": <str>
-          },
-          "maximum_channel_count": <int>,
-          "id": <str>,
-          "maximum_sampling_rate": <int>,
-          "previewable": <bool>,
-          "sampleable": <bool>,
-          "displayable": <bool>,
-          "streamable": <bool>,
-          "streamable_at": <int>,
-          "downloadable": <bool>,
-          "purchasable_at": <int>,
-          "purchasable": <bool>,
-          "release_date_original": <str>,
-          "release_date_download": <str>,
-          "release_date_stream": <str>,
-          "release_date_purchase": <str>,
-          "hires": <bool>,
-          "hires_streamable": <bool>
-        },
-        "work": <str>,
-        "composer": {
-          "name": <str>,
-          "id": <int>
-        },
-        "isrc": <str>,
-        "title": <str>,
-        "version": <str>,
-        "duration": <int>,
-        "parental_warning": <bool>,
-        "track_number": <int>,
-        "maximum_channel_count": <int>,
-        "id": <int>,
-        "media_number": <int>,
-        "maximum_sampling_rate": <int>,
-        "release_date_original": <str>,
-        "release_date_download": <str>,
-        "release_date_stream": <str>,
-        "release_date_purchase": <str>,
-        "purchasable": <bool>,
-        "streamable": <bool>,
-        "previewable": <bool>,
-        "sampleable": <bool>,
-        "downloadable": <bool>,
-        "displayable": <bool>,
-        "purchasable_at": <int>,
-        "streamable_at": <int>,
-        "hires": <bool>,
-        "hires_streamable": <bool>
-      }
-    ]
-  },
-  "artists": {
-    "limit": <int>,
-    "offset": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "picture": <str>,
-        "image": {
-          "small": <str>,
-          "medium": <str>,
-          "large": <str>,
-          "extralarge": <str>,
-          "mega": <str>
-        },
-        "name": <str>,
-        "slug": <str>,
-        "albums_count": <int>,
-        "id": <int>
-      }
-    ]
-  },
-  "playlists": {
-    "limit": <int>,
-    "offset": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "image_rectangle_mini": [<str>],
-        "is_published": <bool>,
-        "featured_artists": <list>,
-        "description": <str>,
-        "created_at": <int>,
-        "timestamp_position": <int>,
-        "images300": [<str>],
-        "duration": <int>,
-        "updated_at": <int>,
-        "published_to": <int>,
-        "genres": <list>,
-        "image_rectangle": [<str>],
-        "id": <int>,
-        "slug": <str>,
-        "owner": {
-          "id": <int>,
-          "name": <str>
-        },
-        "users_count": <int>,
-        "images150": [<str>],
-        "images": [<str>],
-        "is_collaborative": <bool>,
-        "stores": [<str>],
-        "tags": [
-          {
-            "featured_tag_id": <str>,
-            "name_json": <str>,
-            "slug": <str>,
-            "color": <str>,
-            "genre_tag": <str>,
-            "is_discover": <bool>
-          }
-        ],
-        "tracks_count": <int>,
-        "public_at": <int>,
-        "name": <str>,
-        "is_public": <bool>,
-        "published_from": <int>,
-        "is_featured": <bool>
-      }
-    ]
-  },
-  "focus": {
-    "limit": <int>,
-    "offset": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "image": <str>,
-        "name_superbloc": <str>,
-        "accroche": <str>,
-        "id": <str>,
-        "title": <str>,
-        "genre_ids": [<str>],
-        "author": <str>,
-        "date": <str>
-      }
-    ]
-  },
-  "articles": {
-    "limit": <int>,
-    "offset": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "image": <str>,
-        "thumbnail": <str>,
-        "root_category": <int>,
-        "author": <str>,
-        "abstract": <str>,
-        "source": <str>,
-        "title": <str>,
-        "type": <str>,
-        "url": <str>,
-        "image_original": <str>,
-        "category_id": <int>,
-        "source_image": <str>,
-        "id": <int>,
-        "published_at": <int>,
-        "category": <str>
-      }
-    ]
-  },
-  "stories": {
-    "limit": <int>,
-    "offset": <int>,
-    "total": <int>,
-    "items": [
-      {
-        "id": <str>,
-        "section_slugs": [<str>],
-        "title": <str>,
-        "description_short": <str>,
-        "authors": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "slug": <str>
-          }
-        ],
-        "image": <str>,
-        "display_date": <int>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-set_auth_token(auth_token: str = None, *, email: str = None, password: str = None) → None[source]#
-

Set the private Qobuz API user authentication token.

-
-
Parameters:
-
-
auth_tokenstr, optional

User authentication token.

-
-
emailstr, keyword-only, optional

Account email address.

-
-
passwordstr, keyword-only, optional

Account password.

-
-
-
-
-
- -
-
-set_flow(flow: str, *, app_id: str = None, app_secret: str = None, auth_token: str = None, browser: bool = False, save: bool = True) → None[source]#
-

Set the authorization flow.

-
-
Parameters:
-
-
flowstr, keyword-only, optional

Authorization flow.

-
-

Valid values:

-
    -

  • "password" for the password flow.

    • -

  • None for no authentication.

    • -
-
-
-
app_idstr, keyword-only, optional

App ID. Required if an user authentication token is provided -in auth_token.

-
-
app_secretstr, keyword-only, optional

App secret. Required if an user authentication token is -provided in auth_token.

-
-
auth_tokenstr, keyword-only, optional

User authentication token.

-
-
browserbool, keyword-only, default: False

Determines whether a web browser is opened with the Qobuz login -page using the Playwright framework by Microsoft to complete the -password flow.

-
-
savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens -and their associated properties to the Minim configuration -file.

-
-
-
-
-
- -
-
-unfavorite_items(*, album_ids: str | list[str] = None, artist_ids: int | str | list[int | str] = None, track_ids: int | str | list[int | str] = None) → None[source]#
-

Unfavorite albums, artists, and/or tracks.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-

See also

-

For playlists, use unfavorite_playlist().

-
-
-
Parameters:
-
-
album_idsstr or list, keyword-only, optional

Qobuz album ID(s).

-
-
artist_idsint, str, or list, keyword-only, optional

Qobuz artist ID(s).

-
-
track_idsint, str, or list, keyword-only, optional

Qobuz track ID(s).

-
-
-
-
-
- -
-
-unfavorite_playlist(playlist_id: int | str) → None[source]#
-

Unsubscribe from a playlist.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
playlist_idint or str

Qobuz playlist ID.

-

Example: 15732665.

-
-
-
-
-
- -
-
-update_playlist(playlist_id: int | str, *, name: str = None, description: str = None, public: bool = None, collaborative: bool = None) → dict[str, Any][source]#
-

Update the title, description, and/or privacy of a playlist -owned by the current user.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
playlist_idint or str

Qobuz user playlist ID.

-

Example: 17737508.

-
-
namestr, keyword-only, optional

Qobuz playlist name.

-
-
descriptionstr, keyword-only, optional

Brief playlist description.

-
-
publicbool, keyword-only, optional

Determines whether the playlist is public (True) or -private (False).

-
-
collaborativebool, keyword-only, optional

Determines whether the playlist is collaborative.

-
-
-
-
Returns:
-
-
playliststr

Qobuz catalog information for the updated playlist.

-
-

Sample response

-
{
-  "id": <int>,
-  "name": <str>,
-  "description": <str>,
-  "tracks_count": <int>,
-  "users_count": <int>,
-  "duration": <int>,
-  "public_at": <int>,
-  "created_at": <int>,
-  "updated_at": <int>,
-  "is_public": <bool>,
-  "is_collaborative": <bool>,
-  "owner": {
-    "id": <int>,
-    "name": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-update_playlist_position(from_playlist_id: int | str, to_playlist_id: int | str) → None[source]#
-

Organize a user’s playlists.

-
-

User authentication

-

Requires user authentication via the password flow.

-
-
-
Parameters:
-
-
from_playlist_idint or str

Qobuz user playlist ID of playlist to move.

-

Example: 17737508.

-
-
to_playlist_idint or str

Qobuz user playlist ID of playlist to swap with that in -from_playlist_id.

-

Example: 17737509.

-
-
-
-
-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.qobuz.html b/docs/api/minim.qobuz.html deleted file mode 100644 index 3761699c..00000000 --- a/docs/api/minim.qobuz.html +++ /dev/null @@ -1,344 +0,0 @@ - - - - - - - - - qobuz - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

qobuz#

-
-

Qobuz#

-

This module contains a minimum implementation of the private Qobuz API.

-
-

Classes

-
- - - - - - -

PrivateAPI

Private Qobuz API client.

-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.spotify.PrivateLyricsService.html b/docs/api/minim.spotify.PrivateLyricsService.html deleted file mode 100644 index df61a031..00000000 --- a/docs/api/minim.spotify.PrivateLyricsService.html +++ /dev/null @@ -1,524 +0,0 @@ - - - - - - - - - PrivateLyricsService - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

PrivateLyricsService#

-
-
-class minim.spotify.PrivateLyricsService(*, sp_dc: str = None, access_token: str = None, expiry: datetime | str = None, save: bool = True)[source]#
-

Bases: object

-

Spotify Lyrics service client.

-

The Spotify Lyrics service, which is powered by Musixmatch (or -PetitLyrics in Japan), provides line- or word-synced lyrics for -Spotify tracks when available. The Spotify Lyrics interface is not -publicly documented, so its endpoints have been determined by -watching HTTP network traffic.

-
-

Attention

-

As the Spotify Lyrics service is not designed to be publicly -accessible, this class can be disabled or removed at any time to -ensure compliance with the Spotify Developer Terms of Service.

-
-

Requests to the Spotify Lyrics endpoints must be accompanied by a -valid access token in the header. An access token can be obtained -using the Spotify Web Player sp_dc cookie, which must either -be provided to this class’s constructor as a keyword argument or be -stored as SPOTIFY_SP_DC in the operating system’s -environment variables.

-
-

Hint

-

The sp_dc cookie can be extracted from the local storage -of your web browser after you log into Spotify.

-
-

If an existing access token is available, it and its expiry time can -be provided to this class’s constructor as keyword arguments to -bypass the access token exchange process. It is recommended that all -other authorization-related keyword arguments be specified so that -a new access token can be obtained when the existing one expires.

-
-

Tip

-

The sp_dc cookie and access token can be changed or -updated at any time using set_sp_dc() and -set_access_token(), respectively.

-
-

Minim also stores and manages access tokens and their properties. -When an access token is acquired, it is automatically saved to the -Minim configuration file to be loaded on the next instantiation of -this class. This behavior can be disabled if there are any security -concerns, like if the computer being used is a shared device.

-
-
Parameters:
-
-
sp_dcstr, optional

Spotify Web Player sp_dc cookie. If it is not stored -as SPOTIFY_SP_DC in the operating system’s environment -variables or found in the Minim configuration file, it must be -provided here.

-
-
access_tokenstr, keyword-only, optional

Access token. If provided here or found in the Minim -configuration file, the authorization process is bypassed. In -the former case, all other relevant keyword arguments should be -specified to automatically refresh the access token when it -expires.

-
-
expirydatetime.datetime or str, keyword-only, optional

Expiry time of access_token in the ISO 8601 format -%Y-%m-%dT%H:%M:%SZ. If provided, the user will be -reauthenticated when access_token expires.

-
-
savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their -associated properties are stored to the Minim configuration -file.

-
-
-
-
Attributes:
-
-
LYRICS_URLstr

Base URL for the Spotify Lyrics service.

-
-
TOKEN_URLstr

URL for the Spotify Web Player access token endpoint.

-
-
sessionrequests.Session

Session used to send requests to the Spotify Lyrics service.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - -

get_lyrics

Get lyrics for a Spotify track.

set_access_token

Set the Spotify Lyrics service access token.

set_sp_dc

Set the Spotify Web Player sp_dc cookie.

-
-
-
-get_lyrics(track_id: str) → dict[str, Any][source]#
-

Get lyrics for a Spotify track.

-
-
Parameters:
-
-
track_idstr

The Spotify ID for the track.

-

Example: "0VjIjW4GlUZAMYd2vXMi3b".

-
-
-
-
Returns:
-
-
lyricsdict

Formatted or time-synced lyrics.

-
-

Sample response

-
{
-  "lyrics": {
-    "syncType": <str>,
-    "lines": [
-      {
-        "startTimeMs": <str>,
-        "words": <str>,
-        "syllables": [],
-        "endTimeMs": <str>
-      }
-    ],
-    "provider": <str>,
-    "providerLyricsId": <str>,
-    "providerDisplayName": <str>,
-    "syncLyricsUri": <str>,
-    "isDenseTypeface": <bool>,
-    "alternatives": [],
-    "language": <str>,
-    "isRtlLanguage": <bool>,
-    "fullscreenAction": <str>,
-    "showUpsell": <bool>
-  },
-  "colors": {
-    "background": <int>,
-    "text": <int>,
-    "highlightText": <int>
-  },
-  "hasVocalRemoval": <bool>
-}
-
-
-
-
-
-
-
-
- -
-
-set_access_token(access_token: str = None, expiry: datetime | str = None) → None[source]#
-

Set the Spotify Lyrics service access token.

-
-
Parameters:
-
-
access_tokenstr, optional

Access token. If not provided, an access token is obtained -from the Spotify Web Player using the sp_dc cookie.

-
-
expirystr or datetime.datetime, keyword-only, optional

Access token expiry timestamp in the ISO 8601 format -%Y-%m-%dT%H:%M:%SZ. If provided, the user will be -reauthenticated (if sp_dc is found or provided) when the -access_token expires.

-
-
-
-
-
- -
-
-set_sp_dc(sp_dc: str = None, *, save: bool = True) → None[source]#
-

Set the Spotify Web Player sp_dc cookie.

-
-
Parameters:
-
-
sp_dcstr, optional

Spotify Web Player sp_dc cookie.

-
-
savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens -and their associated properties to the Minim configuration -file.

-
-
-
-
-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.spotify.WebAPI.html b/docs/api/minim.spotify.WebAPI.html deleted file mode 100644 index 4db3d6cd..00000000 --- a/docs/api/minim.spotify.WebAPI.html +++ /dev/null @@ -1,8427 +0,0 @@ - - - - - - - - - WebAPI - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

WebAPI#

-
-
-class minim.spotify.WebAPI(*, client_id: str = None, client_secret: str = None, flow: str = 'web_player', browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, scopes: str | list[str] = '', sp_dc: str = None, access_token: str = None, refresh_token: str = None, expiry: datetime | str = None, overwrite: bool = False, save: bool = True)[source]#
-

Bases: object

-

Spotify Web API client.

-

The Spotify Web API enables the creation of applications that can -interact with Spotify’s streaming service, such as retrieving -content metadata, getting recommendations, creating and managing -playlists, or controlling playback.

-
-

Important

-
    -

  • Spotify content may not be downloaded.

    • -

  • Keep visual content in its original form.

    • -

  • Ensure content attribution.

    • -
-
-
-

See also

-

For more information, see the Spotify Web API Reference.

-
-

Requests to the Spotify Web API endpoints must be accompanied by a -valid access token in the header. An access token can be obtained -with or without user authentication. While authentication is not -necessary to search for and retrieve data from public content, it -is required to access personal content and control playback.

-

Minim can obtain client-only access tokens via the client -credentials flow and user access -tokens via the authorization code and authorization -code with proof key for code exchange (PKCE) flows. These OAuth 2.0 authorization flows -require valid client credentials (client ID and client secret) to -either be provided to this class’s constructor as keyword arguments -or be stored as SPOTIFY_CLIENT_ID and -SPOTIFY_CLIENT_SECRET in the operating system’s environment -variables.

-
-

See also

-

To get client credentials, see the guide on how to create a new -Spotify application. To take advantage -of Minim’s automatic authorization code retrieval functionality -for the authorization code (with PKCE) flow, the redirect URI -should be in the form http://localhost:{port}/callback, -where {port} is an open port on localhost.

-
-

Alternatively, a access token can be acquired without client -credentials through the Spotify Web Player, but this approach is not -recommended and should only be used as a last resort since it is not -officially supported and can be deprecated by Spotify at any time. -The access token is client-only unless a Spotify Web Player -sp_dc cookie is either provided to this class’s constructor -as a keyword argument or be stored as SPOTIFY_SP_DC in the -operating system’s environment variables, in which case a user -access token with all authorization scopes is granted instead.

-

If an existing access token is available, it and its accompanying -information (refresh token and expiry time) can be provided to this -class’s constructor as keyword arguments to bypass the access token -retrieval process. It is recommended that all other -authorization-related keyword arguments be specified so that a new -access token can be obtained when the existing one expires.

-
-

Tip

-

The authorization flow and access token can be changed or updated -at any time using set_flow() and set_access_token(), -respectively.

-
-

Minim also stores and manages access tokens and their properties. -When any of the authorization flows above are used to acquire an -access token, it is automatically saved to the Minim configuration -file to be loaded on the next instantiation of this class. This -behavior can be disabled if there are any security concerns, like if -the computer being used is a shared device.

-
-
Parameters:
-
-
client_idstr, keyword-only, optional

Client ID. Required for the authorization code and client -credentials flows. If it is not stored as -SPOTIFY_CLIENT_ID in the operating system’s environment -variables or found in the Minim configuration file, it must be -provided here.

-
-
client_secretstr, keyword-only, optional

Client secret. Required for the authorization code and client -credentials flows. If it is not stored as -SPOTIFY_CLIENT_SECRET in the operating system’s -environment variables or found in the Minim configuration file, -it must be provided here.

-
-
flowstr, keyword-only, default: "web_player"

Authorization flow.

-
-

Valid values:

-
    -

  • "authorization_code" for the authorization code -flow.

    • -

  • "pkce" for the authorization code with proof -key for code exchange (PKCE) flow.

    • -

  • "client_credentials" for the client credentials -flow.

    • -

  • "web_player" for a Spotify Web Player access -token.

    • -
-
-
-
browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for the -authorization code (with PKCE) flow. If False, users -will have to manually open the authorization URL. Not applicable -when web_framework=”playwright”.

-
-
web_frameworkstr, keyword-only, optional

Determines which web framework to use for the authorization code -(with PKCE) flow.

-
-

Valid values:

-
    -

  • "http.server" for the built-in implementation of -HTTP servers.

    • -

  • "flask" for the Flask framework.

    • -

  • "playwright" for the Playwright framework by -Microsoft.

    • -
-
-
-
portint or str, keyword-only, default: 8888

Port on localhost to use for the authorization code -flow with the http.server and Flask frameworks. Only -used if redirect_uri is not specified.

-
-
redirect_uristr, keyword-only, optional

Redirect URI for the authorization code flow. If not on -localhost, the automatic authorization code retrieval -functionality is not available.

-
-
scopesstr or list, keyword-only, optional

Authorization scopes to request user access for in the -authorization code flow.

-
-

See also

-

See get_scopes() for the complete list of scopes.

-
-
-
sp_dcstr, keyword-only, optional

Spotify Web Player sp_dc cookie to send with the access -token request. If provided here, stored as SPOTIFY_SP_DC -in the operating system’s environment variables, or found in the -Minim configuration file, a user access token with all -authorization scopes is obtained instead of a client-only access -token.

-
-
access_tokenstr, keyword-only, optional

Access token. If provided here or found in the Minim -configuration file, the authorization process is bypassed. In -the former case, all other relevant keyword arguments should be -specified to automatically refresh the access token when it -expires.

-
-
refresh_tokenstr, keyword-only, optional

Refresh token accompanying access_token. If not provided, -the user will be reauthenticated using the specified -authorization flow when access_token expires.

-
-
expirydatetime.datetime or str, keyword-only, optional

Expiry time of access_token in the ISO 8601 format -%Y-%m-%dT%H:%M:%SZ. If provided, the user will be -reauthenticated using refresh_token (if available) or the -specified authorization flow (if possible) when access_token -expires.

-
-
overwritebool, keyword-only, default: False

Determines whether to overwrite an existing access token in the -Minim configuration file.

-
-
savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their -associated properties are stored to the Minim configuration -file.

-
-
-
-
Attributes:
-
-
API_URLstr

Base URL for the Spotify Web API.

-
-
AUTH_URLstr

URL for Spotify Web API authorization code requests.

-
-
TOKEN_URLstr

URL for Spotify Web API access token requests.

-
-
WEB_PLAYER_TOKEN_URLstr

URL for Spotify Web Player access token requests.

-
-
sessionrequests.Session

Session used to send requests to the Spotify Web API.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

add_playlist_cover_image

Playlists > Add Custom Playlist Cover Image: Replace the image used to represent a specific playlist.

add_playlist_items

Playlists > Add Items to Playlist: Add one or more items to a user's playlist.

add_to_queue

Player > Add Item to Playback Queue: Add an item to the end of the user's current playback queue.

change_playlist_details

Playlists > Change Playlist Details: Change a playlist's name and public/private state.

check_followed_people

Users > Check If User Follows Artists or Users: Check to see if the current user is following one or more artists or other Spotify users.

check_playlist_followers

Users > Check If Users Follow Playlist: Check to see if one or more Spotify users are following a specified playlist.

check_saved_albums

Albums > Check User's Saved Albums: Check if one or more albums is already saved in the current Spotify user's 'Your Music' library.

check_saved_audiobooks

Audiobooks > Check User's Saved Audiobooks: Check if one or more audiobooks are already saved in the current Spotify user's library.

check_saved_episodes

Episodes > Check User's Saved Episodes: Check if one or more episodes is already saved in the current Spotify user's 'Your Episodes' library.

check_saved_shows

Shows > Check User's Saved Shows: Check if one or more shows is already saved in the current Spotify user's library.

check_saved_tracks

Tracks > Check User's Saved Tracks: Check if one or more tracks is already saved in the current Spotify user's 'Your Music' library.

create_playlist

Playlists > Create Playlist: Create a playlist for a Spotify user.

follow_people

Users > Follow Artists or Users: Add the current user as a follower of one or more artists or other Spotify users.

follow_playlist

Users > Follow Playlist: Add the current user as a follower of a playlist.

get_album

Albums > Get Album: Get Spotify catalog information for a single album.

get_album_tracks

Albums > Get Album Tracks: Get Spotify catalog information for an album's tracks.

get_albums

Albums > Get Several Albums: Get Spotify catalog information for albums identified by their Spotify IDs.

get_artist

Artists > Get Artist: Get Spotify catalog information for a single artist identified by their unique Spotify ID.

get_artist_albums

Artist > Get Artist's Albums: Get Spotify catalog information about an artist's albums.

get_artist_top_tracks

Artist > Get Artist's Top Tracks: Get Spotify catalog information about an artist's top tracks by country.

get_artists

Artists > Get Several Artists: Get Spotify catalog information for several artists based on their Spotify IDs.

get_audiobook

Audiobooks > Get an Audiobook: Get Spotify catalog information for a single audiobook.

get_audiobook_chapters

Audiobooks > Get Audiobook Chapters: Get Spotify catalog information about an audiobook's chapters.

get_audiobooks

Audiobooks > Get Several Audiobooks: Get Spotify catalog information for several audiobooks identified by their Spotify IDs.

get_categories

Categories > Get Several Browse Categories: Get a list of categories used to tag items in Spotify (on, for example, the Spotify player's "Browse" tab).

get_category

Categories > Get Single Browse Category: Get a single category used to tag items in Spotify (on, for example, the Spotify player's "Browse" tab).

get_category_playlists

Playlists > Get Category's Playlists: Get a list of Spotify playlists tagged with a particular category.

get_chapter

Chapters > Get a Chapter: Get Spotify catalog information for a single chapter.

get_chapters

Chapters > Get Several Chapters: Get Spotify catalog information for several chapters identified by their Spotify IDs.

get_currently_playing

Player > Get Currently Playing Track: Get the object currently being played on the user's Spotify account.

get_devices

Player > Get Available Devices: Get information about a user's available devices.

get_episode

Episodes > Get Episode: Get Spotify catalog information for a single episode identified by its unique Spotify ID.

get_episodes

Episodes > Get Several Episodes: Get Spotify catalog information for several episodes based on their Spotify IDs.

get_featured_playlists

Playlists > Get Featured Playlists: Get a list of Spotify featured playlists (shown, for example, on a Spotify player's 'Browse' tab).

get_followed_artists

Users > Get Followed Artists: Get the current user's followed artists.

get_genre_seeds

Genres > Get Available Genre Seeds: Retrieve a list of available genres seed parameter values for use in get_recommendations().

get_markets

Markets > Get Available Markets: Get the list of markets where Spotify is available.

get_new_albums

Albums > Get New Releases: Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player's "Browse" tab).

get_personal_playlists

Playlist > Get Current User's Playlists: Get a list of the playlists owned or followed by the current Spotify user.

get_playback_state

Player > Get Playback State: Get information about the user's current playback state, including track or episode, progress, and active device.

get_playlist

Playlists > Get Playlist: Get a playlist owned by a Spotify user.

get_playlist_cover_image

Playlists > Get Playlist Cover Image: Get the current image associated with a specific playlist.

get_playlist_items

Playlists > Get Playlist Items: Get full details of the items of a playlist owned by a Spotify user.

get_profile

Users > Get Current User's Profile: Get detailed profile information about the current user (including the current user's username).

get_queue

Player > Get the User's Queue: Get the list of objects that make up the user's queue.

get_recently_played

Player > Get Recently Played Tracks: Get tracks from the current user's recently played tracks.

get_recommendations

Tracks > Get Recommendations: Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks.

get_related_artists

Artists > Get Artist's Related Artists: Get Spotify catalog information about artists similar to a given artist.

get_saved_albums

Albums > Get User's Saved Albums: Get a list of the albums saved in the current Spotify user's 'Your Music' library.

get_saved_audiobooks

Audiobooks > Get User's Saved Audiobooks: Get a list of the albums saved in the current Spotify user's audiobooks library.

get_saved_episodes

Episodes > Get User's Saved Episodes: Get a list of the episodes saved in the current Spotify user's library.

get_saved_shows

Shows > Get User's Saved Shows: Get a list of shows saved in the current Spotify user's library.

get_saved_tracks

Tracks > Get User's Saved Tracks: Get a list of the songs saved in the current Spotify user's 'Your Music' library.

get_scopes

Get Spotify Web API and Open Access authorization scopes for the specified categories.

get_show

Shows > Get Show: Get Spotify catalog information for a single show identified by its unique Spotify ID.

get_show_episodes

Shows > Get Show Episodes: Get Spotify catalog information about an show's episodes.

get_shows

Shows > Get Several Shows: Get Spotify catalog information for several shows based on their Spotify IDs.

get_top_items

Users > Get User's Top Items: Get the current user's top artists or tracks based on calculated affinity.

get_track

Tracks > Get Track: Get Spotify catalog information for a single track identified by its unique Spotify ID.

get_track_audio_analysis

Tracks > Get Track's Audio Analysis: Get a low-level audio analysis for a track in the Spotify catalog.

get_track_audio_features

Tracks > Get Track's Audio Features: Get audio feature information for a single track identified by its unique Spotify ID.

get_tracks

Tracks > Get Several Tracks: Get Spotify catalog information for multiple tracks based on their Spotify IDs.

get_tracks_audio_features

Tracks > Get Tracks' Audio Features: Get audio features for multiple tracks based on their Spotify IDs.

get_user_playlists

Playlist > Get User's Playlists: Get a list of the playlists owned or followed by a Spotify user.

get_user_profile

Users > Get User's Profile: Get public profile information about a Spotify user.

pause_playback

Player > Pause Playback: Pause playback on the user's account.

remove_playlist_items

Playlists > Remove Playlist Items: Remove one or more items from a user's playlist.

remove_saved_albums

Albums > Remove Users' Saved Albums: Remove one or more albums from the current user's 'Your Music' library.

remove_saved_audiobooks

Audiobooks > Remove User's Saved Audiobooks: Delete one or more audiobooks from current Spotify user's library.

remove_saved_episodes

Episodes > Remove User's Saved Episodes: Remove one or more episodes from the current user's library.

remove_saved_shows

Shows > Remove User's Saved Shows: Delete one or more shows from current Spotify user's library.

remove_saved_tracks

Tracks > Remove User's Saved Tracks: Remove one or more tracks from the current user's 'Your Music' library.

save_albums

Albums > Save Albums for Current User: Save one or more albums to the current user's 'Your Music' library.

save_audiobooks

Audiobooks > Save Audiobooks for Current User: Save one or more audiobooks to current Spotify user's library.

save_episodes

Episodes > Save Episodes for Current User: Save one or more episodes to the current user's library.

save_shows

Shows > Save Shows for Current User: Save one or more shows to current Spotify user's library.

save_tracks

Tracks > Save Track for Current User: Save one or more tracks to the current user's 'Your Music' library.

search

Search > Search for Item: Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string.

seek_to_position

Player > Seek To Position: Seeks to the given position in the user's currently playing track.

set_access_token

Set the Spotify Web API access token.

set_flow

Set the authorization flow.

set_playback_volume

Player > Set Playback Volume: Set the volume for the user's current playback device.

set_repeat_mode

Player > Set Repeat Mode: Set the repeat mode for the user's playback.

skip_to_next

Player > Skip To Next: Skips to next track in the user's queue.

skip_to_previous

Player > Skip To Previous: Skips to previous track in the user's queue.

start_playback

Player > Start/Resume Playback: Start a new context or resume current playback on the user's active device.

toggle_playback_shuffle

Player > Toggle Playback Shuffle: Toggle shuffle on or off for user's playback.

transfer_playback

Player > Transfer Playback: Transfer playback to a new device and determine if it should start playing.

unfollow_people

Users > Unfollow Artists or Users: Remove the current user as a follower of one or more artists or other Spotify users.

unfollow_playlist

Users > Unfollow Playlist: Remove the current user as a follower of a playlist.

update_playlist_items

Playlists > Update Playlist Items: Either reorder or replace items in a playlist depending on the request's parameters.

-
-
-
-add_playlist_cover_image(playlist_id: str, image: bytes) → None[source]#
-

Playlists > Add Custom Playlist Cover Image: Replace the image used to -represent a specific playlist.

-
-

Authorization scope

-

Requires the ugc-image-upload and the -playlist-modify-public or -playlist-modify-private scope.

-
-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
imagebytes

Base64-encoded JPEG image data. The maximum payload size is -256 KB.

-
-
-
-
-
- -
-
-add_playlist_items(playlist_id: str, uris: str | list[str], *, position: int = None) → str[source]#
-

Playlists > Add Items to Playlist: Add one or more items to -a user’s playlist.

-
-

Authorization scope

-

Requires the playlist-modify-public or the -playlist-modify-private scope.

-
-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
urisstr or list, keyword-only, optional

A (comma-separated) list of Spotify URIs to add; can be -track or episode URIs. A maximum of 100 items can be added -in one request.

-
-

Note

-

It is likely that passing a large number of item URIs as -a query parameter will exceed the maximum length of the -request URI. When adding a large number of items, it is -recommended to pass them in the request body (as a -list).

-
-

Example: "spotify:track:4iV5W9uYEdYUVa79Axb7Rh, -spotify:track:1301WleyT98MSxVHPZCA6M, -spotify:episode:512ojhOuo1ktJprKbVcKyQ".

-
-
positionint, keyword-only, optional

The position to insert the items, a zero-based index. If -omitted, the items will be appended to the playlist. Items -are added in the order they are listed in the query string -or request body.

-
-

Examples:

-
    -

  • 0 to insert the items in the first position.

    • -

  • 2 to insert the items in the third position.

    • -
-
-
-
-
-
Returns:
-
-
snapshot_idstr

The updated playlist’s snapshot ID.

-
-
-
-
-
- -
-
-add_to_queue(uri: str, *, device_id: str = None) → None[source]#
-

Player > Add Item to Playback Queue: Add an item to the end of the user’s current -playback queue.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
uristr

The URI of the item to add to the queue. Must be a track or -an episode URL.

-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
-
-
-
- -
-
-change_playlist_details(playlist_id: str, *, name: str = None, public: bool = None, collaborative: bool = None, description: str = None) → None[source]#
-

Playlists > Change Playlist Details: Change a playlist’s -name and public/private state. (The user must, of course, own -the playlist.)

-
-

Authorization scope

-

Requires the playlist-modify-public or the -playlist-modify-private scope.

-
-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
namestr, keyword-only, optional

The new name for the playlist.

-

Example: "My New Playlist Title".

-
-
publicbool, keyword-only, optional

If True, the playlist will be public. If -False, it will be private.

-
-
collaborativebool, keyword-only, optional

If True, the playlist will become collaborative and -other users will be able to modify the playlist in their -Spotify client.

-
-

Note

-

You can only set collaborative=True on non-public -playlists.

-
-
-
descriptionstr, keyword-only, optional

Value for playlist description as displayed in Spotify -clients and in the Web API.

-
-
-
-
-
- -
-
-check_followed_people(ids: str | list[str], type: str) → list[bool][source]#
-

Users > Check If User Follows Artists or Users: Check to see if the -current user is following one or more artists or other Spotify -users.

-
-

Authorization scope

-

Requires the user-follow-read scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the artist or user Spotify IDs.

-

Maximum: Up to 50 IDs can be sent in one request.

-

Example: "2CIMQHirSU0MQqyYHq0eOx, -57dN52uHvrHOxijzpIgu3E, 1vCWHaC5f2uS3yhpwWbIA6".

-
-
typestr

The ID type.

-

Valid values: "artist" and "user".

-
-
-
-
Returns:
-
-
containslist

Array of booleans specifying whether the user follows the -specified artists or Spotify users.

-

Example: [False, True].

-
-
-
-
-
- -
-
-check_playlist_followers(playlist_id: str, ids: str | list[str]) → list[bool][source]#
-

Users > Check If Users Follow Playlist: Check to see if -one or more Spotify users are following a specified playlist.

-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
idsstr or list

A (comma-separated) list of Spotify user IDs; the IDs of the -users that you want to check to see if they follow the -playlist.

-

Maximum: 5 IDs.

-

Example: "jmperezperez,thelinmichael,wizzler".

-
-
-
-
Returns:
-
-
followslist

Array of booleans specifying whether the users follow the -playlist.

-

Example: [False, True].

-
-
-
-
-
- -
-
-check_saved_albums(ids: str | list[str]) → list[bool][source]#
-

Albums > Check User’s Saved Albums: Check if one or more -albums is already saved in the current Spotify user’s ‘Your -Music’ library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the albums.

-

Maximum: 20 IDs.

-
-
-
-
Returns:
-
-
containslist

Array of booleans specifying whether the albums are found in -the user’s ‘Your Library > Albums’.

-

Example: [False, True].

-
-
-
-
-
- -
-
-check_saved_audiobooks(ids: str | list[str]) → list[bool][source]#
-

Audiobooks > Check User’s Saved Audiobooks: Check if one or -more audiobooks are already saved in the current Spotify user’s -library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the -audiobooks.

-

Maximum: 50 IDs.

-

Example: "18yVqkdbdRvS24c0Ilj2ci, -1HGw3J3NxZO1TP1BTtVhpZ, 7iHfbu1YPACw6oZPAFJtqe".

-
-
-
-
Returns:
-
-
containslist

Array of booleans specifying whether the audiobooks are -found in the user’s saved audiobooks.

-

Example: [False, True].

-
-
-
-
-
- -
-
-check_saved_episodes(ids: str | list[str]) → list[bool][source]#
-

Episodes > Check User’s Saved Episodes: Check if one or more -episodes is already saved in the current Spotify user’s ‘Your -Episodes’ library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the -episodes.

-

Maximum: 50 IDs.

-

Example: -"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf".

-
-
-
-
Returns:
-
-
containslist

Array of booleans specifying whether the episodes are found -in the user’s ‘Liked Songs’.

-

Example: [False, True].

-
-
-
-
-
- -
-
-check_saved_shows(ids: str | list[str]) → list[bool][source]#
-

Shows > Check User’s Saved Shows: Check if one or more -shows is already saved in the current Spotify user’s library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the shows.

-

Maximum: 50 IDs.

-

Example: -"5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ".

-
-
-
-
Returns:
-
-
containslist

Array of booleans specifying whether the shows are found in -the user’s saved shows.

-

Example: [False, True].

-
-
-
-
-
- -
-
-check_saved_tracks(ids: str | list[str]) → list[bool][source]#
-

Tracks > Check User’s Saved Tracks: Check if one or more -tracks is already saved in the current Spotify user’s ‘Your -Music’ library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the tracks.

-

Maximum: 50 IDs.

-

Example: "7ouMYWpwJ422jRcDASZB7P, -4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

-
-
-
-
Returns:
-
-
containslist

Array of booleans specifying whether the tracks are found in -the user’s ‘Liked Songs’.

-

Example: [False, True].

-
-
-
-
-
- -
-
-create_playlist(name: str, *, public: bool = True, collaborative: bool = None, description: str = None) → dict[str, Any][source]#
-

Playlists > Create Playlist: Create a -playlist for a Spotify user. (The playlist will be empty until -you add tracks.)

-
-

Authorization scope

-

Requires the playlist-modify-public or the -playlist-modify-private scope.

-
-
-
Parameters:
-
-
namestr

The name for the new playlist. This name does not need to be -unique; a user may have several playlists with the same -name.

-

Example: "Your Coolest Playlist".

-
-
publicbool, keyword-only, default: True

If True, the playlist will be public; if -False, it will be private.

-
-

Note

-

To be able to create private playlists, the user must -have granted the playlist-modify-private scope.

-
-
-
collaborativebool, keyword-only, optional

If True, the playlist will be collaborative.

-
-

Note

-

To create a collaborative playlist, you must also set -public to False. To create collaborative -playlists, you must have granted the -playlist-modify-private and -playlist-modify-public scopes.

-
-

Default: False.

-
-
descriptionstr, keyword-only, optional

The playlist description, as displayed in Spotify Clients -and in the Web API.

-
-
-
-
Returns:
-
-
playlistdict

Spotify catalog information for the newly created playlist.

-
-

Sample response

-
{
-  "collaborative": <bool>,
-  "description": <str>,
-  "external_urls": {
-    "spotify": <str>
-  },
-  "followers": {
-    "href": <str>,
-    "total": <int>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "name": <str>,
-  "owner": {
-    "external_urls": {
-      "spotify": <str>
-    },
-    "followers": {
-      "href": <str>,
-      "total": <int>
-    },
-    "href": <str>,
-    "id": <str>,
-    "type": "user",
-    "uri": <str>,
-    "display_name": <str>
-  },
-  "public": <bool>,
-  "snapshot_id": <str>,
-  "tracks": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "added_at": <str>,
-        "added_by": {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "followers": {
-            "href": <str>,
-            "total": <int>
-          },
-          "href": <str>,
-          "id": <str>,
-          "type": "user",
-          "uri": <str>
-        },
-        "is_local": <bool>,
-        "track": {
-          "album": {
-            "album_type": <str>,
-            "total_tracks": <int>,
-            "available_markets": [<str>],
-            "external_urls": {
-              "spotify": <str>
-            },
-            "href": <str>,
-            "id": <str>,
-            "images": [
-              {
-                "url": <str>,
-                "height": <int>,
-                "width": <int>
-              }
-            ],
-            "name": <str>,
-            "release_date": <str>,
-            "release_date_precision": <str>,
-            "restrictions": {
-              "reason": <str>
-            },
-            "type": "album",
-            "uri": <str>,
-            "copyrights": [
-              {
-                "text": <str>,
-                "type": <str>
-              }
-            ],
-            "external_ids": {
-              "isrc": <str>,
-              "ean": <str>,
-              "upc": <str>
-            },
-            "genres": [<str>],
-            "label": <str>,
-            "popularity": <int>,
-            "album_group": <str>,
-            "artists": [
-              {
-                "external_urls": {
-                  "spotify": <str>
-                },
-                "href": <str>,
-                "id": <str>,
-                "name": <str>,
-                "type": "artist",
-                "uri": <str>
-              }
-            ]
-          },
-          "artists": [
-            {
-              "external_urls": {
-                "spotify": <str>
-              },
-              "followers": {
-                "href": <str>,
-                "total": <int>
-              },
-              "genres": [<str>],
-              "href": <str>,
-              "id": <str>,
-              "images": [
-                {
-                  "url": <str>,
-                  "height": <int>,
-                  "width": <int>
-                }
-              ],
-              "name": <str>,
-              "popularity": <int>,
-              "type": "artist",
-              "uri": <str>
-            }
-          ],
-          "available_markets": [<str>],
-          "disc_number": <int>,
-          "duration_ms": <int>,
-          "explicit": <bool>,
-          "external_ids": {
-            "isrc": <str>,
-            "ean": <str>,
-            "upc": <str>
-          },
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "is_playable": <bool>
-          "linked_from": {
-          },
-          "restrictions": {
-            "reason": <str>
-          },
-          "name": <str>,
-          "popularity": <int>,
-          "preview_url": <str>,
-          "track_number": <int>,
-          "type": "track",
-          "uri": <str>,
-          "is_local": <bool>
-        }
-      }
-    ]
-  },
-  "type": <str>,
-  "uri": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-follow_people(ids: str | list[str], type: str) → None[source]#
-

Users > Follow Artists or Users: Add the current user as a follower of -one or more artists or other Spotify users.

-
-

Authorization scope

-

Requires the user-follow-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the artist or user Spotify IDs.

-

Maximum: Up to 50 IDs can be sent in one request.

-

Example: "2CIMQHirSU0MQqyYHq0eOx, -57dN52uHvrHOxijzpIgu3E, 1vCWHaC5f2uS3yhpwWbIA6".

-
-
typestr

The ID type.

-

Valid values: "artist" and "user".

-
-
-
-
-
- -
-
-follow_playlist(playlist_id: str) → None[source]#
-

Users > Follow Playlist: -Add the current user as a follower of a playlist.

-
-

Authorization scope

-

Requires the playlist-modify-private scope.

-
-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n"

-
-
-
-
-
- -
-
-get_album(id: str, *, market: str = None) → dict[source]#
-

Albums > Get Album: -Get Spotify catalog information for a single album.

-
-
Parameters:
-
-
idstr

The Spotify ID of the album.

-

Example: "4aawyAB9vmqN3uQ7FjRGTy".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
albumdict

Spotify catalog information for a single album.

-
-

Sample response

-
{
-  "album_type": <str>,
-  "total_tracks": <int>,
-  "available_markets": [<str>],
-  "external_urls": {
-    "spotify": <str>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "name": <str>,
-  "release_date": <str>,
-  "release_date_precision": <str>,
-  "restrictions": {
-    "reason": <str>
-  },
-  "type": "album",
-  "uri": <str>,
-  "copyrights": [
-    {
-      "text": <str>,
-      "type": <str>
-    }
-  ],
-  "external_ids": {
-    "isrc": <str>,
-    "ean": <str>,
-    "upc": <str>
-  },
-  "genres": [<str>],
-  "label": <str>,
-  "popularity": <int>,
-  "artists": [
-    {
-      "external_urls": {
-        "spotify": <str>
-      },
-      "followers": {
-        "href": <str>,
-        "total": <int>
-      },
-      "genres": [<str>],
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "popularity": <int>,
-      "type": "artist",
-      "uri": <str>
-    }
-  ],
-  "tracks": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "href": <str>,
-            "id": <str>,
-            "name": <str>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ],
-        "available_markets": [<str>],
-        "disc_number": <int>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "is_playable": <bool>
-        "linked_from": {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "type": <str>,
-          "uri": <str>
-        },
-        "restrictions": {
-          "reason": <str>
-        },
-        "name": <str>,
-        "preview_url": <str>,
-        "track_number": <int>,
-        "type": <str>,
-        "uri": <str>,
-        "is_local": <bool>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_album_tracks(id: str, *, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#
-

Albums > Get Album Tracks: Get Spotify catalog information for an -album’s tracks. Optional parameters can be used to limit the -number of tracks returned.

-
-
Parameters:
-
-
idstr

The Spotify ID of the album.

-

Example: "4aawyAB9vmqN3uQ7FjRGTy".

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Valid values: offset must be between 0 and 1,000.

-

Default: 0.

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing Spotify catalog information for an -album’s tracks and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "name": <str>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ],
-      "available_markets": [<str>],
-      "disc_number": <int>,
-      "duration_ms": <int>,
-      "explicit": <bool>,
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "is_playable": <bool>
-      "linked_from": {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "type": <str>,
-        "uri": <str>
-      },
-      "restrictions": {
-        "reason": <str>
-      },
-      "name": <str>,
-      "preview_url": <str>,
-      "track_number": <int>,
-      "type": <str>,
-      "uri": <str>,
-      "is_local": <bool>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_albums(ids: str | list[str], *, market: str = None) → dict[str, Any][source]#
-

Albums > Get Several Albums: Get Spotify catalog information for -albums identified by their Spotify IDs.

-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the albums.

-

Maximum: 20 IDs.

-

Example: "382ObEPsp2rxGrnsizN5TX, -1A2GTWGtFfWp7KSQTwWOyo, 2noRn2Aes5aoNVsU6iWThc".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
albumslist

A list containing Spotify catalog information for multiple -albums.

-
-

Sample response

-
[
-  {
-    "album_type": <str>,
-    "total_tracks": <int>,
-    "available_markets": [<str>],
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "name": <str>,
-    "release_date": <str>,
-    "release_date_precision": <str>,
-    "restrictions": {
-      "reason": <str>
-    },
-    "type": "album",
-    "uri": <str>,
-    "copyrights": [
-      {
-        "text": <str>,
-        "type": <str>
-      }
-    ],
-    "external_ids": {
-      "isrc": <str>,
-      "ean": <str>,
-      "upc": <str>
-    },
-    "genres": [<str>],
-    "label": <str>,
-    "popularity": <int>,
-    "artists": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "genres": [<str>],
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "popularity": <int>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ],
-    "tracks": {
-      "href": <str>,
-      "limit": <int>,
-      "next": <str>,
-      "offset": <int>,
-      "previous": <str>,
-      "total": <int>,
-      "items": [
-        {
-          "artists": [
-            {
-              "external_urls": {
-                "spotify": <str>
-              },
-              "href": <str>,
-              "id": <str>,
-              "name": <str>,
-              "type": "artist",
-              "uri": <str>
-            }
-          ],
-          "available_markets": [<str>],
-          "disc_number": <int>,
-          "duration_ms": <int>,
-          "explicit": <bool>,
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "is_playable": <bool>
-          "linked_from": {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "href": <str>,
-            "id": <str>,
-            "type": <str>,
-            "uri": <str>
-          },
-          "restrictions": {
-            "reason": <str>
-          },
-          "name": <str>,
-          "preview_url": <str>,
-          "track_number": <int>,
-          "type": <str>,
-          "uri": <str>,
-          "is_local": <bool>
-        }
-      ]
-    }
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_artist(id: str) → dict[str, Any][source]#
-

Artists > Get Artist: -Get Spotify catalog information for a single artist identified -by their unique Spotify ID.

-
-
Parameters:
-
-
idstr

The Spotify ID of the artist.

-

Example: "0TnOYISbd1XYRBk9myaseg".

-
-
-
-
Returns:
-
-
artistdict

Spotify catalog information for a single artist.

-
-

Sample response

-
{
-  "external_urls": {
-    "spotify": <str>
-  },
-  "followers": {
-    "href": <str>,
-    "total": <int>
-  },
-  "genres": [<str>],
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "name": <str>,
-  "popularity": <int>,
-  "type": "artist",
-  "uri": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_albums(id: str, *, include_groups: str | list[str] = None, limit: int = None, market: str = None, offset: int = None) → list[dict[str, Any]][source]#
-

Artist > Get Artist’s Albums: Get Spotify catalog information about -an artist’s albums.

-
-
Parameters:
-
-
idstr

The Spotify ID of the artist.

-

Example: "0TnOYISbd1XYRBk9myaseg".

-
-
include_groupsstr or list, keyword-only, optional

A comma-separated list of keywords that will be used to -filter the response. If not supplied, all album types will -be returned.

-
-

Valid values:

-
    -

  • "album" for albums.

    • -

  • "single" for singles or promotional releases.

    • -

  • "appears_on" for albums that artist appears -on as a featured artist.

    • -

  • "compilation" for compilations.

    • -
-

Examples:

-
    -

  • "album,single" for albums and singles where -artist is the main album artist.

    • -

  • "single,appears_on" for singles and albums that -artist appears on.

    • -
-
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
albumslist

A list containing Spotify catalog information for the -artist’s albums.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "album_type": <str>,
-      "total_tracks": <int>,
-      "available_markets": [<str>],
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "restrictions": {
-        "reason": <str>
-      },
-      "type": "album",
-      "uri": <str>,
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "genres": [<str>],
-      "label": <str>,
-      "popularity": <int>,
-      "album_group": <str>,
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "name": <str>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ]
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_top_tracks(id: str, *, market: str = 'US') → list[dict[str, Any]][source]#
-

Artist > Get Artist’s Top Tracks: Get Spotify catalog -information about an artist’s top tracks by country.

-
-
Parameters:
-
-
idstr

The Spotify ID of the artist.

-

Example: "0TnOYISbd1XYRBk9myaseg".

-
-
marketstr, keyword-only, default: "US"

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
trackslist

A list containing Spotify catalog information for the -artist’s top tracks.

-
-

Sample response

-
[
-  {
-    "album": {
-      "album_type": <str>,
-      "total_tracks": <int>,
-      "available_markets": [<str>],
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "restrictions": {
-        "reason": <str>
-      },
-      "type": "album",
-      "uri": <str>,
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "genres": [<str>],
-      "label": <str>,
-      "popularity": <int>,
-      "album_group": <str>,
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "name": <str>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ]
-    },
-    "artists": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "genres": [<str>],
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "popularity": <int>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ],
-    "available_markets": [<str>],
-    "disc_number": <int>,
-    "duration_ms": <int>,
-    "explicit": <bool>,
-    "external_ids": {
-      "isrc": <str>,
-      "ean": <str>,
-      "upc": <str>
-    },
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "is_playable": <bool>,
-    "linked_from": {
-    },
-    "restrictions": {
-      "reason": <str>
-    },
-    "name": <str>,
-    "popularity": <int>,
-    "preview_url": <str>,
-    "track_number": <int>,
-    "type": "track",
-    "uri": <str>,
-    "is_local": <bool>
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_artists(ids: int | str | list[int | str]) → list[dict[str, Any]][source]#
-

Artists > Get Several Artists: Get Spotify catalog information for -several artists based on their Spotify IDs.

-
-
Parameters:
-
-
idsstr

A (comma-separated) list of the Spotify IDs for the artists.

-

Maximum: 50 IDs.

-

Example: "2CIMQHirSU0MQqyYHq0eOx, -57dN52uHvrHOxijzpIgu3E, 1vCWHaC5f2uS3yhpwWbIA6".

-
-
-
-
Returns:
-
-
artistslist

A list containing Spotify catalog information for multiple -artists.

-
-

Sample response

-
[
-  {
-    "external_urls": {
-      "spotify": <str>
-    },
-    "followers": {
-      "href": <str>,
-      "total": <int>
-    },
-    "genres": [<str>],
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "name": <str>,
-    "popularity": <int>,
-    "type": "artist",
-    "uri": <str>
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_audiobook(id: str, *, market: str = None) → dict[str, Any][source]#
-

Audiobooks > Get an Audiobook: Get Spotify catalog information for a -single audiobook.

-
-

Note

-

Audiobooks are only available for the US, UK, Ireland, New -Zealand, and Australia markets.

-
-
-
Parameters:
-
-
idstr

The Spotify ID for the audiobook.

-

Example: "7iHfbu1YPACw6oZPAFJtqe".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
audiobookdict

Spotify catalog information for a single audiobook.

-
-

Sample response

-
{
-  "authors": [
-    {
-      "name": <str>
-    }
-  ],
-  "available_markets": [<str>],
-  "copyrights": [
-    {
-      "text": <str>,
-      "type": <str>
-    }
-  ],
-  "description": <str>,
-  "html_description": <str>,
-  "edition": <str>,
-  "explicit": <bool>,
-  "external_urls": {
-    "spotify": <str>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "languages": [<str>],
-  "media_type": <str>,
-  "name": <str>,
-  "narrators": [
-    {
-      "name": <str>
-    }
-  ],
-  "publisher": <str>,
-  "type": "audiobook",
-  "uri": <str>,
-  "total_chapters": <int>,
-  "chapters": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "audio_preview_url": <str>,
-        "available_markets": [<str>],
-        "chapter_number": <int>,
-        "description": <str>,
-        "html_description": <str>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "is_playable": <bool>
-        "languages": [<str>],
-        "name": <str>,
-        "release_date": <str>,
-        "release_date_precision": <str>,
-        "resume_point": {
-          "fully_played": <bool>,
-          "resume_position_ms": <int>
-        },
-        "type": "episode",
-        "uri": <str>,
-        "restrictions": {
-          "reason": <str>
-        }
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_audiobook_chapters(id: str, *, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#
-

Audiobooks > Get Audiobook Chapters: Get Spotify catalog -information about an audiobook’s chapters.

-
-

Note

-

Audiobooks are only available for the US, UK, Ireland, New -Zealand, and Australia markets.

-
-
-
Parameters:
-
-
idstr

The Spotify ID for the audiobook.

-

Example: "7iHfbu1YPACw6oZPAFJtqe".

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Valid values: offset must be between 0 and 1,000.

-

Default: 0.

-
-
-
-
Returns:
-
-
audiobooksdict

A dictionary containing Spotify catalog information for an -audiobook’s chapters and the number of results returned.

-
-

Sample

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "audio_preview_url": <str>,
-      "available_markets": [<str>],
-      "chapter_number": <int>,
-      "description": <str>,
-      "html_description": <str>,
-      "duration_ms": <int>,
-      "explicit": <bool>,
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "is_playable": <bool>
-      "languages": [<str>],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "resume_point": {
-        "fully_played": <bool>,
-        "resume_position_ms": <int>
-      },
-      "type": "episode",
-      "uri": <str>,
-      "restrictions": {
-        "reason": <str>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_audiobooks(ids: int | str | list[int | str], *, market: str = None) → list[dict[str, Any]][source]#
-

Audiobooks > Get Several Audiobooks: Get Spotify catalog -information for several audiobooks identified by their Spotify -IDs.

-
-

Note

-

Audiobooks are only available for the US, UK, Ireland, New -Zealand, and Australia markets.

-
-
-
Parameters:
-
-
idsint, str, or list

A (comma-separated) list of the Spotify IDs for the -audiobooks.

-

Maximum: 50 IDs.

-

Example: "18yVqkdbdRvS24c0Ilj2ci, -1HGw3J3NxZO1TP1BTtVhpZ, 7iHfbu1YPACw6oZPAFJtqe".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
audiobooksdict or list

A list containing Spotify catalog information for multiple -audiobooks.

-
-

Sample response

-
[
-  {
-    "authors": [
-      {
-        "name": <str>
-      }
-    ],
-    "available_markets": [<str>],
-    "copyrights": [
-      {
-        "text": <str>,
-        "type": <str>
-      }
-    ],
-    "description": <str>,
-    "html_description": <str>,
-    "edition": <str>,
-    "explicit": <bool>,
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "languages": [<str>],
-    "media_type": <str>,
-    "name": <str>,
-    "narrators": [
-      {
-        "name": <str>
-      }
-    ],
-    "publisher": <str>,
-    "type": "audiobook",
-    "uri": <str>,
-    "total_chapters": <int>,
-    "chapters": {
-      "href": <str>,
-      "limit": <int>,
-      "next": <str>,
-      "offset": <int>,
-      "previous": <str>,
-      "total": <int>,
-      "items": [
-        {
-          "audio_preview_url": <str>,
-          "available_markets": [<str>],
-          "chapter_number": <int>,
-          "description": <str>,
-          "html_description": <str>,
-          "duration_ms": <int>,
-          "explicit": <bool>,
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "images": [
-            {
-              "url": <str>,
-              "height": <int>,
-              "width": <int>
-            }
-          ],
-          "is_playable": <bool>
-          "languages": [<str>],
-          "name": <str>,
-          "release_date": <str>,
-          "release_date_precision": <str>,
-          "resume_point": {
-            "fully_played": <bool>,
-            "resume_position_ms": <int>
-          },
-          "type": "episode",
-          "uri": <str>,
-          "restrictions": {
-            "reason": <str>
-          }
-        }
-      ]
-    }
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_categories(*, country: str = None, limit: int = None, locale: str = None, offset: int = None) → dict[str, Any][source]#
-

Categories > Get Several Browse Categories: Get a list of categories used to -tag items in Spotify (on, for example, the Spotify player’s -“Browse” tab).

-
-
Parameters:
-
-
countrystr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. Provide this parameter -to ensure that the category exists for a particular country.

-

Example: "SE".

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
localestr, keyword-only, optional

The desired language, consisting of an ISO 639-1 language -code and an ISO 3166-1 alpha-2 country code, joined by an -underscore. Provide this parameter if you want the category -strings returned in a particular language.

-
-

Note

-

If locale is not supplied, or if the specified language -is not available, the category strings returned will be -in the Spotify default language (American English).

-
-

Example: "es_MX" for “Spanish (Mexico)”.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
categoriesdict

A dictionary containing nformation for the browse categories -and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-    "items": [
-      {
-        "href": <str>,
-        "icons": [
-          {
-            "height": <int>,
-            "url": <str>,
-            "width": <int>
-          }
-        ],
-        "id": <str>,
-        "name": <str>
-      }
-    ],
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>
-}
-
-
-
-
-
-
-
-
- -
-
-get_category(category_id: str, *, country: str = None, locale: str = None) → dict[str, Any][source]#
-

Categories > Get Single Browse Category: Get a single category used to -tag items in Spotify (on, for example, the Spotify player’s -“Browse” tab).

-
-
Parameters:
-
-
category_idstr

The Spotify category ID for the category.

-

Example: "dinner".

-
-
countrystr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. Provide this parameter -to ensure that the category exists for a particular country.

-

Example: "SE".

-
-
localestr, keyword-only, optional

The desired language, consisting of an ISO 639-1 language -code and an ISO 3166-1 alpha-2 country code, joined by an -underscore. Provide this parameter if you want the category -strings returned in a particular language.

-
-

Note

-

If locale is not supplied, or if the specified language -is not available, the category strings returned will be -in the Spotify default language (American English).

-
-

Example: "es_MX" for “Spanish (Mexico)”.

-
-
-
-
Returns:
-
-
categorydict

Information for a single browse category.

-
-

Sample response

-
{
-  "href": <str>,
-  "icons": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "id": <str>,
-  "name": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_category_playlists(category_id: str, *, country: str = None, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Playlists > Get Category’s Playlists: Get a list of Spotify playlists -tagged with a particular category.

-
-
Parameters:
-
-
category_idstr

The Spotify category ID for the category.

-

Example: "dinner".

-
-
countrystr, keyword-only, optional

A country: an ISO 3166-1 alpha-2 country code. Provide this -parameter to ensure that the category exists for a -particular country.

-

Example: "SE".

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Valid values: offset must be between 0 and 1,000.

-

Default: 0.

-
-
-
-
Returns:
-
-
playlistsdict

A dictionary containing a message and a list of playlists in -a particular category.

-
-

Sample response

-
{
-  "message": <str>,
-  "playlists": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "collaborative": <bool>,
-        "description": <str>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "owner": {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "followers": {
-            "href": <str>,
-            "total": <int>
-          },
-          "href": <str>,
-          "id": <str>,
-          "type": "user",
-          "uri": <str>,
-          "display_name": <str>
-        },
-        "public": <bool>,
-        "snapshot_id": <str>,
-        "tracks": {
-          "href": <str>,
-          "total": <int>
-        },
-        "type": <str>,
-        "uri": <str>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_chapter(id: str, *, market: str = None) → dict[str, Any][source]#
-

Chapters > Get a Chapter: -Get Spotify catalog information for a single chapter.

-
-

Note

-

Chapters are only available for the US, UK, Ireland, New -Zealand, and Australia markets.

-
-
-
Parameters:
-
-
idstr

The Spotify ID for the chapter.

-

Example: "0D5wENdkdwbqlrHoaJ9g29".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
chapterdict

Spotify catalog information for a single chapter.

-
-

Sample response

-
{
-  "audio_preview_url": <str>,
-  "available_markets": [<str>],
-  "chapter_number": <int>,
-  "description": <str>,
-  "html_description": <str>,
-  "duration_ms": <int>,
-  "explicit": <bool>,
-  "external_urls": {
-    "spotify": <str>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "is_playable": <bool>
-  "languages": [<str>],
-  "name": <str>,
-  "release_date": <str>,
-  "release_date_precision": <str>,
-  "resume_point": {
-    "fully_played": <bool>,
-    "resume_position_ms": <int>
-  },
-  "type": "episode",
-  "uri": <str>,
-  "restrictions": {
-    "reason": <str>
-  },
-  "audiobook": {
-    "authors": [
-      {
-        "name": <str>
-      }
-    ],
-    "available_markets": [<str>],
-    "copyrights": [
-      {
-        "text": <str>,
-        "type": <str>
-      }
-    ],
-    "description": <str>,
-    "html_description": <str>,
-    "edition": <str>,
-    "explicit": <bool>,
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "languages": [<str>],
-    "media_type": <str>,
-    "name": <str>,
-    "narrators": [
-      {
-        "name": <str>
-      }
-    ],
-    "publisher": <str>,
-    "type": "audiobook",
-    "uri": <str>,
-    "total_chapters": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_chapters(ids: int | str | list[int | str], *, market: str = None) → list[dict[str, Any]][source]#
-

Chapters > Get Several Chapters: Get Spotify catalog information for -several chapters identified by their Spotify IDs.

-
-

Note

-

Chapters are only available for the US, UK, Ireland, New -Zealand, and Australia markets.

-
-
-
Parameters:
-
-
idsint, str, or list

A (comma-separated) list of the Spotify IDs for the -chapters.

-

Maximum: 50 IDs.

-

Example: "0IsXVP0JmcB2adSE338GkK, -3ZXb8FKZGU0EHALYX6uCzU, 0D5wENdkdwbqlrHoaJ9g29".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
chapterslist

A list containing Spotify catalog information for multiple -chapters.

-
-

Sample response

-
[
-  {
-    "audio_preview_url": <str>,
-    "available_markets": [<str>],
-    "chapter_number": <int>,
-    "description": <str>,
-    "html_description": <str>,
-    "duration_ms": <int>,
-    "explicit": <bool>,
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "is_playable": <bool>
-    "languages": [<str>],
-    "name": <str>,
-    "release_date": <str>,
-    "release_date_precision": <str>,
-    "resume_point": {
-      "fully_played": <bool>,
-      "resume_position_ms": <int>
-    },
-    "type": "episode",
-    "uri": <str>,
-    "restrictions": {
-      "reason": <str>
-    },
-    "audiobook": {
-      "authors": [
-        {
-          "name": <str>
-        }
-      ],
-      "available_markets": [<str>],
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "description": <str>,
-      "html_description": <str>,
-      "edition": <str>,
-      "explicit": <bool>,
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "languages": [<str>],
-      "media_type": <str>,
-      "name": <str>,
-      "narrators": [
-        {
-          "name": <str>
-        }
-      ],
-      "publisher": <str>,
-      "type": "audiobook",
-      "uri": <str>,
-      "total_chapters": <int>
-    }
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_currently_playing(*, market: str = None, additional_types: str = None) → dict[str, Any][source]#
-

Player > Get Currently Playing Track: Get the object -currently being played on the user’s Spotify account.

-
-

Authorization scope

-

Requires the user-read-currently-playing scope.

-
-
-
Parameters:
-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
additional_typesstr, keyword-only, optional

A comma-separated list of item types that your client -supports besides the default track type.

-
-

Note

-

This parameter was introduced to allow existing clients -to maintain their current behavior and might be -deprecated in the future.

-
-

Valid: "track" and "episode".

-
-
-
-
Returns:
-
-
itemdict

Information about the object currently being played.

-
-

Sample response

-
{
-  "device": {
-    "id": <str>,
-    "is_active": <bool>,
-    "is_private_session": <bool>,
-    "is_restricted": <bool>,
-    "name": <str>,
-    "type": <str>,
-    "volume_percent": <int>
-  },
-  "repeat_state": <str>,
-  "shuffle_state": <bool>,
-  "context": {
-    "type": <str>,
-    "href": <str>,
-    "external_urls": {
-      "spotify": <str>
-    },
-    "uri": <str>
-  },
-  "timestamp": <int>,
-  "progress_ms": <int>,
-  "is_playing": <bool>,
-  "item": {
-    "album": {
-      "album_type": <str>,
-      "total_tracks": <int>,
-      "available_markets": [<str>],
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "restrictions": {
-        "reason": <str>
-      },
-      "type": "album",
-      "uri": <str>,
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "genres": [<str>],
-      "label": <str>,
-      "popularity": <int>,
-      "album_group": <str>,
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "name": <str>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ]
-    },
-    "artists": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "genres": [<str>],
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "popularity": <int>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ],
-    "available_markets": [<str>],
-    "disc_number": <int>,
-    "duration_ms": <int>,
-    "explicit": <bool>,
-    "external_ids": {
-      "isrc": <str>,
-      "ean": <str>,
-      "upc": <str>
-    },
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "is_playable": <bool>
-    "linked_from": {
-    },
-    "restrictions": {
-      "reason": <str>
-    },
-    "name": <str>,
-    "popularity": <int>,
-    "preview_url": <str>,
-    "track_number": <int>,
-    "type": "track",
-    "uri": <str>,
-    "is_local": <bool>
-  },
-  "currently_playing_type": <str>,
-  "actions": {
-    "interrupting_playback": <bool>,
-    "pausing": <bool>,
-    "resuming": <bool>,
-    "seeking": <bool>,
-    "skipping_next": <bool>,
-    "skipping_prev": <bool>,
-    "toggling_repeat_context": <bool>,
-    "toggling_shuffle": <bool>,
-    "toggling_repeat_track": <bool>,
-    "transferring_playback": <bool>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_devices() → list[dict[str, Any]][source]#
-

Player > Get Available Devices: Get information about a user’s -available devices.

-
-

Authorization scope

-

Requires the user-read-playback-state scope.

-
-
-
Returns:
-
-
deviceslist

A list containing information about the available devices.

-
-

Sample response

-
[
-  {
-    "devices": [
-      {
-        "id": <str>,
-        "is_active": <bool>,
-        "is_private_session": <bool>,
-        "is_restricted": <bool>,
-        "name": <str>,
-        "type": <str>,
-        "volume_percent": <int>
-      }
-    ]
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_episode(id: str, *, market: str = None) → dict[str, Any][source]#
-

Episodes > Get Episode: Get Spotify catalog information for a single -episode identified by its unique Spotify ID.

-
-
Parameters:
-
-
idstr

The Spotify ID for the episode.

-

Example: "512ojhOuo1ktJprKbVcKyQ".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
episodedict

Spotify catalog information for a single episode.

-
-

Sample response

-
{
-  "audio_preview_url": <str>,
-  "description": <str>,
-  "html_description": <str>,
-  "duration_ms": <int>,
-  "explicit": <bool>,
-  "external_urls": {
-    "spotify": <str>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "is_externally_hosted": <bool>,
-  "is_playable": <bool>
-  "language": <str>,
-  "languages": [<str>],
-  "name": <str>,
-  "release_date": <str>,
-  "release_date_precision": <str>,
-  "resume_point": {
-    "fully_played": <bool>,
-    "resume_position_ms": <int>
-  },
-  "type": "episode",
-  "uri": <str>,
-  "restrictions": {
-    "reason": <str>
-  },
-  "show": {
-    "available_markets": [<str>],
-    "copyrights": [
-      {
-        "text": <str>,
-        "type": <str>
-      }
-    ],
-    "description": <str>,
-    "html_description": <str>,
-    "explicit": <bool>,
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "is_externally_hosted": <bool>,
-    "languages": [<str>],
-    "media_type": <str>,
-    "name": <str>,
-    "publisher": <str>,
-    "type": "show",
-    "uri": <str>,
-    "total_episodes": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_episodes(ids: int | str | list[int | str], *, market: str = None) → list[dict[str, Any]][source]#
-

Episodes > Get Several Episodes: Get Spotify catalog -information for several episodes based on their Spotify IDs.

-
-
Parameters:
-
-
idsint, str, or list

A (comma-separated) list of the Spotify IDs for the episodes.

-

Maximum: 50 IDs.

-

Example: -"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
episodeslist

A list containing Spotify catalog information for multiple -episodes.

-
-

Sample

-
[
-  {
-    "audio_preview_url": <str>,
-    "description": <str>,
-    "html_description": <str>,
-    "duration_ms": <int>,
-    "explicit": <bool>,
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "is_externally_hosted": <bool>,
-    "is_playable": <bool>
-    "language": <str>,
-    "languages": [<str>],
-    "name": <str>,
-    "release_date": <str>,
-    "release_date_precision": <str>,
-    "resume_point": {
-      "fully_played": <bool>,
-      "resume_position_ms": <int>
-    },
-    "type": "episode",
-    "uri": <str>,
-    "restrictions": {
-      "reason": <str>
-    },
-    "show": {
-      "available_markets": [<str>],
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "description": <str>,
-      "html_description": <str>,
-      "explicit": <bool>,
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "is_externally_hosted": <bool>,
-      "languages": [<str>],
-      "media_type": <str>,
-      "name": <str>,
-      "publisher": <str>,
-      "type": "show",
-      "uri": <str>,
-      "total_episodes": <int>
-    }
-  }
-]
-
-
-
-
-
-
-
-
- -
- -

Playlists > Get Featured Playlists: Get a list of Spotify featured -playlists (shown, for example, on a Spotify player’s ‘Browse’ -tab).

-
-
Parameters:
-
-
countrystr, keyword-only, optional

A country: an ISO 3166-1 alpha-2 country code. Provide this -parameter if you want the list of returned items to be -relevant to a particular country. If omitted, the returned -items will be relevant to all countries.

-

Example: "SE".

-
-
localestr, keyword-only, optional

The desired language, consisting of an ISO 639-1 language -code and an ISO 3166-1 alpha-2 country code, joined by an -underscore. Provide this parameter if you want the category -strings returned in a particular language.

-
-

Note

-

If locale is not supplied, or if the specified language -is not available, the category strings returned will be -in the Spotify default language (American English).

-
-

Example: "es_MX" for “Spanish (Mexico)”.

-
-
timestampstr, keyword-only, optional

A timestamp in ISO 8601 format: yyyy-MM-ddTHH:mm:ss. Use -this parameter to specify the user’s local time to get -results tailored for that specific date and time in the day. -If there were no featured playlists (or there is no data) at -the specified time, the response will revert to the current -UTC time. If not provided, the response defaults to the -current UTC time.

-

Example: "2014-10-23T09:00:00" for a user whose -local time is 9 AM.

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
playlistsdict

A dictionary containing a message and a list of featured -playlists.

-
-

Sample response

-
{
-  "message": <str>,
-  "playlists": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "collaborative": <bool>,
-        "description": <str>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "owner": {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "followers": {
-            "href": <str>,
-            "total": <int>
-          },
-          "href": <str>,
-          "id": <str>,
-          "type": "user",
-          "uri": <str>,
-          "display_name": <str>
-        },
-        "public": <bool>,
-        "snapshot_id": <str>,
-        "tracks": {
-          "href": <str>,
-          "total": <int>
-        },
-        "type": <str>,
-        "uri": <str>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_followed_artists(*, after: str = None, limit: int = None) → dict[str, Any][source]#
-

Users > Get Followed Artists: -Get the current user’s followed artists.

-
-

Authorization scope

-

Requires the user-follow-read scope.

-
-
-
Parameters:
-
-
afterstr, keyword-only, optional

The last artist ID retrieved from the previous request.

-

Example: "0I2XqVXqHScXjHhk6AYYRe"

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
-
-
Returns:
-
-
artistsdict

A dictionary containing Spotify catalog information for a -user’s followed artists and the number of results returned.

-
-

Sample response

-
{
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "cursors": {
-      "after": <str>,
-      "before": <str>
-    },
-    "total": <int>,
-    "items": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "genres": [<str>],
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "popularity": <int>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ]
-  }
-
-
-
-
-
-
-
-
- -
-
-get_genre_seeds() → list[str][source]#
-

Genres > Get Available Genre Seeds: Retrieve a list of -available genres seed parameter values for use in -get_recommendations().

-
-
Returns:
-
-
genreslist

Array of genres.

-

Example: ["acoustic", "afrobeat", ...].

-
-
-
-
-
- -
-
-get_markets() → list[str][source]#
-

Markets > Get Available Markets: Get the list of markets where Spotify -is available.

-
-
Returns:
-
-
marketslist

Array of country codes.

-

Example: ["CA", "BR", "IT"].

-
-
-
-
-
- -
-
-get_new_albums(*, country: str = None, limit: int = None, offset: int = None) → list[dict[str, Any]][source]#
-

Albums > Get New Releases: Get a list of new album releases featured -in Spotify (shown, for example, on a Spotify player’s “Browse” -tab).

-
-
Parameters:
-
-
countrystr, keyword-only, optional

A country: an ISO 3166-1 alpha-2 country code. Provide this -parameter if you want the list of returned items to be -relevant to a particular country. If omitted, the returned -items will be relevant to all countries.

-

Example: "SE".

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Valid values: offset must be between 0 and 1,000.

-

Default: 0.

-
-
-
-
Returns:
-
-
albumslist

A list containing Spotify catalog information for -newly-released albums.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "album_type": <str>,
-      "total_tracks": <int>,
-      "available_markets": [<str>],
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "restrictions": {
-        "reason": <str>
-      },
-      "type": "album",
-      "uri": <str>,
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "genres": [<str>],
-      "label": <str>,
-      "popularity": <int>,
-      "album_group": <str>,
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "name": <str>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ]
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_personal_playlists(*, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Playlist > Get Current User’s Playlists: Get a list of the -playlists owned or followed by the current Spotify user.

-
-

Authorization scope

-

Requires the playlist-read-private and the -playlist-read-collaborative scopes.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
playlistsdict

A dictionary containing the current user’s playlists and the -number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "collaborative": <bool>,
-      "description": <str>,
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "owner": {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "href": <str>,
-        "id": <str>,
-        "type": "user",
-        "uri": <str>,
-        "display_name": <str>
-      },
-      "public": <bool>,
-      "snapshot_id": <str>,
-      "tracks": {
-        "href": <str>,
-        "total": <int>
-      },
-      "type": <str>,
-      "uri": <str>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_playback_state(*, market: str = None, additional_types: str = None) → dict[str, Any][source]#
-

Player > Get Playback State: Get -information about the user’s current playback state, including -track or episode, progress, and active device.

-
-

Authorization scope

-

Requires the user-read-playback-state scope.

-
-
-
Parameters:
-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
additional_typesstr, keyword-only, optional

A comma-separated list of item types that your client -supports besides the default track type.

-
-

Note

-

This parameter was introduced to allow existing clients -to maintain their current behavior and might be -deprecated in the future.

-
-

Valid: "track" and "episode".

-
-
-
-
Returns:
-
-
statedict

Information about playback state.

-
-

Sample response

-
{
-  "device": {
-    "id": <str>,
-    "is_active": <bool>,
-    "is_private_session": <bool>,
-    "is_restricted": <bool>,
-    "name": <str>,
-    "type": <str>,
-    "volume_percent": <int>
-  },
-  "repeat_state": <str>,
-  "shuffle_state": <bool>,
-  "context": {
-    "type": <str>,
-    "href": <str>,
-    "external_urls": {
-      "spotify": <str>
-    },
-    "uri": <str>
-  },
-  "timestamp": <int>,
-  "progress_ms": <int>,
-  "is_playing": <bool>,
-  "item": {
-    "album": {
-      "album_type": <str>,
-      "total_tracks": <int>,
-      "available_markets": [<str>],
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "restrictions": {
-        "reason": <str>
-      },
-      "type": "album",
-      "uri": <str>,
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "genres": [<str>],
-      "label": <str>,
-      "popularity": <int>,
-      "album_group": <str>,
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "name": <str>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ]
-    },
-    "artists": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "genres": [<str>],
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "popularity": <int>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ],
-    "available_markets": [<str>],
-    "disc_number": <int>,
-    "duration_ms": <int>,
-    "explicit": <bool>,
-    "external_ids": {
-      "isrc": <str>,
-      "ean": <str>,
-      "upc": <str>
-    },
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "is_playable": <bool>
-    "linked_from": {
-    },
-    "restrictions": {
-      "reason": <str>
-    },
-    "name": <str>,
-    "popularity": <int>,
-    "preview_url": <str>,
-    "track_number": <int>,
-    "type": "track",
-    "uri": <str>,
-    "is_local": <bool>
-  },
-  "currently_playing_type": <str>,
-  "actions": {
-    "interrupting_playback": <bool>,
-    "pausing": <bool>,
-    "resuming": <bool>,
-    "seeking": <bool>,
-    "skipping_next": <bool>,
-    "skipping_prev": <bool>,
-    "toggling_repeat_context": <bool>,
-    "toggling_shuffle": <bool>,
-    "toggling_repeat_track": <bool>,
-    "transferring_playback": <bool>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_playlist(playlist_id: str, *, additional_types: str | list[str] = None, fields: str = None, market: str = None) → dict[str, Any][source]#
-

Playlists > Get Playlist: -Get a playlist owned by a Spotify user.

-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
additional_typesstr or list, keyword-only, optional

A (comma-separated) list of item types besides the default -track type.

-
-

Note

-

This parameter was introduced to allow existing clients -to maintain their current behavior and might be -deprecated in the future.

-
-

Valid values: "track" and "episode".

-
-
fieldsstr or list, keyword-only, optional

Filters for the query: a (comma-separated) list of the -fields to return. If omitted, all fields are returned. -A dot separator can be used to specify non-reoccurring -fields, while parentheses can be used to specify reoccurring -fields within objects. Use multiple parentheses to drill -down into nested objects. Fields can be excluded by -prefixing them with an exclamation mark.

-
-

Examples:

-
    -

  • "description,uri" to get just the playlist’s -description and URI,

    • -

  • "tracks.items(added_at,added_by.id)" to get just -the added date and user ID of the adder,

    • -

  • "tracks.items(track(name,href,album(name,href)))" -to drill down into the album, and

    • -

  • "tracks.items(track(name,href,album(!name,href)))" -to exclude the album name.

    • -
-
-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
playlistdict

Spotify catalog information for a single playlist.

-
-

Sample response

-
{
-  "collaborative": <bool>,
-  "description": <str>,
-  "external_urls": {
-    "spotify": <str>
-  },
-  "followers": {
-    "href": <str>,
-    "total": <int>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "name": <str>,
-  "owner": {
-    "external_urls": {
-      "spotify": <str>
-    },
-    "followers": {
-      "href": <str>,
-      "total": <int>
-    },
-    "href": <str>,
-    "id": <str>,
-    "type": "user",
-    "uri": <str>,
-    "display_name": <str>
-  },
-  "public": <bool>,
-  "snapshot_id": <str>,
-  "tracks": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "added_at": <str>,
-        "added_by": {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "followers": {
-            "href": <str>,
-            "total": <int>
-          },
-          "href": <str>,
-          "id": <str>,
-          "type": "user",
-          "uri": <str>
-        },
-        "is_local": <bool>,
-        "track": {
-          "album": {
-            "album_type": <str>,
-            "total_tracks": <int>,
-            "available_markets": [<str>],
-            "external_urls": {
-              "spotify": <str>
-            },
-            "href": <str>,
-            "id": <str>,
-            "images": [
-              {
-                "url": <str>,
-                "height": <int>,
-                "width": <int>
-              }
-            ],
-            "name": <str>,
-            "release_date": <str>,
-            "release_date_precision": <str>,
-            "restrictions": {
-              "reason": <str>
-            },
-            "type": "album",
-            "uri": <str>,
-            "copyrights": [
-              {
-                "text": <str>,
-                "type": <str>
-              }
-            ],
-            "external_ids": {
-              "isrc": <str>,
-              "ean": <str>,
-              "upc": <str>
-            },
-            "genres": [<str>],
-            "label": <str>,
-            "popularity": <int>,
-            "album_group": <str>,
-            "artists": [
-              {
-                "external_urls": {
-                  "spotify": <str>
-                },
-                "href": <str>,
-                "id": <str>,
-                "name": <str>,
-                "type": "artist",
-                "uri": <str>
-              }
-            ]
-          },
-          "artists": [
-            {
-              "external_urls": {
-                "spotify": <str>
-              },
-              "followers": {
-                "href": <str>,
-                "total": <int>
-              },
-              "genres": [<str>],
-              "href": <str>,
-              "id": <str>,
-              "images": [
-                {
-                  "url": <str>,
-                  "height": <int>,
-                  "width": <int>
-                }
-              ],
-              "name": <str>,
-              "popularity": <int>,
-              "type": "artist",
-              "uri": <str>
-            }
-          ],
-          "available_markets": [<str>],
-          "disc_number": <int>,
-          "duration_ms": <int>,
-          "explicit": <bool>,
-          "external_ids": {
-            "isrc": <str>,
-            "ean": <str>,
-            "upc": <str>
-          },
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "is_playable": <bool>
-          "linked_from": {
-          },
-          "restrictions": {
-            "reason": <str>
-          },
-          "name": <str>,
-          "popularity": <int>,
-          "preview_url": <str>,
-          "track_number": <int>,
-          "type": "track",
-          "uri": <str>,
-          "is_local": <bool>
-        }
-      }
-    ]
-  },
-  "type": <str>,
-  "uri": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_playlist_cover_image(playlist_id: str) → dict[str, Any][source]#
-

Playlists > Get Playlist Cover Image: Get the current image associated with a -specific playlist.

-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
-
-
Returns:
-
-
imagedict

A dictionary containing the URL to and the dimensions of -the playlist cover image.

-
-

Sample response

-
{
-  "url": <str>,
-  "height": <int>,
-  "width": <int>
-}
-
-
-
-
-
-
-
-
- -
-
-get_playlist_items(playlist_id: str, *, additional_types: str | list[str] = None, fields: str = None, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#
-

Playlists > Get Playlist Items: Get full details of the items of a -playlist owned by a Spotify user.

-
-

Authorization scope

-

Requires the playlist-modify-private scope.

-
-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
additional_typesstr or list, keyword-only, optional

A (comma-separated) list of item types besides the default -track type.

-
-

Note

-

This parameter was introduced to allow existing clients -to maintain their current behavior and might be -deprecated in the future.

-
-

Valid values: "track" and "episode".

-
-
fieldsstr or list, keyword-only, optional

Filters for the query: a (comma-separated) list of the -fields to return. If omitted, all fields are returned. -A dot separator can be used to specify non-reoccurring -fields, while parentheses can be used to specify reoccurring -fields within objects. Use multiple parentheses to drill -down into nested objects. Fields can be excluded by -prefixing them with an exclamation mark.

-
-

Examples:

-
    -

  • "description,uri" to get just the playlist’s -description and URI,

    • -

  • "tracks.items(added_at,added_by.id)" to get just -the added date and user ID of the adder,

    • -

  • "tracks.items(track(name,href,album(name,href)))" -to drill down into the album, and

    • -

  • "tracks.items(track(name,href,album(!name,href)))" -to exclude the album name.

    • -
-
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
itemsdict

A dictionary containing Spotify catalog information for the -playlist items and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "added_at": <str>,
-      "added_by": {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "href": <str>,
-        "id": <str>,
-        "type": "user",
-        "uri": <str>
-      },
-      "is_local": <bool>,
-      "track": {
-        "album": {
-          "album_type": <str>,
-          "total_tracks": <int>,
-          "available_markets": [<str>],
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "images": [
-            {
-              "url": <str>,
-              "height": <int>,
-              "width": <int>
-            }
-          ],
-          "name": <str>,
-          "release_date": <str>,
-          "release_date_precision": <str>,
-          "restrictions": {
-            "reason": <str>
-          },
-          "type": "album",
-          "uri": <str>,
-          "copyrights": [
-            {
-              "text": <str>,
-              "type": <str>
-            }
-          ],
-          "external_ids": {
-            "isrc": <str>,
-            "ean": <str>,
-            "upc": <str>
-          },
-          "genres": [<str>],
-          "label": <str>,
-          "popularity": <int>,
-          "album_group": <str>,
-          "artists": [
-            {
-              "external_urls": {
-                "spotify": <str>
-              },
-              "href": <str>,
-              "id": <str>,
-              "name": <str>,
-              "type": "artist",
-              "uri": <str>
-            }
-          ]
-        },
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "followers": {
-              "href": <str>,
-              "total": <int>
-            },
-            "genres": [<str>],
-            "href": <str>,
-            "id": <str>,
-            "images": [
-              {
-                "url": <str>,
-                "height": <int>,
-                "width": <int>
-              }
-            ],
-            "name": <str>,
-            "popularity": <int>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ],
-        "available_markets": [<str>],
-        "disc_number": <int>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_ids": {
-          "isrc": <str>,
-          "ean": <str>,
-          "upc": <str>
-        },
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "is_playable": <bool>
-        "linked_from": {
-        },
-        "restrictions": {
-          "reason": <str>
-        },
-        "name": <str>,
-        "popularity": <int>,
-        "preview_url": <str>,
-        "track_number": <int>,
-        "type": "track",
-        "uri": <str>,
-        "is_local": <bool>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_profile() → dict[str, Any][source]#
-

Users > Get Current User’s Profile: Get detailed profile -information about the current user (including the current user’s -username).

-
-

Authorization scope

-

Requires the user-read-private scope.

-
-
-
Returns:
-
-
userdict

A dictionary containing the current user’s information.

-
-

Sample response

-
{
-  "country": <str>,
-  "display_name": <str>,
-  "email": <str>,
-  "explicit_content": {
-    "filter_enabled": <bool>,
-    "filter_locked": <bool>
-  },
-  "external_urls": {
-    "spotify": <str>
-  },
-  "followers": {
-    "href": <str>,
-    "total": <int>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "product": <str>,
-  "type": <str>,
-  "uri": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_queue() → dict[str, Any][source]#
-

Player > Get the User’s Queue: Get the list of -objects that make up the user’s queue.

-
-

Authorization scope

-

Requires the user-read-playback-state scope.

-
-
-
Returns:
-
-
queuedict

Information about the user’s queue, such as the currently -playing item and items in the queue.

-
-

Sample

-
{
-  "currently_playing": {
-    "album": {
-      "album_type": <str>,
-      "total_tracks": <int>,
-      "available_markets": [<str>],
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "restrictions": {
-        "reason": <str>
-      },
-      "type": "album",
-      "uri": <str>,
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "genres": [<str>],
-      "label": <str>,
-      "popularity": <int>,
-      "album_group": <str>,
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "name": <str>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ]
-    },
-    "artists": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "genres": [<str>],
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "popularity": <int>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ],
-    "available_markets": [<str>],
-    "disc_number": <int>,
-    "duration_ms": <int>,
-    "explicit": <bool>,
-    "external_ids": {
-      "isrc": <str>,
-      "ean": <str>,
-      "upc": <str>
-    },
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "is_playable": <bool>
-    "linked_from": {
-    },
-    "restrictions": {
-      "reason": <str>
-    },
-    "name": <str>,
-    "popularity": <int>,
-    "preview_url": <str>,
-    "track_number": <int>,
-    "type": "track",
-    "uri": <str>,
-    "is_local": <bool>
-  },
-  "queue": [
-    {
-      "album": {
-        "album_type": <str>,
-        "total_tracks": <int>,
-        "available_markets": [<str>],
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "release_date": <str>,
-        "release_date_precision": <str>,
-        "restrictions": {
-          "reason": <str>
-        },
-        "type": "album",
-        "uri": <str>,
-        "copyrights": [
-          {
-            "text": <str>,
-            "type": <str>
-          }
-        ],
-        "external_ids": {
-          "isrc": <str>,
-          "ean": <str>,
-          "upc": <str>
-        },
-        "genres": [<str>],
-        "label": <str>,
-        "popularity": <int>,
-        "album_group": <str>,
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "href": <str>,
-            "id": <str>,
-            "name": <str>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ]
-      },
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "followers": {
-            "href": <str>,
-            "total": <int>
-          },
-          "genres": [<str>],
-          "href": <str>,
-          "id": <str>,
-          "images": [
-            {
-              "url": <str>,
-              "height": <int>,
-              "width": <int>
-            }
-          ],
-          "name": <str>,
-          "popularity": <int>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ],
-      "available_markets": [<str>],
-      "disc_number": <int>,
-      "duration_ms": <int>,
-      "explicit": <bool>,
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "is_playable": <bool>
-      "linked_from": {
-      },
-      "restrictions": {
-        "reason": <str>
-      },
-      "name": <str>,
-      "popularity": <int>,
-      "preview_url": <str>,
-      "track_number": <int>,
-      "type": "track",
-      "uri": <str>,
-      "is_local": <bool>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_recently_played(*, limit: int = None, after: int = None, before: int = None) → dict[str, Any][source]#
-

Player > Get Recently Played Tracks: Get tracks from the current user’s -recently played tracks.

-
-

Note

-

Currently doesn’t support podcast episodes.

-
-
-

Authorization scope

-

Requires the user-read-recently-played scope.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
afterint, keyword-only, optional

A Unix timestamp in milliseconds. Returns all items after -(but not including) this cursor position. If after is -specified, before must not be specified.

-

Example: 1484811043508.

-
-
beforeint, keyword-only, optional

A Unix timestamp in milliseconds. Returns all items before -(but not including) this cursor position. If before is -specified, after must not be specified.

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing Spotify catalog information for -the recently played tracks and the number of results -returned.

-
-

Sample

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "cursors": {
-    "after": <str>,
-    "before": <str>
-  },
-  "total": <int>,
-  "items": [
-    {
-      "track": {
-        "album": {
-          "album_type": <str>,
-          "total_tracks": <int>,
-          "available_markets": [<str>],
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "images": [
-            {
-              "url": <str>,
-              "height": <int>,
-              "width": <int>
-            }
-          ],
-          "name": <str>,
-          "release_date": <str>,
-          "release_date_precision": <str>,
-          "restrictions": {
-            "reason": <str>
-          },
-          "type": "album",
-          "uri": <str>,
-          "copyrights": [
-            {
-              "text": <str>,
-              "type": <str>
-            }
-          ],
-          "external_ids": {
-            "isrc": <str>,
-            "ean": <str>,
-            "upc": <str>
-          },
-          "genres": [<str>],
-          "label": <str>,
-          "popularity": <int>,
-          "album_group": <str>,
-          "artists": [
-            {
-              "external_urls": {
-                "spotify": <str>
-              },
-              "href": <str>,
-              "id": <str>,
-              "name": <str>,
-              "type": "artist",
-              "uri": <str>
-            }
-          ]
-        },
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "followers": {
-              "href": <str>,
-              "total": <int>
-            },
-            "genres": [<str>],
-            "href": <str>,
-            "id": <str>,
-            "images": [
-              {
-                "url": <str>,
-                "height": <int>,
-                "width": <int>
-              }
-            ],
-            "name": <str>,
-            "popularity": <int>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ],
-        "available_markets": [<str>],
-        "disc_number": <int>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_ids": {
-          "isrc": <str>,
-          "ean": <str>,
-          "upc": <str>
-        },
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "is_playable": <bool>
-        "linked_from": {
-        },
-        "restrictions": {
-          "reason": <str>
-        },
-        "name": <str>,
-        "popularity": <int>,
-        "preview_url": <str>,
-        "track_number": <int>,
-        "type": "track",
-        "uri": <str>,
-        "is_local": <bool>
-      },
-      "played_at": <str>,
-      "context": {
-        "type": <str>,
-        "href": <str>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "uri": <str>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_recommendations(seed_artists: str | list[str] = None, seed_genres: str | list[str] = None, seed_tracks: str | list[str] = None, *, limit: int = None, market: str = None, **kwargs) → list[dict[str, Any]][source]#
-

Tracks > Get Recommendations: Recommendations are generated based on -the available information for a given seed entity and matched -against similar artists and tracks. If there is sufficient -information about the provided seeds, a list of tracks will be -returned together with pool size details.

-

For artists and tracks that are very new or obscure, there might -not be enough data to generate a list of tracks.

-
-

Important

-

Spotify content may not be used to train machine learning or -AI models.

-
-
-
Parameters:
-
-
seed_artistsstr, optional

A comma separated list of Spotify IDs for seed artists.

-

Maximum: Up to 5 seed values may be provided in any -combination of seed_artists, seed_tracks, and -seed_genres.

-

Example: "4NHQUGzhtTLFvgF5SZesLK".

-
-
seed_genresstr, optional

A comma separated list of any genres in the set of available -genre seeds.

-

Maximum: Up to 5 seed values may be provided in any -combination of seed_artists, seed_tracks, and -seed_genres.

-

Example: "classical,country".

-
-
seed_tracksstr, optional

A comma separated list of Spotify IDs for a seed track.

-

Maximum: Up to 5 seed values may be provided in any -combination of seed_artists, seed_tracks, and -seed_genres.

-

Example: "0c6xIDDpzE81m2q797ordA".

-
-
limitint, keyword-only, optional

The target size of the list of recommended tracks. For seeds -with unusually small pools or when highly restrictive -filtering is applied, it may be impossible to generate the -requested number of recommended tracks. Debugging -information for such cases is available in the response.

-

Minimum: 1.

-

Maximum: 100.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
**kwargs

Tunable track attributes. For a list of available options, -see the Spotify Web API Reference page for this endpoint.

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing Spotify catalog information for the -recommended tracks.

-
-

Sample response

-
{
-  "seeds": [
-    {
-      "afterFilteringSize": <int>,
-      "afterRelinkingSize": <int>,
-      "href": <str>,
-      "id": <str>,
-      "initialPoolSize": <int>,
-      "type": <str>
-    }
-  ],
-  "tracks": [
-    {
-      "album": {
-        "album_type": <str>,
-        "total_tracks": <int>,
-        "available_markets": [<str>],
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "release_date": <str>,
-        "release_date_precision": <str>,
-        "restrictions": {
-          "reason": <str>
-        },
-        "type": "album",
-        "uri": <str>,
-        "copyrights": [
-          {
-            "text": <str>,
-            "type": <str>
-          }
-        ],
-        "external_ids": {
-          "isrc": <str>,
-          "ean": <str>,
-          "upc": <str>
-        },
-        "genres": [<str>],
-        "label": <str>,
-        "popularity": <int>,
-        "album_group": <str>,
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "href": <str>,
-            "id": <str>,
-            "name": <str>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ]
-      },
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "followers": {
-            "href": <str>,
-            "total": <int>
-          },
-          "genres": [<str>],
-          "href": <str>,
-          "id": <str>,
-          "images": [
-            {
-              "url": <str>,
-              "height": <int>,
-              "width": <int>
-            }
-          ],
-          "name": <str>,
-          "popularity": <int>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ],
-      "available_markets": [<str>],
-      "disc_number": <int>,
-      "duration_ms": <int>,
-      "explicit": <bool>,
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "is_playable": <bool>
-      "linked_from": {
-      },
-      "restrictions": {
-        "reason": <str>
-      },
-      "name": <str>,
-      "popularity": <int>,
-      "preview_url": <str>,
-      "track_number": <int>,
-      "type": "track",
-      "uri": <str>,
-      "is_local": <bool>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
- -

Artists > Get Artist’s Related Artists: Get Spotify -catalog information about artists similar to a given artist. -Similarity is based on analysis of the Spotify community’s -listening history.

-
-
Parameters:
-
-
idstr

The Spotify ID of the artist.

-

Example: "0TnOYISbd1XYRBk9myaseg".

-
-
-
-
Returns:
-
-
artistslist

A list containing Spotify catalog information for the -artist’s related artists.

-
-

Sample response

-
[
-  {
-    "external_urls": {
-      "spotify": <str>
-    },
-    "followers": {
-      "href": <str>,
-      "total": <int>
-    },
-    "genres": [<str>],
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "name": <str>,
-    "popularity": <int>,
-    "type": "artist",
-    "uri": <str>
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_saved_albums(*, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#
-

Albums > Get User’s Saved Albums: Get a list of the albums saved in the -current Spotify user’s ‘Your Music’ library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Valid values: offset must be between 0 and 1,000.

-

Default: 0.

-
-
-
-
Returns:
-
-
albumsdict

A dictionary containing Spotify catalog information for a -user’s saved albums and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "added_at": <str>,
-      "album": {
-        "album_type": <str>,
-        "total_tracks": <int>,
-        "available_markets": [<str>],
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "release_date": <str>,
-        "release_date_precision": <str>,
-        "restrictions": {
-          "reason": <str>
-        },
-        "type": "album",
-        "uri": <str>,
-        "copyrights": [
-          {
-            "text": <str>,
-            "type": <str>
-          }
-        ],
-        "external_ids": {
-          "isrc": <str>,
-          "ean": <str>,
-          "upc": <str>
-        },
-        "genres": [<str>],
-        "label": <str>,
-        "popularity": <int>,
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "followers": {
-              "href": <str>,
-              "total": <int>
-            },
-            "genres": [<str>],
-            "href": <str>,
-            "id": <str>,
-            "images": [
-              {
-                "url": <str>,
-                "height": <int>,
-                "width": <int>
-              }
-            ],
-            "name": <str>,
-            "popularity": <int>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ],
-        "tracks": {
-          "href": <str>,
-          "limit": <int>,
-          "next": <str>,
-          "offset": <int>,
-          "previous": <str>,
-          "total": <int>,
-          "items": [
-            {
-              "artists": [
-                {
-                  "external_urls": {
-                    "spotify": <str>
-                  },
-                  "href": <str>,
-                  "id": <str>,
-                  "name": <str>,
-                  "type": "artist",
-                  "uri": <str>
-                }
-              ],
-              "available_markets": [<str>],
-              "disc_number": <int>,
-              "duration_ms": <int>,
-              "explicit": <bool>,
-              "external_urls": {
-                "spotify": <str>
-              },
-              "href": <str>,
-              "id": <str>,
-              "is_playable": <bool>
-              "linked_from": {
-                "external_urls": {
-                  "spotify": <str>
-                },
-                "href": <str>,
-                "id": <str>,
-                "type": <str>,
-                "uri": <str>
-              },
-              "restrictions": {
-                "reason": <str>
-              },
-              "name": <str>,
-              "preview_url": <str>,
-              "track_number": <int>,
-              "type": <str>,
-              "uri": <str>,
-              "is_local": <bool>
-            }
-          ]
-        }
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_saved_audiobooks(*, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Audiobooks > Get User’s Saved Audiobooks: Get a list of the -albums saved in the current Spotify user’s audiobooks library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
audiobooksdict

A dictionary containing Spotify catalog information for a -user’s saved audiobooks and the number of results -returned.

-
-

Sample

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "authors": [
-        {
-          "name": <str>
-        }
-      ],
-      "available_markets": [<str>],
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "description": <str>,
-      "html_description": <str>,
-      "edition": <str>,
-      "explicit": <bool>,
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "languages": [<str>],
-      "media_type": <str>,
-      "name": <str>,
-      "narrators": [
-        {
-          "name": <str>
-        }
-      ],
-      "publisher": <str>,
-      "type": "audiobook",
-      "uri": <str>,
-      "total_chapters": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_saved_episodes(*, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#
-

Episodes > Get User’s Saved Episodes: Get a list of the -episodes saved in the current Spotify user’s library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
episodesdict

A dictionary containing Spotify catalog information for a -user’s saved episodes and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "added_at": <str>,
-      "episode": {
-        "audio_preview_url": <str>,
-        "description": <str>,
-        "html_description": <str>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "is_externally_hosted": <bool>,
-        "is_playable": <bool>
-        "language": <str>,
-        "languages": [<str>],
-        "name": <str>,
-        "release_date": <str>,
-        "release_date_precision": <str>,
-        "resume_point": {
-          "fully_played": <bool>,
-          "resume_position_ms": <int>
-        },
-        "type": "episode",
-        "uri": <str>,
-        "restrictions": {
-          "reason": <str>
-        },
-        "show": {
-          "available_markets": [<str>],
-          "copyrights": [
-            {
-              "text": <str>,
-              "type": <str>
-            }
-          ],
-          "description": <str>,
-          "html_description": <str>,
-          "explicit": <bool>,
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "images": [
-            {
-              "url": <str>,
-              "height": <int>,
-              "width": <int>
-            }
-          ],
-          "is_externally_hosted": <bool>,
-          "languages": [<str>],
-          "media_type": <str>,
-          "name": <str>,
-          "publisher": <str>,
-          "type": "show",
-          "uri": <str>,
-          "total_episodes": <int>
-        }
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_saved_shows(*, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Shows > Get User’s Saved Shows: Get a list of shows saved in the -current Spotify user’s library. Optional parameters can be used -to limit the number of shows returned.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Valid values: offset must be between 0 and 1,000.

-

Default: 0.

-
-
-
-
Returns:
-
-
showsdict

A dictionary containing Spotify catalog information for a -user’s saved shows and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "added_at": <str>,
-      "show": {
-        "available_markets": [
-          <str>
-        ],
-        "copyrights": [
-          {
-            "text": <str>,
-            "type": <str>
-          }
-        ],
-        "description": <str>,
-        "html_description": <str>,
-        "explicit": <bool>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "is_externally_hosted": <bool>,
-        "languages": [
-          <str>
-        ],
-        "media_type": <str>,
-        "name": <str>,
-        "publisher": <str>,
-        "type": "show",
-        "uri": <str>,
-        "total_episodes": <int>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_saved_tracks(*, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#
-

Tracks > Get User’s Saved Tracks: Get a list of the songs -saved in the current Spotify user’s ‘Your Music’ library.

-
-

Authorization scope

-

Requires the user-library-read scope.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Valid values: offset must be between 0 and 1,000.

-

Default: 0.

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing Spotify catalog information for a -user’s saved tracks and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "added_at": <str>,
-      "track": {
-        "album": {
-          "album_type": <str>,
-          "total_tracks": <int>,
-          "available_markets": [<str>],
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "images": [
-            {
-              "url": <str>,
-              "height": <int>,
-              "width": <int>
-            }
-          ],
-          "name": <str>,
-          "release_date": <str>,
-          "release_date_precision": <str>,
-          "restrictions": {
-            "reason": <str>
-          },
-          "type": "album",
-          "uri": <str>,
-          "copyrights": [
-            {
-              "text": <str>,
-              "type": <str>
-            }
-          ],
-          "external_ids": {
-            "isrc": <str>,
-            "ean": <str>,
-            "upc": <str>
-          },
-          "genres": [<str>],
-          "label": <str>,
-          "popularity": <int>,
-          "album_group": <str>,
-          "artists": [
-            {
-              "external_urls": {
-                "spotify": <str>
-              },
-              "href": <str>,
-              "id": <str>,
-              "name": <str>,
-              "type": "artist",
-              "uri": <str>
-            }
-          ]
-        },
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "followers": {
-              "href": <str>,
-              "total": <int>
-            },
-            "genres": [<str>],
-            "href": <str>,
-            "id": <str>,
-            "images": [
-              {
-                "url": <str>,
-                "height": <int>,
-                "width": <int>
-              }
-            ],
-            "name": <str>,
-            "popularity": <int>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ],
-        "available_markets": [<str>],
-        "disc_number": <int>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_ids": {
-          "isrc": <str>,
-          "ean": <str>,
-          "upc": <str>
-        },
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "is_playable": <bool>
-        "linked_from": {
-        },
-        "restrictions": {
-          "reason": <str>
-        },
-        "name": <str>,
-        "popularity": <int>,
-        "preview_url": <str>,
-        "track_number": <int>,
-        "type": "track",
-        "uri": <str>,
-        "is_local": <bool>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-classmethod get_scopes(categories: str | list[str]) → str[source]#
-

Get Spotify Web API and Open Access authorization scopes for -the specified categories.

-
-
Parameters:
-
-
categoriesstr or list

Categories of authorization scopes to get.

-
-

Valid values:

-
    -

  • "images" for scopes related to custom images, -such as ugc-image-upload.

    • -

  • "spotify_connect" for scopes related to Spotify -Connect, such as

    -
      -

    • user-read-playback-state,

      • -

    • user-modify-playback-state, and

      • -

    • user-read-currently-playing.

      • -
    -
    • -

  • "playback" for scopes related to playback -control, such as app-remote-control and -streaming.

    • -

  • "playlists" for scopes related to playlists, -such as

    -
      -

    • playlist-read-private,

      • -

    • playlist-read-collaborative,

      • -

    • playlist-modify-private, and

      • -

    • playlist-modify-public.

      • -
    -
    • -

  • "follow" for scopes related to followed artists -and users, such as user-follow-modify and -user-follow-read.

    • -

  • "listening_history" for scopes related to -playback history, such as

    -
      -

    • user-read-playback-position,

      • -

    • user-top-read, and

      • -

    • user-read-recently-played.

      • -
    -
    • -

  • "library" for scopes related to saved content, -such as user-library-modify and -user-library-read.

    • -

  • "users" for scopes related to user information, -such as user-read-email and -user-read-private.

    • -

  • "all" for all scopes above.

    • -

  • A substring to match in the possible scopes, such as

    -
      -

    • "read" for all scopes above that grant read -access, i.e., scopes with read in the name,

      • -

    • "modify" for all scopes above that grant -modify access, i.e., scopes with modify in -the name, or

      • -

    • "user" for all scopes above that grant access -to all user-related information, i.e., scopes with -user in the name.

      • -
    -
    • -
-
-
-

See also

-

For the endpoints that the scopes allow access to, see the -Scopes page of the Spotify Web API Reference.

-
-
-
-
-
-
- -
-
-get_show(id: str, *, market: str = None) → dict[str, Any][source]#
-

Shows > Get Show: Get Spotify -catalog information for a single show identified by its unique -Spotify ID.

-
-
Parameters:
-
-
idstr

The Spotify ID for the show.

-

Example: "38bS44xjbVVZ3No3ByF1dJ".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
showdict

Spotify catalog information for a single show.

-
-

Sample response

-
{
-  "available_markets": [<str>],
-  "copyrights": [
-    {
-      "text": <str>,
-      "type": <str>
-    }
-  ],
-  "description": <str>,
-  "html_description": <str>,
-  "explicit": <bool>,
-  "external_urls": {
-    "spotify": <str>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "is_externally_hosted": <bool>,
-  "languages": [<str>],
-  "media_type": <str>,
-  "name": <str>,
-  "publisher": <str>,
-  "type": "show",
-  "uri": <str>,
-  "total_episodes": <int>,
-  "episodes": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "audio_preview_url": <str>,
-        "description": <str>,
-        "html_description": <str>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "is_externally_hosted": <bool>,
-        "is_playable": <bool>
-        "language": <str>,
-        "languages": [<str>],
-        "name": <str>,
-        "release_date": <str>,
-        "release_date_precision": <str>,
-        "resume_point": {
-          "fully_played": <bool>,
-          "resume_position_ms": <int>
-        },
-        "type": "episode",
-        "uri": <str>,
-        "restrictions": {
-          "reason": <str>
-        }
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_show_episodes(id: str, *, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#
-

Shows > Get Show Episodes: Get Spotify catalog information about -an show’s episodes. Optional parameters can be used to limit the -number of episodes returned.

-
-
Parameters:
-
-
idstr

The Spotify ID for the show.

-

Example: "38bS44xjbVVZ3No3ByF1dJ".

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
episodesdict

A dictionary containing Spotify catalog information for a -show’s episodes and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "audio_preview_url": <str>,
-      "description": <str>,
-      "html_description": <str>,
-      "duration_ms": <int>,
-      "explicit": <bool>,
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "is_externally_hosted": <bool>,
-      "is_playable": <bool>
-      "language": <str>,
-      "languages": [<str>],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "resume_point": {
-        "fully_played": <bool>,
-        "resume_position_ms": <int>
-      },
-      "type": "episode",
-      "uri": <str>,
-      "restrictions": {
-        "reason": <str>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_shows(ids: str | list[str], *, market: str = None) → list[dict[str, Any]][source]#
-

Shows > Get Several Shows: Get Spotify catalog information for -several shows based on their Spotify IDs.

-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the shows.

-

Maximum: 50 IDs.

-

Example: -"5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
showslist

A list containing Spotify catalog information for multiple -shows.

-
-

Sample response

-
[
-  {
-    "available_markets": [<str>],
-    "copyrights": [
-      {
-        "text": <str>,
-        "type": <str>
-      }
-    ],
-    "description": <str>,
-    "html_description": <str>,
-    "explicit": <bool>,
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "is_externally_hosted": <bool>,
-    "languages": [<str>],
-    "media_type": <str>,
-    "name": <str>,
-    "publisher": <str>,
-    "type": "show",
-    "uri": <str>,
-    "total_episodes": <int>
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_top_items(type: str, *, limit: int = None, offset: int = None, time_range: str = None) → dict[str, Any][source]#
-

Users > Get User’s Top Items: Get the current user’s top -artists or tracks based on calculated affinity.

-
-

Authorization scope

-

Requires the user-top-read scope.

-
-
-
Parameters:
-
-
typestr

The type of entity to return.

-

Valid values: "artists" and "tracks".

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
time_rangestr, keyword-only, optional

Over what time frame the affinities are computed.

-
-

Valid values:

-
    -

  • "long_term" (calculated from several years of -data and including all new data as it becomes -available).

    • -

  • "medium_term" (approximately last 6 months).

    • -

  • "short_term" (approximately last 4 weeks).

    • -
-
-

Default: "medium_term".

-
-
-
-
Returns:
-
-
itemsdict

A dictionary containing Spotify catalog information for a -user’s top items and the number of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "external_urls": {
-        "spotify": <str>
-      },
-      "followers": {
-        "href": <str>,
-        "total": <int>
-      },
-      "genres": [<str>],
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "popularity": <int>,
-      "type": <str>,
-      "uri": <str>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_track(id: str, *, market: str = None) → dict[str, Any][source]#
-

Tracks > Get Track: Get -Spotify catalog information for a single track identified by its -unique Spotify ID.

-
-
Parameters:
-
-
idstr

The Spotify ID for the track.

-

Example: "11dFghVXANMlKmJXsNCbNl".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
trackdict

Spotify catalog information for a single track.

-
-

Sample response

-
{
-  "album": {
-    "album_type": <str>,
-    "total_tracks": <int>,
-    "available_markets": [<str>],
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "images": [
-      {
-        "url": <str>,
-        "height": <int>,
-        "width": <int>
-      }
-    ],
-    "name": <str>,
-    "release_date": <str>,
-    "release_date_precision": <str>,
-    "restrictions": {
-      "reason": <str>
-    },
-    "type": "album",
-    "uri": <str>,
-    "copyrights": [
-      {
-        "text": <str>,
-        "type": <str>
-      }
-    ],
-    "external_ids": {
-      "isrc": <str>,
-      "ean": <str>,
-      "upc": <str>
-    },
-    "genres": [<str>],
-    "label": <str>,
-    "popularity": <int>,
-    "album_group": <str>,
-    "artists": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "name": <str>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ]
-  },
-  "artists": [
-    {
-      "external_urls": {
-        "spotify": <str>
-      },
-      "followers": {
-        "href": <str>,
-        "total": <int>
-      },
-      "genres": [<str>],
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "popularity": <int>,
-      "type": "artist",
-      "uri": <str>
-    }
-  ],
-  "available_markets": [<str>],
-  "disc_number": <int>,
-  "duration_ms": <int>,
-  "explicit": <bool>,
-  "external_ids": {
-    "isrc": <str>,
-    "ean": <str>,
-    "upc": <str>
-  },
-  "external_urls": {
-    "spotify": <str>
-  },
-  "href": <str>,
-  "id": <str>,
-  "is_playable": <bool>
-  "linked_from": {
-  },
-  "restrictions": {
-    "reason": <str>
-  },
-  "name": <str>,
-  "popularity": <int>,
-  "preview_url": <str>,
-  "track_number": <int>,
-  "type": "track",
-  "uri": <str>,
-  "is_local": <bool>
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_audio_analysis(id: str) → dict[str, Any][source]#
-

Tracks > Get Track’s Audio Analysis: Get a low-level audio -analysis for a track in the Spotify catalog. The audio analysis -describes the track’s structure and musical content, including -rhythm, pitch, and timbre.

-
-
Parameters:
-
-
idstr

The Spotify ID of the track.

-

Example: "11dFghVXANMlKmJXsNCbNl".

-
-
-
-
Returns:
-
-
audio_analysisdict

The track’s audio analysis.

-
-

Sample response

-
{
-  "meta": {
-    "analyzer_version": <str>,
-    "platform": <str>,
-    "detailed_status": <str>,
-    "status_code": <int>,
-    "timestamp": <int>,
-    "analysis_time": <float>,
-    "input_process": <str>
-  },
-  "track": {
-    "num_samples": <int>,
-    "duration": <float>,
-    "sample_md5": <str>,
-    "offset_seconds": <int>,
-    "window_seconds": <int>,
-    "analysis_sample_rate": <int>,
-    "analysis_channels": <int>,
-    "end_of_fade_in": <int>,
-    "start_of_fade_out": <float>,
-    "loudness": <float>,
-    "tempo": <float>,
-    "tempo_confidence": <float>,
-    "time_signature": <int>,
-    "time_signature_confidence": <float>,
-    "key": <int>,
-    "key_confidence": <float>,
-    "mode": <int>,
-    "mode_confidence": <float>,
-    "codestring": <str>,
-    "code_version": <float>,
-    "echoprintstring": <str>,
-    "echoprint_version": <float>,
-    "synchstring": <str>,
-    "synch_version": <int>,
-    "rhythmstring": <str>,
-    "rhythm_version": <int>
-  },
-  "bars": [
-    {
-      "start": <float>,
-      "duration": <float>,
-      "confidence": <float>
-    }
-  ],
-  "beats": [
-    {
-      "start": <float>,
-      "duration": <float>,
-      "confidence": <float>
-    }
-  ],
-  "sections": [
-    {
-      "start": <float>,
-      "duration": <float>,
-      "confidence": <float>,
-      "loudness": <float>,
-      "tempo": <float>,
-      "tempo_confidence": <float>,
-      "key": <int>,
-      "key_confidence": <float>,
-      "mode": <int>,
-      "mode_confidence": <float>,
-      "time_signature": <int>,
-      "time_signature_confidence": <float>
-    }
-  ],
-  "segments": [
-    {
-      "start": <float>,
-      "duration": <float>,
-      "confidence": <float>,
-      "loudness_start": <float>,
-      "loudness_max": <float>,
-      "loudness_max_time": <float>,
-      "loudness_end": <int>,
-      "pitches": [<float>],
-      "timbre": [<float>]
-    }
-  ],
-  "tatums": [
-    {
-      "start": <float>,
-      "duration": <float>,
-      "confidence": <float>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_audio_features(id: str) → dict[str, Any][source]#
-

Tracks > Get Track’s Audio Features: Get audio feature information for a -single track identified by its unique Spotify ID.

-
-
Parameters:
-
-
idstr

The Spotify ID of the track.

-

Example: "11dFghVXANMlKmJXsNCbNl".

-
-
-
-
Returns:
-
-
audio_featuresdict

The track’s audio features.

-
-

Sample response

-
{
-  "acousticness": <float>,
-  "analysis_url": <str>,
-  "danceability": <float>,
-  "duration_ms": <int>,
-  "energy": <float>,
-  "id": <str>,
-  "instrumentalness": <float>,
-  "key": <int>,
-  "liveness": <float>,
-  "loudness": <float>,
-  "mode": <int>,
-  "speechiness": <float>,
-  "tempo": <float>,
-  "time_signature": <int>,
-  "track_href": <str>,
-  "type": "audio_features",
-  "uri": <str>,
-  "valence": <float>,
-}
-
-
-
-
-
-
-
-
- -
-
-get_tracks(ids: int | str | list[int | str], *, market: str = None) → list[dict[str, Any]][source]#
-

Tracks > Get Several Tracks: Get Spotify catalog information for -multiple tracks based on their Spotify IDs.

-
-
Parameters:
-
-
idsint, str, or list

A (comma-separated) list of the Spotify IDs for the tracks.

-

Maximum: 50 IDs.

-

Example: "7ouMYWpwJ422jRcDASZB7P, -4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
Returns:
-
-
tracksdict or list

A list containing Spotify catalog information for multiple -tracks.

-
-

Sample response

-
[
-  {
-    "album": {
-      "album_type": <str>,
-      "total_tracks": <int>,
-      "available_markets": [<str>],
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "release_date": <str>,
-      "release_date_precision": <str>,
-      "restrictions": {
-        "reason": <str>
-      },
-      "type": "album",
-      "uri": <str>,
-      "copyrights": [
-        {
-          "text": <str>,
-          "type": <str>
-        }
-      ],
-      "external_ids": {
-        "isrc": <str>,
-        "ean": <str>,
-        "upc": <str>
-      },
-      "genres": [<str>],
-      "label": <str>,
-      "popularity": <int>,
-      "album_group": <str>,
-      "artists": [
-        {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "name": <str>,
-          "type": "artist",
-          "uri": <str>
-        }
-      ]
-    },
-    "artists": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "genres": [<str>],
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "popularity": <int>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ],
-    "available_markets": [<str>],
-    "disc_number": <int>,
-    "duration_ms": <int>,
-    "explicit": <bool>,
-    "external_ids": {
-      "isrc": <str>,
-      "ean": <str>,
-      "upc": <str>
-    },
-    "external_urls": {
-      "spotify": <str>
-    },
-    "href": <str>,
-    "id": <str>,
-    "is_playable": <bool>
-    "linked_from": {
-    },
-    "restrictions": {
-      "reason": <str>
-    },
-    "name": <str>,
-    "popularity": <int>,
-    "preview_url": <str>,
-    "track_number": <int>,
-    "type": "track",
-    "uri": <str>,
-    "is_local": <bool>
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_tracks_audio_features(ids: str | list[str]) → list[dict[str, Any]][source]#
-

Tracks > Get Tracks’ Audio Features: Get audio features -for multiple tracks based on their Spotify IDs.

-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the tracks.

-

Maximum: 100 IDs.

-

Example: "7ouMYWpwJ422jRcDASZB7P, -4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

-
-
-
-
Returns:
-
-
audio_featuresdict or list

A list containing audio features for multiple tracks.

-
-

Sample response

-
[
-  {
-    "acousticness": <float>,
-    "analysis_url": <str>,
-    "danceability": <float>,
-    "duration_ms": <int>,
-    "energy": <float>,
-    "id": <str>,
-    "instrumentalness": <float>,
-    "key": <int>,
-    "liveness": <float>,
-    "loudness": <float>,
-    "mode": <int>,
-    "speechiness": <float>,
-    "tempo": <float>,
-    "time_signature": <int>,
-    "track_href": <str>,
-    "type": "audio_features",
-    "uri": <str>,
-    "valence": <float>,
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_user_playlists(user_id: str, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Playlist > Get User’s Playlists: Get a list of the playlists owned -or followed by a Spotify user.

-
-

Authorization scope

-

Requires the playlist-read-private and the -playlist-read-collaborative scopes.

-
-
-
Parameters:
-
-
user_idstr

The user’s Spotify user ID.

-

Example: "smedjan".

-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Default: 0.

-
-
-
-
Returns:
-
-
playlistsdict

A dictionary containing the user’s playlists and the number -of results returned.

-
-

Sample response

-
{
-  "href": <str>,
-  "limit": <int>,
-  "next": <str>,
-  "offset": <int>,
-  "previous": <str>,
-  "total": <int>,
-  "items": [
-    {
-      "collaborative": <bool>,
-      "description": <str>,
-      "external_urls": {
-        "spotify": <str>
-      },
-      "href": <str>,
-      "id": <str>,
-      "images": [
-        {
-          "url": <str>,
-          "height": <int>,
-          "width": <int>
-        }
-      ],
-      "name": <str>,
-      "owner": {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "href": <str>,
-        "id": <str>,
-        "type": "user",
-        "uri": <str>,
-        "display_name": <str>
-      },
-      "public": <bool>,
-      "snapshot_id": <str>,
-      "tracks": {
-        "href": <str>,
-        "total": <int>
-      },
-      "type": <str>,
-      "uri": <str>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_user_profile(user_id: str) → dict[str, Any][source]#
-

Users > Get User’s Profile: Get public profile information about a -Spotify user.

-
-
Parameters:
-
-
user_idstr

The user’s Spotify user ID.

-

Example: "smedjan"

-
-
-
-
Returns:
-
-
userdict

A dictionary containing the user’s information.

-
-

Sample response

-
{
-  "display_name": <str>,
-  "external_urls": {
-    "spotify": <str>
-  },
-  "followers": {
-    "href": <str>,
-    "total": <int>
-  },
-  "href": <str>,
-  "id": <str>,
-  "images": [
-    {
-      "url": <str>,
-      "height": <int>,
-      "width": <int>
-    }
-  ],
-  "type": "user",
-  "uri": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-pause_playback(*, device_id: str = None) → None[source]#
-

Player > Pause Playback: Pause -playback on the user’s account.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
-
-
-
- -
-
-remove_playlist_items(playlist_id: str, tracks: list[str], *, snapshot_id: str = None) → str[source]#
-

Playlists > Remove Playlist Items: Remove one or more items from a -user’s playlist.

-
-

Authorization scope

-

Requires the playlist-modify-public or the -playlist-modify-private scope.

-
-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
trackslist

A (comma-separated) list containing Spotify URIs of the -tracks or episodes to remove.

-

Maximum: 100 items can be added in one request.

-

Example: "spotify:track:4iV5W9uYEdYUVa79Axb7Rh, -spotify:track:1301WleyT98MSxVHPZCA6M, -spotify:episode:512ojhOuo1ktJprKbVcKyQ".

-
-
snapshot_idstr, keyword-only, optional

The playlist’s snapshot ID against which you want to make -the changes. The API will validate that the specified items -exist and in the specified positions and make the changes, -even if more recent changes have been made to the playlist.

-
-
-
-
Returns:
-
-
snapshot_idstr

The updated playlist’s snapshot ID.

-
-
-
-
-
- -
-
-remove_saved_albums(ids: str | list[str]) → None[source]#
-

Albums > Remove Users’ Saved Albums: Remove one or more albums -from the current user’s ‘Your Music’ library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the albums.

-

Maximum: 20 (str) or 50 (list) IDs.

-

Example: "382ObEPsp2rxGrnsizN5TX, -1A2GTWGtFfWp7KSQTwWOyo, 2noRn2Aes5aoNVsU6iWThc".

-
-
-
-
-
- -
-
-remove_saved_audiobooks(ids: str | list[str]) → None[source]#
-

Audiobooks > Remove User’s Saved Audiobooks: Delete one or more -audiobooks from current Spotify user’s library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the -audiobooks.

-

Maximum: 50 IDs.

-

Example: "18yVqkdbdRvS24c0Ilj2ci, -1HGw3J3NxZO1TP1BTtVhpZ, 7iHfbu1YPACw6oZPAFJtqe".

-
-
-
-
-
- -
-
-remove_saved_episodes(ids: str | list[str]) → None[source]#
-

Episodes > Remove User’s Saved Episodes: Remove one or more -episodes from the current user’s library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the episodes.

-

Maximum: 50 IDs.

-

Example: -"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf".

-
-
-
-
-
- -
-
-remove_saved_shows(ids: str | list[str], *, market: str = None) → None[source]#
-

Shows > Remove User’s Saved Shows: Delete one or more shows from -current Spotify user’s library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the shows. -Maximum: 50 IDs.

-

Example: -"5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ".

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
-
-
-
- -
-
-remove_saved_tracks(ids: str | list[str]) → None[source]#
-

Tracks > Remove User’s Saved Tracks: Remove one or more tracks -from the current user’s ‘Your Music’ library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the tracks.

-

Maximum: 50 IDs.

-

Example: "7ouMYWpwJ422jRcDASZB7P, -4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

-
-
-
-
-
- -
-
-save_albums(ids: str | list[str]) → None[source]#
-

Albums > Save Albums for Current User: Save one or more albums to the -current user’s ‘Your Music’ library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the albums.

-

Maximum: 20 (str) or 50 (list) IDs.

-

Example: "382ObEPsp2rxGrnsizN5TX, -1A2GTWGtFfWp7KSQTwWOyo, 2noRn2Aes5aoNVsU6iWThc".

-
-
-
-
-
- -
-
-save_audiobooks(ids: str | list[str]) → None[source]#
-

Audiobooks > Save Audiobooks for Current User: Save one or more -audiobooks to current Spotify user’s library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the -audiobooks.

-

Maximum: 50 IDs.

-

Example: "18yVqkdbdRvS24c0Ilj2ci, -1HGw3J3NxZO1TP1BTtVhpZ, 7iHfbu1YPACw6oZPAFJtqe".

-
-
-
-
-
- -
-
-save_episodes(ids: str | list[str]) → None[source]#
-

Episodes > Save Episodes for Current User: Save one or more episodes to -the current user’s library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the shows.

-

Maximum: 50 IDs.

-

Example: -"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf".

-
-
-
-
-
- -
-
-save_shows(ids: str | list[str]) → None[source]#
-

Shows > Save Shows for Current User: Save one or more shows to -current Spotify user’s library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the shows. -Maximum: 50 IDs.

-

Example: -"5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ".

-
-
-
-
-
- -
-
-save_tracks(ids: str | list[str]) → None[source]#
-

Tracks > Save Track for Current User: Save one or more tracks to the -current user’s ‘Your Music’ library.

-
-

Authorization scope

-

Requires the user-library-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the Spotify IDs for the tracks.

-

Maximum: 50 IDs.

-

Example: "7ouMYWpwJ422jRcDASZB7P, -4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

-
-
-
-
-
- -
-
-search(q: str, type: str | list[str], *, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#
-

Search > Search for Item: Get -Spotify catalog information about albums, artists, playlists, -tracks, shows, episodes or audiobooks that match a keyword -string.

-
-
Parameters:
-
-
qstr

Your search query.

-
-

Note

-

You can narrow down your search using field filters. The -available filters are album, artist, -track, year, upc, -tag:hipster, tag:new, isrc, and -genre. Each field filter only applies to certain -result types.

-

The artist and year filters can be used -while searching albums, artists and tracks. You can -filter on a single year or a range (e.g. -1955-1960).

-

The album filter can be used while searching -albums and tracks.

-

The genre filter can be used while searching -artists and tracks.

-

The isrc and track filters can be used -while searching tracks.

-

The upc, tag:new and tag:hipster -filters can only be used while searching albums. The -tag:new filter will return albums released in the -past two weeks and tag:hipster can be used to -return only albums with the lowest 10% popularity.

-
-

Example: -"remaster track:Doxy artist:Miles Davis".

-
-
typestr or list

A comma-separated list of item types to search across. -Search results include hits from all the specified item -types.

-

Valid values: "album", "artist", -"audiobook", "episode", "playlist", -"show", and "track".

-
-

Example:

-
    -

  • "track,artist" returns both tracks and artists -matching query.

    • -

  • type=album,track returns both albums and tracks -matching query.

    • -
-
-
-
limitint, keyword-only, optional

The maximum number of results to return in each item type.

-

Valid values: limit must be between 0 and 50.

-

Default: 20.

-
-
marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is -specified, only content that is available in that market -will be returned. If a valid user access token is specified -in the request header, the country associated with the user -account will take priority over this parameter.

-
-

Note

-

If neither market or user country are provided, the -content is considered unavailable for the client.

-
-

Example: "ES".

-
-
offsetint, keyword-only, optional

The index of the first result to return. Use with limit to -get the next page of search results.

-

Valid values: offset must be between 0 and 1,000.

-

Default: 0.

-
-
-
-
Returns:
-
-
resultsdict

The search results.

-
-

Sample

-
{
-  "tracks": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "album": {
-          "album_type": <str>,
-          "total_tracks": <int>,
-          "available_markets": [<str>],
-          "external_urls": {
-            "spotify": <str>
-          },
-          "href": <str>,
-          "id": <str>,
-          "images": [
-            {
-              "url": <str>,
-              "height": <int>,
-              "width": <int>
-            }
-          ],
-          "name": <str>,
-          "release_date": <str>,
-          "release_date_precision": <str>,
-          "restrictions": {
-            "reason": <str>
-          },
-          "type": "album",
-          "uri": <str>,
-          "copyrights": [
-            {
-              "text": <str>,
-              "type": <str>
-            }
-          ],
-          "external_ids": {
-            "isrc": <str>,
-            "ean": <str>,
-            "upc": <str>
-          },
-          "genres": [<str>],
-          "label": <str>,
-          "popularity": <int>,
-          "album_group": <str>,
-          "artists": [
-            {
-              "external_urls": {
-                "spotify": <str>
-              },
-              "href": <str>,
-              "id": <str>,
-              "name": <str>,
-              "type": "artist",
-              "uri": <str>
-            }
-          ]
-        },
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "followers": {
-              "href": <str>,
-              "total": <int>
-            },
-            "genres": [<str>],
-            "href": <str>,
-            "id": <str>,
-            "images": [
-              {
-                "url": <str>,
-                "height": <int>,
-                "width": <int>
-              }
-            ],
-            "name": <str>,
-            "popularity": <int>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ],
-        "available_markets": [<str>],
-        "disc_number": <int>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_ids": {
-          "isrc": <str>,
-          "ean": <str>,
-          "upc": <str>
-        },
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "is_playable": <bool>
-        "linked_from": {
-        },
-        "restrictions": {
-          "reason": <str>
-        },
-        "name": <str>,
-        "popularity": <int>,
-        "preview_url": <str>,
-        "track_number": <int>,
-        "type": "track",
-        "uri": <str>,
-        "is_local": <bool>
-      }
-    ]
-  },
-  "artists": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "external_urls": {
-          "spotify": <str>
-        },
-        "followers": {
-          "href": <str>,
-          "total": <int>
-        },
-        "genres": [<str>],
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "popularity": <int>,
-        "type": "artist",
-        "uri": <str>
-      }
-    ]
-  },
-  "albums": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "album_type": <str>,
-        "total_tracks": <int>,
-        "available_markets": [<str>],
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "release_date": <str>,
-        "release_date_precision": <str>,
-        "restrictions": {
-          "reason": <str>
-        },
-        "type": "album",
-        "uri": <str>,
-        "copyrights": [
-          {
-            "text": <str>,
-            "type": <str>
-          }
-        ],
-        "external_ids": {
-          "isrc": <str>,
-          "ean": <str>,
-          "upc": <str>
-        },
-        "genres": [<str>],
-        "label": <str>,
-        "popularity": <int>,
-        "album_group": <str>,
-        "artists": [
-          {
-            "external_urls": {
-              "spotify": <str>
-            },
-            "href": <str>,
-            "id": <str>,
-            "name": <str>,
-            "type": "artist",
-            "uri": <str>
-          }
-        ]
-      }
-    ]
-  },
-  "playlists": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "collaborative": <bool>,
-        "description": <str>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "name": <str>,
-        "owner": {
-          "external_urls": {
-            "spotify": <str>
-          },
-          "followers": {
-            "href": <str>,
-            "total": <int>
-          },
-          "href": <str>,
-          "id": <str>,
-          "type": "user",
-          "uri": <str>,
-          "display_name": <str>
-        },
-        "public": <bool>,
-        "snapshot_id": <str>,
-        "tracks": {
-          "href": <str>,
-          "total": <int>
-        },
-        "type": <str>,
-        "uri": <str>
-      }
-    ]
-  },
-  "shows": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "available_markets": [<str>],
-        "copyrights": [
-          {
-            "text": <str>,
-            "type": <str>
-          }
-        ],
-        "description": <str>,
-        "html_description": <str>,
-        "explicit": <bool>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "is_externally_hosted": <bool>,
-        "languages": [<str>],
-        "media_type": <str>,
-        "name": <str>,
-        "publisher": <str>,
-        "type": "show",
-        "uri": <str>,
-        "total_episodes": <int>
-      }
-    ]
-  },
-  "episodes": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "audio_preview_url": <str>,
-        "description": <str>,
-        "html_description": <str>,
-        "duration_ms": <int>,
-        "explicit": <bool>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "is_externally_hosted": <bool>,
-        "is_playable": <bool>
-        "language": <str>,
-        "languages": [<str>],
-        "name": <str>,
-        "release_date": <str>,
-        "release_date_precision": <str>,
-        "resume_point": {
-          "fully_played": <bool>,
-          "resume_position_ms": <int>
-        },
-        "type": "episode",
-        "uri": <str>,
-        "restrictions": {
-          "reason": <str>
-        }
-      }
-    ]
-  },
-  "audiobooks": {
-    "href": <str>,
-    "limit": <int>,
-    "next": <str>,
-    "offset": <int>,
-    "previous": <str>,
-    "total": <int>,
-    "items": [
-      {
-        "authors": [
-          {
-            "name": <str>
-          }
-        ],
-        "available_markets": [<str>],
-        "copyrights": [
-          {
-            "text": <str>,
-            "type": <str>
-          }
-        ],
-        "description": <str>,
-        "html_description": <str>,
-        "edition": <str>,
-        "explicit": <bool>,
-        "external_urls": {
-          "spotify": <str>
-        },
-        "href": <str>,
-        "id": <str>,
-        "images": [
-          {
-            "url": <str>,
-            "height": <int>,
-            "width": <int>
-          }
-        ],
-        "languages": [<str>],
-        "media_type": <str>,
-        "name": <str>,
-        "narrators": [
-          {
-            "name": <str>
-          }
-        ],
-        "publisher": <str>,
-        "type": "audiobook",
-        "uri": <str>,
-        "total_chapters": <int>
-      }
-    ]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-seek_to_position(position_ms: int, *, device_id: str = None) → None[source]#
-

Player > Seek To Position: Seeks to the -given position in the user’s currently playing track.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
position_msint

The position in milliseconds to seek to. Passing in a -position that is greater than the length of the track will -cause the player to start playing the next song.

-

Valid values: position_ms must be a positive number.

-

Example: 25000.

-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
-
-
-
- -
-
-set_access_token(access_token: str = None, *, refresh_token: str = None, expiry: str | datetime = None) → None[source]#
-

Set the Spotify Web API access token.

-
-
Parameters:
-
-
access_tokenstr, optional

Access token. If not provided, an access token is obtained -using an OAuth 2.0 authorization flow or from the Spotify -Web Player.

-
-
refresh_tokenstr, keyword-only, optional

Refresh token accompanying access_token.

-
-
expirystr or datetime.datetime, keyword-only, optional

Access token expiry timestamp in the ISO 8601 format -%Y-%m-%dT%H:%M:%SZ. If provided, the user will be -reauthenticated using the refresh token (if available) or -the default authorization flow (if possible) when -access_token expires.

-
-
-
-
-
- -
-
-set_flow(flow: str, *, client_id: str = None, client_secret: str = None, browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, scopes: str | list[str] = '', sp_dc: str = None, save: bool = True) → None[source]#
-

Set the authorization flow.

-
-
Parameters:
-
-
flowstr

Authorization flow.

-
-

Valid values:

-
    -

  • "authorization_code" for the authorization code -flow.

    • -

  • "pkce" for the authorization code with proof -key for code exchange (PKCE) flow.

    • -

  • "client_credentials" for the client credentials -flow.

    • -

  • "web_player" for a Spotify Web Player access -token.

    • -
-
-
-
client_idstr, keyword-only, optional

Client ID. Required for all OAuth 2.0 authorization flows.

-
-
client_secretstr, keyword-only, optional

Client secret. Required for all OAuth 2.0 authorization -flows.

-
-
browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for -the authorization code (with PKCE) flow. If False, -users will have to manually open the authorization URL. -Not applicable when web_framework=”playwright”.

-
-
web_frameworkstr, keyword-only, optional

Web framework used to automatically complete the -authorization code (with PKCE) flow.

-
-

Valid values:

-
    -

  • "http.server" for the built-in implementation of -HTTP servers.

    • -

  • "flask" for the Flask framework.

    • -

  • "playwright" for the Playwright framework.

    • -
-
-
-
portint or str, keyword-only, default: 8888

Port on localhost to use for the authorization code -flow with the http.server and Flask frameworks.

-
-
redirect_uristr, keyword-only, optional

Redirect URI for the authorization code flow. If not -specified, an open port on localhost will be used.

-
-
scopesstr or list, keyword-only, optional

Authorization scopes to request access to in the -authorization code flow.

-
-
sp_dcstr, keyword-only, optional

Spotify Web Player sp_dc cookie.

-
-
savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens -and their associated properties to the Minim configuration -file.

-
-
-
-
-
- -
-
-set_playback_volume(volume_percent: int, *, device_id: str = None) → None[source]#
-

Player > Set Playback Volume: Set the volume for the user’s -current playback device.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
volume_percentint

The volume to set.

-

Valid values: volume_percent must be a value from 0 to -100, inclusive.

-

Example: 50.

-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
-
-
-
- -
-
-set_repeat_mode(state: str, *, device_id: str = None) → None[source]#
-

Player > Set Repeat Mode: Set the repeat mode for -the user’s playback. Options are repeat-track, repeat-context, -and off.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
statestr

Repeat mode.

-
-

Valid values:

-
    -

  • "track" will repeat the current track.

    • -

  • "context" will repeat the current context.

    • -

  • "off" will turn repeat off.

    • -
-
-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
-
-
-
- -
-
-skip_to_next(*, device_id: str = None) → None[source]#
-

Player > Skip To Next: Skips to next track in the -user’s queue.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
-
-
-
- -
-
-skip_to_previous(*, device_id: str = None) → None[source]#
-

Player > Skip To Previous: Skips to previous -track in the user’s queue.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
-
-
-
- -
-
-start_playback(*, device_id: str = None, context_uri: str = None, uris: list[str] = None, offset: dict[str, Any], position_ms: int = None) → None[source]#
-

Player > Start/Resume Playback: Start -a new context or resume current playback on the user’s active -device.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
context_uristr, keyword-only, optional

Spotify URI of the context to play. Only album, artist, and -playlist contexts are valid.

-

Example: "spotify:album:1Je1IMUlBXcx1Fz0WE7oPT".

-
-
urislist, keyword-only, optional

A JSON array of the Spotify track URIs to play.

-

Example: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", -"spotify:track:1301WleyT98MSxVHPZCA6M"].

-
-
offsetdict, keyword-only, optional

Indicates from where in the context playback should start. -Only available when context_uri corresponds to an album or -a playlist.

-
-

Valid values:

-
    -

  • The value corresponding to the "position" key -is zero-based and can’t be negative.

    • -

  • The value corresponding to the "uri" key is a -string representing the URI of the item to start at.

    • -
-

Examples:

-
    -

  • {"position": 5} to start playback at the sixth -item of the collection specified in context_uri.

    • -

  • {"uri": <str>} -to start playback at the item designated by the URI.

    • -
-
-
-
position_msint, keyword-only, optional

The position in milliseconds to seek to. Passing in a -position that is greater than the length of the track will -cause the player to start playing the next song.

-

Valid values: position_ms must be a positive number.

-
-
-
-
-
- -
-
-toggle_playback_shuffle(state: bool, *, device_id: str = None) → None[source]#
-

Player > Toggle Playback Shuffle: Toggle shuffle on or off -for user’s playback.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
statebool

Shuffle mode. If True, shuffle the user’s playback.

-
-
device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not -supplied, the user’s currently active device is the target.

-

Example: -"0d1841b0976bae2a3a310dd74c0f3df354899bc8".

-
-
-
-
-
- -
-
-transfer_playback(device_ids: str | list[str], *, play: bool = None) → None[source]#
-

Player > Transfer Playback: -Transfer playback to a new device and determine if it should -start playing.

-
-

Authorization scope

-

Requires the user-modify-playback-state scope.

-
-
-
Parameters:
-
-
device_idsstr or list

The ID of the device on which playback should be started or -transferred.

-
-

Note

-

Although an array is accepted, only a single device ID is -currently supported. Supplying more than one will return -400 Bad Request.

-
-

Example: ["74ASZWbe4lXaubB36ztrGX"].

-
-
playbool

If True, playback happens on the new device; if -False or not provided, the current playback state is -kept.

-
-
-
-
-
- -
-
-unfollow_people(ids: str | list[str], type: str) → None[source]#
-

Users > Unfollow Artists or Users: Remove the current user -as a follower of one or more artists or other Spotify users.

-
-

Authorization scope

-

Requires the user-follow-modify scope.

-
-
-
Parameters:
-
-
idsstr or list

A (comma-separated) list of the artist or user Spotify IDs.

-

Maximum: Up to 50 IDs can be sent in one request.

-

Example: "2CIMQHirSU0MQqyYHq0eOx, -57dN52uHvrHOxijzpIgu3E, 1vCWHaC5f2uS3yhpwWbIA6".

-
-
typestr

The ID type.

-

Valid values: "artist" and "user".

-
-
-
-
-
- -
-
-unfollow_playlist(playlist_id: str) → None[source]#
-

Users > Unfollow Playlist: Remove the current user as a follower of a -playlist.

-
-

Authorization scope

-

Requires the playlist-modify-private scope.

-
-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n"

-
-
-
-
-
- -
-
-update_playlist_items(playlist_id: str, *, uris: str | list[str] = None, range_start: int = None, insert_before: int = None, range_length: int = 1, snapshot_id: str = None) → str[source]#
-

Playlists > Update Playlist Items: Either reorder or -replace items in a playlist depending on the request’s -parameters.

-

To reorder items, include range_start, insert_before, -range_length, and snapshot_id as keyword arguments. To -replace items, include uris as a keyword argument. Replacing -items in a playlist will overwrite its existing items. This -operation can be used for replacing or clearing items in a -playlist.

-
-

Note

-

Replace and reorder are mutually exclusive operations which -share the same endpoint, but have different parameters. These -operations can’t be applied together in a single request.

-
-
-

Authorization scope

-

Requires the playlist-modify-public or the -playlist-modify-private scope.

-
-
-
Parameters:
-
-
playlist_idstr

The Spotify ID of the playlist.

-

Example: "3cEYpjA9oz9GiPac4AsH4n".

-
-
urisstr or list, keyword-only, optional

A (comma-separated) list of Spotify URIs to add; can be -track or episode URIs. A maximum of 100 items can be added -in one request.

-
-

Note

-

It is likely that passing a large number of item URIs as -a query parameter will exceed the maximum length of the -request URI. When adding a large number of items, it is -recommended to pass them in the request body (as a -list).

-
-

Example: "spotify:track:4iV5W9uYEdYUVa79Axb7Rh, -spotify:track:1301WleyT98MSxVHPZCA6M, -spotify:episode:512ojhOuo1ktJprKbVcKyQ".

-
-
range_startint, keyword-only, optional

The position of the first item to be reordered.

-
-
insert_beforeint, keyword-only, optional

The position where the items should be inserted. To reorder -the items to the end of the playlist, simply set -insert_before to the position after the last item.

-
-

Examples:

-
    -

  • range_start=0, insert_before=10 to reorder the -first item to the last position in a playlist with 10 -items, and

    • -

  • range_start=9, insert_before=0 to reorder the -last item in a playlist with 10 items to the start of -the playlist.

    • -
-
-
-
range_lengthint, keyword-only, default: 1

The amount of items to be reordered. The range of items to -be reordered begins from the range_start position, and -includes the range_length subsequent items.

-

Example: range_start=9, range_length=2 to move -the items at indices 9–10 to the start of the playlist.

-
-
snapshot_idstr, keyword-only, optional

The playlist’s snapshot ID against which you want to make -the changes.

-
-
-
-
Returns:
-
-
snapshot_idstr

The updated playlist’s snapshot ID.

-
-
-
-
-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.spotify.html b/docs/api/minim.spotify.html deleted file mode 100644 index e0cf1135..00000000 --- a/docs/api/minim.spotify.html +++ /dev/null @@ -1,349 +0,0 @@ - - - - - - - - - spotify - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

spotify#

-
-

Spotify#

-

This module contains a complete implementation of all Spotify Web API -endpoints and a minimal implementation to use the private Spotify Lyrics -service.

-
-

Classes

-
- - - - - - - - - -

PrivateLyricsService

Spotify Lyrics service client.

WebAPI

Spotify Web API client.

-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.tidal.API.html b/docs/api/minim.tidal.API.html deleted file mode 100644 index de955b8a..00000000 --- a/docs/api/minim.tidal.API.html +++ /dev/null @@ -1,1977 +0,0 @@ - - - - - - - - - API - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

API#

-
-
-class minim.tidal.API(*, client_id: str = None, client_secret: str = None, flow: str = 'client_credentials', access_token: str = None, expiry: datetime | str = None, overwrite: bool = False, save: bool = True)[source]#
-

Bases: object

-

TIDAL API client.

-

The TIDAL API exposes TIDAL functionality and data, making it -possible to build applications that can search for and retrieve -metadata from the TIDAL catalog.

-
-

See also

-

For more information, see the TIDAL API Reference.

-
-

Requests to the TIDAL API endpoints must be accompanied by a valid -access token in the header. Minim can obtain client-only access -tokens via the client credentials flow, which requires valid client -credentials (client ID and client secret) to either be provided to -this class’s constructor as keyword arguments or be stored as -TIDAL_CLIENT_ID and TIDAL_CLIENT_SECRET in the -operating system’s environment variables.

-
-

See also

-

To get client credentials, see the guide on how to register a new -TIDAL application.

-
-

If an existing access token is available, it and its expiry time can -be provided to this class’s constructor as keyword arguments to -bypass the access token retrieval process. It is recommended that -all other authorization-related keyword arguments be specified so -that a new access token can be obtained when the existing one -expires.

-
-

Tip

-

The authorization flow and access token can be changed or updated -at any time using set_auflow() and set_access_token(), -respectively.

-
-

Minim also stores and manages access tokens and their properties. -When an access token is acquired, it is automatically saved to the -Minim configuration file to be loaded on the next instantiation of -this class. This behavior can be disabled if there are any security -concerns, like if the computer being used is a shared device.

-
-
Parameters:
-
-
client_idstr, keyword-only, optional

Client ID. Required for the client credentials flow. If it is -not stored as TIDAL_CLIENT_ID in the operating system’s -environment variables or found in the Minim configuration file, -it must be provided here.

-
-
client_secretstr, keyword-only, optional

Client secret. Required for the client credentials flow. If it -is not stored as TIDAL_CLIENT_SECRET in the operating -system’s environment variables or found in the Minim -configuration file, it must be provided here.

-
-
flowstr, keyword-only, optional

Authorization flow.

-
-

Valid values:

-
    -

  • "client_credentials" for the client credentials -flow.

    • -
-
-
-
access_tokenstr, keyword-only, optional

Access token. If provided here or found in the Minim -configuration file, the authorization process is bypassed. In -the former case, all other relevant keyword arguments should be -specified to automatically refresh the access token when it -expires.

-
-
expirydatetime.datetime or str, keyword-only, optional

Expiry time of access_token in the ISO 8601 format -%Y-%m-%dT%H:%M:%SZ. If provided, the user will be -reauthenticated using the specified authorization flow (if -possible) when access_token expires.

-
-
overwritebool, keyword-only, default: False

Determines whether to overwrite an existing access token in the -Minim configuration file.

-
-
savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their -associated properties are stored to the Minim configuration -file.

-
-
-
-
Attributes:
-
-
sessionrequests.Session

Session used to send requests to the TIDAL API.

-
-
API_URLstr

Base URL for the TIDAL API.

-
-
TOKEN_URLstr

URL for the TIDAL API token endpoint.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

get_album

Album API > Get single album: Retrieve album details by TIDAL album ID.

get_album_by_barcode_id

Album API > Get album by barcode ID: Retrieve a list of album details by barcode ID.

get_album_items

Album API > Get album items: Retrieve a list of album items (tracks and videos) by TIDAL album ID.

get_albums

Album API > Get multiple albums: Retrieve a list of album details by TIDAL album IDs.

get_artist

Artist API > Get single artist: Retrieve artist details by TIDAL artist ID.

get_artist_albums

Artist API > Get albums by artist: Retrieve a list of albums by TIDAL artist ID.

get_artist_tracks

Track API > Get tracks by artist: Retrieve a list of tracks made by the specified artist.

get_artists

Artist API > Get multiple artists: Retrieve a list of artist details by TIDAL artist IDs.

get_similar_albums

Album API > Get similar albums for the given album: Retrieve a list of albums similar to the given album.

get_similar_artists

Artist API > Get similar artists for the given artist: Retrieve a list of artists similar to the given artist.

get_similar_tracks

Track API > Get similar tracks for the given track: Retrieve a list of tracks similar to the given track.

get_track

Track API > Get single track: Retrieve track details by TIDAL track ID.

get_tracks

Album API > Get multiple tracks: Retrieve a list of track details by TIDAL track IDs.

get_tracks_by_isrc

Track API > Get tracks by ISRC: Retrieve a list of track details by ISRC.

get_video

Video API > Get single video: Retrieve video details by TIDAL video ID.

get_videos

Album API > Get multiple videos: Retrieve a list of video details by TIDAL video IDs.

search

Search API > Search for catalog items: Search for albums, artists, tracks, and videos.

set_access_token

Set the TIDAL API access token.

set_flow

Set the authorization flow.

-
-
-
-get_album(album_id: int | str, country_code: str) → dict[str, Any][source]#
-

Album API > Get single album: Retrieve -album details by TIDAL album ID.

-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Example: 251380836.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
albumdict

TIDAL catalog information for a single album.

-
-

Sample response

-
{
-  "id": <str>,
-  "barcodeId": <str>,
-  "title": <str>,
-  "artists": [
-    {
-      "id": <str>,
-      "name": <str>,
-      "picture": [
-        {
-          "url": <str>,
-          "width": <int>,
-          "height": <int>
-        }
-      ],
-      "main": <bool>
-    }
-  ],
-  "duration": <int>,
-  "releaseDate": <str>,
-  "imageCover": [
-    {
-      "url": <str>,
-      "width": <int>,
-      "height": <int>
-    }
-  ],
-  "videoCover": [
-    {
-      "url": <str>,
-      "width": <int>,
-      "height": <int>
-    }
-  ],
-  "numberOfVolumes": <int>,
-  "numberOfTracks": <int>,
-  "numberOfVideos": <int>,
-  "type": "ALBUM",
-  "copyright": <str>,
-  "mediaMetadata": {
-    "tags": [<str>]
-  },
-  "properties": {
-    "content": [<str>]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_album_by_barcode_id(barcode_id: int | str, country_code: str) → dict[str, Any][source]#
-

Album API > Get album by barcode ID: Retrieve a list of album -details by barcode ID.

-
-
Parameters:
-
-
barcode_idint or str

Barcode ID in EAN-13 or UPC-A format.

-

Example: 196589525444.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
albumdict

TIDAL catalog information for a single album.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "id": <str>,
-        "barcodeId": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "duration": <int>,
-        "releaseDate": <str>,
-        "imageCover": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ],
-        "videoCover": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ],
-        "numberOfVolumes": <int>,
-        "numberOfTracks": <int>,
-        "numberOfVideos": <int>,
-        "type": "ALBUM",
-        "copyright": <str>,
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "properties": {
-          "content": [<str>]
-        }
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "metadata": {
-    "requested": 1,
-    "success": 1,
-    "failure": 0
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_album_items(album_id: int | str, country_code: str, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Album API > Get album items: -Retrieve a list of album items (tracks and videos) by TIDAL -album ID.

-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Examples: 251380836.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
itemsdict

A dictionary containing TIDAL catalog information for -tracks and videos in the specified album and metadata for -the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "artifactType": <str>,
-        "id": <str>,
-        "title": str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "album": {
-          "id": <str>,
-          "title": <str>,
-          "imageCover": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-          ],
-          "videoCover": []
-        },
-        "duration": <int>,
-        "trackNumber": <int>,
-        "volumeNumber": <int>,
-        "isrc": <str>,
-        "copyright": <str>,
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "properties": {
-          "content": [<str>]
-        }
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "metadata": {
-    "total": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_albums(album_ids: int | str | list[int | str], country_code: str) → list[dict[str, Any]][source]#
-

Album API > Get multiple albums: -Retrieve a list of album details by TIDAL album IDs.

-
-
Parameters:
-
-
album_idsint, str, or list

TIDAL album ID(s).

-

Examples: "251380836,275646830" or -[251380836, 275646830].

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
albumsdict

A dictionary containing TIDAL catalog information for -multiple albums and metadata for the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "id": <str>,
-        "barcodeId": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "duration": <int>,
-        "releaseDate": <str>,
-        "imageCover": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ],
-        "videoCover": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ],
-        "numberOfVolumes": <int>,
-        "numberOfTracks": <int>,
-        "numberOfVideos": <int>,
-        "type": "ALBUM",
-        "copyright": <str>,
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "properties": {
-          "content": [<str>]
-        }
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "metadata": {
-    "requested": <int>,
-    "success": <int>,
-    "failure": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist(artist_id: int | str, country_code: str) → dict[str, Any][source]#
-

Artist API > Get single artist: Retrieve -artist details by TIDAL artist ID.

-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
artistdict

TIDAL catalog information for a single artist.

-
-

Sample response

-
{
-  "id": <str>,
-  "name": <str>,
-  "picture": [
-    {
-      "url": <str>,
-      "width": <int>,
-      "height": <int>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_albums(artist_id: int | str, country_code: str, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Artist API > Get albums by artist: -Retrieve a list of albums by TIDAL artist ID.

-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
albumsdict

A dictionary containing TIDAL catalog information for -albums by the specified artist and metadata for the -returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "id": <str>,
-        "barcodeId": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "duration": <int>,
-        "releaseDate": <str>,
-        "imageCover": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ],
-        "videoCover": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ],
-        "numberOfVolumes": <int>,
-        "numberOfTracks": <int>,
-        "numberOfVideos": <int>,
-        "type": "ALBUM",
-        "copyright": <str>,
-        "mediaMetadata": {
-          "tags": <str>
-        },
-        "properties": {
-          "content": <str>
-        }
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "metadata": {
-    "total": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_tracks(artist_id: int | str, country_code: str, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Track API > Get tracks by artist: -Retrieve a list of tracks made by the specified artist.

-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing TIDAL catalog information for tracks -by the specified artist and metadata for the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "properties": {
-          "content": <str>
-        },
-        "id": <str>,
-        "version": <str>,
-        "duration": <int>,
-        "album": {
-          "id": <str>,
-          "title": <str>,
-          "imageCover": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-          ],
-          "videoCover": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-          ]
-        },
-        "title": <str>,
-        "copyright": <str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "popularity": <float>,
-        "isrc": <str>,
-        "trackNumber": <int>,
-        "volumeNumber": <int>,
-        "tidalUrl": <str>,
-        "providerInfo": {
-          "providerId": <str>,
-          "providerName": <str>
-        },
-        "artifactType": <str>,
-        "mediaMetadata": {
-          "tags": <str>
-        }
-      },
-      "id": <str>,
-      "status": <int>,
-      "message": <str>
-    }
-  ],
-  "metadata": {
-    "total": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_artists(artist_ids: int | str | list[int | str], country_code: str) → dict[str, Any][source]#
-

Artist API > Get multiple artists: -Retrieve a list of artist details by TIDAL artist IDs.

-
-
Parameters:
-
-
artist_idsint, str, or list

TIDAL artist ID(s).

-

Examples: "1566,7804" or [1566, 7804].

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
artistsdict

A dictionary containing TIDAL catalog information for -multiple artists and metadata for the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "id": <str>,
-        "name": <str>,
-        "picture": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ]
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "metadata": {
-    "requested": <int>,
-    "success": <int>,
-    "failure": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_similar_albums(album_id: int | str, country_code: str, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Album API > Get similar albums for the given album: -Retrieve a list of albums similar to the given album.

-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Examples: 251380836.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
album_idsdict

A dictionary containing TIDAL album IDs for similar albums -and metadata for the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "id": <str>
-      }
-    }
-  ],
-  "metadata": {
-    "total": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_similar_artists(artist_id: int | str, country_code: str, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Artist API > Get similar artists for the given artist: -Retrieve a list of artists similar to the given artist.

-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
artist_idsdict

A dictionary containing TIDAL artist IDs for similar albums -and metadata for the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "id": <str>
-      }
-    }
-  ],
-  "metadata": {
-    "total": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_similar_tracks(track_id: int | str, country_code: str, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Track API > Get similar tracks for the given track: -Retrieve a list of tracks similar to the given track.

-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
track_idsdict

A dictionary containing TIDAL track IDs for similar albums -and metadata for the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "id": <str>
-      }
-    }
-  ],
-  "metadata": {
-    "total": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_track(track_id: int | str, country_code: str) → dict[str, Any][source]#
-

Track API > Get single track: Retrieve -track details by TIDAL track ID.

-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
trackdict

TIDAL catalog information for a single track.

-
-

Sample response

-
{
-  "artifactType": "track",
-  "id": <str>,
-  "title": <str>,
-  "artists": [
-    {
-      "id": <str>,
-      "name": <str>,
-      "picture": [
-        {
-          "url": <str>,
-          "width": <int>,
-          "height": <int>
-        }
-      ],
-      "main": <bool>
-    }
-  ],
-  "album": {
-    "id": <str>,
-    "title": <str>,
-    "imageCover": [
-      {
-        "url": <str>,
-        "width": <int>,
-        "height": <int>
-      }
-    ],
-    "videoCover": [
-        {
-          "url": <str>,
-          "width": <int>,
-          "height": <int>
-        }
-    ]
-  },
-  "duration": <int>,
-  "trackNumber": <int>,
-  "volumeNumber": <int>,
-  "isrc": <int>,
-  "copyright": <int>,
-  "mediaMetadata": {
-    "tags": [<str>]
-  },
-  "properties": {
-    "content": [<str>]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_tracks(track_ids: int | str | list[int | str], country_code: str) → dict[str, Any][source]#
-

Album API > Get multiple tracks: -Retrieve a list of track details by TIDAL track IDs.

-
-
Parameters:
-
-
track_idsint, str, or list

TIDAL track ID(s).

-

Examples: "251380837,251380838" or -[251380837, 251380838].

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing TIDAL catalog information for -multiple tracks and metadata for the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "artifactType": "track",
-        "id": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "album": {
-          "id": <str>,
-          "title": <str>,
-          "imageCover": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-          ],
-          "videoCover": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-          ]
-        },
-        "duration": <int>,
-        "trackNumber": <int>,
-        "volumeNumber": <int>,
-        "isrc": <int>,
-        "copyright": <int>,
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "properties": {
-          "content": [<str>]
-        }
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "metadata": {
-    "requested": <int>,
-    "success": <int>,
-    "failure": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_tracks_by_isrc(isrc: str, country_code: str, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Track API > Get tracks by ISRC: -Retrieve a list of track details by ISRC.

-
-
Parameters:
-
-
isrcstr

Valid ISRC code (usually comprises 12 alphanumeric -characters).

-

Example: "USSM12209515".

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
limitint, optional

Page size.

-

Example: 10.

-
-
offsetint, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing TIDAL catalog information for -tracks with the specified ISRC and metadata for the -returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "resource": {
-        "artifactType": "track",
-        "id": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "album": {
-          "id": <str>,
-          "title": <str>,
-          "imageCover": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-          ],
-          "videoCover": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-          ]
-        },
-        "duration": <int>,
-        "trackNumber": <int>,
-        "volumeNumber": <int>,
-        "isrc": <int>,
-        "copyright": <int>,
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "properties": {
-          "content": [<str>]
-        }
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "metadata": {
-    "requested": <int>,
-    "success": <int>,
-    "failure": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_video(video_id: int | str, country_code: str) → dict[str, Any][source]#
-

Video API > Get single video: Retrieve -video details by TIDAL video ID.

-
-
Parameters:
-
-
video_idint or str

TIDAL video ID.

-

Example: 75623239.

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
videodict

TIDAL catalog information for a single video.

-
-

Sample response

-
{
-  "artifactType": "video",
-  "id": <str>,
-  "title": <str>,
-  "image": [
-        {
-          "url": <str>,
-          "width": <int>,
-          "height": <int>
-        }
-  ],
-  "releaseDate": <str>,
-  "artists": [
-    {
-      "id": <str>,
-      "name": <str>,
-      "picture": [
-        {
-          "url": <str>,
-          "width": <int>,
-          "height": <int>
-        }
-      ],
-      "main": <bool>
-    }
-  ],
-  "duration": <int>,
-  "trackNumber": <int>,
-  "volumeNumber": <int>,
-  "isrc": <str>,
-  "properties": {
-    "content": [<str>]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_videos(video_ids: int | str | list[int | str], country_code: str) → list[dict[str, Any]][source]#
-

Album API > Get multiple videos: -Retrieve a list of video details by TIDAL video IDs.

-
-
Parameters:
-
-
video_idsint, str, or list

TIDAL video ID(s).

-

Examples: "59727844,75623239" or -[59727844, 75623239].

-
-
country_codestr

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
Returns:
-
-
videosdict

A dictionary containing TIDAL catalog information for -multiple videos and metadata for the returned results.

-
-

Sample response

-
{
-  "data": [
-    {
-      "artifactType": "video",
-      "id": <str>,
-      "title": <str>,
-      "image": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-      ],
-      "releaseDate": <str>,
-      "artists": [
-        {
-          "id": <str>,
-          "name": <str>,
-          "picture": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-          ],
-          "main": <bool>
-        }
-      ],
-      "duration": <int>,
-      "trackNumber": <int>,
-      "volumeNumber": <int>,
-      "isrc": <str>,
-      "properties": {
-        "content": [<str>]
-      }
-    }
-  ],
-  "metadata": {
-    "requested": <int>,
-    "success": <int>,
-    "failure": <int>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-search(query: str, country_code: str, *, type: str = None, limit: int = None, offset: int = None, popularity: str = None) → dict[str, list[dict[str, Any]]][source]#
-

Search API > Search for catalog items: Search for -albums, artists, tracks, and videos.

-
-
Parameters:
-
-
querystr

Search query.

-

Example: "Beyoncé".

-
-
country_code: `str`

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
typestr, keyword-only, optional

Target search type. Searches for all types if not specified.

-

Valid values: "ALBUMS", "ARTISTS", -"TRACKS", "VIDEOS".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
popularitystr, keyword-only, optional

Specify which popularity type to apply for query result. -"WORLDWIDE" is used if not specified.

-

Valid values: "WORLDWIDE" or "COUNTRY".

-
-
-
-
Returns:
-
-
resultsdict

A dictionary containing TIDAL catalog information for -albums, artists, tracks, and videos matching the search -query, and metadata for the returned results.

-
-

Sample response

-
{
-  "albums": [
-    {
-      "resource": {
-        "id": <str>,
-        "barcodeId": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "duration": <int>,
-        "releaseDate": <str>,
-        "imageCover": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ],
-        "videoCover": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ],
-        "numberOfVolumes": <int>,
-        "numberOfTracks": <int>,
-        "numberOfVideos": <int>,
-        "type": "ALBUM",
-        "copyright": <str>,
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "properties": {
-          "content": [<str>]
-        }
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "artists": [
-    {
-      "resource": {
-        "id": <str>,
-        "name": <str>,
-        "picture": [
-          {
-            "url": <str>,
-            "width": <int>,
-            "height": <int>
-          }
-        ]
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "tracks": [
-    {
-      "resource": {
-        "artifactType": "track",
-        "id": <str>,
-        "title": <str>,
-        "artists": [
-          {
-            "id": <str>,
-            "name": <str>,
-            "picture": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-            ],
-            "main": <bool>
-          }
-        ],
-        "album": {
-          "id": <str>,
-          "title": <str>,
-          "imageCover": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-          ],
-          "videoCover": [
-              {
-                "url": <str>,
-                "width": <int>,
-                "height": <int>
-              }
-          ]
-        },
-        "duration": <int>,
-        "trackNumber": <int>,
-        "volumeNumber": <int>,
-        "isrc": <int>,
-        "copyright": <int>,
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "properties": {
-          "content": [<str>]
-        }
-      },
-      "id": <str>,
-      "status": 200,
-      "message": "success"
-    }
-  ],
-  "videos": [
-    {
-      "artifactType": "video",
-      "id": <str>,
-      "title": <str>,
-      "image": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-      ],
-      "releaseDate": <str>,
-      "artists": [
-        {
-          "id": <str>,
-          "name": <str>,
-          "picture": [
-            {
-              "url": <str>,
-              "width": <int>,
-              "height": <int>
-            }
-          ],
-          "main": <bool>
-        }
-      ],
-      "duration": <int>,
-      "trackNumber": <int>,
-      "volumeNumber": <int>,
-      "isrc": <str>,
-      "properties": {
-        "content": [<str>]
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-set_access_token(access_token: str = None, *, expiry: str | datetime = None) → None[source]#
-

Set the TIDAL API access token.

-
-
Parameters:
-
-
access_tokenstr, optional

Access token. If not provided, an access token is obtained -using an OAuth 2.0 authorization flow.

-
-
expirystr or datetime.datetime, keyword-only, optional

Access token expiry timestamp in the ISO 8601 format -%Y-%m-%dT%H:%M:%SZ. If provided, the user will be -reauthenticated using the default authorization flow (if -possible) when access_token expires.

-
-
-
-
-
- -
-
-set_flow(flow: str, *, client_id: str = None, client_secret: str = None, save: bool = True) → None[source]#
-

Set the authorization flow.

-
-
Parameters:
-
-
flowstr

Authorization flow.

-
-

Valid values:

-
    -

  • "client_credentials" for the client credentials -flow.

    • -
-
-
-
client_idstr, keyword-only, optional

Client ID. Required for all authorization flows.

-
-
client_secretstr, keyword-only, optional

Client secret. Required for all authorization flows.

-
-
savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens -and their associated properties to the Minim configuration -file.

-
-
-
-
-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.tidal.PrivateAPI.html b/docs/api/minim.tidal.PrivateAPI.html deleted file mode 100644 index c6b8a8f5..00000000 --- a/docs/api/minim.tidal.PrivateAPI.html +++ /dev/null @@ -1,5524 +0,0 @@ - - - - - - - - - PrivateAPI - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

PrivateAPI#

-
-
-class minim.tidal.PrivateAPI(*, client_id: str = None, client_secret: str = None, flow: str = None, browser: bool = False, scopes: str | list[str] = 'r_usr', user_agent: str = None, access_token: str = None, refresh_token: str = None, expiry: datetime = None, overwrite: bool = False, save: bool = True)[source]#
-

Bases: object

-

Private TIDAL API client.

-

The private TIDAL API allows media (tracks, videos), collections -(albums, playlists), and performers to be queried, and information -about them to be retrieved. As there is no available official -documentation for the private TIDAL API, its endpoints have been -determined by watching HTTP network traffic.

-
-

Attention

-

As the private TIDAL API is not designed to be publicly -accessible, this class can be disabled or removed at any time to -ensure compliance with the TIDAL Developer Terms of Service.

-
-

While authentication is not necessary to search for and retrieve -data from public content, it is required to access personal content -and stream media (with an active TIDAL subscription). In the latter -case, requests to the private TIDAL API endpoints must be -accompanied by a valid user access token in the header.

-

Minim can obtain user access tokens via the authorization code with -proof key for code exchange (PKCE) and device code flows. These -OAuth 2.0 authorization flows require valid client credentials -(client ID and client secret) to either be provided to this class’s -constructor as keyword arguments or be stored as -TIDAL_PRIVATE_CLIENT_ID and -TIDAL_PRIVATE_CLIENT_SECRET in the operating system’s -environment variables.

-
-

Hint

-

Client credentials can be extracted from the software you use to -access TIDAL, including but not limited to the TIDAL Web Player -and the Android, iOS, macOS, and Windows applications. Only the -TIDAL Web Player and desktop application client credentials can -be used without authorization.

-
-

If an existing access token is available, it and its accompanying -information (refresh token and expiry time) can be provided to this -class’s constructor as keyword arguments to bypass the access token -retrieval process. It is recommended that all other -authorization-related keyword arguments be specified so that a new -access token can be obtained when the existing one expires.

-
-

Tip

-

The authorization flow and access token can be changed or updated -at any time using set_flow() and set_access_token(), -respectively.

-
-

Minim also stores and manages access tokens and their properties. -When an access token is acquired, it is automatically saved to the -Minim configuration file to be loaded on the next instantiation of -this class. This behavior can be disabled if there are any security -concerns, like if the computer being used is a shared device.

-
-
Parameters:
-
-
client_idstr, keyword-only, optional

Client ID. If it is not stored as -TIDAL_PRIVATE_CLIENT_ID in the operating system’s -environment variables or found in the Minim configuration file, -it must be provided here.

-
-
client_secretstr, keyword-only, optional

Client secret. Required for the authorization code and device -code flows. If it is not stored as -TIDAL_PRIVATE_CLIENT_SECRET in the operating system’s -environment variables or found in the Minim configuration file, -it must be provided here.

-
-
flowstr, keyword-only, optional

Authorization flow. If not specified, no user authorization -will be performed.

-
-

Valid values:

-
    -

  • "pkce" for the authorization code with proof key -for code exchange (PKCE) flow.

    • -

  • "device_code" for the device code flow.

    • -
-
-
-
browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for the -authorization code with PKCE or device code flows. If -False, users will have to manually open the -authorization URL, and for the authorization code flow, provide -the full callback URI via the terminal. For the authorization -code with PKCE flow, the Playwright framework by Microsoft is -used.

-
-
scopesstr or list, keyword-only, default: "r_usr"

Authorization scopes to request user access for in the OAuth 2.0 -flows.

-

Valid values: "r_usr", "w_usr", and -"w_sub" (device code flow only).

-
-
user_agentstr, keyword-only, optional

User agent information to send in the header of HTTP requests.

-
-

Note

-

If not specified, TIDAL may temporarily block your IP address -if you are making requests too quickly.

-
-
-
access_tokenstr, keyword-only, optional

Access token. If provided here or found in the Minim -configuration file, the authorization process is bypassed. In -the former case, all other relevant keyword arguments should be -specified to automatically refresh the access token when it -expires.

-
-
refresh_tokenstr, keyword-only, optional

Refresh token accompanying access_token. If not provided, -the user will be reauthenticated using the specified -authorization flow when access_token expires.

-
-
expirydatetime.datetime or str, keyword-only, optional

Expiry time of access_token in the ISO 8601 format -%Y-%m-%dT%H:%M:%SZ. If provided, the user will be -reauthenticated using refresh_token (if available) or the -specified authorization flow (if possible) when access_token -expires.

-
-
overwritebool, keyword-only, default: False

Determines whether to overwrite an existing access token in the -Minim configuration file.

-
-
savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their -associated properties are stored to the Minim configuration -file.

-
-
-
-
Attributes:
-
-
API_URLstr

Base URL for the private TIDAL API.

-
-
AUTH_URLstr

URL for device code requests.

-
-
LOGIN_URLstr

URL for authorization code requests.

-
-
REDIRECT_URLstr

URL for authorization code callbacks.

-
-
RESOURCES_URLstr

URL for cover art and image requests.

-
-
TOKEN_URLstr

URL for access token requests.

-
-
WEB_URLstr

URL for the TIDAL Web Player.

-
-
sessionrequests.Session

Session used to send requests to the private TIDAL API.

-
-
-
-
-

Methods

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

add_playlist_items

Add items to a playlist owned by the current user.

block_artist

Block an artist from appearing in mixes and the radio.

block_user

Block a user.

create_playlist

Create a user playlist.

create_playlist_folder

Create a user playlist folder.

delete_playlist

Delete a playlist owned by the current user.

delete_playlist_folder

Delete a playlist folder owned by the current user.

delete_playlist_item

Delete an item from a playlist owned by the current user.

favorite_albums

Add albums to the current user's collection.

favorite_artists

Add artists to the current user's collection.

favorite_mixes

Add mixes to the current user's collection.

favorite_playlists

Add playlists to the current user's collection.

favorite_tracks

Add tracks to the current user's collection.

favorite_videos

Add videos to the current user's collection.

follow_user

Follow a user.

get_album

Get TIDAL catalog information for an album.

get_album_credits

Get credits for an album.

get_album_items

Get TIDAL catalog information for items (tracks and videos) in an album.

get_album_page

Get the TIDAL page for an album.

get_album_review

Get a review of or a synopsis for an album.

get_artist

Get TIDAL catalog information for an artist.

get_artist_albums

Get TIDAL catalog information for albums by an artist.

get_artist_biography

Get an artist's biographical information.

get_artist_links

Get links to websites associated with an artist.

get_artist_mix_id

Get the ID of a curated mix of tracks based on an artist's works.

get_artist_page

Get the TIDAL page for an artist.

get_artist_radio

Get TIDAL catalog information for tracks inspired by an artist's works.

get_artist_top_tracks

Get TIDAL catalog information for an artist's top tracks.

get_artist_videos

Get TIDAL catalog information for an artist's videos.

get_blocked_artists

Get TIDAL catalog information for the current user's blocked artists.

get_blocked_users

Get users blocked by the current user.

get_collection_streams

Get audio and video stream data for items (tracks and videos) in an album, mix, or playlist.

get_country_code

Get the country code based on the current IP address.

get_favorite_albums

Get TIDAL catalog information for albums in the current user's collection.

get_favorite_artists

Get TIDAL catalog information for artists in the current user's collection.

get_favorite_ids

Get TIDAL IDs or UUIDs of the albums, artists, playlists, tracks, and videos in the current user's collection.

get_favorite_mixes

Get TIDAL catalog information for or IDs of mixes in the current user's collection.

get_favorite_tracks

Get TIDAL catalog information for tracks in the current user's collection.

get_favorite_videos

Get TIDAL catalog information for videos in the current user's collection.

get_image

Get (animated) cover art or image for a TIDAL item.

get_mix_items

Get TIDAL catalog information for items (tracks and videos) in a mix.

get_mix_page

Get the TIDAL page for a mix.

get_personal_playlist_folders

Get TIDAL catalog information for a playlist folder (and optionally, playlists and other playlist folders in it) created by the current user.

get_personal_playlists

Get TIDAL catalog information for playlists created by the current user.

get_playlist

Get TIDAL catalog information for a playlist.

get_playlist_etag

Get the entity tag (ETag) for a playlist.

get_playlist_items

Get TIDAL catalog information for items (tracks and videos) in a playlist.

get_playlist_recommendations

Get TIDAL catalog information for recommended tracks based on a playlist's items.

get_profile

Get the current user's profile information.

get_session

Get information about the current private TIDAL API session.

get_similar_albums

Get TIDAL catalog information for albums similar to the specified album.

get_similar_artists

Get TIDAL catalog information for artists similar to a specified artist.

get_track

Get TIDAL catalog information for a track.

get_track_composers

Get the composers, lyricists, and/or songwriters of a track.

get_track_contributors

Get the contributors to a track and their roles.

get_track_credits

Get credits for a track.

get_track_lyrics

Get lyrics for a track.

get_track_mix_id

Get the curated mix of tracks based on a track.

get_track_playback_info

Get playback information for a track.

get_track_recommendations

Get TIDAL catalog information for a track's recommended tracks and videos.

get_track_stream

Get the audio stream data for a track.

get_user_followers

Get a TIDAL user's followers.

get_user_following

Get the people (artists, users, etc.) a TIDAL user follows.

get_user_playlist

Get TIDAL catalog information for a user playlist.

get_user_playlists

Get TIDAL catalog information for playlists created by a TIDAL user.

get_user_profile

Get a TIDAL user's profile information.

get_video

Get TIDAL catalog information for a video.

get_video_page

Get the TIDAL page for a video.

get_video_playback_info

Get playback information for a video.

get_video_stream

Get the video stream data for a music video.

move_playlist

Move a playlist in the current user's collection.

move_playlist_item

Move an item in a playlist owned by the current user.

search

Search for albums, artists, tracks, and videos.

set_access_token

Set the private TIDAL API access token.

set_flow

Set the authorization flow.

set_playlist_privacy

Set the privacy of a playlist owned by the current user.

unblock_artist

Unblock an artist from appearing in mixes and the radio.

unblock_user

Unblock a user.

unfavorite_albums

Remove albums from the current user's collection.

unfavorite_artists

Remove artists from the current user's collection.

unfavorite_mixes

Remove mixes from the current user's collection.

unfavorite_playlist

Remove a playlist from the current user's collection.

unfavorite_tracks

Remove tracks from the current user's collection.

unfavorite_videos

Remove videos from the current user's collection.

unfollow_user

Unfollow a user.

update_playlist

Update the title or description of a playlist owned by the current user.

-
-
-
-add_playlist_items(playlist_uuid: str, items: int | str | list[int | str] = None, *, from_playlist_uuid: str = None, on_duplicate: str = 'FAIL', on_artifact_not_found: str = 'FAIL') → None[source]#
-

Add items to a playlist owned by the current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

-
-
itemsint, str, or list, optional

Items to add to the playlist. If not specified, -from_playlist_uuid must be provided.

-
-

Note

-

If both items and from_playlist_uuid are specified, -only the items in items will be added to the playlist.

-
-
-
from_playlist_uuidstr, keyword-only, optional

TIDAL playlist from which to copy items.

-
-
on_duplicatestr, keyword-only, default: "FAIL"

Behavior when the item to be added is already in the -playlist.

-

Valid values: "ADD", "SKIP", and -"FAIL".

-
-
on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

-

Valid values: "FAIL".

-
-
-
-
-
- -
-
-block_artist(artist_id: int | str) → None[source]#
-

Block an artist from appearing in mixes and the radio.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
-
-
-
- -
-
-block_user(user_id: int | str) → None[source]#
-

Block a user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
user_idint or str

TIDAL user ID.

-

Example: 172311284.

-
-
-
-
-
- -
-
-create_playlist(name: str, *, description: str = None, folder_uuid: str = 'root', public: bool = None) → dict[str, Any][source]#
-

Create a user playlist.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
namestr

Playlist name.

-
-
descriptionstr, keyword-only, optional

Brief playlist description.

-
-
folder_uuidstr, keyword-only, default: "root"

UUID of the folder the new playlist will be placed in. To -place a playlist directly under “My Playlists”, use -folder_id="root".

-
-
publicbool, keyword-only, optional

Determines whether the playlist is public (True) or -private (False).

-
-
-
-
Returns:
-
-
playlistdict

TIDAL catalog information for the newly created playlist.

-
-

Sample response

-
{
-  "trn": <str>,
-  "itemType": "PLAYLIST",
-  "addedAt": <str>,
-  "lastModifiedAt": <str>,
-  "name": <str>,
-  "parent": <str>,
-  "data": {
-    "uuid": <str>,
-    "type": "USER",
-    "creator": {
-      "id": <int>,
-      "name": <str>,
-      "picture": <str>,
-      "type": "USER"
-    },
-    "contentBehavior": <str>,
-    "sharingLevel": <str>,
-    "status": "READY",
-    "source": <str>,
-    "title": <str>,
-    "description": <str>,
-    "image": <str>,
-    "squareImage": <str>,
-    "url": <str>,
-    "created": <str>,
-    "lastUpdated": <str>,
-    "lastItemAddedAt": <str>,
-    "duration": <int>,
-    "numberOfTracks": <int>,
-    "numberOfVideos": <int>,
-    "promotedArtists": <list>,
-    "trn": <str>,
-    "itemType": "PLAYLIST"
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-create_playlist_folder(name: str, *, folder_uuid: str = 'root') → None[source]#
-

Create a user playlist folder.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
namestr

Playlist folder name.

-
-
folder_uuidstr, keyword-only, default: "root"

UUID of the folder in which the new playlist folder should -be created in. To create a folder directly under “My -Playlists”, use folder_id="root".

-
-
-
-
-
- -
-
-delete_playlist(playlist_uuid: str) → None[source]#
-

Delete a playlist owned by the current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

-
-
-
-
-
- -
-
-delete_playlist_folder(folder_uuid: str) → None[source]#
-

Delete a playlist folder owned by the current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
folder_uuidstr

TIDAL playlist folder UUID.

-

Example: "92b3c1ea-245a-4e5a-a5a4-c215f7a65b9f".

-
-
-
-
-
- -
-
-delete_playlist_item(playlist_uuid: str, index: int | str) → None[source]#
-

Delete an item from a playlist owned by the current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

-
-
indexint or str

Item index.

-
-
-
-
-
- -
-
-favorite_albums(album_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None[source]#
-

Add albums to the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
album_idsint, str, or list

TIDAL album ID(s).

-

Examples: "251380836,275646830" or -[251380836, 275646830].

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

-

Valid values: "FAIL" or "SKIP".

-
-
-
-
-
- -
-
-favorite_artists(artist_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None[source]#
-

Add artists to the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
artist_idsint, str, or list

TIDAL artist ID(s).

-

Examples: "1566,7804" or [1566, 7804].

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

-

Valid values: "FAIL" or "SKIP".

-
-
-
-
-
- -
-
-favorite_mixes(mix_ids: str | list[str], *, on_artifact_not_found: str = 'FAIL') → None[source]#
-

Add mixes to the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
mix_idsstr or list

TIDAL mix ID(s).

-

Examples: "000ec0b01da1ddd752ec5dee553d48,            000dd748ceabd5508947c6a5d3880a" or -["000ec0b01da1ddd752ec5dee553d48", -"000dd748ceabd5508947c6a5d3880a"]

-
-
on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

-

Valid values: "FAIL" or "SKIP".

-
-
-
-
-
- -
-
-favorite_playlists(playlist_uuids: str | list[str], *, folder_id: str = 'root') → None[source]#
-

Add playlists to the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidsstr or list

TIDAL playlist UUID(s).

-

Example: ["36ea71a8-445e-41a4-82ab-6628c581535d", -"4261748a-4287-4758-aaab-6d5be3e99e52"].

-
-
folder_idstr, keyword-only, default: "root"

ID of the folder to move the playlist into. To place a -playlist directly under “My Playlists”, use -folder_id="root".

-
-
-
-
-
- -
-
-favorite_tracks(track_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None[source]#
-

Add tracks to the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
track_idsint, str, or list

TIDAL track ID(s).

-

Examples: "251380837,251380838" or -[251380837, 251380838].

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

-

Valid values: "FAIL" or "SKIP".

-
-
-
-
-
- -
-
-favorite_videos(video_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None[source]#
-

Add videos to the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
video_idsint, str, or list

TIDAL video ID(s).

-

Examples: "59727844,75623239" or -[59727844, 75623239].

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

-

Valid values: "FAIL" or "SKIP".

-
-
-
-
-
- -
-
-follow_user(user_id: int | str) → None[source]#
-

Follow a user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
user_idint or str

TIDAL user ID.

-

Example: 172311284.

-
-
-
-
-
- -
-
-get_album(album_id: int | str, country_code: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for an album.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Example: 251380836.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
albumdict

TIDAL catalog information for an album.

-
-

Sample response

-
{
-  "id": <int>,
-  "title": <str>,
-  "duration": <int>,
-  "streamReady": <bool>,
-  "adSupportedStreamReady": <bool>,
-  "djReady": <bool>,
-  "stemReady": <bool>,
-  "streamStartDate": <str>,
-  "allowStreaming": <bool>,
-  "premiumStreamingOnly": <bool>,
-  "numberOfTracks": <int>,
-  "numberOfVideos": <int>,
-  "numberOfVolumes": <int>,
-  "releaseDate": <str>,
-  "copyright": <str>,
-  "type": "ALBUM",
-  "version": <str>,
-  "url": <str>,
-  "cover": <str>,
-  "vibrantColor": <str>,
-  "videoCover": <str>,
-  "explicit": <bool>,
-  "upc": <str>,
-  "popularity": <int>,
-  "audioQuality": <str>,
-  "audioModes": [<str>],
-  "mediaMetadata": {
-    "tags": [<str>]
-  },
-  "artist": {
-    "id": <int>,
-    "name": <str>,
-    "type": <str>,
-    "picture": <str>
-  },
-  "artists": [
-    {
-      "id": <int>,
-      "name": <str>,
-      "type": <str>,
-      "picture": <str>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_album_credits(album_id: int | str, country_code: str = None) → dict[str, Any][source]#
-

Get credits for an album.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Example: 251380836.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
creditsdict

A dictionary containing TIDAL catalog information for the -album contributors.

-
-

Sample response

-
[
-  {
-    "type": <str>,
-    "contributors": [
-      {
-        "name": <str>
-      }
-    ]
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_album_items(album_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None, credits: bool = False) → dict[str, Any][source]#
-

Get TIDAL catalog information for items (tracks and videos) in -an album.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Examples: 251380836.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 100

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
creditsbool, keyword-only, default: False

Determines whether credits for each item is returned.

-
-
-
-
Returns:
-
-
itemsdict

A dictionary containing TIDAL catalog information for -tracks and videos in the specified album and metadata for -the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "item": {
-        "id": <int>,
-        "title": <str>,
-        "duration": <int>,
-        "replayGain": <float>,
-        "peak": <float>,
-        "allowStreaming": <bool>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "premiumStreamingOnly": <bool>,
-        "trackNumber": <int>,
-        "volumeNumber": >int>,
-        "version": <str>,
-        "popularity": <int>,
-        "copyright": <str>,
-        "url": <str>,
-        "isrc": <str>,
-        "editable": <bool>,
-        "explicit": <bool>,
-        "audioQuality": <str>,
-        "audioModes": [<str>],
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ],
-        "album": {
-          "id": <int>,
-          "title": <str>,
-          "cover": <str>,
-          "vibrantColor": <str>,
-          "videoCover": <str>
-        },
-        "mixes": {
-          "TRACK_MIX": <str>
-        }
-      },
-      "type": "track"
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_album_page(album_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any][source]#
-

Get the TIDAL page for an album.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Example: 251380836.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
device_typestr, keyword-only, default: "BROWSER"

Device type.

-
-

Valid values:

-
    -

  • "BROWSER" for a web browser.

    • -

  • "DESKTOP" for the desktop TIDAL application.

    • -

  • "PHONE" for the mobile TIDAL application.

    • -

  • "TV" for the smart TV TIDAL application.

    • -
-
-
-
-
-
Returns:
-
-
pagedict

A dictionary containing the page ID, title, and submodules.

-
-
-
-
-
- -
-
-get_album_review(album_id: int | str, country_code: str = None) → dict[str, str][source]#
-

Get a review of or a synopsis for an album.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Example: 251380836.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
reviewdict

A dictionary containing a review of or a synopsis for an -album and its source.

-
-

Sample response

-
{
-  "source": <str>,
-  "lastUpdated": <str>,
-  "text": <str>,
-  "summary": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist(artist_id: int | str, country_code: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for an artist.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
artistdict

TIDAL catalog information for an artist.

-
-

Sample response

-
{
-  "id": <int>,
-  "name": <str>,
-  "artistTypes": [<str>],
-  "url": <str>,
-  "picture": <str>,
-  "popularity": <int>,
-  "artistRoles": [
-    {
-      "categoryId": <int>,
-      "category": <str>
-    }
-  ],
-  "mixes": {
-    "ARTIST_MIX": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_albums(artist_id: int | str, country_code: str = None, *, filter: str = None, limit: int = 100, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for albums by an artist.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
filterstr, keyword-only, optional

Subset of albums to retrieve.

-

Valid values: "EPSANDSINGLES" and -"COMPILATIONS".

-
-
limitint, keyword-only, default: 100

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
albumsdict

A dictionary containing TIDAL catalog information for -albums by the specified artist and metadata for the -returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "id": <int>,
-      "title": <str>,
-      "duration": <int>,
-      "streamReady": <bool>,
-      "adSupportedStreamReady": <bool>,
-      "djReady": <bool>,
-      "stemReady": <bool>,
-      "streamStartDate": <str>,
-      "allowStreaming": <bool>,
-      "premiumStreamingOnly": <bool>,
-      "numberOfTracks": <int>,
-      "numberOfVideos": <int>,
-      "numberOfVolumes": <int>,
-      "releaseDate": <str>,
-      "copyright": <str>,
-      "type": "ALBUM",
-      "version": <str>,
-      "url": <str>,
-      "cover": <str>,
-      "vibrantColor": <str>,
-      "videoCover": <str>,
-      "explicit": <bool>,
-      "upc": <str>,
-      "popularity": <int>,
-      "audioQuality": <str>,
-      "audioModes": [<str>],
-      "mediaMetadata": {
-        "tags": [<str>]
-      },
-      "artist": {
-        "id": <int>,
-        "name": <str>,
-        "type": <str>,
-        "picture": <str>
-      },
-      "artists": [
-        {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        }
-      ]
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_biography(artist_id: int | str, country_code: str = None) → dict[str, str][source]#
-

Get an artist’s biographical information.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
biographydict

A dictionary containing an artist’s biographical information -and its source.

-
-

Sample response

-
{
-  "source": <str>,
-  "lastUpdated": <str>,
-  "text": <str>,
-  "summary": <str>
-}
-
-
-
-
-
-
-
-
- -
- -

Get links to websites associated with an artist.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
linksdict

A dictionary containing the artist’s links and metadata for -the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "url": <str>,
-      "siteName": <str>
-    }
-  ],
-  "source": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_mix_id(artist_id: int | str, country_code: str = None) → str[source]#
-

Get the ID of a curated mix of tracks based on an artist’s -works.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
mix_idstr

TIDAL mix ID.

-

Example: "000ec0b01da1ddd752ec5dee553d48".

-
-
-
-
-
- -
-
-get_artist_page(artist_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any][source]#
-

Get the TIDAL page for an artist.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
device_typestr, keyword-only, default: "BROWSER"

Device type.

-
-

Valid values:

-
    -

  • "BROWSER" for a web browser.

    • -

  • "DESKTOP" for the desktop TIDAL application.

    • -

  • "PHONE" for the mobile TIDAL application.

    • -

  • "TV" for the smart TV TIDAL application.

    • -
-
-
-
-
-
Returns:
-
-
pagedict

A dictionary containing the page ID, title, and submodules.

-
-
-
-
-
- -
-
-get_artist_radio(artist_id: int | str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for tracks inspired by an artist’s -works.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-

Note

-

This method is functionally identical to first getting the -artist mix ID using get_artist_mix_id() and then -retrieving TIDAL catalog information for the items in the mix -using get_mix_items().

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Default: 100.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing TIDAL catalog information for tracks -inspired by an artist’s works and metadata for the returned -results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "id": <int>,
-      "title": <str>,
-      "duration": <int>,
-      "replayGain": <float>,
-      "peak": <float>,
-      "allowStreaming": <bool>,
-      "streamReady": <bool>,
-      "adSupportedStreamReady": <bool>,
-      "djReady": <bool>,
-      "stemReady": <bool>,
-      "streamStartDate": <str>,
-      "premiumStreamingOnly": <bool>,
-      "trackNumber": <int>,
-      "volumeNumber": <int>,
-      "version": <str>,
-      "popularity": <int>,
-      "copyright": <str>,
-      "url": <str>,
-      "isrc": <str>,
-      "editable": <bool>,
-      "explicit": <bool>,
-      "audioQuality": <str>,
-      "audioModes": [<str>],
-      "mediaMetadata": {
-        "tags": [<str>]
-      },
-      "artist": {
-        "id": <int>,
-        "name": <str>,
-        "type": <str>,
-        "picture": <str>
-      },
-      "artists": [
-        {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        }
-      ],
-      "album": {
-        "id": <int>,
-        "title": <str>,
-        "cover": <str>,
-        "vibrantColor": <str>,
-        "videoCover": <str>
-      },
-      "mixes": {
-        "TRACK_MIX": <str>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_top_tracks(artist_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for an artist’s top tracks.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 100

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing TIDAL catalog information for the -artist’s top tracks and metadata for the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "id": <int>,
-      "title": <str>,
-      "duration": <int>,
-      "replayGain": <float>,
-      "peak": <float>,
-      "allowStreaming": <bool>,
-      "streamReady": <bool>,
-      "adSupportedStreamReady": <bool>,
-      "djReady": <bool>,
-      "stemReady": <bool>,
-      "streamStartDate": <str>,
-      "premiumStreamingOnly": <bool>,
-      "trackNumber": <int>,
-      "volumeNumber": <int>,
-      "version": <str>,
-      "popularity": <int>,
-      "copyright": <str>,
-      "url": <str>,
-      "isrc": <str>,
-      "editable": <bool>,
-      "explicit": <bool>,
-      "audioQuality": <str>,
-      "audioModes": [<str>],
-      "mediaMetadata": {
-        "tags": [<str>]
-      },
-      "artist": {
-        "id": <int>,
-        "name": <str>,
-        "type": <str>,
-        "picture": <str>
-      },
-      "artists": [
-        {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        }
-      ],
-      "album": {
-        "id": <int>,
-        "title": <str>,
-        "cover": <str>,
-        "vibrantColor": <str>,
-        "videoCover": <str>
-      },
-      "mixes": {
-        "TRACK_MIX": <str>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_artist_videos(artist_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for an artist’s videos.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 100

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
videosdict

A dictionary containing TIDAL catalog information for the -artist’s videos and metadata for the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "id": <int>,
-      "title": <str>,
-      "volumeNumber": <int>,
-      "trackNumber": <int>,
-      "releaseDate": <str>,
-      "imagePath": <str>,
-      "imageId": <str>,
-      "vibrantColor": <str>,
-      "duration": <int>,
-      "quality": <str>,
-      "streamReady": <bool>,
-      "adSupportedStreamReady": <bool>,
-      "djReady": <bool>,
-      "stemReady": <bool>,
-      "streamStartDate": <str>,
-      "allowStreaming": <bool>,
-      "explicit": <bool>,
-      "popularity": <int>,
-      "type": "Music Video",
-      "adsUrl": <str>,
-      "adsPrePaywallOnly": <bool>,
-      "artist": {
-        "id": <int>,
-        "name": <str>,
-        "type": <str>,
-        "picture": <str>
-      },
-      "artists": [
-        {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        }
-      ],
-      "album": <dict>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_blocked_artists(*, limit: int = 50, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for the current user’s blocked -artists.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
artistsdict

A dictionary containing TIDAL catalog information for the -the current user’s blocked artists and metadata for the -returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "item": {
-        "id": <int>,
-        "name": <str>,
-        "type": <str>,
-        "artistTypes": [<str>],
-        "url": <str>,
-        "picture": <str>,
-        "popularity": <int>,
-        "banner": <str>,
-        "artistRoles": [
-          {
-            "categoryId": <int>,
-            "category": <str>
-          }
-        ],
-        "mixes": {
-          "ARTIST_MIX": <str>
-        }
-      },
-      "created": <str>,
-      "type": "ARTIST"
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_blocked_users(*, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get users blocked by the current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
usersdict

A dictionary containing the users blocked by the current -user and the number of results.

-
-
-
-
-
- -
-
-get_collection_streams(collection_id: int | str, type: str, *, audio_quality: str = 'HI_RES', video_quality: str = 'HIGH', max_resolution: int = 2160, playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → list[tuple[bytes, str]][source]#
-

Get audio and video stream data for items (tracks and videos) in -an album, mix, or playlist.

-
-

User authentication, authorization scope, and - subscription

-

Requires the r_usr authorization scope if the device -code flow was used.

-

Full track and video playback information and lossless audio -is only available with user authentication and an active -TIDAL subscription.

-

High-resolution and immersive audio is only available with -the HiFi Plus plan and when the current client credentials -are from a supported device.

-
-

See also

-

For more information on audio quality availability, see -the Download TIDAL, -TIDAL Pricing, and -Dolby Atmos web pages.

-
-
-
-

Note

-

This method is provided for convenience and is not a private -TIDAL API endpoint.

-
-
-
Parameters:
-
-
collection_idint or str

TIDAL collection ID or UUID.

-
-
typestr

Collection type.

-

Valid values: "album", "mix", and -"playlist".

-
-
audio_qualitystr, keyword-only, default: "HI-RES"

Audio quality.

-
-

Valid values:

-
    -

  • "LOW" for 64 kbps (22.05 kHz) MP3 without user -authentication or 96 kbps AAC with user authentication.

    • -

  • "HIGH" for 320 kbps AAC.

    • -

  • "LOSSLESS" for 1411 kbps (16-bit, 44.1 kHz) ALAC -or FLAC.

    • -

  • "HI_RES" for up to 9216 kbps (24-bit, 96 kHz) -MQA-encoded FLAC.

    • -
-
-
-
video_qualitystr, keyword-only, default: "HIGH"

Video quality.

-

Valid values: "AUDIO_ONLY", "LOW", -"MEDIUM", and "HIGH".

-
-
max_resolutionint, keyword-only, default: 2160

Maximum video resolution (number of vertical pixels).

-
-
playback_modestr, keyword-only, default: "STREAM"

Playback mode.

-

Valid values: "STREAM" and "OFFLINE".

-
-
asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

-
-

Valid values:

-
    -

  • "FULL": Full track or video.

    • -

  • "PREVIEW": 30-second preview of the track or -video.

    • -
-
-
-
streaming_session_idstr, keyword-only, optional

Streaming session ID.

-
-
-
-
Returns:
-
-
streamslist

Audio and video stream data and their MIME types.

-
-
-
-
-
- -
-
-get_country_code() → str[source]#
-

Get the country code based on the current IP address.

-
-
Returns:
-
-
countrystr, keyword-only, optional

ISO 3166-1 alpha-2 country code.

-

Example: "US".

-
-
-
-
-
- -
-
-get_favorite_albums(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC') → None[source]#
-

Get TIDAL catalog information for albums in the current user’s -collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
orderstr, keyword-only, default: "DATE"

Sorting order.

-

Valid values: "DATE" and "NAME".

-
-
order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

-

Valid values: "DESC" and "ASC".

-
-
-
-
Returns:
-
-
albumsdict

A dictionary containing TIDAL catalog information for albums -in the current user’s collection and metadata for the -returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "created": <str>,
-      "item": {
-        "id": <int>,
-        "title": <str>,
-        "duration": <int>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "allowStreaming": <bool>,
-        "premiumStreamingOnly": <bool>,
-        "numberOfTracks": <int>,
-        "numberOfVideos": <int>,
-        "numberOfVolumes": <int>,
-        "releaseDate": <str>,
-        "copyright": <str>,
-        "type": "ALBUM",
-        "version": <str>,
-        "url": <str>,
-        "cover": <str>,
-        "vibrantColor": <str>,
-        "videoCover": <str>,
-        "explicit": <bool>,
-        "upc": <str>,
-        "popularity": <int>,
-        "audioQuality": <str>,
-        "audioModes": [<str>],
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ]
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_favorite_artists(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC') → None[source]#
-

Get TIDAL catalog information for artists in the current user’s -collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
orderstr, keyword-only, default: "DATE"

Sorting order.

-

Valid values: "DATE" and "NAME".

-
-
order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

-

Valid values: "DESC" and "ASC".

-
-
-
-
Returns:
-
-
artistsdict

A dictionary containing TIDAL catalog information for -artists in the current user’s collection and metadata for -the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "created": <str>,
-      "item": {
-        "id": <int>,
-        "name": <str>,
-        "artistTypes": [<str>],
-        "url": <str>,
-        "picture": <str>,
-        "popularity": <int>,
-        "artistRoles": [
-          {
-            "categoryId": <int>,
-            "category": <str>
-          }
-        ],
-        "mixes": {
-          "ARTIST_MIX": <str>
-        }
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_favorite_ids() → dict[str, list[str]][source]#
-

Get TIDAL IDs or UUIDs of the albums, artists, playlists, -tracks, and videos in the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Returns:
-
-
idsdict

A dictionary containing the IDs or UUIDs of the items in the -current user’s collection.

-
-

Sample response

-
{
-  "ARTIST": [<str>],
-  "ALBUM": [<str>],
-  "VIDEO": [<str>],
-  "PLAYLIST": [<str>],
-  "TRACK": [<str>]
-}
-
-
-
-
-
-
-
-
- -
-
-get_favorite_mixes(*, ids: bool = False, limit: int = 50, cursor: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for or IDs of mixes in the -current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
idsbool, keyword-only, default: False

Determine whether TIDAL catalog information about the mixes -(False) or the mix IDs (True) are -returned.

-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. -Use with limit to get the next page of search results.

-
-
-
-
Returns:
-
-
mixesdict

A dictionary containing the TIDAL catalog information for or -IDs of the mixes in the current user’s collection and the -cursor position.

-
-

Sample response

-
{
-  "items": [
-    {
-      "dateAdded": <str>,
-      "title": <str>,
-      "id": <str>,
-      "mixType": <str>,
-      "updated": <str>,
-      "subTitleTextInfo": {
-        "text": <str>,
-        "color": <str>
-      },
-      "images": {
-        "SMALL": {
-          "width": <int>,
-          "height": <int>,
-          "url": <str>
-        },
-        "MEDIUM": {
-          "width": <int>,
-          "height": <int>,
-          "url": <str>
-        },
-        "LARGE": {
-          "width": <int>,
-          "height": <int>,
-          "url": <str>
-        },
-      },
-      "detailImages": {
-        "SMALL": {
-          "width": <int>,
-          "height": <int>,
-          "url": <str>
-        },
-        "MEDIUM": {
-          "width": <int>,
-          "height": <int>,
-          "url": <str>
-        },
-        "LARGE": {
-          "width": <int>,
-          "height": <int>,
-          "url": <str>
-        }
-      },
-      "master": <bool>,
-      "subTitle": <str>,
-      "titleTextInfo": {
-        "text": <str>,
-        "color": <str>
-      }
-    }
-  ],
-  "cursor": <str>,
-  "lastModifiedAt": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_favorite_tracks(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC')[source]#
-

Get TIDAL catalog information for tracks in the current user’s -collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
orderstr, keyword-only, default: "DATE"

Sorting order.

-

Valid values: "DATE" and "NAME".

-
-
order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

-

Valid values: "DESC" and "ASC".

-
-
-
-
Returns:
-
-
tracksdict

A dictionary containing TIDAL catalog information for tracks -in the current user’s collection and metadata for the -returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "created": <str>,
-      "item": {
-        "id": <int>,
-        "title": <str>,
-        "duration": <int>,
-        "replayGain": <float>,
-        "peak": <float>,
-        "allowStreaming": <bool>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "premiumStreamingOnly": <bool>,
-        "trackNumber": <int>,
-        "volumeNumber": <int>,
-        "version": <str>,
-        "popularity": <int>,
-        "copyright": <str>,
-        "url": <str>,
-        "isrc": <str>,
-        "editable": <bool>,
-        "explicit": <bool>,
-        "audioQuality": <str>,
-        "audioModes": [<str>],
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ],
-        "album": {
-          "id": <int>,
-          "title": <str>,
-          "cover": <str>,
-          "vibrantColor": <str>,
-          "videoCover": <str>
-        },
-        "mixes": {
-          "TRACK_MIX": <str>
-        }
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_favorite_videos(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC')[source]#
-

Get TIDAL catalog information for videos in the current user’s -collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
orderstr, keyword-only, default: "DATE"

Sorting order.

-

Valid values: "DATE" and "NAME".

-
-
order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

-

Valid values: "DESC" and "ASC".

-
-
-
-
Returns:
-
-
videosdict

A dictionary containing TIDAL catalog information for videos -in the current user’s collection and metadata for the -returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "created": <str>,
-      "item": {
-        "id": <int>,
-        "title": <str>,
-        "volumeNumber": <int>,
-        "trackNumber": <int>,
-        "releaseDate": <str>,
-        "imagePath": <str>,
-        "imageId": <str>,
-        "vibrantColor": <str>,
-        "duration": <int>,
-        "quality": <str>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "allowStreaming": <bool>,
-        "explicit": <bool>,
-        "popularity": <int>,
-        "type": <str>,
-        "adsUrl": <str>,
-        "adsPrePaywallOnly": <bool>,
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": "<str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ],
-        "album": <dict>
-      }
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_image(uuid: str, type: str = None, animated: bool = False, *, width: int = None, height: int = None, filename: str | Path = None) → bytes[source]#
-

Get (animated) cover art or image for a TIDAL item.

-
-

Note

-

This method is provided for convenience and is not a private -TIDAL API endpoint.

-
-
-
Parameters:
-
-
uuidstr

Image UUID.

-

Example: "d3c4372b-a652-40e0-bdb1-fc8d032708f6".

-
-
typestr

Item type.

-

Valid values: "artist", "album", -"playlist", "track", "userProfile", -and "video".

-
-
animatedbool, default: False

Specifies whether the image is animated.

-
-
widthint, keyword-only, optional

Valid image width for the item type. If not specified, the -default size for the item type is used.

-
-
heightint, keyword-only, optional

Valid image height for the item type. If not specified, the -default size for the item type is used.

-
-
filenamestr or pathlib.Path, keyword-only, optional

Filename with the .jpg or .mp4 extension. If -specified, the image is saved to a file instead.

-
-
-
-
Returns:
-
-
imagebytes

Image data. If save=True, the stream data is saved -to an image or video file and its filename is returned -instead.

-
-
-
-
-
- -
-
-get_mix_items(mix_id: str, country_code: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for items (tracks and videos) in -a mix.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
mix_idstr

TIDAL mix ID.

-

Example: "000ec0b01da1ddd752ec5dee553d48".

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
itemsdict

A dictionary containing TIDAL catalog information for -tracks and videos in the specified mix and metadata for -the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "item": {
-        "id": <int>,
-        "title": <str>,
-        "duration": <int>,
-        "replayGain": <float>,
-        "peak": <float>,
-        "allowStreaming": <bool>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "premiumStreamingOnly": <bool>,
-        "trackNumber": <int>,
-        "volumeNumber": >int>,
-        "version": <str>,
-        "popularity": <int>,
-        "copyright": <str>,
-        "url": <str>,
-        "isrc": <str>,
-        "editable": <bool>,
-        "explicit": <bool>,
-        "audioQuality": <str>,
-        "audioModes": [<str>],
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ],
-        "album": {
-          "id": <int>,
-          "title": <str>,
-          "cover": <str>,
-          "vibrantColor": <str>,
-          "videoCover": <str>
-        },
-        "mixes": {
-          "TRACK_MIX": <str>
-        }
-      },
-      "type": "track"
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_mix_page(mix_id: str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any][source]#
-

Get the TIDAL page for a mix.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
mix_idstr

TIDAL mix ID.

-

Example: "000ec0b01da1ddd752ec5dee553d48".

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
device_typestr, keyword-only, default: "BROWSER"

Device type.

-
-

Valid values:

-
    -

  • "BROWSER" for a web browser.

    • -

  • "DESKTOP" for the desktop TIDAL application.

    • -

  • "PHONE" for the mobile TIDAL application.

    • -

  • "TV" for the smart TV TIDAL application.

    • -
-
-
-
-
-
Returns:
-
-
pagedict

A dictionary containing the page ID, title, and submodules.

-
-
-
-
-
- -
-
-get_personal_playlist_folders(folder_uuid: str = None, *, flattened: bool = False, include_only: str = None, limit: int = 50, order: str = 'DATE', order_direction: str = 'DESC') → dict[str, Any][source]#
-

Get TIDAL catalog information for a playlist folder (and -optionally, playlists and other playlist folders in it) created -by the current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
folder_uuidstr, optional

UUID of the folder in which to look for playlists and other -folders. If not specified, all folders and playlists in “My -Playlists” are returned.

-
-
flattenedbool, keyword-only, default: False

Determines whether the results are flattened into a list.

-
-
include_onlystr, keyword-only, optional

Type of playlist-related item to return.

-

Valid values: "FAVORITE_PLAYLIST", -"FOLDER", and "PLAYLIST".

-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
orderstr, keyword-only, default: "DATE"

Sorting order.

-

Valid values: "DATE", "DATE_UPDATED", -and "NAME".

-
-
order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

-

Valid values: "DESC" and "ASC".

-
-
-
-
Returns:
-
-
itemsdict

A dictionary containing playlist-related items and the total -number of items available.

-
-

Sample response

-
{
-  "lastModifiedAt": <str>,
-  "items": [
-    {
-      "trn": <str>,
-      "itemType": "FOLDER",
-      "addedAt": <str>,
-      "lastModifiedAt": <str>,
-      "name": <str>,
-      "parent": <str>,
-      "data": {
-        "trn": <str>,
-        "name": <str>,
-        "createdAt": <str>,
-        "lastModifiedAt": <str>,
-        "totalNumberOfItems": <int>,
-        "id": <str>,
-        "itemType": "FOLDER"
-      }
-    }
-  ],
-  "totalNumberOfItems": <int>,
-  "cursor": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_personal_playlists(country_code: str = None, *, limit: int = 50, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for playlists created by the -current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
playlistsdict

TIDAL catalog information for a user playlists created by -the current user and metadata for the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "uuid": <str>",
-      "title": <str>,
-      "numberOfTracks": <int>,
-      "numberOfVideos": <int>,
-      "creator": {
-        "id": <int>
-      },
-      "description": <str>,
-      "duration": <int>,
-      "lastUpdated": <str>,
-      "created": <str>,
-      "type": "USER",
-      "publicPlaylist": <bool>,
-      "url": <str>,
-      "image": <str>,
-      "popularity": <int>,
-      "squareImage": <str>,
-      "promotedArtists": [],
-      "lastItemAddedAt": <str>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_playlist(playlist_uuid: str, country_code: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for a playlist.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
playlistdict

TIDAL catalog information for a playlist.

-
-

Sample response

-
{
-  "uuid": <str>,
-  "title": <str>,
-  "numberOfTracks": <int>,
-  "numberOfVideos": <int>,
-  "creator": {
-    "id": <int>
-  },
-  "description": <str>,
-  "duration": <int>,
-  "lastUpdated": <str>,
-  "created": <str>,
-  "type": <str>,
-  "publicPlaylist": <bool>,
-  "url": <str>,
-  "image": <str>,
-  "popularity": <int>,
-  "squareImage": <str>,
-  "promotedArtists": [
-    {
-      "id": <int>,
-      "name": <str>,
-      "type": <str>,
-      "picture": <str>,
-    }
-  ],
-  "lastItemAddedAt": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_playlist_etag(playlist_uuid: str, country_code: str = None) → str[source]#
-

Get the entity tag (ETag) for a playlist.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-

Note

-

This method is provided for convenience and is not a private -TIDAL API endpoint.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
etagstr

ETag for a playlist.

-

Example: "1698984074453".

-
-
-
-
-
- -
-
-get_playlist_items(playlist_uuid: str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for items (tracks and videos) in -a playlist.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 100

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
itemsdict

A dictionary containing TIDAL catalog information for -tracks and videos in the specified playlist and metadata for -the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "item": {
-        "id": <int>,
-        "title": <str>,
-        "duration": <int>,
-        "replayGain": <float>,
-        "peak": <float>,
-        "allowStreaming": <bool>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "premiumStreamingOnly": <bool>,
-        "trackNumber": <int>,
-        "volumeNumber": >int>,
-        "version": <str>,
-        "popularity": <int>,
-        "copyright": <str>,
-        "url": <str>,
-        "isrc": <str>,
-        "editable": <bool>,
-        "explicit": <bool>,
-        "audioQuality": <str>,
-        "audioModes": [<str>],
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ],
-        "album": {
-          "id": <int>,
-          "title": <str>,
-          "cover": <str>,
-          "vibrantColor": <str>,
-          "videoCover": <str>
-        },
-        "mixes": {
-          "TRACK_MIX": <str>
-        }
-      },
-      "type": "track"
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_playlist_recommendations(playlist_uuid: str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for recommended tracks based on a -playlist’s items.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
itemsdict

A dictionary containing TIDAL catalog information for -recommended tracks and videos and metadata for the returned -results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "item": {
-        "id": <int>,
-        "title": <str>,
-        "duration": <int>,
-        "replayGain": <float>,
-        "peak": <float>,
-        "allowStreaming": <bool>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "premiumStreamingOnly": <bool>,
-        "trackNumber": <int>,
-        "volumeNumber": >int>,
-        "version": <str>,
-        "popularity": <int>,
-        "copyright": <str>,
-        "url": <str>,
-        "isrc": <str>,
-        "editable": <bool>,
-        "explicit": <bool>,
-        "audioQuality": <str>,
-        "audioModes": [<str>],
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ],
-        "album": {
-          "id": <int>,
-          "title": <str>,
-          "cover": <str>,
-          "vibrantColor": <str>,
-          "videoCover": <str>
-        },
-        "mixes": {
-          "TRACK_MIX": <str>
-        }
-      },
-      "type": "track"
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_profile() → dict[str, Any][source]#
-

Get the current user’s profile information.

-
-

User authentication

-

Requires user authentication via an OAuth 2.0 authorization -flow.

-
-
-
Returns:
-
-
profiledict

A dictionary containing the current user’s profile -information.

-
-

Sample response

-
{
-  "userId": <int>,
-  "email": <str>,
-  "countryCode": <str>,
-  "fullName": <str>,
-  "firstName": <str>,
-  "lastName": <str>,
-  "nickname": <str>,
-  "username": <str>,
-  "address": <str>,
-  "city": <str>,
-  "postalcode": <str>,
-  "usState": <str>,
-  "phoneNumber": <int>,
-  "birthday": <int>,
-  "channelId": <int>,
-  "parentId": <int>,
-  "acceptedEULA": <bool>,
-  "created": <int>,
-  "updated": <int>,
-  "facebookUid": <int>,
-  "appleUid": <int>,
-  "googleUid": <int>,
-  "accountLinkCreated": <bool>,
-  "emailVerified": <bool>,
-  "newUser": <bool>
-}
-
-
-
-
-
-
-
-
- -
-
-get_session() → dict[str, Any][source]#
-

Get information about the current private TIDAL API session.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Returns:
-
-
sessiondict

Information about the current private TIDAL API session.

-
-

Sample response

-
{
-  "sessionId": <str>,
-  "userId": <int>,
-  "countryCode": <str>,
-  "channelId": <int>,
-  "partnerId": <int>,
-  "client": {
-    "id": <int>,
-    "name": <str>,
-    "authorizedForOffline": <bool>,
-    "authorizedForOfflineDate": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_similar_albums(album_id: int | str, country_code: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for albums similar to the -specified album.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
album_idint or str

TIDAL album ID.

-

Example: 251380836.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
albumdict

TIDAL catalog information for an album.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "id": <int>,
-      "title": <str>,
-      "duration": <int>,
-      "streamReady": <bool>,
-      "adSupportedStreamReady": <bool>,
-      "djReady": <bool>,
-      "stemReady": <bool>,
-      "streamStartDate": <str>,
-      "allowStreaming": <bool>,
-      "premiumStreamingOnly": <bool>,
-      "numberOfTracks": <int>,
-      "numberOfVideos": <int>,
-      "numberOfVolumes": <int>,
-      "releaseDate": <str>,
-      "copyright": <str>,
-      "type": "ALBUM",
-      "version": <str>,
-      "url": <str>,
-      "cover": <str>,
-      "vibrantColor": <str>,
-      "videoCover": <str>,
-      "explicit": <bool>,
-      "upc": <str>,
-      "popularity": <int>,
-      "audioQuality": <str>,
-      "audioModes": [<str>],
-      "mediaMetadata": {
-        "tags": [<str>]
-      },
-      "artist": {
-        "id": <int>,
-        "name": <str>,
-        "type": <str>,
-        "picture": <str>
-      },
-      "artists": [
-        {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        }
-      ]
-    }
-  ],
-  "source": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_similar_artists(artist_id: str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for artists similar to a specified -artist.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 100

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
artistsdict

A dictionary containing TIDAL catalog information for -artists similar to the specified artist and metadata for the -returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "id": <int>,
-      "name": <str>,
-      "type": None,
-      "artistTypes": [<str>],
-      "url": <str>,
-      "picture": <str>,
-      "popularity": <int>,
-      "banner": <str>,
-      "artistRoles": <list>,
-      "mixes": <dict>,
-      "relationType": "SIMILAR_ARTIST"
-    }
-  ],
-  "source": "TIDAL"
-}
-
-
-
-
-
-
-
-
- -
-
-get_track(track_id: int | str, country_code: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for a track.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
trackdict

TIDAL catalog information for a track.

-
-

Sample response

-
{
-  "id": <int>,
-  "title": <str>,
-  "duration": <int>,
-  "replayGain": <float>,
-  "peak": <float>,
-  "allowStreaming": <bool>,
-  "streamReady": <bool>,
-  "adSupportedStreamReady": <bool>,
-  "djReady": <bool>,
-  "stemReady": <bool>,
-  "streamStartDate": <str>,
-  "premiumStreamingOnly": <bool>,
-  "trackNumber": <int>,
-  "volumeNumber": <int>,
-  "version": <str>,
-  "popularity": <int>,
-  "copyright": <str>,
-  "url": <str>,
-  "isrc": <str>,
-  "editable": <bool>,
-  "explicit": <bool>,
-  "audioQuality": <str>,
-  "audioModes": [<str>],
-  "mediaMetadata": {
-    "tags": [<str>]
-  },
-  "artist": {
-    "id": <int>,
-    "name": <str>,
-    "type": <str>,
-    "picture": <str>
-  },
-  "artists": [
-    {
-      "id": <int>,
-      "name": <str>,
-      "type": <str>,
-      "picture": <str>
-    }
-  ],
-  "album": {
-    "id": <int>,
-    "title": <str>,
-    "cover": <str>,
-    "vibrantColor": <str>,
-    "videoCover": <str>
-  },
-  "mixes": {
-    "TRACK_MIX": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_composers(track_id: int | str) → list[str][source]#
-

Get the composers, lyricists, and/or songwriters of a track.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-

Note

-

This method is provided for convenience and is not a private -TIDAL API endpoint.

-
-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
-
-
Returns:
-
-
composerslist

Composers, lyricists, and/or songwriters of the track.

-

Example: ['Tommy Wright III', 'Beyoncé', -'Kelman Duran', 'Terius "The-Dream" G...de-Diamant', -'Mike Dean']

-
-
-
-
-
- -
-
-get_track_contributors(track_id: int | str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Get the contributors to a track and their roles.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, default: 100

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
contributorsdict

A dictionary containing a track’s contributors and their -roles, and metadata for the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "name": <str>,
-      "role": <str>
-    }
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_credits(track_id: int | str, country_code: str = None) → list[dict[str, Any]][source]#
-

Get credits for a track.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-
-
countrystr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If not specified, the -country associated with the user account will be used.

-

Example: "US".

-
-
-
-
Returns:
-
-
creditslist

A list of roles and their associated contributors.

-
-

Sample response

-
[
-  {
-    "type": <str>,
-    "contributors": [
-      {
-        "name": <str>,
-        "id": <int>
-      }
-    ]
-  }
-]
-
-
-
-
-
-
-
-
- -
-
-get_track_lyrics(id: int | str, country_code: str = None) → dict[str, Any][source]#
-

Get lyrics for a track.

-
-

User authentication and subscription

-

Requires user authentication via an OAuth 2.0 authorization -flow and an active TIDAL subscription.

-
-
-
Parameters:
-
-
idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
lyricsdict

A dictionary containing formatted and time-synced lyrics (if -available) in the “lyrics” and “subtitles” keys, -respectively.

-
-

Sample response

-
{
-  "trackId": <int>,
-  "lyricsProvider": <str>,
-  "providerCommontrackId": <str>,
-  "providerLyricsId": <str>,
-  "lyrics": <str>,
-  "subtitles": <str>,
-  "isRightToLeft": <bool>
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_mix_id(tidal_id: int | str, country_code: str = None) → str[source]#
-

Get the curated mix of tracks based on a track.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
tidal_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
mix_idstr

TIDAL mix ID.

-

Example: "0017159e6a1f34ae3d981792d72ecf".

-
-
-
-
-
- -
-
-get_track_playback_info(track_id: int | str, *, audio_quality: str = 'HI_RES', playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → dict[str, Any][source]#
-

Get playback information for a track.

-
-

User authentication, authorization scope, and - subscription

-

Requires the r_usr authorization scope if the device -code flow was used.

-

Full track playback information and lossless audio is only -available with user authentication and an active TIDAL -subscription.

-

High-resolution and immersive audio is only available with -the HiFi Plus plan and when the current client credentials -are from a supported device.

-
-

See also

-

For more information on audio quality availability, see -the Download TIDAL, -TIDAL Pricing, and -Dolby Atmos <https://support.tidal.com/hc/en-us/articles -/360004255778-Dolby-Atmos> web pages.

-
-
-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
audio_qualitystr, keyword-only, default: "HI-RES"

Audio quality.

-
-

Valid values:

-
    -

  • "LOW" for 64 kbps (22.05 kHz) MP3 without user -authentication or 96 kbps AAC with user authentication.

    • -

  • "HIGH" for 320 kbps AAC.

    • -

  • "LOSSLESS" for 1411 kbps (16-bit, 44.1 kHz) ALAC -or FLAC.

    • -

  • "HI_RES" for up to 9216 kbps (24-bit, 96 kHz) -MQA-encoded FLAC.

    • -
-
-
-
playback_modestr, keyword-only, default: "STREAM"

Playback mode.

-

Valid values: "STREAM" and "OFFLINE".

-
-
asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

-
-

Valid values:

-
    -

  • "FULL": Full track.

    • -

  • "PREVIEW": 30-second preview of the track.

    • -
-
-
-
streaming_session_idstr, keyword-only, optional

Streaming session ID.

-
-
-
-
Returns:
-
-
infodict

Track playback information.

-
-

Sample response

-
{
-  "trackId": <int>,
-  "assetPresentation": <str>,
-  "audioMode": <str>,
-  "audioQuality": <str>,
-  "manifestMimeType": <str>,
-  "manifestHash": <str>,
-  "manifest": <str>,
-  "albumReplayGain": <float>,
-  "albumPeakAmplitude": <float>,
-  "trackReplayGain": <float>,
-  "trackPeakAmplitude": <float>
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_recommendations(track_id: int | str, country_code: str = None, *, limit: int = None, offset=None) → dict[str, Any][source]#
-

Get TIDAL catalog information for a track’s recommended -tracks and videos.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
recommendationsdict

A dictionary containing TIDAL catalog information for the -recommended tracks and metadata for the returned results.

-
-

Sample response

-
{
-  "limit": <int>,
-  "offset": <int>,
-  "totalNumberOfItems": <int>,
-  "items": [
-    {
-      "id": <int>,
-      "title": <str>,
-      "duration": <int>,
-      "replayGain": <float>,
-      "peak": <float>,
-      "allowStreaming": <bool>,
-      "streamReady": <bool>,
-      "adSupportedStreamReady": <bool>,
-      "djReady": <bool>,
-      "stemReady": <bool>,
-      "streamStartDate": <str>,
-      "premiumStreamingOnly": <bool>,
-      "trackNumber": <int>,
-      "volumeNumber": <int>,
-      "version": <str>,
-      "popularity": <int>,
-      "copyright": <str>,
-      "url": <str>,
-      "isrc": <str>,
-      "editable": <bool>,
-      "explicit": <bool>,
-      "audioQuality": <str>,
-      "audioModes": [<str>],
-      "mediaMetadata": {
-        "tags": [<str>]
-      },
-      "artist": {
-        "id": <int>,
-        "name": <str>,
-        "type": <str>,
-        "picture": <str>
-      },
-      "artists": [
-        {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        }
-      ],
-      "album": {
-        "id": <int>,
-        "title": <str>,
-        "cover": <str>,
-        "vibrantColor": <str>,
-        "videoCover": <str>
-      },
-      "mixes": {
-        "TRACK_MIX": <str>
-      }
-    },
-    "sources": [
-      "SUGGESTED_TRACKS"
-    ]
-  ]
-}
-
-
-
-
-
-
-
-
- -
-
-get_track_stream(track_id: int | str, *, audio_quality: str = 'HI_RES', playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → bytes | str[source]#
-

Get the audio stream data for a track.

-
-

User authentication, authorization scope, and - subscription

-

Requires the r_usr authorization scope if the device -code flow was used.

-

Full track playback information and lossless audio is only -available with user authentication and an active TIDAL -subscription.

-

High-resolution and immersive audio is only available with -the HiFi Plus plan and when the current client credentials -are from a supported device.

-
-

See also

-

For more information on audio quality availability, see -the Download TIDAL, -TIDAL Pricing, and -Dolby Atmos web pages.

-
-
-
-

Note

-

This method is provided for convenience and is not a private -TIDAL API endpoint.

-
-
-
Parameters:
-
-
track_idint or str

TIDAL track ID.

-

Example: 251380837.

-
-
audio_qualitystr, keyword-only, default: "HI-RES"

Audio quality.

-
-

Valid values:

-
    -

  • "LOW" for 64 kbps (22.05 kHz) MP3 without user -authentication or 96 kbps AAC with user authentication.

    • -

  • "HIGH" for 320 kbps AAC.

    • -

  • "LOSSLESS" for 1411 kbps (16-bit, 44.1 kHz) ALAC -or FLAC.

    • -

  • "HI_RES" for up to 9216 kbps (24-bit, 96 kHz) -MQA-encoded FLAC.

    • -
-
-
-
playback_modestr, keyword-only, default: "STREAM"

Playback mode.

-

Valid values: "STREAM" and "OFFLINE".

-
-
asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

-
-

Valid values:

-
    -

  • "FULL": Full track.

    • -

  • "PREVIEW": 30-second preview of the track.

    • -
-
-
-
streaming_session_idstr, keyword-only, optional

Streaming session ID.

-
-
-
-
Returns:
-
-
streambytes

Audio stream data.

-
-
codecstr

Audio codec.

-
-
-
-
-
- -
-
-get_user_followers(user_id: int | str = None, *, limit: int = 500, cursor: str = None) → dict[str, Any][source]#
-

Get a TIDAL user’s followers.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
user_idstr

TIDAL user ID. If not specified, the ID associated with the -user account in the current session is used.

-

Example: 172311284.

-
-
limitint, keyword-only, default: 500

Page size.

-

Example: 10.

-
-
cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. -Use with limit to get the next page of search results.

-
-
-
-
Returns:
-
-
followersdict

A dictionary containing the user’s followers and the cursor -position.

-
-
-
-
-
- -
-
-get_user_following(user_id: int | str = None, *, include_only: str = None, limit: int = 500, cursor: str = None)[source]#
-

Get the people (artists, users, etc.) a TIDAL user follows.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
user_idstr

TIDAL user ID. If not specified, the ID associated with the -user account in the current session is used.

-

Example: 172311284.

-
-
include_onlystr, keyword-only, optional

Type of people to return.

-

Valid values: "ARTIST" and "USER".

-
-
limitint, keyword-only, default: 500

Page size.

-

Example: 10.

-
-
cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. -Use with limit to get the next page of search results.

-
-
-
-
Returns:
-
-
followingdict

A dictionary containing the people following the user and -the cursor position.

-
-

Sample response

-
{
-  "items": [
-    {
-      "id": <int>,
-      "name": <str>,
-      "picture": <str>,
-      "imFollowing": <bool>,
-      "trn": <str>,
-      "followType": <str>
-    }
-  ],
-  "cursor": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_user_playlist(playlist_uuid: str) → dict[str, Any][source]#
-

Get TIDAL catalog information for a user playlist.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL user playlist UUID.

-

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

-
-
-
-
Returns:
-
-
playlistdict

TIDAL catalog information for a user playlist.

-
-

Sample response

-
{
-  "playlist": {
-    "uuid": <str>,
-    "type": "USER",
-    "creator": {
-      "id": <int>,
-      "name": <str>,
-      "picture": <str>,
-      "type": "USER"
-    },
-    "contentBehavior": <str>,
-    "sharingLevel": <str>,
-    "status": <str>,
-    "source": <str>,
-    "title": <str>,
-    "description": <str>,
-    "image": <str>,
-    "squareImage": <str>,
-    "url": <str>,
-    "created": <str>,
-    "lastUpdated": <str>,
-    "lastItemAddedAt": <str>,
-    "duration": <int>,
-    "numberOfTracks": <int>,
-    "numberOfVideos": <int>,
-    "promotedArtists": [],
-    "trn": <str>,
-  },
-  "followInfo": {
-    "nrOfFollowers": <int>,
-    "tidalResourceName": <str>,
-    "followed": <bool>,
-    "followType": "PLAYLIST"
-  },
-  "profile": {
-    "userId": <int>,
-    "name": <str>,
-    "color": [<str>]
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-get_user_playlists(user_id: int | str = None, *, limit: int = 50, cursor: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for playlists created by a TIDAL -user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
user_idstr

TIDAL user ID. If not specified, the ID associated with the -user account in the current session is used.

-
-
limitint, keyword-only, default: 50

Page size.

-

Example: 10.

-
-
cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. -Use with limit to get the next page of search results.

-
-
-
-
Returns:
-
-
playlistsdict

A dictionary containing the user’s playlists and the cursor -position.

-
-

Sample response

-
{
-  "items": [
-    {
-      "playlist": {
-        "uuid": <str>,
-        "type": "USER",
-        "creator": {
-          "id": <int>,
-          "name": <str>,
-          "picture": <str>,
-          "type": "USER"
-        },
-        "contentBehavior": <str>,
-        "sharingLevel": <str>,
-        "status": <str>,
-        "source": <str>,
-        "title": <str>,
-        "description": <str>,
-        "image": <str>,
-        "squareImage": <str>,
-        "url": <str>,
-        "created": <str>,
-        "lastUpdated": <str>,
-        "lastItemAddedAt": <str>,
-        "duration": <int>,
-        "numberOfTracks": <int>,
-        "numberOfVideos": <int>,
-        "promotedArtists": [],
-        "trn": <str>,
-      },
-      "followInfo": {
-        "nrOfFollowers": <int>,
-        "tidalResourceName": <str>,
-        "followed": <bool>,
-        "followType": "PLAYLIST"
-      },
-      "profile": {
-        "userId": <int>,
-        "name": <str>,
-        "color": [<str>]
-      }
-    }
-  ],
-  "cursor": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_user_profile(user_id: int | str) → dict[str, Any][source]#
-

Get a TIDAL user’s profile information.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
user_idint or str

TIDAL user ID.

-

Example: 172311284.

-
-
-
-
Returns:
-
-
profiledict

A dictionary containing the user’s profile information.

-
-

Sample response

-
{
-  "userId": <int>,
-  "name": <str>,
-  "color": [<str>],
-  "picture": <str>,
-  "numberOfFollowers": <int>,
-  "numberOfFollows": <int>,
-  "prompts": [
-    {
-      "id": <int>,
-      "title": <str>,
-      "description": <str>,
-      "colors": {
-        "primary": <str>,
-        "secondary": <str>,
-      },
-      "trn": <str>,
-      "data": <str>,
-      "updatedTime": <str>,
-      "supportedContentType": "TRACK"
-    }
-  ],
-  "profileType": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_video(video_id: int | str, country_code: str = None) → dict[str, Any][source]#
-

Get TIDAL catalog information for a video.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
video_idint or str

TIDAL video ID.

-

Example: 59727844.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
-
-
Returns:
-
-
videodict

TIDAL catalog information for a video.

-
-

Sample response

-
{
-  "id": <int>,
-  "title": <str>,
-  "volumeNumber": <int>,
-  "trackNumber": <int>,
-  "releaseDate": <str>,
-  "imagePath": <str>,
-  "imageId": <str>,
-  "vibrantColor": <str>,
-  "duration": <int>,
-  "quality": <str>,
-  "streamReady": <bool>,
-  "adSupportedStreamReady": <bool>,
-  "djReady": <bool>,
-  "stemReady": <bool>,
-  "streamStartDate": <str>,
-  "allowStreaming": <bool>,
-  "explicit": <bool>,
-  "popularity": <int>,
-  "type": <str>,
-  "adsUrl": <str>,
-  "adsPrePaywallOnly": <bool>,
-  "artist": {
-    "id": <int>,
-    "name": <str>,
-    "type": <str>,
-    "picture": <str>,
-  },
-  "artists": [
-    {
-      "id": <int>,
-      "name": <str>,
-      "type": <str>,
-      "picture": <str>,
-    }
-  ],
-  "album": <dict>
-}
-
-
-
-
-
-
-
-
- -
-
-get_video_page(video_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any][source]#
-

Get the TIDAL page for a video.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
video_idint or str

TIDAL video ID.

-

Example: 75623239.

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
device_typestr, keyword-only, default: "BROWSER"

Device type.

-
-

Valid values:

-
    -

  • "BROWSER" for a web browser.

    • -

  • "DESKTOP" for the desktop TIDAL application.

    • -

  • "PHONE" for the mobile TIDAL application.

    • -

  • "TV" for the smart TV TIDAL application.

    • -
-
-
-
-
-
Returns:
-
-
pagedict

A dictionary containing the page ID, title, and submodules.

-
-
-
-
-
- -
-
-get_video_playback_info(video_id: int | str, *, video_quality: str = 'HIGH', playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → dict[str, Any][source]#
-

Get playback information for a video.

-
-

User authentication, authorization scope, and - subscription

-

Requires the r_usr authorization scope if the device -code flow was used.

-

Full video playback information is only available with user -authentication and an active TIDAL subscription.

-
-
-
Parameters:
-
-
video_idint or str

TIDAL video ID.

-

Example: 59727844.

-
-
video_qualitystr, keyword-only, default: "HIGH"

Video quality.

-

Valid values: "AUDIO_ONLY", "LOW", -"MEDIUM", and "HIGH".

-
-
playback_modestr, keyword-only, default: "STREAM"

Playback mode.

-

Valid values: "STREAM" and "OFFLINE".

-
-
asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

-
-

Valid values:

-
    -

  • "FULL": Full video.

    • -

  • "PREVIEW": 30-second preview of the video.

    • -
-
-
-
streaming_session_idstr, keyword-only, optional

Streaming session ID.

-
-
-
-
Returns:
-
-
infodict

Video playback information.

-
-

Sample response

-
{
-  "videoId": <int>,
-  "streamType": <str>,
-  "assetPresentation": <str>,
-  "videoQuality": <str>,
-  "manifestMimeType": <str>,
-  "manifestHash": <str>,
-  "manifest": <str>
-}
-
-
-
-
-
-
-
-
- -
-
-get_video_stream(video_id: int | str, *, video_quality: str = 'HIGH', max_resolution: int = 2160, playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → tuple[bytes, str][source]#
-

Get the video stream data for a music video.

-
-

User authentication, authorization scope, and - subscription

-

Requires the r_usr authorization scope if the device -code flow was used.

-

Full video playback information is only available with user -authentication and an active TIDAL subscription.

-
-
-

Note

-

This method is provided for convenience and is not a private -TIDAL API endpoint.

-
-
-
Parameters:
-
-
video_idint or str

TIDAL video ID.

-

Example: 59727844.

-
-
video_qualitystr, keyword-only, default: "HIGH"

Video quality.

-

Valid values: "AUDIO_ONLY", "LOW", -"MEDIUM", and "HIGH".

-
-
max_resolutionint, keyword-only, default: 2160

Maximum video resolution (number of vertical pixels).

-
-
playback_modestr, keyword-only, default: "STREAM"

Playback mode.

-

Valid values: "STREAM" and "OFFLINE".

-
-
asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

-
-

Valid values:

-
    -

  • "FULL": Full video.

    • -

  • "PREVIEW": 30-second preview of the video.

    • -
-
-
-
streaming_session_idstr, keyword-only, optional

Streaming session ID.

-
-
-
-
Returns:
-
-
streambytes

Video stream data.

-
-
codecstr

Video codec.

-
-
-
-
-
- -
-
-move_playlist(playlist_uuid: str, folder_id: str) → None[source]#
-

Move a playlist in the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

-
-
folder_idstr

ID of the folder to move the playlist into. To place a -playlist directly under “My Playlists”, use -folder_id="root".

-
-
-
-
-
- -
-
-move_playlist_item(playlist_uuid: str, from_index: int | str, to_index: int | str) → None[source]#
-

Move an item in a playlist owned by the current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

-
-
from_indexint or str

Current item index.

-
-
to_indexint or str

Desired item index.

-
-
-
-
-
- -
-
-search(query: str, country_code: str = None, *, type: str = None, limit: int = None, offset: int = None) → dict[str, Any][source]#
-

Search for albums, artists, tracks, and videos.

-
-

Authorization scope

-

Requires the r_usr authorization scope if the device -code flow was used.

-
-
-
Parameters:
-
-
querystr

Search query.

-

Example: "Beyoncé".

-
-
country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the -country code associated with the user account in the current -session or the current IP address will be used instead.

-

Example: "US".

-
-
typestr, keyword-only, optional

Target search type. Searches for all types if not specified.

-

Valid values: "ALBUMS", "ARTISTS", -"TRACKS", "VIDEOS".

-
-
limitint, keyword-only, optional

Page size.

-

Example: 10.

-
-
offsetint, keyword-only, optional

Pagination offset (in number of items).

-

Example: 0.

-
-
-
-
Returns:
-
-
resultsdict

A dictionary containing TIDAL catalog information for -albums, artists, tracks, and videos matching the search -query, and metadata for the returned results.

-
-

Sample response

-
{
-  "artists": {
-    "limit": <int>,
-    "offset": <int>,
-    "totalNumberOfItems": <int>,
-    "items": [
-      {
-        "id": <int>,
-        "name": <str>,
-        "artistTypes": [<str>],
-        "url": <str>,
-        "picture": <str>,
-        "popularity": <int>,
-        "artistRoles": [
-          {
-            "categoryId": <int>,
-            "category": <str>
-          }
-        ],
-        "mixes": {
-          "ARTIST_MIX": <str>
-        }
-      }
-    ]
-  },
-  "albums": {
-    "limit": <int>,
-    "offset": <int>,
-    "totalNumberOfItems": <int>,
-    "items": [
-      {
-        "id": <int>,
-        "title": <str>,
-        "duration": <int>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "allowStreaming": <bool>,
-        "premiumStreamingOnly": <bool>,
-        "numberOfTracks": <int>,
-        "numberOfVideos": <int>,
-        "numberOfVolumes": <int>,
-        "releaseDate": <str>,
-        "copyright": <str>,
-        "type": "ALBUM",
-        "version": <str>,
-        "url": <str>,
-        "cover": <str>,
-        "vibrantColor": <str>,
-        "videoCover": <str>,
-        "explicit": <bool>,
-        "upc": <str>,
-        "popularity": <int>,
-        "audioQuality": <str>,
-        "audioModes": [<str>],
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ]
-      }
-    ]
-  },
-  "playlists": {
-    "limit": <int>,
-    "offset": <int>,
-    "totalNumberOfItems": <int>,
-    "items": [
-      {
-        "uuid": <str>,
-        "title": <str>,
-        "numberOfTracks": <int>,
-        "numberOfVideos": <int>,
-        "creator": {
-          "id": <int>
-        },
-        "description": <str>,
-        "duration": <int>,
-        "lastUpdated": <str>,
-        "created": <str>,
-        "type": <str>,
-        "publicPlaylist": <bool>,
-        "url": <str>,
-        "image": <str>,
-        "popularity": <int>,
-        "squareImage": <str>,
-        "promotedArtists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>,
-          }
-        ],
-        "lastItemAddedAt": <str>
-      }
-    ]
-  },
-  "tracks": {
-    "limit": <int>,
-    "offset": <int>,
-    "totalNumberOfItems": <int>,
-    "items": [
-      {
-        "id": <int>,
-        "title": <str>,
-        "duration": <int>,
-        "replayGain": <float>,
-        "peak": <float>,
-        "allowStreaming": <bool>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "premiumStreamingOnly": <bool>,
-        "trackNumber": <int>,
-        "volumeNumber": <int>,
-        "version": <str>,
-        "popularity": <int>,
-        "copyright": <str>,
-        "url": <str>,
-        "isrc": <str>,
-        "editable": <bool>,
-        "explicit": <bool>,
-        "audioQuality": <str>,
-        "audioModes": [<str>],
-        "mediaMetadata": {
-          "tags": [<str>]
-        },
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>
-          }
-        ],
-        "album": {
-          "id": <int>,
-          "title": <str>,
-          "cover": <str>,
-          "vibrantColor": <str>,
-          "videoCover": <str>
-        },
-        "mixes": {
-          "TRACK_MIX": <str>
-        }
-      }
-    ]
-  },
-  "videos": {
-    "limit": <int>,
-    "offset": <int>,
-    "totalNumberOfItems": <int>,
-    "items": [
-      {
-        "id": <int>,
-        "title": <str>,
-        "volumeNumber": <int>,
-        "trackNumber": <int>,
-        "releaseDate": <str>,
-        "imagePath": <str>,
-        "imageId": <str>,
-        "vibrantColor": <str>,
-        "duration": <int>,
-        "quality": <str>,
-        "streamReady": <bool>,
-        "adSupportedStreamReady": <bool>,
-        "djReady": <bool>,
-        "stemReady": <bool>,
-        "streamStartDate": <str>,
-        "allowStreaming": <bool>,
-        "explicit": <bool>,
-        "popularity": <int>,
-        "type": <str>,
-        "adsUrl": <str>,
-        "adsPrePaywallOnly": <bool>,
-        "artist": {
-          "id": <int>,
-          "name": <str>,
-          "type": <str>,
-          "picture": <str>,
-        },
-        "artists": [
-          {
-            "id": <int>,
-            "name": <str>,
-            "type": <str>,
-            "picture": <str>,
-          }
-        ],
-        "album": <dict>
-      }
-    ]
-  },
-  "topHit": {
-    "value": <dict>,
-    "type": <str>
-  }
-}
-
-
-
-
-
-
-
-
- -
-
-set_access_token(access_token: str = None, *, refresh_token: str = None, expiry: str | datetime = None) → None[source]#
-

Set the private TIDAL API access token.

-
-
Parameters:
-
-
access_tokenstr, optional

Access token. If not provided, an access token is obtained -using an OAuth 2.0 authorization flow or from the Spotify -Web Player.

-
-
refresh_tokenstr, keyword-only, optional

Refresh token accompanying access_token.

-
-
expirystr or datetime.datetime, keyword-only, optional

Access token expiry timestamp in the ISO 8601 format -%Y-%m-%dT%H:%M:%SZ. If provided, the user will be -reauthenticated using the refresh token (if available) or -the default authorization flow (if possible) when -access_token expires.

-
-
-
-
-
- -
-
-set_flow(flow: str, client_id: str, *, client_secret: str = None, browser: bool = False, scopes: str | list[str] = '', save: bool = True) → None[source]#
-

Set the authorization flow.

-
-
Parameters:
-
-
flowstr

Authorization flow. If not specified, no user authentication -will be performed.

-
-

Valid values:

-
    -

  • "pkce" for the authorization code with proof -key for code exchange (PKCE) flow.

    • -

  • "client_credentials" for the client credentials -flow.

    • -
-
-
-
client_idstr

Client ID.

-
-
client_secretstr, keyword-only, optional

Client secret. Required for all OAuth 2.0 authorization -flows.

-
-
browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for -the authorization code with PKCE or device code flows. If -False, users will have to manually open the -authorization URL, and for the authorization code flow, -provide the full callback URI via the terminal. For the -authorization code with PKCE flow, the Playwright framework -by Microsoft is used.

-
-
scopesstr or list, keyword-only, optional

Authorization scopes to request user access for in the OAuth -2.0 flows.

-

Valid values: "r_usr", "w_usr", and -"w_sub" (device code flow only).

-
-
savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens -and their associated properties to the Minim configuration -file.

-
-
-
-
-
- -
-
-set_playlist_privacy(playlist_uuid: str, public: bool) → None[source]#
-

Set the privacy of a playlist owned by the current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

-
-
publicbool

Determines whether the playlist is public (True) or -private (False).

-
-
-
-
-
- -
-
-unblock_artist(artist_id: int | str) → None[source]#
-

Unblock an artist from appearing in mixes and the radio.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
artist_idint or str

TIDAL artist ID.

-

Example: 1566.

-
-
-
-
-
- -
-
-unblock_user(user_id: int | str) → None[source]#
-

Unblock a user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
user_idint or str

TIDAL user ID.

-

Example: 172311284.

-
-
-
-
-
- -
-
-unfavorite_albums(album_ids: int | str | list[int | str]) → None[source]#
-

Remove albums from the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
album_idsint, str, or list

TIDAL album ID(s).

-

Examples: "251380836,275646830" or -[251380836, 275646830].

-
-
-
-
-
- -
-
-unfavorite_artists(artist_ids: int | str | list[int | str]) → None[source]#
-

Remove artists from the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
artist_idsint, str, or list

TIDAL artist ID(s).

-

Examples: "1566,7804" or [1566, 7804].

-
-
-
-
-
- -
-
-unfavorite_mixes(mix_ids: str | list[str]) → None[source]#
-

Remove mixes from the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
mix_idsstr or list

TIDAL mix ID(s).

-

Examples: "000ec0b01da1ddd752ec5dee553d48,            000dd748ceabd5508947c6a5d3880a" or -["000ec0b01da1ddd752ec5dee553d48", -"000dd748ceabd5508947c6a5d3880a"]

-
-
-
-
-
- -
-
-unfavorite_playlist(playlist_uuid: str) → None[source]#
-

Remove a playlist from the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

-
-
-
-
-
- -
-
-unfavorite_tracks(track_ids: int | str | list[int | str]) → None[source]#
-

Remove tracks from the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
track_idsint, str, or list

TIDAL track ID(s).

-

Examples: "251380837,251380838" or -[251380837, 251380838].

-
-
-
-
-
- -
-
-unfavorite_videos(video_ids: int | str | list[int | str]) → None[source]#
-

Remove videos from the current user’s collection.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
video_idsint, str, or list

TIDAL video ID(s).

-

Examples: "59727844,75623239" or -[59727844, 75623239].

-
-
-
-
-
- -
-
-unfollow_user(user_id: int | str) → None[source]#
-

Unfollow a user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
user_idint or str

TIDAL user ID.

-

Example: 172311284.

-
-
-
-
-
- -
-
-update_playlist(playlist_uuid: str, *, title: str = None, description: str = None) → None[source]#
-

Update the title or description of a playlist owned by the -current user.

-
-

User authentication and authorization scope

-

Requires user authentication and the r_usr -authorization scope if the device code flow was used.

-
-
-
Parameters:
-
-
playlist_uuidstr

TIDAL playlist UUID.

-

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

-
-
titlestr, keyword-only, optional

New playlist title.

-
-
descriptionstr, keyword-only, optional

New playlist description.

-
-
-
-
-
- -
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.tidal.html b/docs/api/minim.tidal.html deleted file mode 100644 index 666d48e8..00000000 --- a/docs/api/minim.tidal.html +++ /dev/null @@ -1,349 +0,0 @@ - - - - - - - - - tidal - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

tidal#

-
-

TIDAL#

-

This module contains a complete implementation of all public TIDAL API -endpoints and a minimum implementation of the more robust but private -TIDAL API.

-
-

Classes

-
- - - - - - - - - -

API

TIDAL API client.

PrivateAPI

Private TIDAL API client.

-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.utility.format_multivalue.html b/docs/api/minim.utility.format_multivalue.html deleted file mode 100644 index d0b3ebf1..00000000 --- a/docs/api/minim.utility.format_multivalue.html +++ /dev/null @@ -1,364 +0,0 @@ - - - - - - - - - format_multivalue - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

format_multivalue#

-
-
-minim.utility.format_multivalue(value: Any, multivalue: bool, *, primary: bool = False, sep: str | tuple[str] = (', ', ' & ')) → str | list[Any][source]#
-

Format a field value based on whether multivalue for that field is -supported.

-
-
Parameters:
-
-
valueAny

Field value to format.

-
-
multivaluebool

Determines whether multivalue tags are supported. If -False, the items in value are concatenated using the -separator(s) specified in sep.

-
-
primarybool, keyword-only, default: False

Specifies whether the first item in value should be used when -value is a list and multivalue=False.

-
-
sepstr or tuple, keyword-only, default: (", ", " & ")

Separator(s) to use to concatenate multivalue tags. If a -str is provided, it is used to concatenate all values. -If a tuple is provided, the first str is used to -concatenate all values except the last, and the second -str is used to append the final value.

-
-
-
-
Returns:
-
-
valueAny

Formatted field value.

-
-
-
-
-
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.utility.gestalt_ratio.html b/docs/api/minim.utility.gestalt_ratio.html deleted file mode 100644 index 70b92523..00000000 --- a/docs/api/minim.utility.gestalt_ratio.html +++ /dev/null @@ -1,356 +0,0 @@ - - - - - - - - - gestalt_ratio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

gestalt_ratio#

-
-
-minim.utility.gestalt_ratio(reference: str, strings: str | list[str]) → float | list[float] | ndarray[float][source]#
-

Compute the Gestalt or Ratcliff–Obershelp ratios, a measure of -similarity, for strings with respect to a reference string.

-
-
Parameters:
-
-
referencestr

Reference string.

-
-
stringsstr or list

Strings to compare with reference.

-
-
-
-
Returns:
-
-
ratiosfloat, list, or numpy.ndarray

Gestalt or Ratcliff–Obershelp ratios. If strings is a str, a -float is returned. If strings is a list, a numpy.ndarray -is returned if NumPy is installed; otherwise, a list is -returned.

-
-
-
-
-
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.utility.html b/docs/api/minim.utility.html deleted file mode 100644 index 5d9389ce..00000000 --- a/docs/api/minim.utility.html +++ /dev/null @@ -1,350 +0,0 @@ - - - - - - - - - utility - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

utility#

-
-

Utility functions#

-

This module contains a collection of utility functions.

-
-

Functions

-
- - - - - - - - - - - - -

format_multivalue

Format a field value based on whether multivalue for that field is supported.

gestalt_ratio

Compute the Gestalt or Ratcliff–Obershelp ratios, a measure of similarity, for strings with respect to a reference string.

levenshtein_ratio

Compute the Levenshtein ratios, a measure of similarity, for strings with respect to a reference string.

-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/minim.utility.levenshtein_ratio.html b/docs/api/minim.utility.levenshtein_ratio.html deleted file mode 100644 index c3dcc765..00000000 --- a/docs/api/minim.utility.levenshtein_ratio.html +++ /dev/null @@ -1,347 +0,0 @@ - - - - - - - - - levenshtein_ratio - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

levenshtein_ratio#

-
-
-minim.utility.levenshtein_ratio(reference: str, strings: str | list[str]) → float | list[float] | ndarray[float][source]#
-

Compute the Levenshtein ratios, a measure of similarity, for -strings with respect to a reference string.

-
-
Parameters:
-
-
referencestr

Reference string.

-
-
stringsstr or list

Strings to compare with reference.

-
-
-
-
Returns:
-
-
ratiosfloat, list, or numpy.ndarray

Levenshtein ratios. If strings is a str, a float is -returned. If strings is a list, a numpy.ndarray is -returned if NumPy is installed; otherwise, a list is returned.

-
-
-
-
-
- -
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/notebooks/getting_started.html b/docs/notebooks/getting_started.html deleted file mode 100644 index 8981358c..00000000 --- a/docs/notebooks/getting_started.html +++ /dev/null @@ -1,2336 +0,0 @@ - - - - - - - - - Getting Started - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

Getting Started#

-
-

Installation#

-

Minim is a Python package and can be installed from source using pip, the package installer for Python.

-
-

Note

-

Minim will be coming to PyPI and conda-forge once the PEP 541 request is resolved!

-
-
    -

  1. Grab a copy of the Minim repository:

    -
    git clone https://github.com/bbye98/minim.git
-
    -
    -
    2. -

  2. Enter the repository directory:

    -
    cd minim
-
    -
    -
    3. -

  3. Optional: Create a virtual environment to prevent dependency conflicts.

    -

    Conda

    -
      -

    • Create an environment named minim and install the required dependencies using one of the following commands:

      -
      conda create -n minim --file requirements_minimal.txt  # required dependencies only
-conda env create -f environment.yml                    # all dependencies
-
      -
      -
      • -

    • Activate the environment:

      -
      conda activate minim
-
      -
      -
      • -
    -

    venv

    -
      -

    • Create an environment named minim:

      -
      python -m venv minim
-
      -
      -
      • -

    • Activate the environment using one of the following commands:

      -
      source minim/bin/activate        # POSIX: bash or zsh
-minim\Scripts\activate.bat       # Windows: cmd.exe
-minim\Scripts\Activate.ps1       # Windows: PowerShell
-
      -
      -
      • -

    • The required dependencies will be installed automatically alongside Minim in the next step. To install all dependencies instead:

      -
      python -m pip install -r requirements.txt
-
      -
      -
      • -
    -

    virtualenv

    -
      -

    • Create an environment named minim:

      -
      virtualenv minim
-
      -
      -
      • -

    • Activate the environment using one of the following commands:

      -
      source minim/bin/activate        # Linux or macOS
-.\minim\Scripts\activate         # Windows
-
      -
      -
      • -

    • The required dependencies will be installed automatically alongside Minim in the next step. To install all dependencies instead:

      -
      python -m pip install -r requirements.txt
-
      -
      -
      • -
    -
    4. -

  4. Install Minim (and required dependencies, if you have not already done so) using pip:

    -
    python -m pip install -e .
-
    -
    -
    5. -

  5. Try importing Minim in Python:

    -
    python -c "import minim"
-
    -
    -

    If no errors like ModuleNotFoundError: No module named 'minim' are raised, you have successfully installed Minim!

    -
    6. -
-
-
-

Usage#

-
-

Music service APIs#

-
-
-
from minim import itunes, qobuz, spotify, tidal
-
-
-
-
-

Currently, clients for iTunes Search API, Qobuz API, Spotify Web API, and TIDAL APIs have been implemented. Other than the iTunes Search API, which does not require client credentials or support user authentication and can be used out of the box, the other APIs have a few additional prerequisite steps before they can be used. If you authenticate via Minim, the tokens and their related information will be cached and updated automatically as they expire and are refreshed.

-
-

iTunes Search API (minim.itunes.SearchAPI)#

-

To use the iTunes Search API, simply create a client by instantiating a minim.itunes.SearchAPI object with no arguments:

-
-
-
client_itunes = itunes.SearchAPI()
-
-
-
-
-
-
-

Private Qobuz API (minim.qobuz.PrivateAPI)#

-

If you already have a user authentication token, you can provide it and its accompanying app credentials to the client as keyword arguments auth_token, app_id, and app_secret, respectively, and skip this section.

-

To use the Qobuz API without user authentication, simply create a client by instantiating a minim.qobuz.PrivateAPI object with no arguments:

-
-
-
client_qobuz = qobuz.PrivateAPI()
-
-
-
-
-

To use the Qobuz API with user authentication and get access to all public and protected endpoints, you can pass flow="password" and provide your Qobuz email and password as keyword arguments email and password to the constructor:

-
client_qobuz = qobuz.PrivateAPI(flow="password", email=<QOBUZ_EMAIL>, password=<QOBUZ_PASSWORD>)
-
-
-

which will authenticate you via a POST request to and retrieve the user authentication token from the Qobuz Web Player, or specify browser=True to have Minim spawn a web browser with the Qobuz Web Player login page:

-
client_qobuz = qobuz.PrivateAPI(flow="password", browser=True)
-
-
-

which you can use to log in normally.

-
-
-

Private Spotify Lyrics Service (minim.spotify.PrivateLyricsService)#

-

If you already have a user access token, you can provide it and optionally its accompanying expiry time and sp_dc cookie to the client as keyword arguments access_token, expiry, and sp_dc, respectively, and skip this section.

-

To use the Spotify Lyrics service,

-
    -

  1. Launch a web browser and log into the Spotify Web Player.

    2. -

  2. Find the sp_dc cookie in your web browser’s storage.

    -
      -

    • For Chromium-based browsers, press F12 to open DevTools and navigate to Application > Storage > Cookies > https://open.spotify.com.

      • -

    • For Firefox, press Shift + F9 to open Storage Inspector and nagivate to Storage > Cookies > https://open.spotify.com.

      • -
    -
    3. -

  3. Create a client by instantiating a minim.spotify.WebAPI object with the sp_dc cookie as a keyword argument:

    -
    client_spotify_lyrics = spotify.PrivateLyricsService(sp_dc=<SPOTIFY_SP_DC>)
-
    -
    -

    or store the sp_dc cookie as an environment variable SPOTIFY_SP_DC and call the constructor with no arguments:

    -
    4. -
-
-
-
client_spotify_lyrics = spotify.PrivateLyricsService()
-
-
-
-
-
-
-

Spotify Web API (minim.spotify.WebAPI)#

-

If you already have an access token, you can provide it and optionally its accompanying refresh token, expiry time, and client credentials to the client as keyword arguments access_token, refresh_token, expiry, client_id, and client_secret, respectively, and skip this section.

-

First, register a Spotify application here and grab its client credentials. For the redirect URI, use http://localhost:8888/callback. You can replace 8888 with an open port of your choice, but you will need to pass port=<SPOTIFY_PORT> when you create a client.

-

To use the Spotify Web API without user authentication, you can provide the client credentials as keyword arguments client_id and client_secret to the constructor:

-
client_spotify = spotify.WebAPI(client_id=<SPOTIFY_CLIENT_ID>, 
-                                client_secret=<SPOTIFY_CLIENT_SECRET>)
-
-
-

or store the client credentials as environment variables SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET and call the constructor with no arguments:

-
-
-
client_spotify = spotify.WebAPI()
-
-
-
-
-

To use the Spotify Web API with user authentication,

-
    -

  1. Get the necessary authorization scopes using spotify.WebAPI.get_scopes():

    2. -
-
-
-
scopes = spotify.WebAPI.get_scopes("all")
-
-
-
-
-
    -

  1. Create a client with flow="pkce", the client credentials in client_id and client_secret, the authorization scopes in scopes, and optionally framework="http.server" to automate the authorization code retrieval process:

    -
    client_spotify = spotify.WebAPI(client_id=<SPOTIFY_CLIENT_ID>, 
-                                client_secret=<SPOTIFY_CLIENT_SECRET>,
-                                flow="pkce", scopes=scopes, framework="http.server")
-
    -
    -
    2. -

  2. If framework=None, open the authorization URL in a web browser.

    3. -

  3. Log into your Spotify account and authorize Minim by clicking Agree.

    4. -

  4. If framework=None, copy and paste the redirect URI into the prompt.

    5. -
-
-
-

TIDAL API (minim.tidal.API)#

-

If you already have a client-only access token, you can provide it and optionally its accompanying refresh token, expiry time, and client credentials to the client as keyword arguments access_token, refresh_token, expiry, client_id, and client_secret, respectively, and skip this section.

-

First, register a TIDAL application here and jot down the client credentials.

-

To use the TIDAL API, you can provide the client credentials as keyword arguments client_id and client_secret to the minim.tidal.API constructor:

-
client_tidal = tidal.API(client_id=<TIDAL_CLIENT_ID>, client_secret=<TIDAL_CLIENT_SECRET>)
-
-
-

or store the client credentials as environment variables TIDAL_CLIENT_ID and TIDAL_CLIENT_SECRET and create a client with no arguments:

-
-
-
client_tidal = tidal.API()
-
-
-
-
-
-
-

Private TIDAL API (minim.tidal.PrivateAPI)#

-

If you already have an access token, you can provide it and optionally its accompanying refresh token, expiry time, and client credentials to the client as keyword arguments access_token, refresh_token, expiry, client_id, and client_secret, respectively, and skip this section.

-

To use the TIDAL API without user authentication, simply create a client by instantiating a minim.tidal.PrivateAPI object with no arguments:

-
-
-
client_tidal_private = tidal.PrivateAPI()
-
-
-
-
-

To use the TIDAL API with user authentication,

-
    -

  1. Get client credentials from the TIDAL Web Player or the Android, iOS, macOS, and Windows applications by using a web debugging proxy tool to intercept web traffic.

    2. -

  2. Create a client with the client credentials in client_id and client_secret and optionally browser=True to automatically open a web browser for the authorization flow. Use the authorization code with PKCE flow:

    -
    client_tidal_private = tidal.PrivateAPI(client_id=<TIDAL_CLIENT_ID>, 
-                                        client_secret=<TIDAL_CLIENT_SECRET>,
-                                        flow="pkce", browser=True)
-
    -
    -

    if you obtained client credentials from the TIDAL Web Player or the desktop applications, or the device code flow:

    -
    client_tidal_private = tidal.PrivateAPI(client_id=<TIDAL_CLIENT_ID>, 
-                                        client_secret=<TIDAL_CLIENT_SECRET>,
-                                        flow="device", browser=True)
-
    -
    -

    if you obtained client credentials from the Android or iOS applications.

    -
    3. -

  3. Follow the instructions in the console (browser=False) or the web browser (browser=True) to log into your TIDAL account and authorize Minim.

    4. -
-
-
-

Examples#

-
-
Searching for artists#
-

Each of the APIs has a search() method that can be used to search for and retrieve information about an artist, such as the EDM group Galantis:

-
-
iTunes Search API#
-
-
-
client_itunes.search("Galantis", entity="musicArtist", limit=1)["results"][0]
-
-
-
-
- - -Hide code cell output - -
-
{'wrapperType': 'artist',
- 'artistType': 'Artist',
- 'artistName': 'Galantis',
- 'artistLinkUrl': 'https://music.apple.com/us/artist/galantis/543322169?uo=4',
- 'artistId': 543322169,
- 'amgArtistId': 2616267,
- 'primaryGenreName': 'Dance',
- 'primaryGenreId': 17}
-
-
-
-
-
-
-
-
Private Qobuz API#
-
-
-
client_qobuz.search("Galantis", limit=1, strict=True)["artists"]["items"][0]
-
-
-
-
- - -Hide code cell output - -
-
{'picture': 'https://static.qobuz.com/images/artists/covers/small/8dcf30e5c8e30281ecbb13b0886426c8.jpg',
- 'image': {'small': 'https://static.qobuz.com/images/artists/covers/small/8dcf30e5c8e30281ecbb13b0886426c8.jpg',
-  'medium': 'https://static.qobuz.com/images/artists/covers/medium/8dcf30e5c8e30281ecbb13b0886426c8.jpg',
-  'large': 'https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg',
-  'extralarge': 'https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg',
-  'mega': 'https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg'},
- 'name': 'Galantis',
- 'slug': 'galantis',
- 'albums_count': 143,
- 'id': 865362}
-
-
-
-
-
-
-
-
Spotify Web API#
-
-
-
client_spotify.search("Galantis", "artist", limit=1)["items"][0]
-
-
-
-
- - -Hide code cell output - -
-
{'external_urls': {'spotify': 'https://open.spotify.com/artist/4sTQVOfp9vEMCemLw50sbu'},
- 'followers': {'href': None, 'total': 3343551},
- 'genres': ['dance pop', 'edm', 'pop', 'pop dance'],
- 'href': 'https://api.spotify.com/v1/artists/4sTQVOfp9vEMCemLw50sbu',
- 'id': '4sTQVOfp9vEMCemLw50sbu',
- 'images': [{'height': 640,
-   'url': 'https://i.scdn.co/image/ab6761610000e5eb7bda087d6fb48d481efd3344',
-   'width': 640},
-  {'height': 320,
-   'url': 'https://i.scdn.co/image/ab676161000051747bda087d6fb48d481efd3344',
-   'width': 320},
-  {'height': 160,
-   'url': 'https://i.scdn.co/image/ab6761610000f1787bda087d6fb48d481efd3344',
-   'width': 160}],
- 'name': 'Galantis',
- 'popularity': 70,
- 'type': 'artist',
- 'uri': 'spotify:artist:4sTQVOfp9vEMCemLw50sbu'}
-
-
-
-
-
-
-
-
TIDAL API#
-
-
-
client_tidal.search("Galantis", "US", type="ARTISTS", limit=1)["artists"][0]
-
-
-
-
- - -Hide code cell output - -
-
{'resource': {'id': '4676988',
-  'name': 'Galantis',
-  'picture': [{'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/1024x256.jpg',
-    'width': 1024,
-    'height': 256},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/1080x720.jpg',
-    'width': 1080,
-    'height': 720},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/160x107.jpg',
-    'width': 160,
-    'height': 107},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/160x160.jpg',
-    'width': 160,
-    'height': 160},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/320x214.jpg',
-    'width': 320,
-    'height': 214},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/320x320.jpg',
-    'width': 320,
-    'height': 320},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/480x480.jpg',
-    'width': 480,
-    'height': 480},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/640x428.jpg',
-    'width': 640,
-    'height': 428},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/750x500.jpg',
-    'width': 750,
-    'height': 500},
-   {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/750x750.jpg',
-    'width': 750,
-    'height': 750}],
-  'tidalUrl': 'https://tidal.com/browse/artist/4676988'},
- 'id': '4676988',
- 'status': 200,
- 'message': 'success'}
-
-
-
-
-
-
-
-
Private TIDAL API#
-
-
-
client_tidal_private.search("Galantis", type="artist", limit=1)["items"][0]
-
-
-
-
- - -Hide code cell output - -
-
{'id': 4676988,
- 'name': 'Galantis',
- 'artistTypes': ['ARTIST', 'CONTRIBUTOR'],
- 'url': 'http://www.tidal.com/artist/4676988',
- 'picture': 'a627e21c-60f7-4e90-b2bb-e50b178c4f0b',
- 'popularity': 72,
- 'artistRoles': [{'categoryId': -1, 'category': 'Artist'},
-  {'categoryId': 3, 'category': 'Engineer'},
-  {'categoryId': 11, 'category': 'Performer'},
-  {'categoryId': 10, 'category': 'Production team'},
-  {'categoryId': 1, 'category': 'Producer'},
-  {'categoryId': 2, 'category': 'Songwriter'}],
- 'mixes': {'ARTIST_MIX': '000202a7e72fd90d0c0df2ed56ddea'}}
-
-
-
-
-
-
-
-
-
Searching for tracks#
-

The search() methods can also be used to search for and retrieve information about a track, such as “Everybody Talks” by Neon Trees:

-
-
iTunes Search API#
-
-
-
client_itunes.search("Everybody Talks", media="music", limit=1)["results"][0]
-
-
-
-
- - -Hide code cell output - -
-
{'wrapperType': 'track',
- 'kind': 'song',
- 'artistId': 350172836,
- 'collectionId': 1443469527,
- 'trackId': 1443469581,
- 'artistName': 'Neon Trees',
- 'collectionName': 'Picture Show',
- 'trackName': 'Everybody Talks',
- 'collectionCensoredName': 'Picture Show',
- 'trackCensoredName': 'Everybody Talks',
- 'artistViewUrl': 'https://music.apple.com/us/artist/neon-trees/350172836?uo=4',
- 'collectionViewUrl': 'https://music.apple.com/us/album/everybody-talks/1443469527?i=1443469581&uo=4',
- 'trackViewUrl': 'https://music.apple.com/us/album/everybody-talks/1443469527?i=1443469581&uo=4',
- 'previewUrl': 'https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview122/v4/5c/29/bf/5c29bf6b-ca2c-4e8b-2be6-c51a282c7dae/mzaf_1255557534804450018.plus.aac.p.m4a',
- 'artworkUrl30': 'https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/30x30bb.jpg',
- 'artworkUrl60': 'https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/60x60bb.jpg',
- 'artworkUrl100': 'https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/100x100bb.jpg',
- 'collectionPrice': 6.99,
- 'trackPrice': 1.29,
- 'releaseDate': '2012-01-01T12:00:00Z',
- 'collectionExplicitness': 'explicit',
- 'trackExplicitness': 'explicit',
- 'discCount': 1,
- 'discNumber': 1,
- 'trackCount': 12,
- 'trackNumber': 3,
- 'trackTimeMillis': 177280,
- 'country': 'USA',
- 'currency': 'USD',
- 'primaryGenreName': 'Alternative',
- 'contentAdvisoryRating': 'Explicit',
- 'isStreamable': True}
-
-
-
-
-
-
-
-
Private Qobuz API#
-
-
-
track_qobuz = client_qobuz.search("Everybody Talks", "ReleaseName", limit=1,
-                                  strict=True)["tracks"]["items"][0]
-track_qobuz
-
-
-
-
- - -Hide code cell output - -
-
{'maximum_bit_depth': 16,
- 'copyright': '2022 Arko Boom 2022 Arko Boom',
- 'performers': 'Arko Boom, MainArtist - Arkos Todd, Songwriter, ComposerLyricist',
- 'audio_info': {'replaygain_track_peak': 1, 'replaygain_track_gain': -3.06},
- 'performer': {'name': 'Arko Boom', 'id': 15899504},
- 'album': {'image': {'small': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_230.jpg',
-   'thumbnail': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_50.jpg',
-   'large': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_600.jpg'},
-  'maximum_bit_depth': 16,
-  'media_count': 1,
-  'artist': {'image': None,
-   'name': 'Arko Boom',
-   'id': 15899504,
-   'albums_count': 1,
-   'slug': 'arko-boom',
-   'picture': None},
-  'upc': '0859766309663',
-  'released_at': 1665180000,
-  'label': {'name': 'Arko Boom',
-   'id': 4026379,
-   'albums_count': 1,
-   'supplier_id': 95,
-   'slug': 'arko-boom'},
-  'title': 'Speedy',
-  'qobuz_id': 178369185,
-  'version': None,
-  'duration': 536,
-  'parental_warning': False,
-  'tracks_count': 4,
-  'popularity': 0,
-  'genre': {'path': [133],
-   'color': '#5eabc1',
-   'name': 'Hip-Hop/Rap',
-   'id': 133,
-   'slug': 'rap-hip-hop'},
-  'maximum_channel_count': 2,
-  'id': 'ilfmuz10e7vfc',
-  'maximum_sampling_rate': 44.1,
-  'previewable': True,
-  'sampleable': True,
-  'displayable': True,
-  'streamable': True,
-  'streamable_at': 1711522800,
-  'downloadable': False,
-  'purchasable_at': None,
-  'purchasable': False,
-  'release_date_original': '2022-10-08',
-  'release_date_download': '2022-10-08',
-  'release_date_stream': '2022-10-08',
-  'release_date_purchase': '2022-10-08',
-  'hires': False,
-  'hires_streamable': False},
- 'work': None,
- 'composer': {'name': 'Arkos Todd', 'id': 15899505},
- 'isrc': 'TCAGM2280786',
- 'title': 'Everybody Talks',
- 'version': None,
- 'duration': 127,
- 'parental_warning': False,
- 'track_number': 2,
- 'maximum_channel_count': 2,
- 'id': 178369187,
- 'media_number': 1,
- 'maximum_sampling_rate': 44.1,
- 'release_date_original': '2022-10-08',
- 'release_date_download': '2022-10-08',
- 'release_date_stream': '2022-10-08',
- 'release_date_purchase': '2022-10-08',
- 'purchasable': True,
- 'streamable': True,
- 'previewable': True,
- 'sampleable': True,
- 'downloadable': True,
- 'displayable': True,
- 'purchasable_at': 1711522800,
- 'streamable_at': 1711522800,
- 'hires': False,
- 'hires_streamable': False}
-
-
-
-
-
-
-
-
Spotify Web API#
-
-
-
track_spotify = client_spotify.search("Everybody Talks", "track",
-                                      limit=1)["items"][0]
-track_spotify
-
-
-
-
- - -Hide code cell output - -
-
{'album': {'album_type': 'album',
-  'artists': [{'external_urls': {'spotify': 'https://open.spotify.com/artist/0RpddSzUHfncUWNJXKOsjy'},
-    'href': 'https://api.spotify.com/v1/artists/0RpddSzUHfncUWNJXKOsjy',
-    'id': '0RpddSzUHfncUWNJXKOsjy',
-    'name': 'Neon Trees',
-    'type': 'artist',
-    'uri': 'spotify:artist:0RpddSzUHfncUWNJXKOsjy'}],
-  'available_markets': ['AR',
-   'AU',
-   'AT',
-   'BE',
-   'BO',
-   'BR',
-   'BG',
-   'CA',
-   'CL',
-   'CO',
-   'CR',
-   'CY',
-   'CZ',
-   'DK',
-   'DO',
-   'DE',
-   'EC',
-   'EE',
-   'SV',
-   'FI',
-   'FR',
-   'GR',
-   'GT',
-   'HN',
-   'HK',
-   'HU',
-   'IS',
-   'IE',
-   'IT',
-   'LV',
-   'LT',
-   'LU',
-   'MY',
-   'MT',
-   'NL',
-   'NZ',
-   'NI',
-   'NO',
-   'PA',
-   'PY',
-   'PE',
-   'PH',
-   'PL',
-   'PT',
-   'SG',
-   'SK',
-   'ES',
-   'SE',
-   'CH',
-   'TW',
-   'TR',
-   'UY',
-   'US',
-   'GB',
-   'AD',
-   'LI',
-   'MC',
-   'ID',
-   'TH',
-   'VN',
-   'RO',
-   'IL',
-   'ZA',
-   'SA',
-   'AE',
-   'BH',
-   'QA',
-   'OM',
-   'KW',
-   'EG',
-   'TN',
-   'LB',
-   'JO',
-   'PS',
-   'IN',
-   'BY',
-   'KZ',
-   'MD',
-   'UA',
-   'AL',
-   'BA',
-   'HR',
-   'ME',
-   'MK',
-   'RS',
-   'SI',
-   'KR',
-   'BD',
-   'PK',
-   'LK',
-   'GH',
-   'KE',
-   'NG',
-   'TZ',
-   'UG',
-   'AG',
-   'AM',
-   'BS',
-   'BB',
-   'BZ',
-   'BT',
-   'BW',
-   'BF',
-   'CV',
-   'CW',
-   'DM',
-   'FJ',
-   'GM',
-   'GD',
-   'GW',
-   'GY',
-   'HT',
-   'JM',
-   'KI',
-   'LS',
-   'LR',
-   'MW',
-   'MV',
-   'ML',
-   'MH',
-   'FM',
-   'NA',
-   'NR',
-   'NE',
-   'PW',
-   'PG',
-   'WS',
-   'ST',
-   'SN',
-   'SC',
-   'SL',
-   'SB',
-   'KN',
-   'LC',
-   'VC',
-   'SR',
-   'TL',
-   'TO',
-   'TT',
-   'TV',
-   'AZ',
-   'BN',
-   'BI',
-   'KH',
-   'CM',
-   'TD',
-   'KM',
-   'GQ',
-   'SZ',
-   'GA',
-   'GN',
-   'KG',
-   'LA',
-   'MO',
-   'MR',
-   'MN',
-   'NP',
-   'RW',
-   'TG',
-   'UZ',
-   'ZW',
-   'BJ',
-   'MG',
-   'MU',
-   'MZ',
-   'AO',
-   'CI',
-   'DJ',
-   'ZM',
-   'CD',
-   'CG',
-   'IQ',
-   'TJ',
-   'VE',
-   'XK'],
-  'external_urls': {'spotify': 'https://open.spotify.com/album/0uRFz92JmjwDbZbB7hEBIr'},
-  'href': 'https://api.spotify.com/v1/albums/0uRFz92JmjwDbZbB7hEBIr',
-  'id': '0uRFz92JmjwDbZbB7hEBIr',
-  'images': [{'height': 640,
-    'url': 'https://i.scdn.co/image/ab67616d0000b2734a6c0376235e5aa44e59d2c2',
-    'width': 640},
-   {'height': 300,
-    'url': 'https://i.scdn.co/image/ab67616d00001e024a6c0376235e5aa44e59d2c2',
-    'width': 300},
-   {'height': 64,
-    'url': 'https://i.scdn.co/image/ab67616d000048514a6c0376235e5aa44e59d2c2',
-    'width': 64}],
-  'name': 'Picture Show',
-  'release_date': '2012-01-01',
-  'release_date_precision': 'day',
-  'total_tracks': 11,
-  'type': 'album',
-  'uri': 'spotify:album:0uRFz92JmjwDbZbB7hEBIr'},
- 'artists': [{'external_urls': {'spotify': 'https://open.spotify.com/artist/0RpddSzUHfncUWNJXKOsjy'},
-   'href': 'https://api.spotify.com/v1/artists/0RpddSzUHfncUWNJXKOsjy',
-   'id': '0RpddSzUHfncUWNJXKOsjy',
-   'name': 'Neon Trees',
-   'type': 'artist',
-   'uri': 'spotify:artist:0RpddSzUHfncUWNJXKOsjy'}],
- 'available_markets': ['AR',
-  'AU',
-  'AT',
-  'BE',
-  'BO',
-  'BR',
-  'BG',
-  'CA',
-  'CL',
-  'CO',
-  'CR',
-  'CY',
-  'CZ',
-  'DK',
-  'DO',
-  'DE',
-  'EC',
-  'EE',
-  'SV',
-  'FI',
-  'FR',
-  'GR',
-  'GT',
-  'HN',
-  'HK',
-  'HU',
-  'IS',
-  'IE',
-  'IT',
-  'LV',
-  'LT',
-  'LU',
-  'MY',
-  'MT',
-  'NL',
-  'NZ',
-  'NI',
-  'NO',
-  'PA',
-  'PY',
-  'PE',
-  'PH',
-  'PL',
-  'PT',
-  'SG',
-  'SK',
-  'ES',
-  'SE',
-  'CH',
-  'TW',
-  'TR',
-  'UY',
-  'US',
-  'GB',
-  'AD',
-  'LI',
-  'MC',
-  'ID',
-  'TH',
-  'VN',
-  'RO',
-  'IL',
-  'ZA',
-  'SA',
-  'AE',
-  'BH',
-  'QA',
-  'OM',
-  'KW',
-  'EG',
-  'TN',
-  'LB',
-  'JO',
-  'PS',
-  'IN',
-  'BY',
-  'KZ',
-  'MD',
-  'UA',
-  'AL',
-  'BA',
-  'HR',
-  'ME',
-  'MK',
-  'RS',
-  'SI',
-  'KR',
-  'BD',
-  'PK',
-  'LK',
-  'GH',
-  'KE',
-  'NG',
-  'TZ',
-  'UG',
-  'AG',
-  'AM',
-  'BS',
-  'BB',
-  'BZ',
-  'BT',
-  'BW',
-  'BF',
-  'CV',
-  'CW',
-  'DM',
-  'FJ',
-  'GM',
-  'GD',
-  'GW',
-  'GY',
-  'HT',
-  'JM',
-  'KI',
-  'LS',
-  'LR',
-  'MW',
-  'MV',
-  'ML',
-  'MH',
-  'FM',
-  'NA',
-  'NR',
-  'NE',
-  'PW',
-  'PG',
-  'WS',
-  'ST',
-  'SN',
-  'SC',
-  'SL',
-  'SB',
-  'KN',
-  'LC',
-  'VC',
-  'SR',
-  'TL',
-  'TO',
-  'TT',
-  'TV',
-  'AZ',
-  'BN',
-  'BI',
-  'KH',
-  'CM',
-  'TD',
-  'KM',
-  'GQ',
-  'SZ',
-  'GA',
-  'GN',
-  'KG',
-  'LA',
-  'MO',
-  'MR',
-  'MN',
-  'NP',
-  'RW',
-  'TG',
-  'UZ',
-  'ZW',
-  'BJ',
-  'MG',
-  'MU',
-  'MZ',
-  'AO',
-  'CI',
-  'DJ',
-  'ZM',
-  'CD',
-  'CG',
-  'IQ',
-  'TJ',
-  'VE',
-  'XK'],
- 'disc_number': 1,
- 'duration_ms': 177280,
- 'explicit': True,
- 'external_ids': {'isrc': 'USUM71119189'},
- 'external_urls': {'spotify': 'https://open.spotify.com/track/2iUmqdfGZcHIhS3b9E9EWq'},
- 'href': 'https://api.spotify.com/v1/tracks/2iUmqdfGZcHIhS3b9E9EWq',
- 'id': '2iUmqdfGZcHIhS3b9E9EWq',
- 'is_local': False,
- 'name': 'Everybody Talks',
- 'popularity': 80,
- 'preview_url': None,
- 'track_number': 3,
- 'type': 'track',
- 'uri': 'spotify:track:2iUmqdfGZcHIhS3b9E9EWq'}
-
-
-
-
-
-
-
-
TIDAL API#
-
-
-
client_tidal.search("Everybody Talks", "US", type="TRACKS", limit=1)["tracks"][0]
-
-
-
-
- - -Hide code cell output - -
-
{'resource': {'artifactType': 'track',
-  'id': '14492425',
-  'title': 'Everybody Talks',
-  'artists': [{'id': '3665225',
-    'name': 'Neon Trees',
-    'picture': [{'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/1024x256.jpg',
-      'width': 1024,
-      'height': 256},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/1080x720.jpg',
-      'width': 1080,
-      'height': 720},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/160x107.jpg',
-      'width': 160,
-      'height': 107},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/160x160.jpg',
-      'width': 160,
-      'height': 160},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/320x214.jpg',
-      'width': 320,
-      'height': 214},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/320x320.jpg',
-      'width': 320,
-      'height': 320},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/480x480.jpg',
-      'width': 480,
-      'height': 480},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/640x428.jpg',
-      'width': 640,
-      'height': 428},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/750x500.jpg',
-      'width': 750,
-      'height': 500},
-     {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/750x750.jpg',
-      'width': 750,
-      'height': 750}],
-    'main': True}],
-  'album': {'id': '14492422',
-   'title': 'Picture Show',
-   'imageCover': [{'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/1080x1080.jpg',
-     'width': 1080,
-     'height': 1080},
-    {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/1280x1280.jpg',
-     'width': 1280,
-     'height': 1280},
-    {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/160x160.jpg',
-     'width': 160,
-     'height': 160},
-    {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/320x320.jpg',
-     'width': 320,
-     'height': 320},
-    {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/640x640.jpg',
-     'width': 640,
-     'height': 640},
-    {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/750x750.jpg',
-     'width': 750,
-     'height': 750},
-    {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/80x80.jpg',
-     'width': 80,
-     'height': 80}],
-   'videoCover': []},
-  'duration': 177,
-  'trackNumber': 3,
-  'volumeNumber': 1,
-  'isrc': 'USUM71119189',
-  'copyright': 'A Mercury Records Release; ℗ 2011 UMG Recordings, Inc.',
-  'mediaMetadata': {'tags': ['LOSSLESS']},
-  'properties': {'content': ['explicit']},
-  'tidalUrl': 'https://tidal.com/browse/track/14492425'},
- 'id': '14492425',
- 'status': 200,
- 'message': 'success'}
-
-
-
-
-
-
-
-
Private TIDAL API#
-
-
-
track_tidal_private = client_tidal_private.search("Everybody Talks",
-                                                  type="track",
-                                                  limit=1)["items"][0]
-track_tidal_private
-
-
-
-
- - -Hide code cell output - -
-
{'id': 14492425,
- 'title': 'Everybody Talks',
- 'duration': 177,
- 'replayGain': -11.7,
- 'peak': 0.999969,
- 'allowStreaming': True,
- 'streamReady': True,
- 'adSupportedStreamReady': True,
- 'djReady': True,
- 'stemReady': False,
- 'streamStartDate': '2012-04-17T00:00:00.000+0000',
- 'premiumStreamingOnly': False,
- 'trackNumber': 3,
- 'volumeNumber': 1,
- 'version': None,
- 'popularity': 60,
- 'copyright': 'A Mercury Records Release; ℗ 2011 UMG Recordings, Inc.',
- 'bpm': 155,
- 'url': 'http://www.tidal.com/track/14492425',
- 'isrc': 'USUM71119189',
- 'editable': False,
- 'explicit': True,
- 'audioQuality': 'LOSSLESS',
- 'audioModes': ['STEREO'],
- 'mediaMetadata': {'tags': ['LOSSLESS']},
- 'artist': {'id': 3665225,
-  'name': 'Neon Trees',
-  'type': 'MAIN',
-  'picture': 'e6f17398-759e-45a0-9673-6ded6811e199'},
- 'artists': [{'id': 3665225,
-   'name': 'Neon Trees',
-   'type': 'MAIN',
-   'picture': 'e6f17398-759e-45a0-9673-6ded6811e199'}],
- 'album': {'id': 14492422,
-  'title': 'Picture Show',
-  'cover': '1c2d7c90-034e-485a-be1f-24a669c7e6ee',
-  'vibrantColor': '#f8af88',
-  'videoCover': None},
- 'mixes': {'TRACK_MIX': '0019768c833a193c29829e5bf473fc'}}
-
-
-
-
-
-
-
-
-
Creating, modifying, and deleting a personal playlist#
-

If the clients are authenticated, you can create and modify user playlists. As an example, we will create a private playlist named “Minim”, make it public, add “Everybody Talks” by Neon Trees to it, and then delete it.

-
-
Private Qobuz API#
-
-
-
playlist_qobuz = client_qobuz.create_playlist(
-    "Minim",
-    description="A playlist created using Minim.",
-    public=False
-)
-client_qobuz.update_playlist(playlist_qobuz["id"], public=True)
-client_qobuz.add_playlist_tracks(playlist_qobuz["id"], track_qobuz["id"])
-playlist_qobuz = client_qobuz.get_playlist(playlist_qobuz["id"])
-playlist_qobuz["owner"] = None  # remove personal identifying information
-playlist_qobuz
-
-
-
-
- - -Hide code cell output - -
-
{'owner': None,
- 'users_count': 0,
- 'images150': ['https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_150.jpg'],
- 'images': ['https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_50.jpg'],
- 'is_collaborative': False,
- 'description': 'A playlist created using Minim.',
- 'created_at': 1716796037,
- 'images300': ['https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_300.jpg'],
- 'duration': 127,
- 'updated_at': 1716796038,
- 'published_to': None,
- 'genres': [],
- 'tracks_count': 1,
- 'public_at': 1716796037,
- 'name': 'Minim',
- 'is_public': True,
- 'published_from': None,
- 'id': 21785616,
- 'slug': 'minim-12',
- 'is_featured': False,
- 'tracks': {'offset': 0,
-  'limit': 50,
-  'total': 1,
-  'items': [{'maximum_bit_depth': 16,
-    'copyright': '2022 Arko Boom 2022 Arko Boom',
-    'performers': 'Arko Boom, MainArtist - Arkos Todd, Songwriter, ComposerLyricist',
-    'audio_info': {'replaygain_track_peak': 1, 'replaygain_track_gain': -3.06},
-    'performer': {'name': 'Arko Boom', 'id': 15899504},
-    'album': {'image': {'small': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_230.jpg',
-      'thumbnail': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_50.jpg',
-      'large': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_600.jpg'},
-     'maximum_bit_depth': 16,
-     'media_count': 1,
-     'artist': {'image': None,
-      'name': 'Arko Boom',
-      'id': 15899504,
-      'albums_count': 1,
-      'slug': 'arko-boom',
-      'picture': None},
-     'upc': '0859766309663',
-     'released_at': 1665180000,
-     'label': {'name': 'Arko Boom',
-      'id': 4026379,
-      'albums_count': 1,
-      'supplier_id': 95,
-      'slug': 'arko-boom'},
-     'title': 'Speedy',
-     'qobuz_id': 178369185,
-     'version': None,
-     'duration': 536,
-     'parental_warning': False,
-     'tracks_count': 4,
-     'popularity': 0,
-     'genre': {'path': [133],
-      'color': '#5eabc1',
-      'name': 'Hip-Hop/Rap',
-      'id': 133,
-      'slug': 'rap-hip-hop'},
-     'maximum_channel_count': 2,
-     'id': 'ilfmuz10e7vfc',
-     'maximum_sampling_rate': 44.1,
-     'previewable': True,
-     'sampleable': True,
-     'displayable': True,
-     'streamable': True,
-     'streamable_at': 1711522800,
-     'downloadable': False,
-     'purchasable_at': None,
-     'purchasable': False,
-     'release_date_original': '2022-10-08',
-     'release_date_download': '2022-10-08',
-     'release_date_stream': '2022-10-08',
-     'release_date_purchase': '2022-10-08',
-     'hires': False,
-     'hires_streamable': False},
-    'work': None,
-    'composer': {'name': 'Arkos Todd', 'id': 15899505},
-    'isrc': 'TCAGM2280786',
-    'title': 'Everybody Talks',
-    'version': None,
-    'duration': 127,
-    'parental_warning': False,
-    'track_number': 2,
-    'maximum_channel_count': 2,
-    'id': 178369187,
-    'media_number': 1,
-    'maximum_sampling_rate': 44.1,
-    'release_date_original': '2022-10-08',
-    'release_date_download': '2022-10-08',
-    'release_date_stream': '2022-10-08',
-    'release_date_purchase': '2022-10-08',
-    'purchasable': True,
-    'streamable': True,
-    'previewable': True,
-    'sampleable': True,
-    'downloadable': True,
-    'displayable': True,
-    'purchasable_at': 1711522800,
-    'streamable_at': 1711522800,
-    'hires': False,
-    'hires_streamable': False,
-    'position': 1,
-    'created_at': 1716796038,
-    'playlist_track_id': 4800410944}]}}
-
-
-
-
-
-
-
-
client_qobuz.delete_playlist(playlist_qobuz["id"])
-
-
-
-
-
-
-
Spotify Web API#
-
-
-
playlist_spotify = client_spotify.create_playlist(
-    "Minim",
-    description="A playlist created using Minim.",
-    public=False
-)
-client_spotify.change_playlist_details(playlist_spotify["id"], public=True)
-client_spotify.add_playlist_items(playlist_spotify["id"],
-                                  [f"spotify:track:{track_spotify['id']}"])
-playlist_spotify = client_spotify.get_playlist(playlist_spotify["id"])
-# remove personal identifying information
-playlist_spotify["owner"] = playlist_spotify["tracks"]["items"][0]["added_by"] = None
-playlist_spotify
-
-
-
-
- - -Hide code cell output - -
-
{'collaborative': False,
- 'description': 'A playlist created using Minim.',
- 'external_urls': {'spotify': 'https://open.spotify.com/playlist/1tPv85ugl5VCyv3LRFEn4F'},
- 'followers': {'href': None, 'total': 0},
- 'href': 'https://api.spotify.com/v1/playlists/1tPv85ugl5VCyv3LRFEn4F',
- 'id': '1tPv85ugl5VCyv3LRFEn4F',
- 'images': [{'height': None,
-   'url': 'https://i.scdn.co/image/ab67616d00001e024a6c0376235e5aa44e59d2c2',
-   'width': None}],
- 'name': 'Minim',
- 'owner': None,
- 'primary_color': None,
- 'public': True,
- 'snapshot_id': 'AAAAAQcwPwQ+ZPBO3L6L2C171Urki7mV',
- 'tracks': {'href': 'https://api.spotify.com/v1/playlists/1tPv85ugl5VCyv3LRFEn4F/tracks?offset=0&limit=100',
-  'items': [{'added_at': '2024-05-27T07:47:19Z',
-    'added_by': None,
-    'is_local': False,
-    'primary_color': None,
-    'track': {'preview_url': None,
-     'available_markets': ['AR',
-      'AU',
-      'AT',
-      'BE',
-      'BO',
-      'BR',
-      'BG',
-      'CA',
-      'CL',
-      'CO',
-      'CR',
-      'CY',
-      'CZ',
-      'DK',
-      'DO',
-      'DE',
-      'EC',
-      'EE',
-      'SV',
-      'FI',
-      'FR',
-      'GR',
-      'GT',
-      'HN',
-      'HK',
-      'HU',
-      'IS',
-      'IE',
-      'IT',
-      'LV',
-      'LT',
-      'LU',
-      'MY',
-      'MT',
-      'NL',
-      'NZ',
-      'NI',
-      'NO',
-      'PA',
-      'PY',
-      'PE',
-      'PH',
-      'PL',
-      'PT',
-      'SG',
-      'SK',
-      'ES',
-      'SE',
-      'CH',
-      'TW',
-      'TR',
-      'UY',
-      'US',
-      'GB',
-      'AD',
-      'LI',
-      'MC',
-      'ID',
-      'TH',
-      'VN',
-      'RO',
-      'IL',
-      'ZA',
-      'SA',
-      'AE',
-      'BH',
-      'QA',
-      'OM',
-      'KW',
-      'EG',
-      'TN',
-      'LB',
-      'JO',
-      'PS',
-      'IN',
-      'BY',
-      'KZ',
-      'MD',
-      'UA',
-      'AL',
-      'BA',
-      'HR',
-      'ME',
-      'MK',
-      'RS',
-      'SI',
-      'KR',
-      'BD',
-      'PK',
-      'LK',
-      'GH',
-      'KE',
-      'NG',
-      'TZ',
-      'UG',
-      'AG',
-      'AM',
-      'BS',
-      'BB',
-      'BZ',
-      'BT',
-      'BW',
-      'BF',
-      'CV',
-      'CW',
-      'DM',
-      'FJ',
-      'GM',
-      'GD',
-      'GW',
-      'GY',
-      'HT',
-      'JM',
-      'KI',
-      'LS',
-      'LR',
-      'MW',
-      'MV',
-      'ML',
-      'MH',
-      'FM',
-      'NA',
-      'NR',
-      'NE',
-      'PW',
-      'PG',
-      'WS',
-      'ST',
-      'SN',
-      'SC',
-      'SL',
-      'SB',
-      'KN',
-      'LC',
-      'VC',
-      'SR',
-      'TL',
-      'TO',
-      'TT',
-      'TV',
-      'AZ',
-      'BN',
-      'BI',
-      'KH',
-      'CM',
-      'TD',
-      'KM',
-      'GQ',
-      'SZ',
-      'GA',
-      'GN',
-      'KG',
-      'LA',
-      'MO',
-      'MR',
-      'MN',
-      'NP',
-      'RW',
-      'TG',
-      'UZ',
-      'ZW',
-      'BJ',
-      'MG',
-      'MU',
-      'MZ',
-      'AO',
-      'CI',
-      'DJ',
-      'ZM',
-      'CD',
-      'CG',
-      'IQ',
-      'TJ',
-      'VE',
-      'XK'],
-     'explicit': True,
-     'type': 'track',
-     'episode': False,
-     'track': True,
-     'album': {'available_markets': ['AR',
-       'AU',
-       'AT',
-       'BE',
-       'BO',
-       'BR',
-       'BG',
-       'CA',
-       'CL',
-       'CO',
-       'CR',
-       'CY',
-       'CZ',
-       'DK',
-       'DO',
-       'DE',
-       'EC',
-       'EE',
-       'SV',
-       'FI',
-       'FR',
-       'GR',
-       'GT',
-       'HN',
-       'HK',
-       'HU',
-       'IS',
-       'IE',
-       'IT',
-       'LV',
-       'LT',
-       'LU',
-       'MY',
-       'MT',
-       'NL',
-       'NZ',
-       'NI',
-       'NO',
-       'PA',
-       'PY',
-       'PE',
-       'PH',
-       'PL',
-       'PT',
-       'SG',
-       'SK',
-       'ES',
-       'SE',
-       'CH',
-       'TW',
-       'TR',
-       'UY',
-       'US',
-       'GB',
-       'AD',
-       'LI',
-       'MC',
-       'ID',
-       'TH',
-       'VN',
-       'RO',
-       'IL',
-       'ZA',
-       'SA',
-       'AE',
-       'BH',
-       'QA',
-       'OM',
-       'KW',
-       'EG',
-       'TN',
-       'LB',
-       'JO',
-       'PS',
-       'IN',
-       'BY',
-       'KZ',
-       'MD',
-       'UA',
-       'AL',
-       'BA',
-       'HR',
-       'ME',
-       'MK',
-       'RS',
-       'SI',
-       'KR',
-       'BD',
-       'PK',
-       'LK',
-       'GH',
-       'KE',
-       'NG',
-       'TZ',
-       'UG',
-       'AG',
-       'AM',
-       'BS',
-       'BB',
-       'BZ',
-       'BT',
-       'BW',
-       'BF',
-       'CV',
-       'CW',
-       'DM',
-       'FJ',
-       'GM',
-       'GD',
-       'GW',
-       'GY',
-       'HT',
-       'JM',
-       'KI',
-       'LS',
-       'LR',
-       'MW',
-       'MV',
-       'ML',
-       'MH',
-       'FM',
-       'NA',
-       'NR',
-       'NE',
-       'PW',
-       'PG',
-       'WS',
-       'ST',
-       'SN',
-       'SC',
-       'SL',
-       'SB',
-       'KN',
-       'LC',
-       'VC',
-       'SR',
-       'TL',
-       'TO',
-       'TT',
-       'TV',
-       'AZ',
-       'BN',
-       'BI',
-       'KH',
-       'CM',
-       'TD',
-       'KM',
-       'GQ',
-       'SZ',
-       'GA',
-       'GN',
-       'KG',
-       'LA',
-       'MO',
-       'MR',
-       'MN',
-       'NP',
-       'RW',
-       'TG',
-       'UZ',
-       'ZW',
-       'BJ',
-       'MG',
-       'MU',
-       'MZ',
-       'AO',
-       'CI',
-       'DJ',
-       'ZM',
-       'CD',
-       'CG',
-       'IQ',
-       'TJ',
-       'VE',
-       'XK'],
-      'type': 'album',
-      'album_type': 'album',
-      'href': 'https://api.spotify.com/v1/albums/0uRFz92JmjwDbZbB7hEBIr',
-      'id': '0uRFz92JmjwDbZbB7hEBIr',
-      'images': [{'url': 'https://i.scdn.co/image/ab67616d0000b2734a6c0376235e5aa44e59d2c2',
-        'width': 640,
-        'height': 640},
-       {'url': 'https://i.scdn.co/image/ab67616d00001e024a6c0376235e5aa44e59d2c2',
-        'width': 300,
-        'height': 300},
-       {'url': 'https://i.scdn.co/image/ab67616d000048514a6c0376235e5aa44e59d2c2',
-        'width': 64,
-        'height': 64}],
-      'name': 'Picture Show',
-      'release_date': '2012-01-01',
-      'release_date_precision': 'day',
-      'uri': 'spotify:album:0uRFz92JmjwDbZbB7hEBIr',
-      'artists': [{'external_urls': {'spotify': 'https://open.spotify.com/artist/0RpddSzUHfncUWNJXKOsjy'},
-        'href': 'https://api.spotify.com/v1/artists/0RpddSzUHfncUWNJXKOsjy',
-        'id': '0RpddSzUHfncUWNJXKOsjy',
-        'name': 'Neon Trees',
-        'type': 'artist',
-        'uri': 'spotify:artist:0RpddSzUHfncUWNJXKOsjy'}],
-      'external_urls': {'spotify': 'https://open.spotify.com/album/0uRFz92JmjwDbZbB7hEBIr'},
-      'total_tracks': 11},
-     'artists': [{'external_urls': {'spotify': 'https://open.spotify.com/artist/0RpddSzUHfncUWNJXKOsjy'},
-       'href': 'https://api.spotify.com/v1/artists/0RpddSzUHfncUWNJXKOsjy',
-       'id': '0RpddSzUHfncUWNJXKOsjy',
-       'name': 'Neon Trees',
-       'type': 'artist',
-       'uri': 'spotify:artist:0RpddSzUHfncUWNJXKOsjy'}],
-     'disc_number': 1,
-     'track_number': 3,
-     'duration_ms': 177280,
-     'external_ids': {'isrc': 'USUM71119189'},
-     'external_urls': {'spotify': 'https://open.spotify.com/track/2iUmqdfGZcHIhS3b9E9EWq'},
-     'href': 'https://api.spotify.com/v1/tracks/2iUmqdfGZcHIhS3b9E9EWq',
-     'id': '2iUmqdfGZcHIhS3b9E9EWq',
-     'name': 'Everybody Talks',
-     'popularity': 80,
-     'uri': 'spotify:track:2iUmqdfGZcHIhS3b9E9EWq',
-     'is_local': False},
-    'video_thumbnail': {'url': None}}],
-  'limit': 100,
-  'next': None,
-  'offset': 0,
-  'previous': None,
-  'total': 1},
- 'type': 'playlist',
- 'uri': 'spotify:playlist:1tPv85ugl5VCyv3LRFEn4F'}
-
-
-
-
-
-
-
-
client_spotify.unfollow_playlist(playlist_spotify["id"])
-
-
-
-
-
-
-
Private TIDAL API#
-
-
-
playlist_tidal_private = client_tidal_private.create_playlist(
-    "Minim",
-    description="A playlist created using Minim.",
-    public=False
-)
-client_tidal_private.set_playlist_privacy(playlist_tidal_private["data"]["uuid"],
-                                          True)
-client_tidal_private.add_playlist_items(playlist_tidal_private["data"]["uuid"],
-                                        track_tidal_private["id"])
-playlist_tidal_private = client_tidal_private.get_user_playlist(
-    playlist_tidal_private["data"]["uuid"]
-)
-# remove personal identifying information
-playlist_tidal_private["playlist"]["creator"] = playlist_tidal_private["profile"] = None
-playlist_tidal_private
-
-
-
-
- - -Hide code cell output - -
-
{'playlist': {'uuid': 'd577851a-4e6a-4cf4-81d1-91aa4851fbe0',
-  'type': 'USER',
-  'creator': None,
-  'contentBehavior': 'UNRESTRICTED',
-  'sharingLevel': 'PUBLIC',
-  'status': 'READY',
-  'source': 'DEFAULT',
-  'title': 'Minim',
-  'description': 'A playlist created using Minim.',
-  'image': 'abc9781d-acae-4b50-9233-1674305e8fb4',
-  'squareImage': 'b735427d-fff9-4688-a366-70a68d0f27fc',
-  'url': 'http://www.tidal.com/playlist/d577851a-4e6a-4cf4-81d1-91aa4851fbe0',
-  'created': '2024-05-27T07:47:20.316+0000',
-  'lastUpdated': '2024-05-27T07:47:20.842+0000',
-  'lastItemAddedAt': '2024-05-27T07:47:20.842+0000',
-  'duration': 177,
-  'numberOfTracks': 1,
-  'numberOfVideos': 0,
-  'promotedArtists': [],
-  'trn': 'trn:playlist:d577851a-4e6a-4cf4-81d1-91aa4851fbe0'},
- 'followInfo': {'nrOfFollowers': 0,
-  'tidalResourceName': 'trn:playlist:d577851a-4e6a-4cf4-81d1-91aa4851fbe0',
-  'followed': True,
-  'followType': 'PLAYLIST'},
- 'profile': None}
-
-
-
-
-
-
-
-
client_tidal_private.delete_playlist(playlist_tidal_private["playlist"]["uuid"])
-
-
-
-
-
-
-
-
-
-

Audio file handlers#

-
-
-
from pathlib import Path
-from minim.audio import Audio, FLACAudio, MP3Audio, MP4Audio, OggAudio, WAVEAudio
-
-
-
-
-

Minim uses Mutagen to load and edit audio files and FFmpeg to convert between different audio formats. Currently, the most common audio formats, such as AAC, ALAC, FLAC, MP3, Opus, Vorbis, and WAVE, are supported.

-
-

Examples#

-
-
Loading and editing audio files#
-

To load an audio file, pass the filename as a str or a pathlib.Path object either to the minim.audio.Audio constructor for Minim to automatically detect the audio format:

-
-
-
file = Path().resolve().parents[2] / "tests/data/samples/middle_c.wav"
-middle_c = Audio(file)
-
-
-
-
-

or the specific class for the audio format if known (in this case, minim.audio.WAVEAudio):

-
middle_c = WAVEAudio(Path().resolve().parents[2] / "tests/data/samples/middle_c.wav")
-
-
-

For this example, both approaches return a minim.audio.WAVEAudio object:

-
-
-
type(middle_c)
-
-
-
-
-
minim.audio.WAVEAudio
-
-
-
-
-

The metadata stored in the audio file can be accessed using dot notation or getattr():

-
-
-
for attr in ["title", "album", "artist", "genre", "codec", "bit_depth"]:
-    print(f"{attr.capitalize().replace('_', ' ')}: {getattr(middle_c, attr)}")
-
-
-
-
-
Title: Middle C
-Album: Minim
-Artist: Square Wave
-Genre: Game
-Codec: lpcm
-Bit depth: 24
-
-
-
-
-

and edited similarly using dot notation or setattr():

-
middle_c.title = "Middle C (261.63 Hz)"
-middle_c.write_metadata()
-
-
-

If changes are made, don’t forget to write them to file using minim.audio.Audio.write_metadata().

-
-
-
Converting between audio formats#
-

Conversion between the supported audio formats is powered by FFmpeg.

-

To re-encode the previous WAVE audio using the ALAC codec and store it in a MP4 container, use the minim.audio.Audio.convert() method:

-
-
-
middle_c.convert("alac", filename="middle_c_alac")
-
-
-
-
- - -Hide code cell output - -
-
size=     116kB time=00:00:01.02 bitrate= 930.3kbits/s speed= 128x    
-
-
-
-
-
-

The call above not only converts the WAVE audio into ALAC audio, but also updates the variable middle_c to now point to a minim.audio.MP4Audio file handler for the new file middle_c.m4a and maintains the metadata:

-
-
-
type(middle_c)
-
-
-
-
-
minim.audio.MP4Audio
-
-
-
-
-
-
-
for attr in ["title", "album", "artist", "genre", "codec", "bit_depth"]:
-    print(f"{attr.capitalize().replace('_', ' ')}: {getattr(middle_c, attr)}")
-
-
-
-
-
Title: Middle C
-Album: Minim
-Artist: Square Wave
-Genre: Game
-Codec: alac
-Bit depth: 24
-
-
-
-
-
-
-
-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/notebooks/user_guide/editing_audio_metadata.html b/docs/notebooks/user_guide/editing_audio_metadata.html deleted file mode 100644 index 0c98379e..00000000 --- a/docs/notebooks/user_guide/editing_audio_metadata.html +++ /dev/null @@ -1,859 +0,0 @@ - - - - - - - - - Editing Audio Metadata - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

Editing Audio Metadata#

-

Last updated: November 25, 2023

-

Minim can organize your local music library by tagging audio files with metadata retrieved from popular music services, such as iTunes, Spotify, and TIDAL.

-
-
-
from pathlib import Path
-
-from minim import audio, itunes, spotify, tidal, utility
-import numpy as np
-
-
-
-
-
-

Setup#

-
-

Instantiating API clients#

-

To get started, we will need to create API clients for the music services that we want to query for album and track information:

-
-
-
client_itunes = itunes.SearchAPI()
-client_spotify = spotify.WebAPI()
-client_tidal = tidal.PrivateAPI()
-
-
-
-
-
-
-

Finding audio files#

-

To find all audio files in a specified directory, we use the pathlib.Path.glob() method:

-
-
-
audio_files = [f for f in (Path().resolve().parents[3]
-                           / "tests/data/previews").glob("**/*")
-               if f.suffix == ".flac"]
-
-
-
-
-
-
-

Defining helper functions#

-

Before diving into the examples, we define a helper function that will print out the metadata of an audio file:

-
-
-
def print_metadata(audio_file):
-    for field, value in audio_file.__dict__.items():
-        if not field.startswith("_"):
-            if field in {"artwork", "lyrics"}:
-                if value:
-                    value = type(value)
-            field = (field.upper() if field == "isrc"
-                     else field.replace("_", " ").capitalize())
-            print(f"{field}: {value}")
-
-
-
-
-

The two examples below highlight the utility of the minim.audio.*Audio classes. The first example involves an audio with no metadata other than that stored in its filename, and the second example shows how to update the tags of an audio file without overwriting existing metadata.

-
-
-
-

Converting and tagging an audio file with no metadata#

-

First, we load the audio file into a file handler by passing its filename and its corresponding regular expression and metadata fields to the minim.audio.Audio constructor:

-
-
-
audio_file = audio.Audio(audio_files[0], pattern=("(.*)_(.*)", ("artist", "title")))
-audio_files[0].name, audio_file
-
-
-
-
-
('spektrem_shine.flac', <minim.audio.FLACAudio at 0x7f1ce4e63810>)
-
-
-
-
-

A minim.audio.FLACAudio object is returned, as the minim.audio.Audio constructor has automatically determined the audio format. Let’s take a look at the file’s metadata:

-
-
-
print_metadata(audio_file)
-
-
-
-
- - -Hide code cell output - -
-
Album: None
-Album artist: None
-Artist: spektrem
-Comment: None
-Composer: None
-Copyright: None
-Date: None
-Genre: None
-ISRC: None
-Lyrics: None
-Tempo: None
-Title: shine
-Compilation: None
-Disc number: None
-Disc count: None
-Track number: None
-Track count: None
-Artwork: None
-Bit depth: 16
-Bitrate: 1030107
-Channel count: 2
-Codec: flac
-Sample rate: 44100
-
-
-
-
-
-

While the file originally had no artist or title information, the search pattern we provided to the minim.audio.Audio constructor has allowed it to pull the information from the filename. At this point, however, the artist and title information have not yet been written to file.

-

If we wanted compatibility with most music players, we can convert the FLAC file to a MP3 file using minim.audio.FLACAudio.convert():

-
-
-
audio_file.convert("mp3")
-audio_file
-
-
-
-
-
size=    1032kB time=00:00:30.09 bitrate= 280.9kbits/s speed=63.1x    
-
-
-
<minim.audio.MP3Audio at 0x7f1ce4e63810>
-
-
-
-
-

With the file conversion, the audio_file object is automatically updated to a minim.audio.MP3Audio object. Let’s take a look at the new file’s metadata:

-
-
-
print_metadata(audio_file)
-
-
-
-
- - -Hide code cell output - -
-
Album: None
-Album artist: None
-Artist: spektrem
-Comment: None
-Compilation: None
-Composer: None
-Copyright: None
-Date: None
-Genre: None
-ISRC: None
-Lyrics: None
-Tempo: None
-Title: shine
-Disc number: None
-Disc count: None
-Track number: None
-Track count: None
-Artwork: None
-Bit depth: None
-Bitrate: 280593
-Channel count: 2
-Codec: mp3
-Sample rate: 44100
-
-
-
-
-
-

The metadata persisted—even the artist and title, which has not been written to the FLAC file—with the exception of format-specific properties, like the bitrate and codec.

-

Now, we start populating the file’s metadata. The Apple Music/iTunes catalog typically contains the most complete and accurate information about a track, so it is generally a good idea to start there. As such, we

-
    -

  • build a query using the only information available to us, namely, the artist and title,

    • -

  • search for the track on iTunes via minim.itunes.SearchAPI.search(),

    • -

  • select the closest match out of the results by choosing the one with the lowest Levenshtein distance/ratio for the artist and title (available via minim.utility.levenshtein_ratio()),

    • -

  • separately get the track’s album information using minim.itunes.SearchAPI.lookup(), and

    • -

  • populate the file handler’s metadata with the JSON results using minim.audio.FLACAudio.set_metadata_using_itunes().

    • -
-
-
-
query = f"{audio_file.artist} {audio_file.title}".lower()
-itunes_results = client_itunes.search(query)["results"]
-itunes_track = itunes_results[
-    np.argmax(
-        utility.levenshtein_ratio(
-            query,
-            [f"{r['artistName']} {r['trackName']}".lower()
-             for r in itunes_results]
-        )
-    )
-]
-itunes_album = client_itunes.lookup(itunes_track["collectionId"])["results"][0]
-audio_file.set_metadata_using_itunes(itunes_track, album_data=itunes_album,
-                                     overwrite=True)
-print_metadata(audio_file)
-
-
-
-
- - -Hide code cell output - -
-
Album: Enter the Spektrem - Single
-Album artist: Spektrem
-Artist: Spektrem
-Comment: None
-Compilation: False
-Composer: None
-Copyright: ℗ 2013 GFTED
-Date: 2013-03-06T12:00:00Z
-Genre: Electronic
-ISRC: None
-Lyrics: None
-Tempo: None
-Title: Shine
-Disc number: 1
-Disc count: 1
-Track number: 2
-Track count: 3
-Artwork: <class 'bytes'>
-Bit depth: None
-Bitrate: 280593
-Channel count: 2
-Codec: mp3
-Sample rate: 44100
-
-
-
-
-
-

We can see that most of the fields have now been filled out. The iTunes Search API does not return composers, ISRC, lyrics, or tempo information, so we will have to use the Spotify Web API and the TIDAL API to complete the metadata.

-

The Spotify catalog contains ISRCs for tracks. Conveniently, the Spotify Web API also has a minim.spotify.WebAPI.get_track_audio_features() endpoint that returns a dict of audio features, including the track’s tempo.

-

Like before for the iTunes Search API, we

-
    -

  • search for the track on Spotify via minim.spotify.WebAPI.search(),

    • -

  • select the closest match out of the results by choosing the one with the lowest Levenshtein distance/ratio for the artist and title,

    • -

  • get the track’s audio features using minim.spotify.WebAPI.get_track_audio_features(), and

    • -

  • populate file handler’s metadata with the JSON results using minim.audio.FLACAudio.set_metadata_using_spotify().

    • -
-
-

Note

-

By default, the minim.audio.FLACAudio.set_metadata_using*() methods do not overwrite existing metadata. To change this behavior, pass overwrite=True as a keyword argument.

-
-
-
-
spotify_results = client_spotify.search(query, type="track")["items"]
-spotify_track = spotify_results[
-    np.argmax(
-        utility.levenshtein_ratio(
-            query,
-            [f"{r['artists'][0]['name']} {r['name']}".lower()
-             for r in spotify_results]
-        )
-    )
-]
-audio_file.set_metadata_using_spotify(
-    spotify_track,
-    audio_features=client_spotify.get_track_audio_features(spotify_track["id"])
-)
-print_metadata(audio_file)
-
-
-
-
- - -Hide code cell output - -
-
Album: Enter the Spektrem - Single
-Album artist: Spektrem
-Artist: Spektrem
-Comment: None
-Compilation: False
-Composer: None
-Copyright: ℗ 2013 GFTED
-Date: 2013-03-06T12:00:00Z
-Genre: Electronic
-ISRC: GB2LD0901581
-Lyrics: None
-Tempo: 128
-Title: Shine
-Disc number: 1
-Disc count: 1
-Track number: 2
-Track count: 3
-Artwork: <class 'bytes'>
-Bit depth: None
-Bitrate: 280593
-Channel count: 2
-Codec: mp3
-Sample rate: 44100
-
-
-
-
-
-

Finally, we repeat the process above using the TIDAL API to get the composers and lyrics by

-
    -

  • searching for the track on TIDAL via minim.tidal.PrivateAPI.search(),

    • -

  • selecting the correct result by matching the ISRC,

    • -

  • getting the track’s composers using minim.tidal.PrivateAPI.get_track_composers(), and

    • -

  • populating the file handler’s metadata with the JSON results using minim.audio.FLACAudio.set_metadata_using_tidal().

    • -
-
-
-
tidal_results = client_tidal.search(query)["tracks"]["items"]
-tidal_track = next((r for r in tidal_results if r["isrc"] == audio_file.isrc), None)
-tidal_composers = client_tidal.get_track_composers(tidal_track["id"])
-audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers)
-print_metadata(audio_file)
-
-
-
-
- - -Hide code cell output - -
-
Album: Enter the Spektrem - Single
-Album artist: Spektrem
-Artist: Spektrem
-Comment: None
-Compilation: False
-Composer: None
-Copyright: ℗ 2013 GFTED
-Date: 2013-03-06T12:00:00Z
-Genre: Electronic
-ISRC: GB2LD0901581
-Lyrics: None
-Tempo: 128
-Title: Shine
-Disc number: 1
-Disc count: 1
-Track number: 2
-Track count: 3
-Artwork: <class 'bytes'>
-Bit depth: None
-Bitrate: 280593
-Channel count: 2
-Codec: mp3
-Sample rate: 44100
-
-
-
-
-
-

The metadata for the track is now practically complete. Lyrics are available through either minim.spotify.PrivateLyricsService.get_lyrics() or minim.tidal.PrivateAPI.get_track_lyrics() with active subscriptions. (For this example, TIDAL did not have songwriting credits for the track. This happens sometimes when the track is not very popular.)

-

Don’t forget to write the changes to file using minim.audio.FLACAudio.write()!

-
-
-
audio_file.write_metadata()
-
-
-
-
-
-
-

Tagging an audio file with existing metadata#

-

Now, we will process an audio file that already has most of the metadata fields populated. As before, we load the file, but this time using the minim.audio.FLACAudio constructor directly:

-
-
-
audio_file = audio.FLACAudio(audio_files[1])
-audio_files[1].name, audio_file
-
-
-
-
-
('tobu_back_to_you.flac', <minim.audio.FLACAudio at 0x7f1ce4e60fd0>)
-
-
-
-
-

Let’s take a look at the file’s metadata:

-
-
-
print_metadata(audio_file)
-
-
-
-
- - -Hide code cell output - -
-
Album: Back To You - Single
-Album artist: Tobu
-Artist: Tobu
-Comment: None
-Composer: Tobu & Toms Burkovskis
-Copyright: 2022 NCS 2022 NCS
-Date: 2023-07-06T07:00:00Z
-Genre: House
-ISRC: GB2LD2210368
-Lyrics: None
-Tempo: None
-Title: Back To You
-Compilation: None
-Disc number: 1
-Disc count: 1
-Track number: 1
-Track count: 1
-Artwork: <class 'bytes'>
-Bit depth: 16
-Bitrate: 1104053
-Channel count: 2
-Codec: flac
-Sample rate: 44100
-
-
-
-
-
-

The file has a poorly formatted copyright string and is missing tempo and cover art information. We can fix this by querying the three APIs as we did in the previous example, and overwrite the existing metadata:

-
-
-
query = f"{audio_file.artist} {audio_file.title}".lower()
-
-# iTunes Search API
-itunes_results = client_itunes.search(query)["results"]
-itunes_track = itunes_results[
-    np.argmax(
-        utility.levenshtein_ratio(
-            query,
-            [f"{r['artistName']} {r['trackName']}".lower()
-             for r in itunes_results]
-        )
-    )
-]
-itunes_album = client_itunes.lookup(itunes_track["collectionId"])["results"][0]
-audio_file.set_metadata_using_itunes(itunes_track, album_data=itunes_album,
-                                     overwrite=True)
-
-# Spotify Web API
-spotify_results = client_spotify.search(query, type="track")["items"]
-spotify_track = spotify_results[
-    np.argmax(
-        utility.levenshtein_ratio(
-            query,
-            [f"{r['artists'][0]['name']} {r['name']}".lower()
-             for r in spotify_results]
-        )
-    )
-]
-audio_file.set_metadata_using_spotify(
-    spotify_track,
-    audio_features=client_spotify.get_track_audio_features(spotify_track["id"])
-)
-
-# Private TIDAL API
-tidal_results = client_tidal.search(query)["tracks"]["items"]
-tidal_track = next((r for r in tidal_results if r["isrc"] == audio_file.isrc),
-                   None)
-tidal_composers = client_tidal.get_track_composers(tidal_track["id"])
-audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers)
-
-
-
-
-

Let’s take another look at the file’s metadata:

-
-
-
print_metadata(audio_file)
-
-
-
-
- - -Hide code cell output - -
-
Album: Back to You - Single
-Album artist: Tobu
-Artist: Tobu
-Comment: None
-Composer: Tobu & Toms Burkovskis
-Copyright: ℗ 2022 NCS
-Date: 2022-11-25T12:00:00Z
-Genre: House
-ISRC: GB2LD2210368
-Lyrics: None
-Tempo: 98
-Title: Back to You
-Compilation: False
-Disc number: 1
-Disc count: 1
-Track number: 1
-Track count: 1
-Artwork: <class 'bytes'>
-Bit depth: 16
-Bitrate: 1104053
-Channel count: 2
-Codec: flac
-Sample rate: 44100
-
-
-
-
-
-

Voilà! The metadata has been updated and is now complete. (Toms Burkovskis, otherwise known as Tobu, appears twice in the composer field because of the unique names. There is no elegant solution to this problem, unfortunately.)

-

As always, don’t forget to write the changes to the file:

-
-
-
audio_file.write_metadata()
-
-
-
-
-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/notebooks/user_guide/getting_recommendations.html b/docs/notebooks/user_guide/getting_recommendations.html deleted file mode 100644 index 5e4fab15..00000000 --- a/docs/notebooks/user_guide/getting_recommendations.html +++ /dev/null @@ -1,491 +0,0 @@ - - - - - - - - - Getting Recommendations - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

Getting Recommendations#

-

Last updated: November 19, 2023

-

Minim can help you discover new artists and music by leveraging the Spotify and TIDAL recommender systems and suggesting tracks based on your music libraries.

-
-
-
from base64 import b64encode
-import random
-
-from IPython.display import HTML, IFrame, display
-from ipywidgets import Output, GridspecLayout
-from minim import spotify, tidal
-
-
-
-
-
-

Spotify#

-

In the Spotify Web API, you can use minim.spotify.WebAPI.get_recommendations() to generate track recommendations based on your favorite artists, genres, and/or tracks, and a number of tunable track attributes.

-

In the following example, we will generate recommendations using only seed tracks.

-

First, we create a Spotify Web API client by instantiating a minim.spotify.WebAPI object:

-
-
-
client_spotify = spotify.WebAPI()
-
-
-
-
-

If you want to access your Spotify library for seed artists and/or tracks, make sure that the appropriate credentials and scopes are passed to the constructor above, stored in environment variables, or available in the Minim configuration file.

-
-

See also

-

See Getting Started for more information about setting up clients with user authentication.

-
-

The seed tracks can either come from your favorite Spotify tracks:

-
seed_tracks = [track["track"]["id"] for track in client_spotify.get_saved_tracks(limit=50)["items"]]
-
-
-

or be specified manually:

-
-
-
seed_tracks = [
-    "0JZ9TvOLtZJaGqIyC4hYZX",   # Avicii - Trouble
-    "0bmB3nzQuHBfI6nM4SETVu",   # Cash Cash - Surrender
-    "1PQ8ywTy9V2iVZWJ7Gyxxb",   # Mako - Our Story
-    "70IFLb5egLA8WUFWgxBoRz",   # Mike Williams - Fallin' In
-    "6jSPbxZLd2yemJTjz2gqOT",   # Passion Pit & Galantis - I Found U
-    "76B6LjxTolaSGXLANjNndR",   # Sick Individuals - Made for This
-    "2V65y3PX4DkRhy1djlxd9p",   # Swedish House Mafia - Don't You Worry Child (feat. John Martin)
-    "1gpF8IwQQj8qOeVjHfIIDU"    # Zedd - Find You (feat. Matthew Koma & Miriam Bryant)
-]
-
-
-
-
-

Since we are limited to 5 seed tracks, we will randomly select 5 tracks from our list of seed tracks and pass them as a keyword argument to minim.spotify.WebAPI.get_recommendations():

-
-
-
recommended_tracks = client_spotify.get_recommendations(
-    seed_tracks=random.choices(seed_tracks, k=5)
-)["tracks"]
-
-
-
-
-

Finally, we can add the recommended tracks to a new private Spotify playlist so that they can be accessed from another device:

-
spotify_playlist = client_spotify.create_playlist("Minim Mix", public=False)
-client_spotify.add_playlist_items(
-    spotify_playlist["id"], 
-    [f"spotify:track:{track['id']}" for track in recommended_tracks]
-)
-with open(globals()["_dh"][0].parents[3] / "assets/minim_mix_small.jpg", "rb") as f:
-    client_spotify.add_playlist_cover_image(spotify_playlist["id"], b64encode(f.read()))
-
-
-

The last two lines above add a nifty custom cover art for mixes created with Minim:

-

Minim Mix cover art

-

If you are building an interactive or web application, you can instead visualize the recommended tracks using embeds:

-
-
-
grid = GridspecLayout(len(recommended_tracks), 1)
-for i, track in enumerate(recommended_tracks):
-    out = Output()
-    with out:
-        display(IFrame(f"https://open.spotify.com/embed/track/{track['id']}", 
-                       frameBorder=0, loading="lazy", height=152, width=510))
-    grid[*divmod(i, 1)] = out
-grid
-
-
-
-
-
-
-
-
-

TIDAL#

-

In the TIDAL API, you can use minim.tidal.API.get_similar_albums(), minim.tidal.API.get_similar_artists(), and minim.tidal.API.get_similar_tracks() to generate recommendations based on your favorite albums, artists, and tracks, respectively.

-

In the following example, we will discover tracks similar to our favorite tracks only since the procedure for generating album and artist recommendations is similar.

-

First, we create a TIDAL API client by instantiating a minim.tidal.API object:

-
-
-
client_tidal = tidal.API()
-
-
-
-
-

and specify the tracks for which to find similar tracks:

-
-
-
favorite_tracks = [
-    51073951,   # Avicii - Trouble
-    62082351,   # Cash Cash - Surrender
-    32553484,   # Mako - Our Story
-    147258423,  # Mike Williams - Fallin' In
-    109273852,  # Passion Pit & Galantis - I Found U
-    237059212,  # Sick Individuals - Made for This
-    17271290,   # Swedish House Mafia - Don't You Worry Child (feat. John Martin)
-    27171015    # Zedd - Find You (feat. Matthew Koma & Miriam Bryant)
-]
-
-
-
-
-

Then, we randomly select a track from our list of favorite tracks and pass it to minim.tidal.API.get_similar_tracks():

-
-
-
similar_tracks = client_tidal.get_similar_tracks(random.choice(favorite_tracks), 
-                                                 "US")["data"]
-
-
-
-
-

Finally, we can display the similar tracks interactively using embeds:

-
-
-
grid = GridspecLayout(len(similar_tracks) // 2, 2)
-for i, track in enumerate(similar_tracks):
-    out = Output()
-    with out:
-        display(
-            HTML('<div class="tidal-embed" '
-                 'style="position:relative;padding-bottom:100%;'
-                 'height:0;overflow:hidden;max-width:100%">'
-                 '<iframe src="https://embed.tidal.com/tracks/'
-                 f'{track["resource"]["id"]}?layout=gridify" '
-                 'allowfullscreen="allowfullscreen" frameborder="0" '
-                 'style="position:absolute;top:0;left:0;width:100%;'
-                 'height:1px;min-height:100%;margin:0 auto">'
-                 '</iframe></div>')
-        )
-    grid[*divmod(i, 2)] = out
-grid
-
-
-
-
-
-
-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/notebooks/user_guide/transferring_music_libraries.html b/docs/notebooks/user_guide/transferring_music_libraries.html deleted file mode 100644 index 3f1d00e8..00000000 --- a/docs/notebooks/user_guide/transferring_music_libraries.html +++ /dev/null @@ -1,975 +0,0 @@ - - - - - - - - - Transferring Music Libraries - Minim 1.0.0 documentation - - - - - - - - - - - - - - - - - - - Contents - - - - - - Menu - - - - - - - - Expand - - - - - - Light mode - - - - - - - - - - - - - - Dark mode - - - - - - - Auto light/dark mode - - - - - - - - - - - - - - - - - - - -
-
-
- -
-
-
Minim 1.0.0 documentation
 -
-
-
- -
- -
-
- -
-
-
- - - - - Back to top - -
- -
- -
- -
-
-
-

Transferring Music Libraries#

-

Last updated: November 19, 2023

-

Minim can be used as a free, open-source alternative to services like TuneMyMusic for moving playlists and synchronizing libraries between the supported streaming services.

-
-
-
from minim import qobuz, spotify, tidal
-
-
-
-
-
-

Prerequisites#

-

All clients must be authenticated to access private user information. Assuming the relevant client credentials are stored as environment variables, the recommended client instantiation is as follows:

-
-
-
client_qobuz = qobuz.PrivateAPI(flow="password", browser=True)
-client_spotify = spotify.WebAPI(flow="pkce",
-                                scopes=spotify.WebAPI.get_scopes("all"),
-                                web_framework="http.server")
-client_tidal = tidal.PrivateAPI(flow="device_code", browser=True)
-
-
-
-
-
-

See also

-

See Getting Started for more information about setting up clients with user authentication.

-
-
-
-

Moving playlists#

-

The general process is to

-
    -

  1. get information about the tracks in the source playlist,

    2. -

  2. create a new playlist in the destination service, and

    3. -

  3. find and add the corresponding tracks to the newly-created playlist.

    4. -
-

The challenge often lies in the third step. The tracks in the source playlist may not be available in the destination service or it may be difficult finding the matching track in the destination service, especially if its catalog lookup does not support searching by ISRC or UPC.

-

The following examples provide barebones implementations of the process above for various service pairs. Additional fine-tuning is likely necessary to handle tracks with complex metadata, such as those with multiple or featured artists, remixes, etc.

-
-

From Qobuz#

-

We start with a Qobuz playlist with 5 tracks:

-
-
-
QOBUZ_PLAYLIST_ID = 17865119
-
-
-
-
-

We can get the playlist information and the items in the playlist using minim.qobuz.PrivateAPI.get_playlist():

-
-
-
qobuz_playlist = client_qobuz.get_playlist(QOBUZ_PLAYLIST_ID)
-
-
-
-
-
-

To Spotify#

-

First, we create a new playlist on Spotify with the same details as the Qobuz playlist using minim.spotify.WebAPI.create_playlist():

-
-
-
new_spotify_playlist = client_spotify.create_playlist(
-    qobuz_playlist["name"],
-    description=qobuz_playlist["description"],
-    public=qobuz_playlist["is_public"],
-    collaborative=qobuz_playlist["is_collaborative"],
-)
-
-
-
-
-

Then, we get the Spotify tracks equivalent to those in the Qobuz playlist. This is a simple process as Spotify allows looking up tracks by their ISRCs with its best-in-class API:

-
-
-
spotify_track_uris = []
-for qobuz_track in qobuz_playlist["tracks"]["items"]:
-    spotify_track = client_spotify.search(f'isrc:{qobuz_track["isrc"]}', type="track", limit=1)["items"][0]
-    spotify_track_uris.append(f"spotify:track:{spotify_track['id']}")
-
-
-
-
-

Finally, we add the tracks to the Spotify playlist using minim.spotify.WebAPI.add_playlist_items():

-
-
-
client_spotify.add_playlist_items(new_spotify_playlist["id"], spotify_track_uris)
-
-
-
-
-
-
-

To TIDAL#

-

First, we create a new playlist on TIDAL with the same details as the Qobuz playlist using minim.tidal.PrivateAPI.create_playlist():

-
-
-
new_tidal_playlist = client_tidal.create_playlist(
-    qobuz_playlist["name"],
-    description=qobuz_playlist["description"],
-    public=qobuz_playlist["is_public"]
-)
-
-
-
-
-

Then, we try to find TIDAL tracks equivalent to those in the Qobuz playlist. Unfortunately, TIDAL does not support searching by ISRCs, so we have to look up the tracks using their titles and artists. The TIDAL API does, however, return ISRCs so we can confirm that we have the right tracks before adding them to the TIDAL playlist.

-
-
-
tidal_track_ids = []
-for qobuz_track in qobuz_playlist["tracks"]["items"]:
-    title = qobuz_track["title"]
-    if qobuz_track["version"]:
-        title += f' {qobuz_track["version"]}'
-    tidal_track = client_tidal.search(
-        f'{qobuz_track["performer"]["name"]} {title}',
-        type="track",
-        limit=1
-    )["items"][0]
-    if qobuz_track["isrc"] == tidal_track["isrc"]:
-        tidal_track_ids.append(tidal_track["id"])
-
-
-
-
-

Finally, we add the tracks to the TIDAL playlist using minim.tidal.PrivateAPI.add_playlist_items():

-
-
-
client_tidal.add_playlist_items(new_tidal_playlist["data"]["uuid"], tidal_track_ids)
-
-
-
-
-
-
-
-

From Spotify#

-

We start with a Spotify playlist with 5 tracks:

-
-
-
SPOTIFY_PLAYLIST_ID = "3rw9qY60CEh6dfJauWdxMh"
-
-
-
-
-

We can get the playlist information and the items in the playlist using minim.spotify.WebAPI.get_playlist():

-
-
-
spotify_playlist = client_spotify.get_playlist(SPOTIFY_PLAYLIST_ID)
-
-
-
-
-
-

To Qobuz#

-

First, we create a new playlist on Qobuz with the same details as the Spotify playlist using minim.qobuz.PrivateAPI.create_playlist():

-
-
-
new_qobuz_playlist = client_qobuz.create_playlist(
-    spotify_playlist["name"],
-    description=spotify_playlist["description"],
-    public=spotify_playlist["public"],
-    collaborative=spotify_playlist["collaborative"],
-)
-
-
-
-
-

Then, we get the Qobuz tracks equivalent to those in the Spotify playlist. Thankfully, we can search by ISRC on Qobuz, so we can get the correct Qobuz tracks directly if they are available in the Qobuz catalog:

-
-
-
qobuz_track_ids = []
-for spotify_track in spotify_playlist["tracks"]["items"]:
-    qobuz_track = client_qobuz.search(
-        spotify_track["track"]["external_ids"]["isrc"],
-        limit=1
-    )["tracks"]["items"][0]
-    qobuz_track_ids.append(qobuz_track["id"])
-
-
-
-
-

Finally, we add the tracks to the Qobuz playlist using minim.qobuz.PrivateAPI.add_playlist_tracks():

-
-
-
client_qobuz.add_playlist_tracks(new_qobuz_playlist["id"], qobuz_track_ids)
-
-
-
-
-
-
-

To TIDAL#

-

First, we create a new playlist on TIDAL with the same details as the Spotify playlist:

-
-
-
new_tidal_playlist = client_tidal.create_playlist(
-    spotify_playlist["name"],
-    description=spotify_playlist["description"],
-    public=spotify_playlist["public"]
-)
-
-
-
-
-

Then, we try to find TIDAL tracks equivalent to those in the Spotify playlist:

-
-
-
tidal_track_ids = []
-for spotify_track in spotify_playlist["tracks"]["items"]:
-    tidal_track = client_tidal.search(
-        f'{spotify_track["track"]["artists"][0]["name"]} '
-        f'{spotify_track["track"]["name"]}',
-        type="track",
-        limit=1
-    )["items"][0]
-    if spotify_track["track"]["external_ids"]["isrc"] == tidal_track["isrc"]:
-        tidal_track_ids.append(tidal_track["id"])
-
-
-
-
-

Finally, we add the tracks to the TIDAL playlist:

-
-
-
client_tidal.add_playlist_items(new_tidal_playlist["data"]["uuid"], tidal_track_ids)
-
-
-
-
-
-
-
-

From TIDAL#

-

We start with a TIDAL playlist with 5 tracks:

-
-
-
TIDAL_PLAYLIST_UUID = "40052e73-58d4-4abb-bc1c-abace76d2f15"
-
-
-
-
-

We can get the playlist information using minim.tidal.PrivateAPI.get_user_playlist() and the items in the playlist using minim.tidal.PrivateAPI.get_playlist_items():

-
-
-
tidal_playlist = client_tidal.get_user_playlist(TIDAL_PLAYLIST_UUID)
-tidal_playlist_items = client_tidal.get_playlist_items(TIDAL_PLAYLIST_UUID)["items"]
-
-
-
-
-
-

To Qobuz#

-

First, we create a new playlist on Qobuz with the same details as the TIDAL playlist:

-
-
-
new_qobuz_playlist = client_qobuz.create_playlist(
-    spotify_playlist["name"],
-    description=spotify_playlist["description"],
-    public=spotify_playlist["public"],
-    collaborative=spotify_playlist["collaborative"],
-)
-
-
-
-
-

Then, we get the Qobuz tracks equivalent to those in the TIDAL playlist:

-
-
-
qobuz_track_ids = []
-for tidal_track in tidal_playlist_items:
-    qobuz_track = client_qobuz.search(
-        tidal_track["item"]["isrc"],
-        limit=1
-    )["tracks"]["items"][0]
-    qobuz_track_ids.append(qobuz_track["id"])
-
-
-
-
-

Finally, we add the tracks to the Qobuz playlist:

-
-
-
client_qobuz.add_playlist_tracks(new_qobuz_playlist["id"], qobuz_track_ids)
-
-
-
-
-
-
-

To Spotify#

-

First, we create a new playlist on Spotify with the same details as the TIDAL playlist:

-
-
-
new_spotify_playlist = client_spotify.create_playlist(
-    qobuz_playlist["name"],
-    description=qobuz_playlist["description"],
-    public=qobuz_playlist["is_public"],
-    collaborative=qobuz_playlist["is_collaborative"],
-)
-
-
-
-
-

Then, we get the Spotify tracks equivalent to those in the TIDAL playlist:

-
-
-
spotify_track_uris = []
-for tidal_track in tidal_playlist_items:
-    spotify_track = client_spotify.search(f'isrc:{tidal_track["item"]["isrc"]}',
-                                          type="track", limit=1)["items"][0]
-    spotify_track_uris.append(f"spotify:track:{spotify_track['id']}")
-
-
-
-
-

Finally, we add the tracks to the Spotify playlist:

-
-
-
client_spotify.add_playlist_items(new_spotify_playlist["id"],
-                                  spotify_track_uris)
-
-
-
-
-
-
-
-
-

Synchronizing favorites#

-

Synchronizing favorite albums, artists, tracks, etc. across services follows a similar procedure as above; we first get information about the entities in the source service and then try to find the corresponding media or people in the destination service. For albums and tracks, we can search using their UPCs and ISRCs, respectively, when available, or their titles and the main artist names. For artists, we can only search using their names.

-

Sample implementations for synchronizing albums and artists are available below for various service pairs.

-
-

From Qobuz#

-

We start by getting the current user’s favorite albums and artists using minim.qobuz.PrivateAPI.get_favorites():

-
-
-
qobuz_favorites = client_qobuz.get_favorites()
-qobuz_favorite_albums = qobuz_favorites["albums"]["items"]
-qobuz_favorite_artists = qobuz_favorites["artists"]["items"]
-
-
-
-
-
-

To Spotify#

-

The Spotify Web API supports searching for albums by UPC, but sometimes the UPCs returned by Qobuz do not align with those in the Spotify catalog. In those cases, we can search for the albums using their titles and the main artist names. Then, we select the correct album from the search results by matching the album title, main artists, and number of tracks. Finally, we add the albums to the user’s Spotify library using their Spotify album IDs and minim.spotify.WebAPI.save_albums():

-
-
-
spotify_album_ids = []
-for qobuz_album in qobuz_favorite_albums:
-    try:
-        spotify_album = client_spotify.search(f'upc:{qobuz_album["upc"][1:]}',
-                                              "album")["items"][0]
-    except IndexError:
-        spotify_albums = client_spotify.search(
-            f'{qobuz_album["artist"]["name"]} {qobuz_album["title"]}', "album"
-        )["items"]
-        for spotify_album in spotify_albums:
-            if (spotify_album["name"] == qobuz_album["title"]
-                    and spotify_album["artists"][0]["name"]
-                        == qobuz_album["artist"]["name"]
-                    and spotify_album["total_tracks"]
-                        == qobuz_album["tracks_count"]):
-                break
-    spotify_album_ids.append(spotify_album["id"])
-client_spotify.save_albums(spotify_album_ids)
-
-
-
-
-

For artists, we can search for them using their names and add them to the user’s Spotify library using their Spotify artist IDs and minim.spotify.WebAPI.follow_artists():

-
-
-
spotify_artist_ids = []
-for qobuz_artist in qobuz_favorite_artists:
-    spotify_artist = client_spotify.search(qobuz_artist["name"], "artist")["items"][0]
-    spotify_artist_ids.append(spotify_artist["id"])
-client_spotify.follow_people(spotify_artist_ids, "artist")
-
-
-
-
-
-
-

To TIDAL#

-

The private TIDAL API does not support searching for albums by UPC, so we have to search for them using their titles and the main artist names. Then, we select the correct albums by matching UPCs. Finally, we add the albums to the user’s TIDAL library using their TIDAL album IDs and minim.tidal.PrivateAPI.favorite_albums():

-
-
-
tidal_album_ids = []
-for qobuz_album in qobuz_favorite_albums:
-    tidal_albums = client_tidal.search(
-        f'{qobuz_album["artist"]["name"]} {qobuz_album["title"]}', type="album"
-    )["items"]
-    for tidal_album in tidal_albums:
-        if tidal_album["upc"].lstrip("0") == qobuz_album["upc"].lstrip("0"):
-            tidal_album_ids.append(tidal_album["id"])
-            break
-client_tidal.favorite_albums(tidal_album_ids)
-
-
-
-
-

For artists, we can search for them using their names and add them to the user’s TIDAL library using their TIDAL artist IDs and minim.tidal.PrivateAPI.favorite_artists():

-
-
-
tidal_artist_ids = []
-for qobuz_artist in qobuz_favorite_artists:
-    tidal_artist = client_tidal.search(qobuz_artist["name"],
-                                       type="artist")["items"][0]
-    tidal_artist_ids.append(tidal_artist["id"])
-client_tidal.favorite_artists(tidal_artist_ids)
-
-
-
-
-
-
-
-

From Spotify#

-

We start by getting the current user’s favorite albums and artists using minim.spotify.WebAPI.get_saved_albums() and minim.spotify.WebAPI.get_followed_artists(), respectively:

-
-
-
spotify_favorite_albums = client_spotify.get_saved_albums()["items"]
-spotify_favorite_artists = client_spotify.get_followed_artists()["items"]
-
-
-
-
-
-

To Qobuz#

-

The private Qobuz API does not support searching for albums by UPC, so we have to search for them using their titles and the main artist names. Then, we select the correct albums by matching UPCs or the album title, main artists, and number of tracks. Finally, we add the albums to the user’s Qobuz library using their Qobuz album IDs and minim.qobuz.PrivateAPI.favorite_items():

-
-
-
qobuz_album_ids = []
-for spotify_album in spotify_favorite_albums:
-    qobuz_albums = client_qobuz.search(
-        f'{spotify_album["album"]["artists"][0]["name"]} '
-        f'{spotify_album["album"]["name"]}'
-    )["albums"]["items"]
-    for qobuz_album in qobuz_albums:
-        if (spotify_album["album"]["external_ids"]["upc"].lstrip("0")
-                    == qobuz_albums[0]["upc"].lstrip("0")
-                or (spotify_album["album"]["name"] == qobuz_album["title"]
-                    and spotify_album["album"]["artists"][0]["name"]
-                        == qobuz_album["artist"]["name"]
-                    and spotify_album["album"]["tracks"]["total"]
-                        == qobuz_album["tracks_count"])):
-            qobuz_album_ids.append(qobuz_album["id"])
-            break
-client_qobuz.favorite_items(album_ids=qobuz_album_ids)
-
-
-
-
-

For artists, we can search for them using their names and add them to the user’s Qobuz library using their Qobuz artist IDs and minim.qobuz.PrivateAPI.favorite_items():

-
-
-
qobuz_artist_ids = []
-for spotify_artist in spotify_favorite_artists:
-    qobuz_artist = client_qobuz.search(
-        spotify_artist["name"]
-    )["artists"]["items"][0]
-    qobuz_artist_ids.append(qobuz_artist["id"])
-client_qobuz.favorite_items(artist_ids=qobuz_artist_ids)
-
-
-
-
-
-
-

To TIDAL#

-

To search for albums using their titles and the main artist names, select the correct albums by matching UPCs or the album title, main artists, and number of tracks, and add the albums to the user’s TIDAL library,

-
-
-
tidal_album_ids = []
-for spotify_album in spotify_favorite_albums:
-    tidal_albums = client_tidal.search(
-        f'{spotify_album["album"]["artists"][0]["name"]} '
-        f'{spotify_album["album"]["name"]}',
-        type="album"
-    )["items"]
-    for tidal_album in tidal_albums:
-        if (tidal_album["upc"].lstrip("0")
-                    == spotify_album["album"]["external_ids"]["upc"].lstrip("0")
-                or (tidal_album["title"] == spotify_album["album"]["name"]
-                    and tidal_album["artists"][0]["name"]
-                        == spotify_album["album"]["artists"][0]["name"]
-                    and tidal_album["numberOfTracks"]
-                        == spotify_album["album"]["tracks"]["total"])):
-            tidal_album_ids.append(tidal_album["id"])
-            break
-client_tidal.favorite_albums(tidal_album_ids)
-
-
-
-
-

To search for artists using their names and add them to the user’s TIDAL library,

-
-
-
tidal_artist_ids = []
-for spotify_artist in spotify_favorite_artists:
-    tidal_artist = client_tidal.search(spotify_artist["name"],
-                                       type="artist")["items"][0]
-    tidal_artist_ids.append(tidal_artist["id"])
-client_tidal.favorite_artists(tidal_artist_ids)
-
-
-
-
-
-
-
-

From TIDAL#

-

We start by getting the current user’s favorite albums and artists using minim.tidal.PrivateAPI.get_favorite_albums() and minim.tidal.PrivateAPI.get_favorite_artists(), respectively:

-
-
-
tidal_favorite_albums = client_tidal.get_favorite_albums()["items"]
-tidal_favorite_artists = client_tidal.get_favorite_artists()["items"]
-
-
-
-
-
-

To Qobuz#

-

To search for albums using their titles and the main artist names, select the correct albums by matching UPCs or the album title, main artists, and number of tracks, and add the albums to the user’s Qobuz library,

-
-
-
qobuz_album_ids = []
-for tidal_album in tidal_favorite_albums:
-    qobuz_albums = client_qobuz.search(
-        f'{tidal_album["item"]["artist"]["name"]} {tidal_album["item"]["title"]}'
-    )["albums"]["items"]
-    for qobuz_album in qobuz_albums:
-        if (tidal_album["item"]["upc"].lstrip("0")
-                    == qobuz_album["upc"].lstrip("0")
-                or (tidal_album["item"]["title"] == qobuz_album["title"]
-                    and tidal_album["item"]["artist"]["name"]
-                        == qobuz_album["artist"]["name"]
-                    and tidal_album["item"]["numberOfTracks"]
-                        == qobuz_album["tracks_count"])):
-            qobuz_album_ids.append(qobuz_album["id"])
-            break
-client_qobuz.favorite_items(album_ids=qobuz_album_ids)
-
-
-
-
-

To search for artists using their names and add them to the user’s Qobuz library,

-
-
-
qobuz_artist_ids = []
-for tidal_artist in tidal_favorite_artists:
-    qobuz_artist = client_qobuz.search(
-        tidal_artist["item"]["name"]
-    )["artists"]["items"][0]
-    qobuz_artist_ids.append(qobuz_artist["id"])
-client_qobuz.favorite_items(artist_ids=qobuz_artist_ids)
-
-
-
-
-
-
-

To Spotify#

-

To search for albums using their UPCs or titles and the main artist names, select the correct albums by matching the album title, main artists, and number of tracks, and add the albums to the user’s Spotify library,

-
-
-
spotify_album_ids = []
-for tidal_album in tidal_favorite_albums:
-    try:
-        spotify_album = client_spotify.search(
-            f'upc:{tidal_album["item"]["upc"]}',
-            "album"
-        )["items"][0]
-    except IndexError:
-        spotify_albums = client_spotify.search(
-            f'{tidal_album["item"]["artist"]["name"]} '
-            f'{tidal_album["item"]["title"]}',
-            "album"
-        )["items"]
-        for spotify_album in spotify_albums:
-            if (spotify_album["name"] == tidal_album["item"]["title"]
-                    and spotify_album["artists"][0]["name"]
-                        == tidal_album["item"]["artist"]["name"]
-                    and spotify_album["total_tracks"]
-                        == tidal_album["item"]["numberOfTracks"]):
-                break
-    spotify_album_ids.append(spotify_album["id"])
-client_spotify.save_albums(spotify_album_ids)
-
-
-
-
-

To search for artists using their names and add them to the user’s Spotify library,

-
-
-
spotify_artist_ids = []
-for tidal_artist in tidal_favorite_artists:
-    spotify_artist = client_spotify.search(tidal_artist["item"]["name"],
-                                           "artist")["items"][0]
-    spotify_artist_ids.append(spotify_artist["id"])
-client_spotify.follow_people(spotify_artist_ids, "artist")
-
-
-
-
-
-
-
-
- -
-
- -
- -
-
- - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/source/api/minim.audio.Audio.rst b/docs/source/api/minim.audio.Audio.rst deleted file mode 100644 index 8b3c7b89..00000000 --- a/docs/source/api/minim.audio.Audio.rst +++ /dev/null @@ -1,25 +0,0 @@ -Audio -===== - -.. currentmodule:: minim.audio - -.. autoclass:: Audio - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~Audio.convert - ~Audio.set_metadata_using_itunes - ~Audio.set_metadata_using_qobuz - ~Audio.set_metadata_using_spotify - ~Audio.set_metadata_using_tidal - - \ No newline at end of file diff --git a/docs/source/api/minim.audio.FLACAudio.rst b/docs/source/api/minim.audio.FLACAudio.rst deleted file mode 100644 index 796183a3..00000000 --- a/docs/source/api/minim.audio.FLACAudio.rst +++ /dev/null @@ -1,26 +0,0 @@ -FLACAudio -========= - -.. currentmodule:: minim.audio - -.. autoclass:: FLACAudio - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~FLACAudio.convert - ~FLACAudio.set_metadata_using_itunes - ~FLACAudio.set_metadata_using_qobuz - ~FLACAudio.set_metadata_using_spotify - ~FLACAudio.set_metadata_using_tidal - ~FLACAudio.write_metadata - - \ No newline at end of file diff --git a/docs/source/api/minim.audio.MP3Audio.rst b/docs/source/api/minim.audio.MP3Audio.rst deleted file mode 100644 index 13dc5ba1..00000000 --- a/docs/source/api/minim.audio.MP3Audio.rst +++ /dev/null @@ -1,26 +0,0 @@ -MP3Audio -======== - -.. currentmodule:: minim.audio - -.. autoclass:: MP3Audio - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~MP3Audio.convert - ~MP3Audio.set_metadata_using_itunes - ~MP3Audio.set_metadata_using_qobuz - ~MP3Audio.set_metadata_using_spotify - ~MP3Audio.set_metadata_using_tidal - ~MP3Audio.write_metadata - - \ No newline at end of file diff --git a/docs/source/api/minim.audio.MP4Audio.rst b/docs/source/api/minim.audio.MP4Audio.rst deleted file mode 100644 index ea3fbe13..00000000 --- a/docs/source/api/minim.audio.MP4Audio.rst +++ /dev/null @@ -1,26 +0,0 @@ -MP4Audio -======== - -.. currentmodule:: minim.audio - -.. autoclass:: MP4Audio - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~MP4Audio.convert - ~MP4Audio.set_metadata_using_itunes - ~MP4Audio.set_metadata_using_qobuz - ~MP4Audio.set_metadata_using_spotify - ~MP4Audio.set_metadata_using_tidal - ~MP4Audio.write_metadata - - \ No newline at end of file diff --git a/docs/source/api/minim.audio.OGGAudio.rst b/docs/source/api/minim.audio.OGGAudio.rst deleted file mode 100644 index 4f2e6364..00000000 --- a/docs/source/api/minim.audio.OGGAudio.rst +++ /dev/null @@ -1,26 +0,0 @@ -OggAudio -======== - -.. currentmodule:: minim.audio - -.. autoclass:: OggAudio - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~OggAudio.convert - ~OggAudio.set_metadata_using_itunes - ~OggAudio.set_metadata_using_qobuz - ~OggAudio.set_metadata_using_spotify - ~OggAudio.set_metadata_using_tidal - ~OggAudio.write_metadata - - \ No newline at end of file diff --git a/docs/source/api/minim.audio.WAVEAudio.rst b/docs/source/api/minim.audio.WAVEAudio.rst deleted file mode 100644 index 6a23a086..00000000 --- a/docs/source/api/minim.audio.WAVEAudio.rst +++ /dev/null @@ -1,26 +0,0 @@ -WAVEAudio -========= - -.. currentmodule:: minim.audio - -.. autoclass:: WAVEAudio - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~WAVEAudio.convert - ~WAVEAudio.set_metadata_using_itunes - ~WAVEAudio.set_metadata_using_qobuz - ~WAVEAudio.set_metadata_using_spotify - ~WAVEAudio.set_metadata_using_tidal - ~WAVEAudio.write_metadata - - \ No newline at end of file diff --git a/docs/source/api/minim.audio.rst b/docs/source/api/minim.audio.rst deleted file mode 100644 index e74fc2e8..00000000 --- a/docs/source/api/minim.audio.rst +++ /dev/null @@ -1,37 +0,0 @@ -audio -===== - -.. automodule:: minim.audio - - - - - - - - - - - - .. rubric:: Classes - - .. autosummary:: - :toctree: - :template: autosummary/class.rst - :nosignatures: - - Audio - FLACAudio - MP3Audio - MP4Audio - OggAudio - WAVEAudio - - - - - - - - - diff --git a/docs/source/api/minim.discogs.API.rst b/docs/source/api/minim.discogs.API.rst deleted file mode 100644 index 60ec4a5f..00000000 --- a/docs/source/api/minim.discogs.API.rst +++ /dev/null @@ -1,70 +0,0 @@ -API -=== - -.. currentmodule:: minim.discogs - -.. autoclass:: API - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~API.add_collection_folder_release - ~API.add_order_message - ~API.create_collection_folder - ~API.create_listing - ~API.delete_collection_folder - ~API.delete_collection_folder_release - ~API.delete_listing - ~API.delete_user_release_rating - ~API.download_inventory_export - ~API.edit_collection_folder_release - ~API.edit_collection_release_field - ~API.edit_listing - ~API.edit_order - ~API.edit_profile - ~API.export_inventory - ~API.get_artist - ~API.get_artist_releases - ~API.get_collection_fields - ~API.get_collection_folder - ~API.get_collection_folder_releases - ~API.get_collection_folders - ~API.get_collection_folders_by_release - ~API.get_collection_value - ~API.get_community_release_rating - ~API.get_fee - ~API.get_identity - ~API.get_inventory - ~API.get_inventory_export - ~API.get_inventory_exports - ~API.get_label - ~API.get_label_releases - ~API.get_listing - ~API.get_master_release - ~API.get_master_release_versions - ~API.get_order - ~API.get_order_messages - ~API.get_price_suggestions - ~API.get_profile - ~API.get_release - ~API.get_release_marketplace_stats - ~API.get_release_stats - ~API.get_user_contributions - ~API.get_user_orders - ~API.get_user_release_rating - ~API.get_user_submissions - ~API.rename_collection_folder - ~API.search - ~API.set_access_token - ~API.set_flow - ~API.update_user_release_rating - - \ No newline at end of file diff --git a/docs/source/api/minim.discogs.rst b/docs/source/api/minim.discogs.rst deleted file mode 100644 index bfb5edd1..00000000 --- a/docs/source/api/minim.discogs.rst +++ /dev/null @@ -1,32 +0,0 @@ -discogs -======= - -.. automodule:: minim.discogs - - - - - - - - - - - - .. rubric:: Classes - - .. autosummary:: - :toctree: - :template: autosummary/class.rst - :nosignatures: - - API - - - - - - - - - diff --git a/docs/source/api/minim.itunes.SearchAPI.rst b/docs/source/api/minim.itunes.SearchAPI.rst deleted file mode 100644 index e114376f..00000000 --- a/docs/source/api/minim.itunes.SearchAPI.rst +++ /dev/null @@ -1,22 +0,0 @@ -SearchAPI -========= - -.. currentmodule:: minim.itunes - -.. autoclass:: SearchAPI - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~SearchAPI.lookup - ~SearchAPI.search - - \ No newline at end of file diff --git a/docs/source/api/minim.itunes.rst b/docs/source/api/minim.itunes.rst deleted file mode 100644 index e7a936c5..00000000 --- a/docs/source/api/minim.itunes.rst +++ /dev/null @@ -1,32 +0,0 @@ -itunes -====== - -.. automodule:: minim.itunes - - - - - - - - - - - - .. rubric:: Classes - - .. autosummary:: - :toctree: - :template: autosummary/class.rst - :nosignatures: - - SearchAPI - - - - - - - - - diff --git a/docs/source/api/minim.qobuz.PrivateAPI.rst b/docs/source/api/minim.qobuz.PrivateAPI.rst deleted file mode 100644 index 16382596..00000000 --- a/docs/source/api/minim.qobuz.PrivateAPI.rst +++ /dev/null @@ -1,50 +0,0 @@ -PrivateAPI -========== - -.. currentmodule:: minim.qobuz - -.. autoclass:: PrivateAPI - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~PrivateAPI.add_playlist_tracks - ~PrivateAPI.create_playlist - ~PrivateAPI.delete_playlist - ~PrivateAPI.delete_playlist_tracks - ~PrivateAPI.favorite_items - ~PrivateAPI.favorite_playlist - ~PrivateAPI.get_album - ~PrivateAPI.get_artist - ~PrivateAPI.get_collection_streams - ~PrivateAPI.get_curated_tracks - ~PrivateAPI.get_favorites - ~PrivateAPI.get_featured_albums - ~PrivateAPI.get_featured_playlists - ~PrivateAPI.get_label - ~PrivateAPI.get_playlist - ~PrivateAPI.get_profile - ~PrivateAPI.get_purchases - ~PrivateAPI.get_track - ~PrivateAPI.get_track_file_url - ~PrivateAPI.get_track_performers - ~PrivateAPI.get_track_stream - ~PrivateAPI.get_user_playlists - ~PrivateAPI.move_playlist_tracks - ~PrivateAPI.search - ~PrivateAPI.set_auth_token - ~PrivateAPI.set_flow - ~PrivateAPI.unfavorite_items - ~PrivateAPI.unfavorite_playlist - ~PrivateAPI.update_playlist - ~PrivateAPI.update_playlist_position - - \ No newline at end of file diff --git a/docs/source/api/minim.qobuz.rst b/docs/source/api/minim.qobuz.rst deleted file mode 100644 index eed554fe..00000000 --- a/docs/source/api/minim.qobuz.rst +++ /dev/null @@ -1,32 +0,0 @@ -qobuz -===== - -.. automodule:: minim.qobuz - - - - - - - - - - - - .. rubric:: Classes - - .. autosummary:: - :toctree: - :template: autosummary/class.rst - :nosignatures: - - PrivateAPI - - - - - - - - - diff --git a/docs/source/api/minim.rst b/docs/source/api/minim.rst deleted file mode 100644 index bcd91e2c..00000000 --- a/docs/source/api/minim.rst +++ /dev/null @@ -1,36 +0,0 @@ -minim -===== - -.. automodule:: minim - - - - - - - - - - - - - - - - - - - -.. autosummary:: - :toctree: - :template: autosummary/module.rst - :recursive: - - minim.audio - minim.discogs - minim.itunes - minim.qobuz - minim.spotify - minim.tidal - minim.utility - diff --git a/docs/source/api/minim.spotify.PrivateLyricsService.rst b/docs/source/api/minim.spotify.PrivateLyricsService.rst deleted file mode 100644 index 2b2d728d..00000000 --- a/docs/source/api/minim.spotify.PrivateLyricsService.rst +++ /dev/null @@ -1,23 +0,0 @@ -PrivateLyricsService -==================== - -.. currentmodule:: minim.spotify - -.. autoclass:: PrivateLyricsService - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~PrivateLyricsService.get_lyrics - ~PrivateLyricsService.set_access_token - ~PrivateLyricsService.set_sp_dc - - \ No newline at end of file diff --git a/docs/source/api/minim.spotify.WebAPI.rst b/docs/source/api/minim.spotify.WebAPI.rst deleted file mode 100644 index 72aba012..00000000 --- a/docs/source/api/minim.spotify.WebAPI.rst +++ /dev/null @@ -1,111 +0,0 @@ -WebAPI -====== - -.. currentmodule:: minim.spotify - -.. autoclass:: WebAPI - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~WebAPI.add_playlist_cover_image - ~WebAPI.add_playlist_items - ~WebAPI.add_to_queue - ~WebAPI.change_playlist_details - ~WebAPI.check_followed_people - ~WebAPI.check_playlist_followers - ~WebAPI.check_saved_albums - ~WebAPI.check_saved_audiobooks - ~WebAPI.check_saved_episodes - ~WebAPI.check_saved_shows - ~WebAPI.check_saved_tracks - ~WebAPI.create_playlist - ~WebAPI.follow_people - ~WebAPI.follow_playlist - ~WebAPI.get_album - ~WebAPI.get_album_tracks - ~WebAPI.get_albums - ~WebAPI.get_artist - ~WebAPI.get_artist_albums - ~WebAPI.get_artist_top_tracks - ~WebAPI.get_artists - ~WebAPI.get_audiobook - ~WebAPI.get_audiobook_chapters - ~WebAPI.get_audiobooks - ~WebAPI.get_categories - ~WebAPI.get_category - ~WebAPI.get_category_playlists - ~WebAPI.get_chapter - ~WebAPI.get_chapters - ~WebAPI.get_currently_playing - ~WebAPI.get_devices - ~WebAPI.get_episode - ~WebAPI.get_episodes - ~WebAPI.get_featured_playlists - ~WebAPI.get_followed_artists - ~WebAPI.get_genre_seeds - ~WebAPI.get_markets - ~WebAPI.get_new_albums - ~WebAPI.get_personal_playlists - ~WebAPI.get_playback_state - ~WebAPI.get_playlist - ~WebAPI.get_playlist_cover_image - ~WebAPI.get_playlist_items - ~WebAPI.get_profile - ~WebAPI.get_queue - ~WebAPI.get_recently_played - ~WebAPI.get_recommendations - ~WebAPI.get_related_artists - ~WebAPI.get_saved_albums - ~WebAPI.get_saved_audiobooks - ~WebAPI.get_saved_episodes - ~WebAPI.get_saved_shows - ~WebAPI.get_saved_tracks - ~WebAPI.get_scopes - ~WebAPI.get_show - ~WebAPI.get_show_episodes - ~WebAPI.get_shows - ~WebAPI.get_top_items - ~WebAPI.get_track - ~WebAPI.get_track_audio_analysis - ~WebAPI.get_track_audio_features - ~WebAPI.get_tracks - ~WebAPI.get_tracks_audio_features - ~WebAPI.get_user_playlists - ~WebAPI.get_user_profile - ~WebAPI.pause_playback - ~WebAPI.remove_playlist_items - ~WebAPI.remove_saved_albums - ~WebAPI.remove_saved_audiobooks - ~WebAPI.remove_saved_episodes - ~WebAPI.remove_saved_shows - ~WebAPI.remove_saved_tracks - ~WebAPI.save_albums - ~WebAPI.save_audiobooks - ~WebAPI.save_episodes - ~WebAPI.save_shows - ~WebAPI.save_tracks - ~WebAPI.search - ~WebAPI.seek_to_position - ~WebAPI.set_access_token - ~WebAPI.set_flow - ~WebAPI.set_playback_volume - ~WebAPI.set_repeat_mode - ~WebAPI.skip_to_next - ~WebAPI.skip_to_previous - ~WebAPI.start_playback - ~WebAPI.toggle_playback_shuffle - ~WebAPI.transfer_playback - ~WebAPI.unfollow_people - ~WebAPI.unfollow_playlist - ~WebAPI.update_playlist_items - - \ No newline at end of file diff --git a/docs/source/api/minim.spotify.rst b/docs/source/api/minim.spotify.rst deleted file mode 100644 index d75021df..00000000 --- a/docs/source/api/minim.spotify.rst +++ /dev/null @@ -1,33 +0,0 @@ -spotify -======= - -.. automodule:: minim.spotify - - - - - - - - - - - - .. rubric:: Classes - - .. autosummary:: - :toctree: - :template: autosummary/class.rst - :nosignatures: - - PrivateLyricsService - WebAPI - - - - - - - - - diff --git a/docs/source/api/minim.tidal.API.rst b/docs/source/api/minim.tidal.API.rst deleted file mode 100644 index cdb523b2..00000000 --- a/docs/source/api/minim.tidal.API.rst +++ /dev/null @@ -1,39 +0,0 @@ -API -=== - -.. currentmodule:: minim.tidal - -.. autoclass:: API - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~API.get_album - ~API.get_album_by_barcode_id - ~API.get_album_items - ~API.get_albums - ~API.get_artist - ~API.get_artist_albums - ~API.get_artist_tracks - ~API.get_artists - ~API.get_similar_albums - ~API.get_similar_artists - ~API.get_similar_tracks - ~API.get_track - ~API.get_tracks - ~API.get_tracks_by_isrc - ~API.get_video - ~API.get_videos - ~API.search - ~API.set_access_token - ~API.set_flow - - \ No newline at end of file diff --git a/docs/source/api/minim.tidal.PrivateAPI.rst b/docs/source/api/minim.tidal.PrivateAPI.rst deleted file mode 100644 index 0c9c1671..00000000 --- a/docs/source/api/minim.tidal.PrivateAPI.rst +++ /dev/null @@ -1,106 +0,0 @@ -PrivateAPI -========== - -.. currentmodule:: minim.tidal - -.. autoclass:: PrivateAPI - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - - - .. rubric:: Methods - - .. autosummary:: - :nosignatures: - - ~PrivateAPI.add_playlist_items - ~PrivateAPI.block_artist - ~PrivateAPI.block_user - ~PrivateAPI.create_playlist - ~PrivateAPI.create_playlist_folder - ~PrivateAPI.delete_playlist - ~PrivateAPI.delete_playlist_folder - ~PrivateAPI.delete_playlist_item - ~PrivateAPI.favorite_albums - ~PrivateAPI.favorite_artists - ~PrivateAPI.favorite_mixes - ~PrivateAPI.favorite_playlists - ~PrivateAPI.favorite_tracks - ~PrivateAPI.favorite_videos - ~PrivateAPI.follow_user - ~PrivateAPI.get_album - ~PrivateAPI.get_album_credits - ~PrivateAPI.get_album_items - ~PrivateAPI.get_album_page - ~PrivateAPI.get_album_review - ~PrivateAPI.get_artist - ~PrivateAPI.get_artist_albums - ~PrivateAPI.get_artist_biography - ~PrivateAPI.get_artist_links - ~PrivateAPI.get_artist_mix_id - ~PrivateAPI.get_artist_page - ~PrivateAPI.get_artist_radio - ~PrivateAPI.get_artist_top_tracks - ~PrivateAPI.get_artist_videos - ~PrivateAPI.get_blocked_artists - ~PrivateAPI.get_blocked_users - ~PrivateAPI.get_collection_streams - ~PrivateAPI.get_country_code - ~PrivateAPI.get_favorite_albums - ~PrivateAPI.get_favorite_artists - ~PrivateAPI.get_favorite_ids - ~PrivateAPI.get_favorite_mixes - ~PrivateAPI.get_favorite_tracks - ~PrivateAPI.get_favorite_videos - ~PrivateAPI.get_image - ~PrivateAPI.get_mix_items - ~PrivateAPI.get_mix_page - ~PrivateAPI.get_personal_playlist_folders - ~PrivateAPI.get_personal_playlists - ~PrivateAPI.get_playlist - ~PrivateAPI.get_playlist_etag - ~PrivateAPI.get_playlist_items - ~PrivateAPI.get_playlist_recommendations - ~PrivateAPI.get_profile - ~PrivateAPI.get_session - ~PrivateAPI.get_similar_albums - ~PrivateAPI.get_similar_artists - ~PrivateAPI.get_track - ~PrivateAPI.get_track_composers - ~PrivateAPI.get_track_contributors - ~PrivateAPI.get_track_credits - ~PrivateAPI.get_track_lyrics - ~PrivateAPI.get_track_mix_id - ~PrivateAPI.get_track_playback_info - ~PrivateAPI.get_track_recommendations - ~PrivateAPI.get_track_stream - ~PrivateAPI.get_user_followers - ~PrivateAPI.get_user_following - ~PrivateAPI.get_user_playlist - ~PrivateAPI.get_user_playlists - ~PrivateAPI.get_user_profile - ~PrivateAPI.get_video - ~PrivateAPI.get_video_page - ~PrivateAPI.get_video_playback_info - ~PrivateAPI.get_video_stream - ~PrivateAPI.move_playlist - ~PrivateAPI.move_playlist_item - ~PrivateAPI.search - ~PrivateAPI.set_access_token - ~PrivateAPI.set_flow - ~PrivateAPI.set_playlist_privacy - ~PrivateAPI.unblock_artist - ~PrivateAPI.unblock_user - ~PrivateAPI.unfavorite_albums - ~PrivateAPI.unfavorite_artists - ~PrivateAPI.unfavorite_mixes - ~PrivateAPI.unfavorite_playlist - ~PrivateAPI.unfavorite_tracks - ~PrivateAPI.unfavorite_videos - ~PrivateAPI.unfollow_user - ~PrivateAPI.update_playlist - - \ No newline at end of file diff --git a/docs/source/api/minim.tidal.rst b/docs/source/api/minim.tidal.rst deleted file mode 100644 index 12394afb..00000000 --- a/docs/source/api/minim.tidal.rst +++ /dev/null @@ -1,33 +0,0 @@ -tidal -===== - -.. automodule:: minim.tidal - - - - - - - - - - - - .. rubric:: Classes - - .. autosummary:: - :toctree: - :template: autosummary/class.rst - :nosignatures: - - API - PrivateAPI - - - - - - - - - diff --git a/docs/source/api/minim.utility.format_multivalue.rst b/docs/source/api/minim.utility.format_multivalue.rst deleted file mode 100644 index d8c7901a..00000000 --- a/docs/source/api/minim.utility.format_multivalue.rst +++ /dev/null @@ -1,6 +0,0 @@ -format\_multivalue -================== - -.. currentmodule:: minim.utility - -.. autofunction:: format_multivalue \ No newline at end of file diff --git a/docs/source/api/minim.utility.gestalt_ratio.rst b/docs/source/api/minim.utility.gestalt_ratio.rst deleted file mode 100644 index 4611a99d..00000000 --- a/docs/source/api/minim.utility.gestalt_ratio.rst +++ /dev/null @@ -1,6 +0,0 @@ -gestalt\_ratio -============== - -.. currentmodule:: minim.utility - -.. autofunction:: gestalt_ratio \ No newline at end of file diff --git a/docs/source/api/minim.utility.levenshtein_ratio.rst b/docs/source/api/minim.utility.levenshtein_ratio.rst deleted file mode 100644 index 528af40f..00000000 --- a/docs/source/api/minim.utility.levenshtein_ratio.rst +++ /dev/null @@ -1,6 +0,0 @@ -levenshtein\_ratio -================== - -.. currentmodule:: minim.utility - -.. autofunction:: levenshtein_ratio \ No newline at end of file diff --git a/docs/source/api/minim.utility.rst b/docs/source/api/minim.utility.rst deleted file mode 100644 index 62e359e0..00000000 --- a/docs/source/api/minim.utility.rst +++ /dev/null @@ -1,33 +0,0 @@ -utility -======= - -.. automodule:: minim.utility - - - - - - - - .. rubric:: Functions - - .. autosummary:: - :toctree: - :nosignatures: - - format_multivalue - gestalt_ratio - levenshtein_ratio - - - - - - - - - - - - - diff --git a/docs/source/notebooks/getting_started.ipynb b/docs/source/notebooks/getting_started.ipynb index 50eae341..88ae7b47 100644 --- a/docs/source/notebooks/getting_started.ipynb +++ b/docs/source/notebooks/getting_started.ipynb @@ -83,7 +83,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -103,7 +103,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -123,7 +123,7 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -162,7 +162,7 @@ " \n", " - For Firefox, press `Shift` + `F9` to open Storage Inspector and nagivate to `Storage > Cookies > https://open.spotify.com`.\n", " \n", - "3. Create a client by instantiating a `minim.spotify.WebAPI` object with the `sp_dc` cookie as a keyword argument:\n", + "3. Create a client by instantiating a `minim.spotify.PrivateLyricsService` object with the `sp_dc` cookie as a keyword argument:\n", "\n", " ```python\n", " client_spotify_lyrics = spotify.PrivateLyricsService(sp_dc=)\n", @@ -173,8 +173,12 @@ }, { "cell_type": "code", - "execution_count": 5, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_spotify_lyrics = spotify.PrivateLyricsService()" @@ -202,8 +206,12 @@ }, { "cell_type": "code", - "execution_count": 6, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_spotify = spotify.WebAPI()" @@ -220,8 +228,12 @@ }, { "cell_type": "code", - "execution_count": 7, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "scopes = spotify.WebAPI.get_scopes(\"all\")" @@ -267,8 +279,12 @@ }, { "cell_type": "code", - "execution_count": 8, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_tidal = tidal.API()" @@ -287,8 +303,12 @@ }, { "cell_type": "code", - "execution_count": 9, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_tidal_private = tidal.PrivateAPI()" @@ -333,31 +353,13 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'wrapperType': 'artist',\n", - " 'artistType': 'Artist',\n", - " 'artistName': 'Galantis',\n", - " 'artistLinkUrl': 'https://music.apple.com/us/artist/galantis/543322169?uo=4',\n", - " 'artistId': 543322169,\n", - " 'amgArtistId': 2616267,\n", - " 'primaryGenreName': 'Dance',\n", - " 'primaryGenreId': 17}" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "client_itunes.search(\"Galantis\", entity=\"musicArtist\", limit=1)[\"results\"][0]" ] @@ -371,35 +373,15 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'picture': 'https://static.qobuz.com/images/artists/covers/small/8dcf30e5c8e30281ecbb13b0886426c8.jpg',\n", - " 'image': {'small': 'https://static.qobuz.com/images/artists/covers/small/8dcf30e5c8e30281ecbb13b0886426c8.jpg',\n", - " 'medium': 'https://static.qobuz.com/images/artists/covers/medium/8dcf30e5c8e30281ecbb13b0886426c8.jpg',\n", - " 'large': 'https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg',\n", - " 'extralarge': 'https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg',\n", - " 'mega': 'https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg'},\n", - " 'name': 'Galantis',\n", - " 'slug': 'galantis',\n", - " 'albums_count': 143,\n", - " 'id': 865362}" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "client_qobuz.search(\"Galantis\", limit=1, strict=True)[\"artists\"][\"items\"][0]" + "client_qobuz.search('\"Galantis\"', limit=1)[\"artists\"][\"items\"][0]" ] }, { @@ -411,41 +393,13 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'external_urls': {'spotify': 'https://open.spotify.com/artist/4sTQVOfp9vEMCemLw50sbu'},\n", - " 'followers': {'href': None, 'total': 3343551},\n", - " 'genres': ['dance pop', 'edm', 'pop', 'pop dance'],\n", - " 'href': 'https://api.spotify.com/v1/artists/4sTQVOfp9vEMCemLw50sbu',\n", - " 'id': '4sTQVOfp9vEMCemLw50sbu',\n", - " 'images': [{'height': 640,\n", - " 'url': 'https://i.scdn.co/image/ab6761610000e5eb7bda087d6fb48d481efd3344',\n", - " 'width': 640},\n", - " {'height': 320,\n", - " 'url': 'https://i.scdn.co/image/ab676161000051747bda087d6fb48d481efd3344',\n", - " 'width': 320},\n", - " {'height': 160,\n", - " 'url': 'https://i.scdn.co/image/ab6761610000f1787bda087d6fb48d481efd3344',\n", - " 'width': 160}],\n", - " 'name': 'Galantis',\n", - " 'popularity': 70,\n", - " 'type': 'artist',\n", - " 'uri': 'spotify:artist:4sTQVOfp9vEMCemLw50sbu'}" - ] - }, - "execution_count": 12, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "client_spotify.search(\"Galantis\", \"artist\", limit=1)[\"items\"][0]" ] @@ -459,59 +413,13 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'resource': {'id': '4676988',\n", - " 'name': 'Galantis',\n", - " 'picture': [{'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/1024x256.jpg',\n", - " 'width': 1024,\n", - " 'height': 256},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/1080x720.jpg',\n", - " 'width': 1080,\n", - " 'height': 720},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/160x107.jpg',\n", - " 'width': 160,\n", - " 'height': 107},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/160x160.jpg',\n", - " 'width': 160,\n", - " 'height': 160},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/320x214.jpg',\n", - " 'width': 320,\n", - " 'height': 214},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/320x320.jpg',\n", - " 'width': 320,\n", - " 'height': 320},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/480x480.jpg',\n", - " 'width': 480,\n", - " 'height': 480},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/640x428.jpg',\n", - " 'width': 640,\n", - " 'height': 428},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/750x500.jpg',\n", - " 'width': 750,\n", - " 'height': 500},\n", - " {'url': 'https://resources.tidal.com/images/a627e21c/60f7/4e90/b2bb/e50b178c4f0b/750x750.jpg',\n", - " 'width': 750,\n", - " 'height': 750}],\n", - " 'tidalUrl': 'https://tidal.com/browse/artist/4676988'},\n", - " 'id': '4676988',\n", - " 'status': 200,\n", - " 'message': 'success'}" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "client_tidal.search(\"Galantis\", \"US\", type=\"ARTISTS\", limit=1)[\"artists\"][0]" ] @@ -525,36 +433,13 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'id': 4676988,\n", - " 'name': 'Galantis',\n", - " 'artistTypes': ['ARTIST', 'CONTRIBUTOR'],\n", - " 'url': 'http://www.tidal.com/artist/4676988',\n", - " 'picture': 'a627e21c-60f7-4e90-b2bb-e50b178c4f0b',\n", - " 'popularity': 72,\n", - " 'artistRoles': [{'categoryId': -1, 'category': 'Artist'},\n", - " {'categoryId': 3, 'category': 'Engineer'},\n", - " {'categoryId': 11, 'category': 'Performer'},\n", - " {'categoryId': 10, 'category': 'Production team'},\n", - " {'categoryId': 1, 'category': 'Producer'},\n", - " {'categoryId': 2, 'category': 'Songwriter'}],\n", - " 'mixes': {'ARTIST_MIX': '000202a7e72fd90d0c0df2ed56ddea'}}" - ] - }, - "execution_count": 14, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "client_tidal_private.search(\"Galantis\", type=\"artist\", limit=1)[\"items\"][0]" ] @@ -572,55 +457,13 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'wrapperType': 'track',\n", - " 'kind': 'song',\n", - " 'artistId': 350172836,\n", - " 'collectionId': 1443469527,\n", - " 'trackId': 1443469581,\n", - " 'artistName': 'Neon Trees',\n", - " 'collectionName': 'Picture Show',\n", - " 'trackName': 'Everybody Talks',\n", - " 'collectionCensoredName': 'Picture Show',\n", - " 'trackCensoredName': 'Everybody Talks',\n", - " 'artistViewUrl': 'https://music.apple.com/us/artist/neon-trees/350172836?uo=4',\n", - " 'collectionViewUrl': 'https://music.apple.com/us/album/everybody-talks/1443469527?i=1443469581&uo=4',\n", - " 'trackViewUrl': 'https://music.apple.com/us/album/everybody-talks/1443469527?i=1443469581&uo=4',\n", - " 'previewUrl': 'https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview122/v4/5c/29/bf/5c29bf6b-ca2c-4e8b-2be6-c51a282c7dae/mzaf_1255557534804450018.plus.aac.p.m4a',\n", - " 'artworkUrl30': 'https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/30x30bb.jpg',\n", - " 'artworkUrl60': 'https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/60x60bb.jpg',\n", - " 'artworkUrl100': 'https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/100x100bb.jpg',\n", - " 'collectionPrice': 6.99,\n", - " 'trackPrice': 1.29,\n", - " 'releaseDate': '2012-01-01T12:00:00Z',\n", - " 'collectionExplicitness': 'explicit',\n", - " 'trackExplicitness': 'explicit',\n", - " 'discCount': 1,\n", - " 'discNumber': 1,\n", - " 'trackCount': 12,\n", - " 'trackNumber': 3,\n", - " 'trackTimeMillis': 177280,\n", - " 'country': 'USA',\n", - " 'currency': 'USD',\n", - " 'primaryGenreName': 'Alternative',\n", - " 'contentAdvisoryRating': 'Explicit',\n", - " 'isStreamable': True}" - ] - }, - "execution_count": 15, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "client_itunes.search(\"Everybody Talks\", media=\"music\", limit=1)[\"results\"][0]" ] @@ -634,104 +477,17 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'maximum_bit_depth': 16,\n", - " 'copyright': '2022 Arko Boom 2022 Arko Boom',\n", - " 'performers': 'Arko Boom, MainArtist - Arkos Todd, Songwriter, ComposerLyricist',\n", - " 'audio_info': {'replaygain_track_peak': 1, 'replaygain_track_gain': -3.06},\n", - " 'performer': {'name': 'Arko Boom', 'id': 15899504},\n", - " 'album': {'image': {'small': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_230.jpg',\n", - " 'thumbnail': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_50.jpg',\n", - " 'large': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_600.jpg'},\n", - " 'maximum_bit_depth': 16,\n", - " 'media_count': 1,\n", - " 'artist': {'image': None,\n", - " 'name': 'Arko Boom',\n", - " 'id': 15899504,\n", - " 'albums_count': 1,\n", - " 'slug': 'arko-boom',\n", - " 'picture': None},\n", - " 'upc': '0859766309663',\n", - " 'released_at': 1665180000,\n", - " 'label': {'name': 'Arko Boom',\n", - " 'id': 4026379,\n", - " 'albums_count': 1,\n", - " 'supplier_id': 95,\n", - " 'slug': 'arko-boom'},\n", - " 'title': 'Speedy',\n", - " 'qobuz_id': 178369185,\n", - " 'version': None,\n", - " 'duration': 536,\n", - " 'parental_warning': False,\n", - " 'tracks_count': 4,\n", - " 'popularity': 0,\n", - " 'genre': {'path': [133],\n", - " 'color': '#5eabc1',\n", - " 'name': 'Hip-Hop/Rap',\n", - " 'id': 133,\n", - " 'slug': 'rap-hip-hop'},\n", - " 'maximum_channel_count': 2,\n", - " 'id': 'ilfmuz10e7vfc',\n", - " 'maximum_sampling_rate': 44.1,\n", - " 'previewable': True,\n", - " 'sampleable': True,\n", - " 'displayable': True,\n", - " 'streamable': True,\n", - " 'streamable_at': 1711522800,\n", - " 'downloadable': False,\n", - " 'purchasable_at': None,\n", - " 'purchasable': False,\n", - " 'release_date_original': '2022-10-08',\n", - " 'release_date_download': '2022-10-08',\n", - " 'release_date_stream': '2022-10-08',\n", - " 'release_date_purchase': '2022-10-08',\n", - " 'hires': False,\n", - " 'hires_streamable': False},\n", - " 'work': None,\n", - " 'composer': {'name': 'Arkos Todd', 'id': 15899505},\n", - " 'isrc': 'TCAGM2280786',\n", - " 'title': 'Everybody Talks',\n", - " 'version': None,\n", - " 'duration': 127,\n", - " 'parental_warning': False,\n", - " 'track_number': 2,\n", - " 'maximum_channel_count': 2,\n", - " 'id': 178369187,\n", - " 'media_number': 1,\n", - " 'maximum_sampling_rate': 44.1,\n", - " 'release_date_original': '2022-10-08',\n", - " 'release_date_download': '2022-10-08',\n", - " 'release_date_stream': '2022-10-08',\n", - " 'release_date_purchase': '2022-10-08',\n", - " 'purchasable': True,\n", - " 'streamable': True,\n", - " 'previewable': True,\n", - " 'sampleable': True,\n", - " 'downloadable': True,\n", - " 'displayable': True,\n", - " 'purchasable_at': 1711522800,\n", - " 'streamable_at': 1711522800,\n", - " 'hires': False,\n", - " 'hires_streamable': False}" - ] - }, - "execution_count": 16, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "track_qobuz = client_qobuz.search(\"Everybody Talks\", \"ReleaseName\", limit=1,\n", - " strict=True)[\"tracks\"][\"items\"][0]\n", + "track_qobuz = client_qobuz.search('\"Everybody Talks\"', limit=1)[\"tracks\"][\n", + " \"items\"\n", + "][0]\n", "track_qobuz" ] }, @@ -744,421 +500,17 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'album': {'album_type': 'album',\n", - " 'artists': [{'external_urls': {'spotify': 'https://open.spotify.com/artist/0RpddSzUHfncUWNJXKOsjy'},\n", - " 'href': 'https://api.spotify.com/v1/artists/0RpddSzUHfncUWNJXKOsjy',\n", - " 'id': '0RpddSzUHfncUWNJXKOsjy',\n", - " 'name': 'Neon Trees',\n", - " 'type': 'artist',\n", - " 'uri': 'spotify:artist:0RpddSzUHfncUWNJXKOsjy'}],\n", - " 'available_markets': ['AR',\n", - " 'AU',\n", - " 'AT',\n", - " 'BE',\n", - " 'BO',\n", - " 'BR',\n", - " 'BG',\n", - " 'CA',\n", - " 'CL',\n", - " 'CO',\n", - " 'CR',\n", - " 'CY',\n", - " 'CZ',\n", - " 'DK',\n", - " 'DO',\n", - " 'DE',\n", - " 'EC',\n", - " 'EE',\n", - " 'SV',\n", - " 'FI',\n", - " 'FR',\n", - " 'GR',\n", - " 'GT',\n", - " 'HN',\n", - " 'HK',\n", - " 'HU',\n", - " 'IS',\n", - " 'IE',\n", - " 'IT',\n", - " 'LV',\n", - " 'LT',\n", - " 'LU',\n", - " 'MY',\n", - " 'MT',\n", - " 'NL',\n", - " 'NZ',\n", - " 'NI',\n", - " 'NO',\n", - " 'PA',\n", - " 'PY',\n", - " 'PE',\n", - " 'PH',\n", - " 'PL',\n", - " 'PT',\n", - " 'SG',\n", - " 'SK',\n", - " 'ES',\n", - " 'SE',\n", - " 'CH',\n", - " 'TW',\n", - " 'TR',\n", - " 'UY',\n", - " 'US',\n", - " 'GB',\n", - " 'AD',\n", - " 'LI',\n", - " 'MC',\n", - " 'ID',\n", - " 'TH',\n", - " 'VN',\n", - " 'RO',\n", - " 'IL',\n", - " 'ZA',\n", - " 'SA',\n", - " 'AE',\n", - " 'BH',\n", - " 'QA',\n", - " 'OM',\n", - " 'KW',\n", - " 'EG',\n", - " 'TN',\n", - " 'LB',\n", - " 'JO',\n", - " 'PS',\n", - " 'IN',\n", - " 'BY',\n", - " 'KZ',\n", - " 'MD',\n", - " 'UA',\n", - " 'AL',\n", - " 'BA',\n", - " 'HR',\n", - " 'ME',\n", - " 'MK',\n", - " 'RS',\n", - " 'SI',\n", - " 'KR',\n", - " 'BD',\n", - " 'PK',\n", - " 'LK',\n", - " 'GH',\n", - " 'KE',\n", - " 'NG',\n", - " 'TZ',\n", - " 'UG',\n", - " 'AG',\n", - " 'AM',\n", - " 'BS',\n", - " 'BB',\n", - " 'BZ',\n", - " 'BT',\n", - " 'BW',\n", - " 'BF',\n", - " 'CV',\n", - " 'CW',\n", - " 'DM',\n", - " 'FJ',\n", - " 'GM',\n", - " 'GD',\n", - " 'GW',\n", - " 'GY',\n", - " 'HT',\n", - " 'JM',\n", - " 'KI',\n", - " 'LS',\n", - " 'LR',\n", - " 'MW',\n", - " 'MV',\n", - " 'ML',\n", - " 'MH',\n", - " 'FM',\n", - " 'NA',\n", - " 'NR',\n", - " 'NE',\n", - " 'PW',\n", - " 'PG',\n", - " 'WS',\n", - " 'ST',\n", - " 'SN',\n", - " 'SC',\n", - " 'SL',\n", - " 'SB',\n", - " 'KN',\n", - " 'LC',\n", - " 'VC',\n", - " 'SR',\n", - " 'TL',\n", - " 'TO',\n", - " 'TT',\n", - " 'TV',\n", - " 'AZ',\n", - " 'BN',\n", - " 'BI',\n", - " 'KH',\n", - " 'CM',\n", - " 'TD',\n", - " 'KM',\n", - " 'GQ',\n", - " 'SZ',\n", - " 'GA',\n", - " 'GN',\n", - " 'KG',\n", - " 'LA',\n", - " 'MO',\n", - " 'MR',\n", - " 'MN',\n", - " 'NP',\n", - " 'RW',\n", - " 'TG',\n", - " 'UZ',\n", - " 'ZW',\n", - " 'BJ',\n", - " 'MG',\n", - " 'MU',\n", - " 'MZ',\n", - " 'AO',\n", - " 'CI',\n", - " 'DJ',\n", - " 'ZM',\n", - " 'CD',\n", - " 'CG',\n", - " 'IQ',\n", - " 'TJ',\n", - " 'VE',\n", - " 'XK'],\n", - " 'external_urls': {'spotify': 'https://open.spotify.com/album/0uRFz92JmjwDbZbB7hEBIr'},\n", - " 'href': 'https://api.spotify.com/v1/albums/0uRFz92JmjwDbZbB7hEBIr',\n", - " 'id': '0uRFz92JmjwDbZbB7hEBIr',\n", - " 'images': [{'height': 640,\n", - " 'url': 'https://i.scdn.co/image/ab67616d0000b2734a6c0376235e5aa44e59d2c2',\n", - " 'width': 640},\n", - " {'height': 300,\n", - " 'url': 'https://i.scdn.co/image/ab67616d00001e024a6c0376235e5aa44e59d2c2',\n", - " 'width': 300},\n", - " {'height': 64,\n", - " 'url': 'https://i.scdn.co/image/ab67616d000048514a6c0376235e5aa44e59d2c2',\n", - " 'width': 64}],\n", - " 'name': 'Picture Show',\n", - " 'release_date': '2012-01-01',\n", - " 'release_date_precision': 'day',\n", - " 'total_tracks': 11,\n", - " 'type': 'album',\n", - " 'uri': 'spotify:album:0uRFz92JmjwDbZbB7hEBIr'},\n", - " 'artists': [{'external_urls': {'spotify': 'https://open.spotify.com/artist/0RpddSzUHfncUWNJXKOsjy'},\n", - " 'href': 'https://api.spotify.com/v1/artists/0RpddSzUHfncUWNJXKOsjy',\n", - " 'id': '0RpddSzUHfncUWNJXKOsjy',\n", - " 'name': 'Neon Trees',\n", - " 'type': 'artist',\n", - " 'uri': 'spotify:artist:0RpddSzUHfncUWNJXKOsjy'}],\n", - " 'available_markets': ['AR',\n", - " 'AU',\n", - " 'AT',\n", - " 'BE',\n", - " 'BO',\n", - " 'BR',\n", - " 'BG',\n", - " 'CA',\n", - " 'CL',\n", - " 'CO',\n", - " 'CR',\n", - " 'CY',\n", - " 'CZ',\n", - " 'DK',\n", - " 'DO',\n", - " 'DE',\n", - " 'EC',\n", - " 'EE',\n", - " 'SV',\n", - " 'FI',\n", - " 'FR',\n", - " 'GR',\n", - " 'GT',\n", - " 'HN',\n", - " 'HK',\n", - " 'HU',\n", - " 'IS',\n", - " 'IE',\n", - " 'IT',\n", - " 'LV',\n", - " 'LT',\n", - " 'LU',\n", - " 'MY',\n", - " 'MT',\n", - " 'NL',\n", - " 'NZ',\n", - " 'NI',\n", - " 'NO',\n", - " 'PA',\n", - " 'PY',\n", - " 'PE',\n", - " 'PH',\n", - " 'PL',\n", - " 'PT',\n", - " 'SG',\n", - " 'SK',\n", - " 'ES',\n", - " 'SE',\n", - " 'CH',\n", - " 'TW',\n", - " 'TR',\n", - " 'UY',\n", - " 'US',\n", - " 'GB',\n", - " 'AD',\n", - " 'LI',\n", - " 'MC',\n", - " 'ID',\n", - " 'TH',\n", - " 'VN',\n", - " 'RO',\n", - " 'IL',\n", - " 'ZA',\n", - " 'SA',\n", - " 'AE',\n", - " 'BH',\n", - " 'QA',\n", - " 'OM',\n", - " 'KW',\n", - " 'EG',\n", - " 'TN',\n", - " 'LB',\n", - " 'JO',\n", - " 'PS',\n", - " 'IN',\n", - " 'BY',\n", - " 'KZ',\n", - " 'MD',\n", - " 'UA',\n", - " 'AL',\n", - " 'BA',\n", - " 'HR',\n", - " 'ME',\n", - " 'MK',\n", - " 'RS',\n", - " 'SI',\n", - " 'KR',\n", - " 'BD',\n", - " 'PK',\n", - " 'LK',\n", - " 'GH',\n", - " 'KE',\n", - " 'NG',\n", - " 'TZ',\n", - " 'UG',\n", - " 'AG',\n", - " 'AM',\n", - " 'BS',\n", - " 'BB',\n", - " 'BZ',\n", - " 'BT',\n", - " 'BW',\n", - " 'BF',\n", - " 'CV',\n", - " 'CW',\n", - " 'DM',\n", - " 'FJ',\n", - " 'GM',\n", - " 'GD',\n", - " 'GW',\n", - " 'GY',\n", - " 'HT',\n", - " 'JM',\n", - " 'KI',\n", - " 'LS',\n", - " 'LR',\n", - " 'MW',\n", - " 'MV',\n", - " 'ML',\n", - " 'MH',\n", - " 'FM',\n", - " 'NA',\n", - " 'NR',\n", - " 'NE',\n", - " 'PW',\n", - " 'PG',\n", - " 'WS',\n", - " 'ST',\n", - " 'SN',\n", - " 'SC',\n", - " 'SL',\n", - " 'SB',\n", - " 'KN',\n", - " 'LC',\n", - " 'VC',\n", - " 'SR',\n", - " 'TL',\n", - " 'TO',\n", - " 'TT',\n", - " 'TV',\n", - " 'AZ',\n", - " 'BN',\n", - " 'BI',\n", - " 'KH',\n", - " 'CM',\n", - " 'TD',\n", - " 'KM',\n", - " 'GQ',\n", - " 'SZ',\n", - " 'GA',\n", - " 'GN',\n", - " 'KG',\n", - " 'LA',\n", - " 'MO',\n", - " 'MR',\n", - " 'MN',\n", - " 'NP',\n", - " 'RW',\n", - " 'TG',\n", - " 'UZ',\n", - " 'ZW',\n", - " 'BJ',\n", - " 'MG',\n", - " 'MU',\n", - " 'MZ',\n", - " 'AO',\n", - " 'CI',\n", - " 'DJ',\n", - " 'ZM',\n", - " 'CD',\n", - " 'CG',\n", - " 'IQ',\n", - " 'TJ',\n", - " 'VE',\n", - " 'XK'],\n", - " 'disc_number': 1,\n", - " 'duration_ms': 177280,\n", - " 'explicit': True,\n", - " 'external_ids': {'isrc': 'USUM71119189'},\n", - " 'external_urls': {'spotify': 'https://open.spotify.com/track/2iUmqdfGZcHIhS3b9E9EWq'},\n", - " 'href': 'https://api.spotify.com/v1/tracks/2iUmqdfGZcHIhS3b9E9EWq',\n", - " 'id': '2iUmqdfGZcHIhS3b9E9EWq',\n", - " 'is_local': False,\n", - " 'name': 'Everybody Talks',\n", - " 'popularity': 80,\n", - " 'preview_url': None,\n", - " 'track_number': 3,\n", - " 'type': 'track',\n", - " 'uri': 'spotify:track:2iUmqdfGZcHIhS3b9E9EWq'}" - ] - }, - "execution_count": 17, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "track_spotify = client_spotify.search(\"Everybody Talks\", \"track\",\n", - " limit=1)[\"items\"][0]\n", + "track_spotify = client_spotify.search(\"Everybody Talks\", \"track\", limit=1)[\n", + " \"items\"\n", + "][0]\n", "track_spotify" ] }, @@ -1171,96 +523,17 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'resource': {'artifactType': 'track',\n", - " 'id': '14492425',\n", - " 'title': 'Everybody Talks',\n", - " 'artists': [{'id': '3665225',\n", - " 'name': 'Neon Trees',\n", - " 'picture': [{'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/1024x256.jpg',\n", - " 'width': 1024,\n", - " 'height': 256},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/1080x720.jpg',\n", - " 'width': 1080,\n", - " 'height': 720},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/160x107.jpg',\n", - " 'width': 160,\n", - " 'height': 107},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/160x160.jpg',\n", - " 'width': 160,\n", - " 'height': 160},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/320x214.jpg',\n", - " 'width': 320,\n", - " 'height': 214},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/320x320.jpg',\n", - " 'width': 320,\n", - " 'height': 320},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/480x480.jpg',\n", - " 'width': 480,\n", - " 'height': 480},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/640x428.jpg',\n", - " 'width': 640,\n", - " 'height': 428},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/750x500.jpg',\n", - " 'width': 750,\n", - " 'height': 500},\n", - " {'url': 'https://resources.tidal.com/images/e6f17398/759e/45a0/9673/6ded6811e199/750x750.jpg',\n", - " 'width': 750,\n", - " 'height': 750}],\n", - " 'main': True}],\n", - " 'album': {'id': '14492422',\n", - " 'title': 'Picture Show',\n", - " 'imageCover': [{'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/1080x1080.jpg',\n", - " 'width': 1080,\n", - " 'height': 1080},\n", - " {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/1280x1280.jpg',\n", - " 'width': 1280,\n", - " 'height': 1280},\n", - " {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/160x160.jpg',\n", - " 'width': 160,\n", - " 'height': 160},\n", - " {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/320x320.jpg',\n", - " 'width': 320,\n", - " 'height': 320},\n", - " {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/640x640.jpg',\n", - " 'width': 640,\n", - " 'height': 640},\n", - " {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/750x750.jpg',\n", - " 'width': 750,\n", - " 'height': 750},\n", - " {'url': 'https://resources.tidal.com/images/1c2d7c90/034e/485a/be1f/24a669c7e6ee/80x80.jpg',\n", - " 'width': 80,\n", - " 'height': 80}],\n", - " 'videoCover': []},\n", - " 'duration': 177,\n", - " 'trackNumber': 3,\n", - " 'volumeNumber': 1,\n", - " 'isrc': 'USUM71119189',\n", - " 'copyright': 'A Mercury Records Release; ℗ 2011 UMG Recordings, Inc.',\n", - " 'mediaMetadata': {'tags': ['LOSSLESS']},\n", - " 'properties': {'content': ['explicit']},\n", - " 'tidalUrl': 'https://tidal.com/browse/track/14492425'},\n", - " 'id': '14492425',\n", - " 'status': 200,\n", - " 'message': 'success'}" - ] - }, - "execution_count": 18, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "client_tidal.search(\"Everybody Talks\", \"US\", type=\"TRACKS\", limit=1)[\"tracks\"][0]" + "client_tidal.search(\"Everybody Talks\", \"US\", type=\"TRACKS\", limit=1)[\"tracks\"][\n", + " 0\n", + "]" ] }, { @@ -1272,66 +545,17 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'id': 14492425,\n", - " 'title': 'Everybody Talks',\n", - " 'duration': 177,\n", - " 'replayGain': -11.7,\n", - " 'peak': 0.999969,\n", - " 'allowStreaming': True,\n", - " 'streamReady': True,\n", - " 'adSupportedStreamReady': True,\n", - " 'djReady': True,\n", - " 'stemReady': False,\n", - " 'streamStartDate': '2012-04-17T00:00:00.000+0000',\n", - " 'premiumStreamingOnly': False,\n", - " 'trackNumber': 3,\n", - " 'volumeNumber': 1,\n", - " 'version': None,\n", - " 'popularity': 60,\n", - " 'copyright': 'A Mercury Records Release; ℗ 2011 UMG Recordings, Inc.',\n", - " 'bpm': 155,\n", - " 'url': 'http://www.tidal.com/track/14492425',\n", - " 'isrc': 'USUM71119189',\n", - " 'editable': False,\n", - " 'explicit': True,\n", - " 'audioQuality': 'LOSSLESS',\n", - " 'audioModes': ['STEREO'],\n", - " 'mediaMetadata': {'tags': ['LOSSLESS']},\n", - " 'artist': {'id': 3665225,\n", - " 'name': 'Neon Trees',\n", - " 'type': 'MAIN',\n", - " 'picture': 'e6f17398-759e-45a0-9673-6ded6811e199'},\n", - " 'artists': [{'id': 3665225,\n", - " 'name': 'Neon Trees',\n", - " 'type': 'MAIN',\n", - " 'picture': 'e6f17398-759e-45a0-9673-6ded6811e199'}],\n", - " 'album': {'id': 14492422,\n", - " 'title': 'Picture Show',\n", - " 'cover': '1c2d7c90-034e-485a-be1f-24a669c7e6ee',\n", - " 'vibrantColor': '#f8af88',\n", - " 'videoCover': None},\n", - " 'mixes': {'TRACK_MIX': '0019768c833a193c29829e5bf473fc'}}" - ] - }, - "execution_count": 19, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "track_tidal_private = client_tidal_private.search(\"Everybody Talks\",\n", - " type=\"track\",\n", - " limit=1)[\"items\"][0]\n", + "track_tidal_private = client_tidal_private.search(\n", + " \"Everybody Talks\", type=\"track\", limit=1\n", + ")[\"items\"][0]\n", "track_tidal_private" ] }, @@ -1348,144 +572,30 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'owner': None,\n", - " 'users_count': 0,\n", - " 'images150': ['https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_150.jpg'],\n", - " 'images': ['https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_50.jpg'],\n", - " 'is_collaborative': False,\n", - " 'description': 'A playlist created using Minim.',\n", - " 'created_at': 1716795945,\n", - " 'images300': ['https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_300.jpg'],\n", - " 'duration': 127,\n", - " 'updated_at': 1716795946,\n", - " 'published_to': None,\n", - " 'genres': [],\n", - " 'tracks_count': 1,\n", - " 'public_at': 1716795945,\n", - " 'name': 'Minim',\n", - " 'is_public': True,\n", - " 'published_from': None,\n", - " 'id': 21785610,\n", - " 'slug': 'minim-11',\n", - " 'is_featured': False,\n", - " 'tracks': {'offset': 0,\n", - " 'limit': 50,\n", - " 'total': 1,\n", - " 'items': [{'maximum_bit_depth': 16,\n", - " 'copyright': '2022 Arko Boom 2022 Arko Boom',\n", - " 'performers': 'Arko Boom, MainArtist - Arkos Todd, Songwriter, ComposerLyricist',\n", - " 'audio_info': {'replaygain_track_peak': 1, 'replaygain_track_gain': -3.06},\n", - " 'performer': {'name': 'Arko Boom', 'id': 15899504},\n", - " 'album': {'image': {'small': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_230.jpg',\n", - " 'thumbnail': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_50.jpg',\n", - " 'large': 'https://static.qobuz.com/images/covers/fc/7v/ilfmuz10e7vfc_600.jpg'},\n", - " 'maximum_bit_depth': 16,\n", - " 'media_count': 1,\n", - " 'artist': {'image': None,\n", - " 'name': 'Arko Boom',\n", - " 'id': 15899504,\n", - " 'albums_count': 1,\n", - " 'slug': 'arko-boom',\n", - " 'picture': None},\n", - " 'upc': '0859766309663',\n", - " 'released_at': 1665180000,\n", - " 'label': {'name': 'Arko Boom',\n", - " 'id': 4026379,\n", - " 'albums_count': 1,\n", - " 'supplier_id': 95,\n", - " 'slug': 'arko-boom'},\n", - " 'title': 'Speedy',\n", - " 'qobuz_id': 178369185,\n", - " 'version': None,\n", - " 'duration': 536,\n", - " 'parental_warning': False,\n", - " 'tracks_count': 4,\n", - " 'popularity': 0,\n", - " 'genre': {'path': [133],\n", - " 'color': '#5eabc1',\n", - " 'name': 'Hip-Hop/Rap',\n", - " 'id': 133,\n", - " 'slug': 'rap-hip-hop'},\n", - " 'maximum_channel_count': 2,\n", - " 'id': 'ilfmuz10e7vfc',\n", - " 'maximum_sampling_rate': 44.1,\n", - " 'previewable': True,\n", - " 'sampleable': True,\n", - " 'displayable': True,\n", - " 'streamable': True,\n", - " 'streamable_at': 1711522800,\n", - " 'downloadable': False,\n", - " 'purchasable_at': None,\n", - " 'purchasable': False,\n", - " 'release_date_original': '2022-10-08',\n", - " 'release_date_download': '2022-10-08',\n", - " 'release_date_stream': '2022-10-08',\n", - " 'release_date_purchase': '2022-10-08',\n", - " 'hires': False,\n", - " 'hires_streamable': False},\n", - " 'work': None,\n", - " 'composer': {'name': 'Arkos Todd', 'id': 15899505},\n", - " 'isrc': 'TCAGM2280786',\n", - " 'title': 'Everybody Talks',\n", - " 'version': None,\n", - " 'duration': 127,\n", - " 'parental_warning': False,\n", - " 'track_number': 2,\n", - " 'maximum_channel_count': 2,\n", - " 'id': 178369187,\n", - " 'media_number': 1,\n", - " 'maximum_sampling_rate': 44.1,\n", - " 'release_date_original': '2022-10-08',\n", - " 'release_date_download': '2022-10-08',\n", - " 'release_date_stream': '2022-10-08',\n", - " 'release_date_purchase': '2022-10-08',\n", - " 'purchasable': True,\n", - " 'streamable': True,\n", - " 'previewable': True,\n", - " 'sampleable': True,\n", - " 'downloadable': True,\n", - " 'displayable': True,\n", - " 'purchasable_at': 1711522800,\n", - " 'streamable_at': 1711522800,\n", - " 'hires': False,\n", - " 'hires_streamable': False,\n", - " 'position': 1,\n", - " 'created_at': 1716795946,\n", - " 'playlist_track_id': 4800399261}]}}" - ] - }, - "execution_count": 20, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "playlist_qobuz = client_qobuz.create_playlist(\n", - " \"Minim\",\n", - " description=\"A playlist created using Minim.\",\n", - " public=False\n", + " \"Minim\", description=\"A playlist created using Minim.\", public=False\n", ")\n", "client_qobuz.update_playlist(playlist_qobuz[\"id\"], public=True)\n", "client_qobuz.add_playlist_tracks(playlist_qobuz[\"id\"], track_qobuz[\"id\"])\n", - "playlist_qobuz = client_qobuz.get_playlist(playlist_qobuz[\"id\"])\n", - "playlist_qobuz[\"owner\"] = None # remove personal identifying information\n", - "playlist_qobuz" + "playlist_qobuz = client_qobuz.get_playlist(playlist_qobuz[\"id\"])" ] }, { "cell_type": "code", - "execution_count": 21, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_qobuz.delete_playlist(playlist_qobuz[\"id\"])" @@ -1500,466 +610,32 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'collaborative': False,\n", - " 'description': 'A playlist created using Minim.',\n", - " 'external_urls': {'spotify': 'https://open.spotify.com/playlist/2AUucoDJJUNxt6LMqVXfaD'},\n", - " 'followers': {'href': None, 'total': 0},\n", - " 'href': 'https://api.spotify.com/v1/playlists/2AUucoDJJUNxt6LMqVXfaD',\n", - " 'id': '2AUucoDJJUNxt6LMqVXfaD',\n", - " 'images': [{'height': None,\n", - " 'url': 'https://i.scdn.co/image/ab67616d00001e024a6c0376235e5aa44e59d2c2',\n", - " 'width': None}],\n", - " 'name': 'Minim',\n", - " 'owner': None,\n", - " 'primary_color': None,\n", - " 'public': True,\n", - " 'snapshot_id': 'AAAAAX2rci5DFConNf6qeyL9q9Vo7wd7',\n", - " 'tracks': {'href': 'https://api.spotify.com/v1/playlists/2AUucoDJJUNxt6LMqVXfaD/tracks?offset=0&limit=100',\n", - " 'items': [{'added_at': '2024-05-27T07:45:48Z',\n", - " 'added_by': None,\n", - " 'is_local': False,\n", - " 'primary_color': None,\n", - " 'track': {'preview_url': None,\n", - " 'available_markets': ['AR',\n", - " 'AU',\n", - " 'AT',\n", - " 'BE',\n", - " 'BO',\n", - " 'BR',\n", - " 'BG',\n", - " 'CA',\n", - " 'CL',\n", - " 'CO',\n", - " 'CR',\n", - " 'CY',\n", - " 'CZ',\n", - " 'DK',\n", - " 'DO',\n", - " 'DE',\n", - " 'EC',\n", - " 'EE',\n", - " 'SV',\n", - " 'FI',\n", - " 'FR',\n", - " 'GR',\n", - " 'GT',\n", - " 'HN',\n", - " 'HK',\n", - " 'HU',\n", - " 'IS',\n", - " 'IE',\n", - " 'IT',\n", - " 'LV',\n", - " 'LT',\n", - " 'LU',\n", - " 'MY',\n", - " 'MT',\n", - " 'NL',\n", - " 'NZ',\n", - " 'NI',\n", - " 'NO',\n", - " 'PA',\n", - " 'PY',\n", - " 'PE',\n", - " 'PH',\n", - " 'PL',\n", - " 'PT',\n", - " 'SG',\n", - " 'SK',\n", - " 'ES',\n", - " 'SE',\n", - " 'CH',\n", - " 'TW',\n", - " 'TR',\n", - " 'UY',\n", - " 'US',\n", - " 'GB',\n", - " 'AD',\n", - " 'LI',\n", - " 'MC',\n", - " 'ID',\n", - " 'TH',\n", - " 'VN',\n", - " 'RO',\n", - " 'IL',\n", - " 'ZA',\n", - " 'SA',\n", - " 'AE',\n", - " 'BH',\n", - " 'QA',\n", - " 'OM',\n", - " 'KW',\n", - " 'EG',\n", - " 'TN',\n", - " 'LB',\n", - " 'JO',\n", - " 'PS',\n", - " 'IN',\n", - " 'BY',\n", - " 'KZ',\n", - " 'MD',\n", - " 'UA',\n", - " 'AL',\n", - " 'BA',\n", - " 'HR',\n", - " 'ME',\n", - " 'MK',\n", - " 'RS',\n", - " 'SI',\n", - " 'KR',\n", - " 'BD',\n", - " 'PK',\n", - " 'LK',\n", - " 'GH',\n", - " 'KE',\n", - " 'NG',\n", - " 'TZ',\n", - " 'UG',\n", - " 'AG',\n", - " 'AM',\n", - " 'BS',\n", - " 'BB',\n", - " 'BZ',\n", - " 'BT',\n", - " 'BW',\n", - " 'BF',\n", - " 'CV',\n", - " 'CW',\n", - " 'DM',\n", - " 'FJ',\n", - " 'GM',\n", - " 'GD',\n", - " 'GW',\n", - " 'GY',\n", - " 'HT',\n", - " 'JM',\n", - " 'KI',\n", - " 'LS',\n", - " 'LR',\n", - " 'MW',\n", - " 'MV',\n", - " 'ML',\n", - " 'MH',\n", - " 'FM',\n", - " 'NA',\n", - " 'NR',\n", - " 'NE',\n", - " 'PW',\n", - " 'PG',\n", - " 'WS',\n", - " 'ST',\n", - " 'SN',\n", - " 'SC',\n", - " 'SL',\n", - " 'SB',\n", - " 'KN',\n", - " 'LC',\n", - " 'VC',\n", - " 'SR',\n", - " 'TL',\n", - " 'TO',\n", - " 'TT',\n", - " 'TV',\n", - " 'AZ',\n", - " 'BN',\n", - " 'BI',\n", - " 'KH',\n", - " 'CM',\n", - " 'TD',\n", - " 'KM',\n", - " 'GQ',\n", - " 'SZ',\n", - " 'GA',\n", - " 'GN',\n", - " 'KG',\n", - " 'LA',\n", - " 'MO',\n", - " 'MR',\n", - " 'MN',\n", - " 'NP',\n", - " 'RW',\n", - " 'TG',\n", - " 'UZ',\n", - " 'ZW',\n", - " 'BJ',\n", - " 'MG',\n", - " 'MU',\n", - " 'MZ',\n", - " 'AO',\n", - " 'CI',\n", - " 'DJ',\n", - " 'ZM',\n", - " 'CD',\n", - " 'CG',\n", - " 'IQ',\n", - " 'TJ',\n", - " 'VE',\n", - " 'XK'],\n", - " 'explicit': True,\n", - " 'type': 'track',\n", - " 'episode': False,\n", - " 'track': True,\n", - " 'album': {'available_markets': ['AR',\n", - " 'AU',\n", - " 'AT',\n", - " 'BE',\n", - " 'BO',\n", - " 'BR',\n", - " 'BG',\n", - " 'CA',\n", - " 'CL',\n", - " 'CO',\n", - " 'CR',\n", - " 'CY',\n", - " 'CZ',\n", - " 'DK',\n", - " 'DO',\n", - " 'DE',\n", - " 'EC',\n", - " 'EE',\n", - " 'SV',\n", - " 'FI',\n", - " 'FR',\n", - " 'GR',\n", - " 'GT',\n", - " 'HN',\n", - " 'HK',\n", - " 'HU',\n", - " 'IS',\n", - " 'IE',\n", - " 'IT',\n", - " 'LV',\n", - " 'LT',\n", - " 'LU',\n", - " 'MY',\n", - " 'MT',\n", - " 'NL',\n", - " 'NZ',\n", - " 'NI',\n", - " 'NO',\n", - " 'PA',\n", - " 'PY',\n", - " 'PE',\n", - " 'PH',\n", - " 'PL',\n", - " 'PT',\n", - " 'SG',\n", - " 'SK',\n", - " 'ES',\n", - " 'SE',\n", - " 'CH',\n", - " 'TW',\n", - " 'TR',\n", - " 'UY',\n", - " 'US',\n", - " 'GB',\n", - " 'AD',\n", - " 'LI',\n", - " 'MC',\n", - " 'ID',\n", - " 'TH',\n", - " 'VN',\n", - " 'RO',\n", - " 'IL',\n", - " 'ZA',\n", - " 'SA',\n", - " 'AE',\n", - " 'BH',\n", - " 'QA',\n", - " 'OM',\n", - " 'KW',\n", - " 'EG',\n", - " 'TN',\n", - " 'LB',\n", - " 'JO',\n", - " 'PS',\n", - " 'IN',\n", - " 'BY',\n", - " 'KZ',\n", - " 'MD',\n", - " 'UA',\n", - " 'AL',\n", - " 'BA',\n", - " 'HR',\n", - " 'ME',\n", - " 'MK',\n", - " 'RS',\n", - " 'SI',\n", - " 'KR',\n", - " 'BD',\n", - " 'PK',\n", - " 'LK',\n", - " 'GH',\n", - " 'KE',\n", - " 'NG',\n", - " 'TZ',\n", - " 'UG',\n", - " 'AG',\n", - " 'AM',\n", - " 'BS',\n", - " 'BB',\n", - " 'BZ',\n", - " 'BT',\n", - " 'BW',\n", - " 'BF',\n", - " 'CV',\n", - " 'CW',\n", - " 'DM',\n", - " 'FJ',\n", - " 'GM',\n", - " 'GD',\n", - " 'GW',\n", - " 'GY',\n", - " 'HT',\n", - " 'JM',\n", - " 'KI',\n", - " 'LS',\n", - " 'LR',\n", - " 'MW',\n", - " 'MV',\n", - " 'ML',\n", - " 'MH',\n", - " 'FM',\n", - " 'NA',\n", - " 'NR',\n", - " 'NE',\n", - " 'PW',\n", - " 'PG',\n", - " 'WS',\n", - " 'ST',\n", - " 'SN',\n", - " 'SC',\n", - " 'SL',\n", - " 'SB',\n", - " 'KN',\n", - " 'LC',\n", - " 'VC',\n", - " 'SR',\n", - " 'TL',\n", - " 'TO',\n", - " 'TT',\n", - " 'TV',\n", - " 'AZ',\n", - " 'BN',\n", - " 'BI',\n", - " 'KH',\n", - " 'CM',\n", - " 'TD',\n", - " 'KM',\n", - " 'GQ',\n", - " 'SZ',\n", - " 'GA',\n", - " 'GN',\n", - " 'KG',\n", - " 'LA',\n", - " 'MO',\n", - " 'MR',\n", - " 'MN',\n", - " 'NP',\n", - " 'RW',\n", - " 'TG',\n", - " 'UZ',\n", - " 'ZW',\n", - " 'BJ',\n", - " 'MG',\n", - " 'MU',\n", - " 'MZ',\n", - " 'AO',\n", - " 'CI',\n", - " 'DJ',\n", - " 'ZM',\n", - " 'CD',\n", - " 'CG',\n", - " 'IQ',\n", - " 'TJ',\n", - " 'VE',\n", - " 'XK'],\n", - " 'type': 'album',\n", - " 'album_type': 'album',\n", - " 'href': 'https://api.spotify.com/v1/albums/0uRFz92JmjwDbZbB7hEBIr',\n", - " 'id': '0uRFz92JmjwDbZbB7hEBIr',\n", - " 'images': [{'url': 'https://i.scdn.co/image/ab67616d0000b2734a6c0376235e5aa44e59d2c2',\n", - " 'width': 640,\n", - " 'height': 640},\n", - " {'url': 'https://i.scdn.co/image/ab67616d00001e024a6c0376235e5aa44e59d2c2',\n", - " 'width': 300,\n", - " 'height': 300},\n", - " {'url': 'https://i.scdn.co/image/ab67616d000048514a6c0376235e5aa44e59d2c2',\n", - " 'width': 64,\n", - " 'height': 64}],\n", - " 'name': 'Picture Show',\n", - " 'release_date': '2012-01-01',\n", - " 'release_date_precision': 'day',\n", - " 'uri': 'spotify:album:0uRFz92JmjwDbZbB7hEBIr',\n", - " 'artists': [{'external_urls': {'spotify': 'https://open.spotify.com/artist/0RpddSzUHfncUWNJXKOsjy'},\n", - " 'href': 'https://api.spotify.com/v1/artists/0RpddSzUHfncUWNJXKOsjy',\n", - " 'id': '0RpddSzUHfncUWNJXKOsjy',\n", - " 'name': 'Neon Trees',\n", - " 'type': 'artist',\n", - " 'uri': 'spotify:artist:0RpddSzUHfncUWNJXKOsjy'}],\n", - " 'external_urls': {'spotify': 'https://open.spotify.com/album/0uRFz92JmjwDbZbB7hEBIr'},\n", - " 'total_tracks': 11},\n", - " 'artists': [{'external_urls': {'spotify': 'https://open.spotify.com/artist/0RpddSzUHfncUWNJXKOsjy'},\n", - " 'href': 'https://api.spotify.com/v1/artists/0RpddSzUHfncUWNJXKOsjy',\n", - " 'id': '0RpddSzUHfncUWNJXKOsjy',\n", - " 'name': 'Neon Trees',\n", - " 'type': 'artist',\n", - " 'uri': 'spotify:artist:0RpddSzUHfncUWNJXKOsjy'}],\n", - " 'disc_number': 1,\n", - " 'track_number': 3,\n", - " 'duration_ms': 177280,\n", - " 'external_ids': {'isrc': 'USUM71119189'},\n", - " 'external_urls': {'spotify': 'https://open.spotify.com/track/2iUmqdfGZcHIhS3b9E9EWq'},\n", - " 'href': 'https://api.spotify.com/v1/tracks/2iUmqdfGZcHIhS3b9E9EWq',\n", - " 'id': '2iUmqdfGZcHIhS3b9E9EWq',\n", - " 'name': 'Everybody Talks',\n", - " 'popularity': 80,\n", - " 'uri': 'spotify:track:2iUmqdfGZcHIhS3b9E9EWq',\n", - " 'is_local': False},\n", - " 'video_thumbnail': {'url': None}}],\n", - " 'limit': 100,\n", - " 'next': None,\n", - " 'offset': 0,\n", - " 'previous': None,\n", - " 'total': 1},\n", - " 'type': 'playlist',\n", - " 'uri': 'spotify:playlist:2AUucoDJJUNxt6LMqVXfaD'}" - ] - }, - "execution_count": 22, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "playlist_spotify = client_spotify.create_playlist(\n", - " \"Minim\",\n", - " description=\"A playlist created using Minim.\",\n", - " public=False\n", + " \"Minim\", description=\"A playlist created using Minim.\", public=False\n", ")\n", "client_spotify.change_playlist_details(playlist_spotify[\"id\"], public=True)\n", - "client_spotify.add_playlist_items(playlist_spotify[\"id\"],\n", - " [f\"spotify:track:{track_spotify['id']}\"])\n", - "playlist_spotify = client_spotify.get_playlist(playlist_spotify[\"id\"])\n", - "# remove personal identifying information\n", - "playlist_spotify[\"owner\"] = playlist_spotify[\"tracks\"][\"items\"][0][\"added_by\"] = None\n", - "playlist_spotify" + "client_spotify.add_playlist_items(\n", + " playlist_spotify[\"id\"], [f\"spotify:track:{track_spotify['id']}\"]\n", + ")\n", + "playlist_spotify = client_spotify.get_playlist(playlist_spotify[\"id\"])" ] }, { "cell_type": "code", - "execution_count": 23, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_spotify.unfollow_playlist(playlist_spotify[\"id\"])" @@ -1974,73 +650,41 @@ }, { "cell_type": "code", - "execution_count": 24, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'playlist': {'uuid': 'dff69073-b51d-42e9-9539-08958ffeade1',\n", - " 'type': 'USER',\n", - " 'creator': None,\n", - " 'contentBehavior': 'UNRESTRICTED',\n", - " 'sharingLevel': 'PUBLIC',\n", - " 'status': 'READY',\n", - " 'source': 'DEFAULT',\n", - " 'title': 'Minim',\n", - " 'description': 'A playlist created using Minim.',\n", - " 'image': 'ddd25f62-cd42-4555-9dd8-e1e030b42c92',\n", - " 'squareImage': 'b87dda6e-612c-460c-994e-759e153b905e',\n", - " 'url': 'http://www.tidal.com/playlist/dff69073-b51d-42e9-9539-08958ffeade1',\n", - " 'created': '2024-05-27T07:45:48.572+0000',\n", - " 'lastUpdated': '2024-05-27T07:45:48.970+0000',\n", - " 'lastItemAddedAt': '2024-05-27T07:45:48.970+0000',\n", - " 'duration': 177,\n", - " 'numberOfTracks': 1,\n", - " 'numberOfVideos': 0,\n", - " 'promotedArtists': [],\n", - " 'trn': 'trn:playlist:dff69073-b51d-42e9-9539-08958ffeade1'},\n", - " 'followInfo': {'nrOfFollowers': 0,\n", - " 'tidalResourceName': 'trn:playlist:dff69073-b51d-42e9-9539-08958ffeade1',\n", - " 'followed': True,\n", - " 'followType': 'PLAYLIST'},\n", - " 'profile': None}" - ] - }, - "execution_count": 24, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "playlist_tidal_private = client_tidal_private.create_playlist(\n", - " \"Minim\",\n", - " description=\"A playlist created using Minim.\",\n", - " public=False\n", + " \"Minim\", description=\"A playlist created using Minim.\", public=False\n", + ")\n", + "client_tidal_private.set_playlist_privacy(\n", + " playlist_tidal_private[\"data\"][\"uuid\"], True\n", + ")\n", + "client_tidal_private.add_playlist_items(\n", + " playlist_tidal_private[\"data\"][\"uuid\"], track_tidal_private[\"id\"]\n", ")\n", - "client_tidal_private.set_playlist_privacy(playlist_tidal_private[\"data\"][\"uuid\"],\n", - " True)\n", - "client_tidal_private.add_playlist_items(playlist_tidal_private[\"data\"][\"uuid\"],\n", - " track_tidal_private[\"id\"])\n", "playlist_tidal_private = client_tidal_private.get_user_playlist(\n", " playlist_tidal_private[\"data\"][\"uuid\"]\n", - ")\n", - "# remove personal identifying information\n", - "playlist_tidal_private[\"playlist\"][\"creator\"] = playlist_tidal_private[\"profile\"] = None\n", - "playlist_tidal_private" + ")" ] }, { "cell_type": "code", - "execution_count": 25, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ - "client_tidal_private.delete_playlist(playlist_tidal_private[\"playlist\"][\"uuid\"])" + "client_tidal_private.delete_playlist(\n", + " playlist_tidal_private[\"playlist\"][\"uuid\"]\n", + ")" ] }, { @@ -2052,12 +696,19 @@ }, { "cell_type": "code", - "execution_count": 26, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from pathlib import Path\n", - "from minim.audio import Audio, FLACAudio, MP3Audio, MP4Audio, OggAudio, WAVEAudio" + "from minim.audio import (\n", + " Audio,\n", + " FLACAudio,\n", + " MP3Audio,\n", + " MP4Audio,\n", + " OggAudio,\n", + " WAVEAudio,\n", + ")" ] }, { @@ -2075,7 +726,7 @@ }, { "cell_type": "code", - "execution_count": 27, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -2103,20 +754,9 @@ }, { "cell_type": "code", - "execution_count": 28, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "minim.audio.WAVEAudio" - ] - }, - "execution_count": 28, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "type(middle_c)" ] @@ -2130,22 +770,9 @@ }, { "cell_type": "code", - "execution_count": 29, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Title: Middle C\n", - "Album: Minim\n", - "Artist: Square Wave\n", - "Genre: Game\n", - "Codec: lpcm\n", - "Bit depth: 24\n" - ] - } - ], + "outputs": [], "source": [ "for attr in [\"title\", \"album\", \"artist\", \"genre\", \"codec\", \"bit_depth\"]:\n", " print(f\"{attr.capitalize().replace('_', ' ')}: {getattr(middle_c, attr)}\")" @@ -2173,21 +800,13 @@ }, { "cell_type": "code", - "execution_count": 30, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "size= 116kB time=00:00:01.02 bitrate= 930.3kbits/s speed= 135x \n" - ] - } - ], + "outputs": [], "source": [ "middle_c.convert(\"alac\", filename=\"middle_c_alac\")" ] @@ -2201,42 +820,18 @@ }, { "cell_type": "code", - "execution_count": 31, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "minim.audio.MP4Audio" - ] - }, - "execution_count": 31, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "type(middle_c)" ] }, { "cell_type": "code", - "execution_count": 32, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Title: Middle C\n", - "Album: Minim\n", - "Artist: Square Wave\n", - "Genre: Game\n", - "Codec: alac\n", - "Bit depth: 24\n" - ] - } - ], + "outputs": [], "source": [ "for attr in [\"title\", \"album\", \"artist\", \"genre\", \"codec\", \"bit_depth\"]:\n", " print(f\"{attr.capitalize().replace('_', ' ')}: {getattr(middle_c, attr)}\")" @@ -2244,7 +839,7 @@ }, { "cell_type": "code", - "execution_count": 35, + "execution_count": null, "metadata": { "tags": [ "remove-cell" @@ -2258,7 +853,7 @@ ], "metadata": { "kernelspec": { - "display_name": "base", + "display_name": "minim", "language": "python", "name": "python3" }, @@ -2272,7 +867,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.8" + "version": "3.13.12" } }, "nbformat": 4, diff --git a/docs/source/notebooks/user_guide/editing_audio_metadata.ipynb b/docs/source/notebooks/user_guide/editing_audio_metadata.ipynb index 39d0ab36..0e92100e 100644 --- a/docs/source/notebooks/user_guide/editing_audio_metadata.ipynb +++ b/docs/source/notebooks/user_guide/editing_audio_metadata.ipynb @@ -13,7 +13,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -36,11 +36,23 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "client_itunes = itunes.SearchAPI()\n", + "client_itunes = itunes.SearchAPI()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, + "outputs": [], + "source": [ "client_spotify = spotify.WebAPI()\n", "client_tidal = tidal.PrivateAPI()" ] @@ -56,13 +68,15 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "audio_files = [f for f in (Path().resolve().parents[3]\n", - " / \"tests/data/previews\").glob(\"**/*\")\n", - " if f.suffix == \".flac\"]" + "audio_files = [\n", + " f\n", + " for f in (Path().resolve().parents[3] / \"tests/data/previews\").glob(\"**/*\")\n", + " if f.suffix == \".flac\"\n", + "]" ] }, { @@ -76,7 +90,7 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -86,8 +100,11 @@ " if field in {\"artwork\", \"lyrics\"}:\n", " if value:\n", " value = type(value)\n", - " field = (field.upper() if field == \"isrc\"\n", - " else field.replace(\"_\", \" \").capitalize())\n", + " field = (\n", + " field.upper()\n", + " if field == \"isrc\"\n", + " else field.replace(\"_\", \" \").capitalize()\n", + " )\n", " print(f\"{field}: {value}\")" ] }, @@ -109,22 +126,13 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "('spektrem_shine.flac', )" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "audio_file = audio.Audio(audio_files[0], pattern=(\"(.*)_(.*)\", (\"artist\", \"title\")))\n", + "outputs": [], + "source": [ + "audio_file = audio.Audio(\n", + " audio_files[0], pattern=(\"(.*)_(.*)\", (\"artist\", \"title\"))\n", + ")\n", "audio_files[0].name, audio_file" ] }, @@ -137,43 +145,13 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Album: None\n", - "Album artist: None\n", - "Artist: spektrem\n", - "Comment: None\n", - "Composer: None\n", - "Copyright: None\n", - "Date: None\n", - "Genre: None\n", - "ISRC: None\n", - "Lyrics: None\n", - "Tempo: None\n", - "Title: shine\n", - "Compilation: None\n", - "Disc number: None\n", - "Disc count: None\n", - "Track number: None\n", - "Track count: None\n", - "Artwork: None\n", - "Bit depth: 16\n", - "Bitrate: 1030107\n", - "Channel count: 2\n", - "Codec: flac\n", - "Sample rate: 44100\n" - ] - } - ], + "outputs": [], "source": [ "print_metadata(audio_file)" ] @@ -189,27 +167,9 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "size= 1032kB time=00:00:30.09 bitrate= 280.9kbits/s speed=67.7x \n" - ] - }, - { - "data": { - "text/plain": [ - "" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "audio_file.convert(\"mp3\")\n", "audio_file" @@ -224,43 +184,13 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Album: None\n", - "Album artist: None\n", - "Artist: spektrem\n", - "Comment: None\n", - "Compilation: None\n", - "Composer: None\n", - "Copyright: None\n", - "Date: None\n", - "Genre: None\n", - "ISRC: None\n", - "Lyrics: None\n", - "Tempo: None\n", - "Title: shine\n", - "Disc number: None\n", - "Disc count: None\n", - "Track number: None\n", - "Track count: None\n", - "Artwork: None\n", - "Bit depth: None\n", - "Bitrate: 280593\n", - "Channel count: 2\n", - "Codec: mp3\n", - "Sample rate: 44100\n" - ] - } - ], + "outputs": [], "source": [ "print_metadata(audio_file)" ] @@ -282,43 +212,13 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Album: Enter the Spektrem - Single\n", - "Album artist: Spektrem\n", - "Artist: Spektrem\n", - "Comment: None\n", - "Compilation: False\n", - "Composer: None\n", - "Copyright: ℗ 2013 GFTED\n", - "Date: 2013-03-06T12:00:00Z\n", - "Genre: Electronic\n", - "ISRC: None\n", - "Lyrics: None\n", - "Tempo: None\n", - "Title: Shine\n", - "Disc number: 1\n", - "Disc count: 1\n", - "Track number: 2\n", - "Track count: 3\n", - "Artwork: \n", - "Bit depth: None\n", - "Bitrate: 280593\n", - "Channel count: 2\n", - "Codec: mp3\n", - "Sample rate: 44100\n" - ] - } - ], + "outputs": [], "source": [ "query = f\"{audio_file.artist} {audio_file.title}\".lower()\n", "itunes_results = client_itunes.search(query)[\"results\"]\n", @@ -326,14 +226,17 @@ " np.argmax(\n", " utility.levenshtein_ratio(\n", " query,\n", - " [f\"{r['artistName']} {r['trackName']}\".lower()\n", - " for r in itunes_results]\n", + " [\n", + " f\"{r['artistName']} {r['trackName']}\".lower()\n", + " for r in itunes_results\n", + " ],\n", " )\n", " )\n", "]\n", "itunes_album = client_itunes.lookup(itunes_track[\"collectionId\"])[\"results\"][0]\n", - "audio_file.set_metadata_using_itunes(itunes_track, album_data=itunes_album,\n", - " overwrite=True)\n", + "audio_file.set_metadata_using_itunes(\n", + " itunes_track, album_data=itunes_album, overwrite=True\n", + ")\n", "print_metadata(audio_file)" ] }, @@ -359,59 +262,32 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Album: Enter the Spektrem - Single\n", - "Album artist: Spektrem\n", - "Artist: Spektrem\n", - "Comment: None\n", - "Compilation: False\n", - "Composer: None\n", - "Copyright: ℗ 2013 GFTED\n", - "Date: 2013-03-06T12:00:00Z\n", - "Genre: Electronic\n", - "ISRC: GB2LD0901581\n", - "Lyrics: None\n", - "Tempo: 128\n", - "Title: Shine\n", - "Disc number: 1\n", - "Disc count: 1\n", - "Track number: 2\n", - "Track count: 3\n", - "Artwork: \n", - "Bit depth: None\n", - "Bitrate: 280593\n", - "Channel count: 2\n", - "Codec: mp3\n", - "Sample rate: 44100\n" - ] - } - ], + "outputs": [], "source": [ "spotify_results = client_spotify.search(query, type=\"track\")[\"items\"]\n", "spotify_track = spotify_results[\n", " np.argmax(\n", " utility.levenshtein_ratio(\n", " query,\n", - " [f\"{r['artists'][0]['name']} {r['name']}\".lower()\n", - " for r in spotify_results]\n", + " [\n", + " f\"{r['artists'][0]['name']} {r['name']}\".lower()\n", + " for r in spotify_results\n", + " ],\n", " )\n", " )\n", "]\n", "audio_file.set_metadata_using_spotify(\n", " spotify_track,\n", - " audio_features=client_spotify.get_track_audio_features(spotify_track[\"id\"])\n", - ")\n", - "print_metadata(audio_file)" + " audio_features=client_spotify.get_track_audio_features(\n", + " spotify_track[\"id\"]\n", + " ),\n", + ")" ] }, { @@ -428,49 +304,20 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": null, "metadata": { "tags": [ - "hide-output" + "skip-execution" ] }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Album: Enter the Spektrem - Single\n", - "Album artist: Spektrem\n", - "Artist: Spektrem\n", - "Comment: None\n", - "Compilation: False\n", - "Composer: None\n", - "Copyright: ℗ 2013 GFTED\n", - "Date: 2013-03-06T12:00:00Z\n", - "Genre: Electronic\n", - "ISRC: GB2LD0901581\n", - "Lyrics: \n", - "Tempo: 128\n", - "Title: Shine\n", - "Disc number: 1\n", - "Disc count: 1\n", - "Track number: 2\n", - "Track count: 3\n", - "Artwork: \n", - "Bit depth: None\n", - "Bitrate: 280593\n", - "Channel count: 2\n", - "Codec: mp3\n", - "Sample rate: 44100\n" - ] - } - ], + "outputs": [], "source": [ "tidal_results = client_tidal.search(query)[\"tracks\"][\"items\"]\n", - "tidal_track = next((r for r in tidal_results if r[\"isrc\"] == audio_file.isrc), None)\n", + "tidal_track = next(\n", + " (r for r in tidal_results if r[\"isrc\"] == audio_file.isrc), None\n", + ")\n", "tidal_composers = client_tidal.get_track_composers(tidal_track[\"id\"])\n", - "audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers)\n", - "print_metadata(audio_file)" + "audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers)" ] }, { @@ -484,7 +331,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -493,7 +340,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": null, "metadata": { "tags": [ "remove-cell" @@ -515,20 +362,9 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "('tobu_back_to_you.flac', )" - ] - }, - "execution_count": 14, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "audio_file = audio.FLACAudio(audio_files[1])\n", "audio_files[1].name, audio_file" @@ -536,7 +372,7 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": null, "metadata": { "tags": [ "remove-cell" @@ -558,43 +394,13 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Album: Back To You - Single\n", - "Album artist: Tobu\n", - "Artist: Tobu\n", - "Comment: None\n", - "Composer: Tobu & Toms Burkovskis\n", - "Copyright: 2022 NCS 2022 NCS\n", - "Date: 2023-07-06T07:00:00Z\n", - "Genre: House\n", - "ISRC: GB2LD2210368\n", - "Lyrics: None\n", - "Tempo: None\n", - "Title: Back To You\n", - "Compilation: None\n", - "Disc number: 1\n", - "Disc count: 1\n", - "Track number: 1\n", - "Track count: 1\n", - "Artwork: \n", - "Bit depth: 16\n", - "Bitrate: 1104053\n", - "Channel count: 2\n", - "Codec: flac\n", - "Sample rate: 44100\n" - ] - } - ], + "outputs": [], "source": [ "print_metadata(audio_file)" ] @@ -608,49 +414,68 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ "query = f\"{audio_file.artist} {audio_file.title}\".lower()\n", "\n", "# iTunes Search API\n", - "itunes_results = client_itunes.search(query)[\"results\"]\n", + "itunes_results = client_itunes.search(query, media=\"music\")[\"results\"]\n", "itunes_track = itunes_results[\n", " np.argmax(\n", " utility.levenshtein_ratio(\n", " query,\n", - " [f\"{r['artistName']} {r['trackName']}\".lower()\n", - " for r in itunes_results]\n", + " [\n", + " f\"{r['artistName']} {r.get('trackName', '')}\".lower()\n", + " for r in itunes_results\n", + " ],\n", " )\n", " )\n", "]\n", "itunes_album = client_itunes.lookup(itunes_track[\"collectionId\"])[\"results\"][0]\n", - "audio_file.set_metadata_using_itunes(itunes_track, album_data=itunes_album,\n", - " overwrite=True)\n", - "\n", + "audio_file.set_metadata_using_itunes(\n", + " itunes_track, album_data=itunes_album, overwrite=True\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, + "outputs": [], + "source": [ "# Spotify Web API\n", "spotify_results = client_spotify.search(query, type=\"track\")[\"items\"]\n", "spotify_track = spotify_results[\n", " np.argmax(\n", " utility.levenshtein_ratio(\n", " query,\n", - " [f\"{r['artists'][0]['name']} {r['name']}\".lower()\n", - " for r in spotify_results]\n", + " [\n", + " f\"{r['artists'][0]['name']} {r['name']}\".lower()\n", + " for r in spotify_results\n", + " ],\n", " )\n", " )\n", "]\n", "audio_file.set_metadata_using_spotify(\n", " spotify_track,\n", - " audio_features=client_spotify.get_track_audio_features(spotify_track[\"id\"])\n", + " audio_features=client_spotify.get_track_audio_features(\n", + " spotify_track[\"id\"]\n", + " ),\n", ")\n", "\n", "# Private TIDAL API\n", "tidal_results = client_tidal.search(query)[\"tracks\"][\"items\"]\n", - "tidal_track = next((r for r in tidal_results if r[\"isrc\"] == audio_file.isrc),\n", - " None)\n", + "tidal_track = next(\n", + " (r for r in tidal_results if r[\"isrc\"] == audio_file.isrc), None\n", + ")\n", "tidal_composers = client_tidal.get_track_composers(tidal_track[\"id\"])\n", - "audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers)" + "audio_file.set_metadata_using_tidal(tidal_track, composers=tidal_composers)\n" ] }, { @@ -662,43 +487,13 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": null, "metadata": { "tags": [ "hide-output" ] }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Album: Back to You - Single\n", - "Album artist: Tobu\n", - "Artist: Tobu\n", - "Comment: None\n", - "Composer: Tobu & Toms Burkovskis\n", - "Copyright: ℗ 2022 NCS\n", - "Date: 2022-11-25T12:00:00Z\n", - "Genre: House\n", - "ISRC: GB2LD2210368\n", - "Lyrics: \n", - "Tempo: 98\n", - "Title: Back to You\n", - "Compilation: False\n", - "Disc number: 1\n", - "Disc count: 1\n", - "Track number: 1\n", - "Track count: 1\n", - "Artwork: \n", - "Bit depth: 16\n", - "Bitrate: 1104053\n", - "Channel count: 2\n", - "Codec: flac\n", - "Sample rate: 44100\n" - ] - } - ], + "outputs": [], "source": [ "print_metadata(audio_file)" ] @@ -714,7 +509,7 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -723,7 +518,7 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": null, "metadata": { "tags": [ "remove-cell" @@ -751,7 +546,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.6" + "version": "3.13.12" } }, "nbformat": 4, diff --git a/docs/source/notebooks/user_guide/getting_recommendations.ipynb b/docs/source/notebooks/user_guide/getting_recommendations.ipynb index 8c6cbbcc..b32e04f8 100644 --- a/docs/source/notebooks/user_guide/getting_recommendations.ipynb +++ b/docs/source/notebooks/user_guide/getting_recommendations.ipynb @@ -35,7 +35,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "from base64 import b64encode\n", @@ -62,7 +66,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_spotify = spotify.WebAPI()" @@ -90,18 +98,22 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "seed_tracks = [\n", - " \"0JZ9TvOLtZJaGqIyC4hYZX\", # Avicii - Trouble\n", - " \"0bmB3nzQuHBfI6nM4SETVu\", # Cash Cash - Surrender\n", - " \"1PQ8ywTy9V2iVZWJ7Gyxxb\", # Mako - Our Story\n", - " \"70IFLb5egLA8WUFWgxBoRz\", # Mike Williams - Fallin' In\n", - " \"6jSPbxZLd2yemJTjz2gqOT\", # Passion Pit & Galantis - I Found U\n", - " \"76B6LjxTolaSGXLANjNndR\", # Sick Individuals - Made for This\n", - " \"2V65y3PX4DkRhy1djlxd9p\", # Swedish House Mafia - Don't You Worry Child (feat. John Martin)\n", - " \"1gpF8IwQQj8qOeVjHfIIDU\" # Zedd - Find You (feat. Matthew Koma & Miriam Bryant)\n", + " \"0JZ9TvOLtZJaGqIyC4hYZX\", # Avicii - Trouble\n", + " \"0bmB3nzQuHBfI6nM4SETVu\", # Cash Cash - Surrender\n", + " \"1PQ8ywTy9V2iVZWJ7Gyxxb\", # Mako - Our Story\n", + " \"70IFLb5egLA8WUFWgxBoRz\", # Mike Williams - Fallin' In\n", + " \"6jSPbxZLd2yemJTjz2gqOT\", # Passion Pit & Galantis - I Found U\n", + " \"76B6LjxTolaSGXLANjNndR\", # Sick Individuals - Made for This\n", + " \"2V65y3PX4DkRhy1djlxd9p\", # Swedish House Mafia - Don't You Worry Child (feat. John Martin)\n", + " \"1gpF8IwQQj8qOeVjHfIIDU\", # Zedd - Find You (feat. Matthew Koma & Miriam Bryant)\n", "]" ] }, @@ -115,7 +127,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "recommended_tracks = client_spotify.get_recommendations(\n", @@ -154,15 +170,26 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "grid = GridspecLayout(len(recommended_tracks), 1)\n", "for i, track in enumerate(recommended_tracks):\n", " out = Output()\n", " with out:\n", - " display(IFrame(f\"https://open.spotify.com/embed/track/{track['id']}\", \n", - " frameBorder=0, loading=\"lazy\", height=152, width=510))\n", + " display(\n", + " IFrame(\n", + " f\"https://open.spotify.com/embed/track/{track['id']}\",\n", + " frameBorder=0,\n", + " loading=\"lazy\",\n", + " height=152,\n", + " width=510,\n", + " )\n", + " )\n", " grid[*divmod(i, 1)] = out\n", "grid" ] @@ -183,7 +210,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_tidal = tidal.API()" @@ -199,18 +230,22 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "favorite_tracks = [\n", - " 51073951, # Avicii - Trouble\n", - " 62082351, # Cash Cash - Surrender\n", - " 32553484, # Mako - Our Story\n", + " 51073951, # Avicii - Trouble\n", + " 62082351, # Cash Cash - Surrender\n", + " 32553484, # Mako - Our Story\n", " 147258423, # Mike Williams - Fallin' In\n", " 109273852, # Passion Pit & Galantis - I Found U\n", " 237059212, # Sick Individuals - Made for This\n", - " 17271290, # Swedish House Mafia - Don't You Worry Child (feat. John Martin)\n", - " 27171015 # Zedd - Find You (feat. Matthew Koma & Miriam Bryant)\n", + " 17271290, # Swedish House Mafia - Don't You Worry Child (feat. John Martin)\n", + " 27171015, # Zedd - Find You (feat. Matthew Koma & Miriam Bryant)\n", "]" ] }, @@ -224,11 +259,16 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ - "similar_tracks = client_tidal.get_similar_tracks(random.choice(favorite_tracks), \n", - " \"US\")[\"data\"]" + "similar_tracks = client_tidal.get_similar_tracks(\n", + " random.choice(favorite_tracks), \"US\"\n", + ")[\"data\"]" ] }, { @@ -241,7 +281,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "grid = GridspecLayout(len(similar_tracks) // 2, 2)\n", @@ -249,15 +293,17 @@ " out = Output()\n", " with out:\n", " display(\n", - " HTML('
'\n", - " '
')\n", + " HTML(\n", + " '
'\n", + " '
\"\n", + " )\n", " )\n", " grid[*divmod(i, 2)] = out\n", "grid" diff --git a/docs/source/notebooks/user_guide/transferring_music_libraries.ipynb b/docs/source/notebooks/user_guide/transferring_music_libraries.ipynb index 71b63d4f..85aaf5d7 100644 --- a/docs/source/notebooks/user_guide/transferring_music_libraries.ipynb +++ b/docs/source/notebooks/user_guide/transferring_music_libraries.ipynb @@ -14,7 +14,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "from minim import qobuz, spotify, tidal" @@ -32,13 +36,19 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "client_qobuz = qobuz.PrivateAPI(flow=\"password\", browser=True)\n", - "client_spotify = spotify.WebAPI(flow=\"pkce\",\n", - " scopes=spotify.WebAPI.get_scopes(\"all\"),\n", - " web_framework=\"http.server\")\n", + "client_spotify = spotify.WebAPI(\n", + " flow=\"pkce\",\n", + " scopes=spotify.WebAPI.get_scopes(\"all\"),\n", + " web_framework=\"http.server\",\n", + ")\n", "client_tidal = tidal.PrivateAPI(flow=\"device_code\", browser=True)" ] }, @@ -70,7 +80,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "QOBUZ_PLAYLIST_ID = 17865119" @@ -86,7 +100,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "qobuz_playlist = client_qobuz.get_playlist(QOBUZ_PLAYLIST_ID)" @@ -104,7 +122,11 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "new_spotify_playlist = client_spotify.create_playlist(\n", @@ -124,13 +146,19 @@ }, { "cell_type": "code", - "execution_count": 6, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "spotify_track_uris = []\n", "for qobuz_track in qobuz_playlist[\"tracks\"][\"items\"]:\n", - " spotify_track = client_spotify.search(f'isrc:{qobuz_track[\"isrc\"]}', type=\"track\", limit=1)[\"items\"][0]\n", + " spotify_track = client_spotify.search(\n", + " f\"isrc:{qobuz_track['isrc']}\", type=\"track\", limit=1\n", + " )[\"items\"][0]\n", " spotify_track_uris.append(f\"spotify:track:{spotify_track['id']}\")" ] }, @@ -143,24 +171,17 @@ }, { "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [], - "source": [ - "client_spotify.add_playlist_items(new_spotify_playlist[\"id\"], spotify_track_uris)" - ] - }, - { - "cell_type": "code", - "execution_count": 8, + "execution_count": null, "metadata": { "tags": [ - "remove-cell" + "skip-execution" ] }, "outputs": [], "source": [ - "client_spotify.unfollow_playlist(new_spotify_playlist[\"id\"])" + "client_spotify.add_playlist_items(\n", + " new_spotify_playlist[\"id\"], spotify_track_uris\n", + ")" ] }, { @@ -174,14 +195,18 @@ }, { "cell_type": "code", - "execution_count": 9, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "new_tidal_playlist = client_tidal.create_playlist(\n", " qobuz_playlist[\"name\"],\n", " description=qobuz_playlist[\"description\"],\n", - " public=qobuz_playlist[\"is_public\"]\n", + " public=qobuz_playlist[\"is_public\"],\n", ")" ] }, @@ -194,19 +219,21 @@ }, { "cell_type": "code", - "execution_count": 10, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "tidal_track_ids = []\n", "for qobuz_track in qobuz_playlist[\"tracks\"][\"items\"]:\n", " title = qobuz_track[\"title\"]\n", " if qobuz_track[\"version\"]:\n", - " title += f' {qobuz_track[\"version\"]}'\n", + " title += f\" {qobuz_track['version']}\"\n", " tidal_track = client_tidal.search(\n", - " f'{qobuz_track[\"performer\"][\"name\"]} {title}',\n", - " type=\"track\",\n", - " limit=1\n", + " f\"{qobuz_track['performer']['name']} {title}\", type=\"track\", limit=1\n", " )[\"items\"][0]\n", " if qobuz_track[\"isrc\"] == tidal_track[\"isrc\"]:\n", " tidal_track_ids.append(tidal_track[\"id\"])" @@ -221,24 +248,17 @@ }, { "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [], - "source": [ - "client_tidal.add_playlist_items(new_tidal_playlist[\"data\"][\"uuid\"], tidal_track_ids)" - ] - }, - { - "cell_type": "code", - "execution_count": 12, + "execution_count": null, "metadata": { "tags": [ - "remove-cell" + "skip-execution" ] }, "outputs": [], "source": [ - "client_tidal.delete_playlist(new_tidal_playlist[\"data\"][\"uuid\"])" + "client_tidal.add_playlist_items(\n", + " new_tidal_playlist[\"data\"][\"uuid\"], tidal_track_ids\n", + ")" ] }, { @@ -252,8 +272,12 @@ }, { "cell_type": "code", - "execution_count": 13, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "SPOTIFY_PLAYLIST_ID = \"3rw9qY60CEh6dfJauWdxMh\"" @@ -268,8 +292,12 @@ }, { "cell_type": "code", - "execution_count": 14, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "spotify_playlist = client_spotify.get_playlist(SPOTIFY_PLAYLIST_ID)" @@ -286,8 +314,12 @@ }, { "cell_type": "code", - "execution_count": 15, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "new_qobuz_playlist = client_qobuz.create_playlist(\n", @@ -307,15 +339,18 @@ }, { "cell_type": "code", - "execution_count": 16, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "qobuz_track_ids = []\n", "for spotify_track in spotify_playlist[\"tracks\"][\"items\"]:\n", " qobuz_track = client_qobuz.search(\n", - " spotify_track[\"track\"][\"external_ids\"][\"isrc\"],\n", - " limit=1\n", + " spotify_track[\"track\"][\"external_ids\"][\"isrc\"], limit=1\n", " )[\"tracks\"][\"items\"][0]\n", " qobuz_track_ids.append(qobuz_track[\"id\"])" ] @@ -329,50 +364,15 @@ }, { "cell_type": "code", - "execution_count": 17, - "metadata": { - "tags": [ - "remove-output" - ] - }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'id': 21738651,\n", - " 'name': 'Minim Example',\n", - " 'description': 'Moving playlists between music services.',\n", - " 'tracks_count': 5,\n", - " 'users_count': 0,\n", - " 'duration': 1056,\n", - " 'public_at': 1716156000,\n", - " 'created_at': 1716183363,\n", - " 'updated_at': 1716183364,\n", - " 'is_public': True,\n", - " 'is_collaborative': False,\n", - " 'owner': {'id': 3060762, 'name': 'foreign arcanine'}}" - ] - }, - "execution_count": 17, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "client_qobuz.add_playlist_tracks(new_qobuz_playlist[\"id\"], qobuz_track_ids)" - ] - }, - { - "cell_type": "code", - "execution_count": 18, + "execution_count": null, "metadata": { "tags": [ - "remove-cell" + "skip-execution" ] }, "outputs": [], "source": [ - "client_qobuz.delete_playlist(new_qobuz_playlist[\"id\"])" + "client_qobuz.add_playlist_tracks(new_qobuz_playlist[\"id\"], qobuz_track_ids)" ] }, { @@ -386,14 +386,18 @@ }, { "cell_type": "code", - "execution_count": 19, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "new_tidal_playlist = client_tidal.create_playlist(\n", " spotify_playlist[\"name\"],\n", " description=spotify_playlist[\"description\"],\n", - " public=spotify_playlist[\"public\"]\n", + " public=spotify_playlist[\"public\"],\n", ")" ] }, @@ -406,17 +410,21 @@ }, { "cell_type": "code", - "execution_count": 20, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "tidal_track_ids = []\n", "for spotify_track in spotify_playlist[\"tracks\"][\"items\"]:\n", " tidal_track = client_tidal.search(\n", - " f'{spotify_track[\"track\"][\"artists\"][0][\"name\"]} '\n", - " f'{spotify_track[\"track\"][\"name\"]}',\n", + " f\"{spotify_track['track']['artists'][0]['name']} \"\n", + " f\"{spotify_track['track']['name']}\",\n", " type=\"track\",\n", - " limit=1\n", + " limit=1,\n", " )[\"items\"][0]\n", " if spotify_track[\"track\"][\"external_ids\"][\"isrc\"] == tidal_track[\"isrc\"]:\n", " tidal_track_ids.append(tidal_track[\"id\"])" @@ -431,24 +439,17 @@ }, { "cell_type": "code", - "execution_count": 21, - "metadata": {}, - "outputs": [], - "source": [ - "client_tidal.add_playlist_items(new_tidal_playlist[\"data\"][\"uuid\"], tidal_track_ids)" - ] - }, - { - "cell_type": "code", - "execution_count": 22, + "execution_count": null, "metadata": { "tags": [ - "remove-cell" + "skip-execution" ] }, "outputs": [], "source": [ - "client_tidal.delete_playlist(new_tidal_playlist[\"data\"][\"uuid\"])" + "client_tidal.add_playlist_items(\n", + " new_tidal_playlist[\"data\"][\"uuid\"], tidal_track_ids\n", + ")" ] }, { @@ -462,8 +463,12 @@ }, { "cell_type": "code", - "execution_count": 23, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "TIDAL_PLAYLIST_UUID = \"40052e73-58d4-4abb-bc1c-abace76d2f15\"" @@ -478,12 +483,18 @@ }, { "cell_type": "code", - "execution_count": 24, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "tidal_playlist = client_tidal.get_user_playlist(TIDAL_PLAYLIST_UUID)\n", - "tidal_playlist_items = client_tidal.get_playlist_items(TIDAL_PLAYLIST_UUID)[\"items\"]" + "tidal_playlist_items = client_tidal.get_playlist_items(TIDAL_PLAYLIST_UUID)[\n", + " \"items\"\n", + "]" ] }, { @@ -497,8 +508,12 @@ }, { "cell_type": "code", - "execution_count": 25, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "new_qobuz_playlist = client_qobuz.create_playlist(\n", @@ -518,16 +533,19 @@ }, { "cell_type": "code", - "execution_count": 26, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "qobuz_track_ids = []\n", "for tidal_track in tidal_playlist_items:\n", - " qobuz_track = client_qobuz.search(\n", - " tidal_track[\"item\"][\"isrc\"],\n", - " limit=1\n", - " )[\"tracks\"][\"items\"][0]\n", + " qobuz_track = client_qobuz.search(tidal_track[\"item\"][\"isrc\"], limit=1)[\n", + " \"tracks\"\n", + " ][\"items\"][0]\n", " qobuz_track_ids.append(qobuz_track[\"id\"])" ] }, @@ -540,50 +558,15 @@ }, { "cell_type": "code", - "execution_count": 27, - "metadata": { - "tags": [ - "remove-output" - ] - }, - "outputs": [ - { - "data": { - "text/plain": [ - "{'id': 21738652,\n", - " 'name': 'Minim Example',\n", - " 'description': 'Moving playlists between music services.',\n", - " 'tracks_count': 5,\n", - " 'users_count': 0,\n", - " 'duration': 1056,\n", - " 'public_at': 1716156000,\n", - " 'created_at': 1716183367,\n", - " 'updated_at': 1716183368,\n", - " 'is_public': True,\n", - " 'is_collaborative': False,\n", - " 'owner': {'id': 3060762, 'name': 'foreign arcanine'}}" - ] - }, - "execution_count": 27, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "client_qobuz.add_playlist_tracks(new_qobuz_playlist[\"id\"], qobuz_track_ids)" - ] - }, - { - "cell_type": "code", - "execution_count": 28, + "execution_count": null, "metadata": { "tags": [ - "remove-cell" + "skip-execution" ] }, "outputs": [], "source": [ - "client_qobuz.delete_playlist(new_qobuz_playlist[\"id\"])" + "client_qobuz.add_playlist_tracks(new_qobuz_playlist[\"id\"], qobuz_track_ids)" ] }, { @@ -597,8 +580,12 @@ }, { "cell_type": "code", - "execution_count": 29, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "new_spotify_playlist = client_spotify.create_playlist(\n", @@ -618,14 +605,19 @@ }, { "cell_type": "code", - "execution_count": 30, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "spotify_track_uris = []\n", "for tidal_track in tidal_playlist_items:\n", - " spotify_track = client_spotify.search(f'isrc:{tidal_track[\"item\"][\"isrc\"]}',\n", - " type=\"track\", limit=1)[\"items\"][0]\n", + " spotify_track = client_spotify.search(\n", + " f\"isrc:{tidal_track['item']['isrc']}\", type=\"track\", limit=1\n", + " )[\"items\"][0]\n", " spotify_track_uris.append(f\"spotify:track:{spotify_track['id']}\")" ] }, @@ -638,25 +630,17 @@ }, { "cell_type": "code", - "execution_count": 31, - "metadata": {}, - "outputs": [], - "source": [ - "client_spotify.add_playlist_items(new_spotify_playlist[\"id\"],\n", - " spotify_track_uris)" - ] - }, - { - "cell_type": "code", - "execution_count": 32, + "execution_count": null, "metadata": { "tags": [ - "remove-cell" + "skip-execution" ] }, "outputs": [], "source": [ - "client_spotify.unfollow_playlist(new_spotify_playlist[\"id\"])" + "client_spotify.add_playlist_items(\n", + " new_spotify_playlist[\"id\"], spotify_track_uris\n", + ")" ] }, { @@ -674,32 +658,19 @@ "We start by getting the current user's favorite albums and artists using `minim.qobuz.PrivateAPI.get_favorites()`:" ] }, - { - "cell_type": "code", - "execution_count": 33, - "metadata": {}, - "outputs": [], - "source": [ - "qobuz_favorites = client_qobuz.get_favorites()\n", - "qobuz_favorite_albums = qobuz_favorites[\"albums\"][\"items\"]\n", - "qobuz_favorite_artists = qobuz_favorites[\"artists\"][\"items\"]" - ] - }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ - "remove-cell" + "skip-execution" ] }, "outputs": [], "source": [ - "if len(qobuz_favorite_albums) == 0:\n", - " qobuz_favorite_albums.append(\"0075679933652\")\n", - "\n", - "if len(qobuz_favorite_artists) == 0:\n", - " qobuz_favorite_artists.append(\"865362\")" + "qobuz_favorites = client_qobuz.get_favorites()\n", + "qobuz_favorite_albums = qobuz_favorites[\"albums\"][\"items\"]\n", + "qobuz_favorite_artists = qobuz_favorites[\"artists\"][\"items\"]" ] }, { @@ -713,25 +684,31 @@ }, { "cell_type": "code", - "execution_count": 34, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "spotify_album_ids = []\n", "for qobuz_album in qobuz_favorite_albums:\n", " try:\n", - " spotify_album = client_spotify.search(f'upc:{qobuz_album[\"upc\"][1:]}',\n", - " \"album\")[\"items\"][0]\n", + " spotify_album = client_spotify.search(\n", + " f\"upc:{qobuz_album['upc'][1:]}\", \"album\"\n", + " )[\"items\"][0]\n", " except IndexError:\n", " spotify_albums = client_spotify.search(\n", - " f'{qobuz_album[\"artist\"][\"name\"]} {qobuz_album[\"title\"]}', \"album\"\n", + " f\"{qobuz_album['artist']['name']} {qobuz_album['title']}\", \"album\"\n", " )[\"items\"]\n", " for spotify_album in spotify_albums:\n", - " if (spotify_album[\"name\"] == qobuz_album[\"title\"]\n", - " and spotify_album[\"artists\"][0][\"name\"]\n", - " == qobuz_album[\"artist\"][\"name\"]\n", - " and spotify_album[\"total_tracks\"]\n", - " == qobuz_album[\"tracks_count\"]):\n", + " if (\n", + " spotify_album[\"name\"] == qobuz_album[\"title\"]\n", + " and spotify_album[\"artists\"][0][\"name\"]\n", + " == qobuz_album[\"artist\"][\"name\"]\n", + " and spotify_album[\"total_tracks\"] == qobuz_album[\"tracks_count\"]\n", + " ):\n", " break\n", " spotify_album_ids.append(spotify_album[\"id\"])\n", "client_spotify.save_albums(spotify_album_ids)" @@ -746,13 +723,19 @@ }, { "cell_type": "code", - "execution_count": 35, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "spotify_artist_ids = []\n", "for qobuz_artist in qobuz_favorite_artists:\n", - " spotify_artist = client_spotify.search(qobuz_artist[\"name\"], \"artist\")[\"items\"][0]\n", + " spotify_artist = client_spotify.search(qobuz_artist[\"name\"], \"artist\")[\n", + " \"items\"\n", + " ][0]\n", " spotify_artist_ids.append(spotify_artist[\"id\"])\n", "client_spotify.follow_people(spotify_artist_ids, \"artist\")" ] @@ -768,14 +751,18 @@ }, { "cell_type": "code", - "execution_count": 36, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "tidal_album_ids = []\n", "for qobuz_album in qobuz_favorite_albums:\n", " tidal_albums = client_tidal.search(\n", - " f'{qobuz_album[\"artist\"][\"name\"]} {qobuz_album[\"title\"]}', type=\"album\"\n", + " f\"{qobuz_album['artist']['name']} {qobuz_album['title']}\", type=\"album\"\n", " )[\"items\"]\n", " for tidal_album in tidal_albums:\n", " if tidal_album[\"upc\"].lstrip(\"0\") == qobuz_album[\"upc\"].lstrip(\"0\"):\n", @@ -793,14 +780,19 @@ }, { "cell_type": "code", - "execution_count": 37, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "tidal_artist_ids = []\n", "for qobuz_artist in qobuz_favorite_artists:\n", - " tidal_artist = client_tidal.search(qobuz_artist[\"name\"],\n", - " type=\"artist\")[\"items\"][0]\n", + " tidal_artist = client_tidal.search(qobuz_artist[\"name\"], type=\"artist\")[\n", + " \"items\"\n", + " ][0]\n", " tidal_artist_ids.append(tidal_artist[\"id\"])\n", "client_tidal.favorite_artists(tidal_artist_ids)" ] @@ -816,8 +808,12 @@ }, { "cell_type": "code", - "execution_count": 38, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "spotify_favorite_albums = client_spotify.get_saved_albums()[\"items\"]\n", @@ -835,24 +831,30 @@ }, { "cell_type": "code", - "execution_count": 39, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "qobuz_album_ids = []\n", "for spotify_album in spotify_favorite_albums:\n", " qobuz_albums = client_qobuz.search(\n", - " f'{spotify_album[\"album\"][\"artists\"][0][\"name\"]} '\n", - " f'{spotify_album[\"album\"][\"name\"]}'\n", + " f\"{spotify_album['album']['artists'][0]['name']} \"\n", + " f\"{spotify_album['album']['name']}\"\n", " )[\"albums\"][\"items\"]\n", " for qobuz_album in qobuz_albums:\n", - " if (spotify_album[\"album\"][\"external_ids\"][\"upc\"].lstrip(\"0\")\n", - " == qobuz_albums[0][\"upc\"].lstrip(\"0\")\n", - " or (spotify_album[\"album\"][\"name\"] == qobuz_album[\"title\"]\n", - " and spotify_album[\"album\"][\"artists\"][0][\"name\"]\n", - " == qobuz_album[\"artist\"][\"name\"]\n", - " and spotify_album[\"album\"][\"tracks\"][\"total\"]\n", - " == qobuz_album[\"tracks_count\"])):\n", + " if spotify_album[\"album\"][\"external_ids\"][\"upc\"].lstrip(\n", + " \"0\"\n", + " ) == qobuz_albums[0][\"upc\"].lstrip(\"0\") or (\n", + " spotify_album[\"album\"][\"name\"] == qobuz_album[\"title\"]\n", + " and spotify_album[\"album\"][\"artists\"][0][\"name\"]\n", + " == qobuz_album[\"artist\"][\"name\"]\n", + " and spotify_album[\"album\"][\"tracks\"][\"total\"]\n", + " == qobuz_album[\"tracks_count\"]\n", + " ):\n", " qobuz_album_ids.append(qobuz_album[\"id\"])\n", " break\n", "client_qobuz.favorite_items(album_ids=qobuz_album_ids)" @@ -867,15 +869,19 @@ }, { "cell_type": "code", - "execution_count": 40, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "qobuz_artist_ids = []\n", "for spotify_artist in spotify_favorite_artists:\n", - " qobuz_artist = client_qobuz.search(\n", - " spotify_artist[\"name\"]\n", - " )[\"artists\"][\"items\"][0]\n", + " qobuz_artist = client_qobuz.search(spotify_artist[\"name\"])[\"artists\"][\n", + " \"items\"\n", + " ][0]\n", " qobuz_artist_ids.append(qobuz_artist[\"id\"])\n", "client_qobuz.favorite_items(artist_ids=qobuz_artist_ids)" ] @@ -891,25 +897,31 @@ }, { "cell_type": "code", - "execution_count": 41, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "tidal_album_ids = []\n", "for spotify_album in spotify_favorite_albums:\n", " tidal_albums = client_tidal.search(\n", - " f'{spotify_album[\"album\"][\"artists\"][0][\"name\"]} '\n", - " f'{spotify_album[\"album\"][\"name\"]}',\n", - " type=\"album\"\n", + " f\"{spotify_album['album']['artists'][0]['name']} \"\n", + " f\"{spotify_album['album']['name']}\",\n", + " type=\"album\",\n", " )[\"items\"]\n", " for tidal_album in tidal_albums:\n", - " if (tidal_album[\"upc\"].lstrip(\"0\")\n", - " == spotify_album[\"album\"][\"external_ids\"][\"upc\"].lstrip(\"0\")\n", - " or (tidal_album[\"title\"] == spotify_album[\"album\"][\"name\"]\n", - " and tidal_album[\"artists\"][0][\"name\"]\n", - " == spotify_album[\"album\"][\"artists\"][0][\"name\"]\n", - " and tidal_album[\"numberOfTracks\"]\n", - " == spotify_album[\"album\"][\"tracks\"][\"total\"])):\n", + " if tidal_album[\"upc\"].lstrip(\"0\") == spotify_album[\"album\"][\n", + " \"external_ids\"\n", + " ][\"upc\"].lstrip(\"0\") or (\n", + " tidal_album[\"title\"] == spotify_album[\"album\"][\"name\"]\n", + " and tidal_album[\"artists\"][0][\"name\"]\n", + " == spotify_album[\"album\"][\"artists\"][0][\"name\"]\n", + " and tidal_album[\"numberOfTracks\"]\n", + " == spotify_album[\"album\"][\"tracks\"][\"total\"]\n", + " ):\n", " tidal_album_ids.append(tidal_album[\"id\"])\n", " break\n", "client_tidal.favorite_albums(tidal_album_ids)" @@ -924,14 +936,19 @@ }, { "cell_type": "code", - "execution_count": 42, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "tidal_artist_ids = []\n", "for spotify_artist in spotify_favorite_artists:\n", - " tidal_artist = client_tidal.search(spotify_artist[\"name\"],\n", - " type=\"artist\")[\"items\"][0]\n", + " tidal_artist = client_tidal.search(spotify_artist[\"name\"], type=\"artist\")[\n", + " \"items\"\n", + " ][0]\n", " tidal_artist_ids.append(tidal_artist[\"id\"])\n", "client_tidal.favorite_artists(tidal_artist_ids)" ] @@ -947,8 +964,12 @@ }, { "cell_type": "code", - "execution_count": 43, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "tidal_favorite_albums = client_tidal.get_favorite_albums()[\"items\"]\n", @@ -966,23 +987,29 @@ }, { "cell_type": "code", - "execution_count": 44, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "qobuz_album_ids = []\n", "for tidal_album in tidal_favorite_albums:\n", " qobuz_albums = client_qobuz.search(\n", - " f'{tidal_album[\"item\"][\"artist\"][\"name\"]} {tidal_album[\"item\"][\"title\"]}'\n", + " f\"{tidal_album['item']['artist']['name']} {tidal_album['item']['title']}\"\n", " )[\"albums\"][\"items\"]\n", " for qobuz_album in qobuz_albums:\n", - " if (tidal_album[\"item\"][\"upc\"].lstrip(\"0\")\n", - " == qobuz_album[\"upc\"].lstrip(\"0\")\n", - " or (tidal_album[\"item\"][\"title\"] == qobuz_album[\"title\"]\n", - " and tidal_album[\"item\"][\"artist\"][\"name\"]\n", - " == qobuz_album[\"artist\"][\"name\"]\n", - " and tidal_album[\"item\"][\"numberOfTracks\"]\n", - " == qobuz_album[\"tracks_count\"])):\n", + " if tidal_album[\"item\"][\"upc\"].lstrip(\"0\") == qobuz_album[\"upc\"].lstrip(\n", + " \"0\"\n", + " ) or (\n", + " tidal_album[\"item\"][\"title\"] == qobuz_album[\"title\"]\n", + " and tidal_album[\"item\"][\"artist\"][\"name\"]\n", + " == qobuz_album[\"artist\"][\"name\"]\n", + " and tidal_album[\"item\"][\"numberOfTracks\"]\n", + " == qobuz_album[\"tracks_count\"]\n", + " ):\n", " qobuz_album_ids.append(qobuz_album[\"id\"])\n", " break\n", "client_qobuz.favorite_items(album_ids=qobuz_album_ids)" @@ -997,15 +1024,19 @@ }, { "cell_type": "code", - "execution_count": 45, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "qobuz_artist_ids = []\n", "for tidal_artist in tidal_favorite_artists:\n", - " qobuz_artist = client_qobuz.search(\n", - " tidal_artist[\"item\"][\"name\"]\n", - " )[\"artists\"][\"items\"][0]\n", + " qobuz_artist = client_qobuz.search(tidal_artist[\"item\"][\"name\"])[\"artists\"][\n", + " \"items\"\n", + " ][0]\n", " qobuz_artist_ids.append(qobuz_artist[\"id\"])\n", "client_qobuz.favorite_items(artist_ids=qobuz_artist_ids)" ] @@ -1021,29 +1052,34 @@ }, { "cell_type": "code", - "execution_count": 46, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "spotify_album_ids = []\n", "for tidal_album in tidal_favorite_albums:\n", " try:\n", " spotify_album = client_spotify.search(\n", - " f'upc:{tidal_album[\"item\"][\"upc\"]}',\n", - " \"album\"\n", + " f\"upc:{tidal_album['item']['upc']}\", \"album\"\n", " )[\"items\"][0]\n", " except IndexError:\n", " spotify_albums = client_spotify.search(\n", - " f'{tidal_album[\"item\"][\"artist\"][\"name\"]} '\n", - " f'{tidal_album[\"item\"][\"title\"]}',\n", - " \"album\"\n", + " f\"{tidal_album['item']['artist']['name']} \"\n", + " f\"{tidal_album['item']['title']}\",\n", + " \"album\",\n", " )[\"items\"]\n", " for spotify_album in spotify_albums:\n", - " if (spotify_album[\"name\"] == tidal_album[\"item\"][\"title\"]\n", - " and spotify_album[\"artists\"][0][\"name\"]\n", - " == tidal_album[\"item\"][\"artist\"][\"name\"]\n", - " and spotify_album[\"total_tracks\"]\n", - " == tidal_album[\"item\"][\"numberOfTracks\"]):\n", + " if (\n", + " spotify_album[\"name\"] == tidal_album[\"item\"][\"title\"]\n", + " and spotify_album[\"artists\"][0][\"name\"]\n", + " == tidal_album[\"item\"][\"artist\"][\"name\"]\n", + " and spotify_album[\"total_tracks\"]\n", + " == tidal_album[\"item\"][\"numberOfTracks\"]\n", + " ):\n", " break\n", " spotify_album_ids.append(spotify_album[\"id\"])\n", "client_spotify.save_albums(spotify_album_ids)" @@ -1058,14 +1094,19 @@ }, { "cell_type": "code", - "execution_count": 47, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "skip-execution" + ] + }, "outputs": [], "source": [ "spotify_artist_ids = []\n", "for tidal_artist in tidal_favorite_artists:\n", - " spotify_artist = client_spotify.search(tidal_artist[\"item\"][\"name\"],\n", - " \"artist\")[\"items\"][0]\n", + " spotify_artist = client_spotify.search(\n", + " tidal_artist[\"item\"][\"name\"], \"artist\"\n", + " )[\"items\"][0]\n", " spotify_artist_ids.append(spotify_artist[\"id\"])\n", "client_spotify.follow_people(spotify_artist_ids, \"artist\")" ] diff --git a/src/minim/discogs.py b/src/minim/discogs.py index 88a39a40..5d7dd204 100644 --- a/src/minim/discogs.py +++ b/src/minim/discogs.py @@ -5438,7 +5438,7 @@ def get_user_lists( def get_list(self, list_id: int) -> dict[str, Any]: """ - `User Lists > List List `_: Returns the items in a list. diff --git a/src/minim/tidal.py b/src/minim/tidal.py index a7931f0f..3801ff44 100644 --- a/src/minim/tidal.py +++ b/src/minim/tidal.py @@ -2992,7 +2992,7 @@ def search_albums( """ `Search Results > Search albums _: Search for + /get_searchResults__id__relationships_albums>`_: Search for albums in the TIDAL catalog. Parameters @@ -3043,7 +3043,7 @@ def search_artists( """ `Search Results > Search artists _: Search for + /get_searchResults__id__relationships_artists>`_: Search for artists in the TIDAL catalog. Parameters @@ -3094,7 +3094,7 @@ def search_playlists( """ `Search Results > Search playlists _: Search for + /get_searchResults__id__relationships_playlists>`_: Search for playlists in the TIDAL catalog. Parameters @@ -3145,7 +3145,7 @@ def search_top_hits( """ `Search Results > Search top hits _: Search for top + /get_searchResults__id__relationships_topHits>`_: Search for top hits in the TIDAL catalog. Parameters @@ -3196,7 +3196,7 @@ def search_tracks( """ `Search Results > Search tracks _: Search for + /get_searchResults__id__relationships_tracks>`_: Search for tracks in the TIDAL catalog. Parameters @@ -3247,7 +3247,7 @@ def search_videos( """ `Search Results > Search videos _: Search for + /get_searchResults__id__relationships_videos>`_: Search for videos in the TIDAL catalog. Parameters