Welcome to streamrip’s documentation!¶

Indices and tables¶

Clients¶

class streamrip.clients.QobuzClient¶

QobuzClient.

get(item_id: Union[str, int], media_type: str = 'album') → dict¶

Get an item from the API.

Parameters

item_id (Union[str, int]) –
media_type (str) –

Return type

dict

get_file_url(item_id, quality=3) → dict¶

Get the downloadble file url for a track.

Parameters

item_id –
quality –

Return type

dict

get_tokens() → Tuple[str, Sequence[str]]¶

Return app id and secrets.

These can be saved and reused.

Return type: Tuple[str, Sequence[str]]

login(**kwargs)¶

Authenticate the QobuzClient. Must have a paid membership.

If app_id and secrets are not provided, this will run the Spoofer script, which retrieves them. This will take some time, so it is recommended to cache them somewhere for reuse.

Parameters

email (str) – email for the qobuz account
pwd (str) – password for the qobuz account
kwargs – app_id: str, secrets: list, return_secrets: bool

search(query: str, media_type: str = 'album', limit: int = 500) → Generator¶

Search the qobuz API.

If ‘featured’ is given as media type, this will retrieve results from the featured albums in qobuz. The queries available with this type are:

most-streamed

recent-releases

best-sellers

press-awards

ideal-discography

editor-picks

most-featured

qobuzissims

new-releases

new-releases-full

harmonia-mundi

universal-classic

universal-jazz

universal-jeunesse

universal-chanson

Parameters

query (str) –
media_type (str) –
limit (int) –

Return type

Generator

class streamrip.clients.TidalClient¶

TidalClient.

property authorization¶: Get the auth header.

get(item_id, media_type)¶

Public method that internally calls _api_get.

Parameters

item_id –
media_type –

get_file_url(track_id, quality: int = 3, video=False)¶

Get the file url for a track or video given an id.

Parameters

track_id – or video id
quality (int) – 0, 1, 2, or 3. It is irrelevant for videos.
video –

get_tokens() → dict¶

Return tokens to save for later use.

Return type: dict

login(user_id=None, country_code=None, access_token=None, token_expiry=None, refresh_token=None)¶

Login to Tidal using the browser.

Providing information from previous logins will allow a user to stay logged in.

Parameters

user_id –
country_code –
access_token –
token_expiry –
refresh_token –

search(query: str, media_type: str = 'album', limit: int = 100) → dict¶

Search for a query.

Parameters

query (str) –
media_type (str) – track, album, playlist, or video.
limit (int) – max is 100

Return type

dict

class streamrip.clients.DeezerClient¶

DeezerClient.

get(meta_id: Union[str, int], media_type: str = 'album')¶

Get metadata.

Parameters

meta_id (Union[str, int]) –
type (str) –

static get_file_url(meta_id: Union[str, int], quality: int = 6)¶

Get downloadable url for a track.

Parameters

meta_id (Union[str, int]) – The track ID.
quality (int) –

login(**kwargs)¶

Return None.

Dummy method.

Parameters: kwargs –

search(query: str, media_type: str = 'album', limit: int = 200) → dict¶

Search API for query.

Parameters

query (str) –
media_type (str) –
limit (int) –

class streamrip.clients.SoundCloudClient¶

SoundCloudClient.

get(id, media_type='track')¶

Get metadata for a media type given an id.

Parameters

id –
media_type –

get_file_url(track, quality)¶

Get the streamable file url from soundcloud.

It will most likely be an hls stream, which will have to be manually parsed, or downloaded with ffmpeg.

Parameters

track (dict) –
quality –

Return type

dict

login()¶: Login is not necessary for SoundCloud.

search(query: str, media_type='album')¶

Search for a query.

Parameters

query (str) –
media_type – Can be album, though it will return a playlist

response.

Media¶

class streamrip.media.Track(client: streamrip.clients.Client, **kwargs)¶

Represents a downloadable track.

Loading metadata as a single track: >>> t = Track(client, id=’20252078’) >>> t.load_meta() # load metadata from api

Loading metadata as part of an Album: >>> t = Track.from_album_meta(api_track_dict, client)

where api_track_dict is a track entry in an album tracklist.

Downloading and tagging: >>> t.download() >>> t.tag()

convert(codec: str = 'ALAC', **kwargs)¶

Convert the track to another codec.

Valid values for codec:

FLAC
ALAC
MP3
OPUS
OGG
VORBIS
AAC
M4A

Parameters

codec (str) – the codec to convert the track to
kwargs –

download(quality: int = 3, parent_folder: str = 'StreamripDownloads', progress_bar: bool = True, **kwargs)¶

Download the track.

Parameters

quality (int) – (0, 1, 2, 3, 4)
folder (Optional[Union[str, os.PathLike]]) – folder to download the files to
progress_bar (bool) – turn on/off progress bar

download_cover(width=999999, height=999999)¶: Download the cover art, if cover_url is given.

format_final_path() → str¶

Return the final filepath of the downloaded file.

This uses the get_formatter method of TrackMetadata, which returns a dict with the keys allowed in formatter strings, and their values in the TrackMetadata object.

classmethod from_album_meta(album: streamrip.metadata.TrackMetadata, track: dict, client: streamrip.clients.Client)¶

Return a new Track object initialized with info.

Parameters

album – album metadata returned by API
pos – index of the track
client (Client) – qopy client object

:raises IndexError

classmethod from_api(item: dict, client: streamrip.clients.Client)¶

Return a new Track initialized from search result.

Parameters

item (dict) –
client (Client) –

get(*keys, default=None) → Any¶

Safe get method that allows for layered access.

Parameters

keys –
default –

load_meta(**kwargs)¶

Send a request to the client to get metadata for this Track.

Usually only called for single tracks and last.fm playlists.

move(path: str)¶

Move the Track and set self.path to the new path.

Parameters: path (str) –

set(key, val)¶

Set attribute key to val.

Equivalent to __setitem__. Implemented only for consistency.

Parameters

key –
val –

tag(album_meta: Optional[dict] = None, cover: Optional[Union[mutagen.flac.Picture, mutagen.id3.APIC, mutagen.mp4.MP4Cover]] = None, embed_cover: bool = True, **kwargs)¶

Tag the track using the stored metadata.

The info stored in the TrackMetadata object (self.meta) can be updated with album metadata if necessary. The cover must be a mutagen cover-type object that already has the bytes loaded.

Parameters

album_meta (dict) – album metadata to update Track with
cover (Union[Picture, APIC]) – initialized mutagen cover object
embed_cover (bool) – Embed cover art into file

property title: str¶

Get the title of the track.

Return type: str

class streamrip.media.Booklet(resp: dict)¶

Only for Qobuz.

download(parent_folder: str, **kwargs)¶

Download the Booklet.

Parameters

parent_folder (str) –
kwargs –

class streamrip.media.Video(client: streamrip.clients.Client, id: str, **kwargs)¶

Only for Tidal.

download(**kwargs)¶

Download the Video.

Parameters: kwargs –

classmethod from_album_meta(track: dict, client: streamrip.clients.Client)¶

Return a new Video object given an album API response.

Parameters

track (dict) – track dict from album
client (Client) –

load_meta(**kwargs)¶: Given an id at contruction, get the metadata of the video.

property path: str¶

Get path to download the mp4 file.

Return type: str

tag(*args, **kwargs)¶

Return False.

This is a dummy method.

Parameters

args –
kwargs –

class streamrip.media.YoutubeVideo(url: str)¶

Dummy class implemented for consistency with the Media API.

class DummyClient¶: Used because YouTube downloads use youtube-dl, not a client.

download(parent_folder: str = 'StreamripDownloads', download_youtube_videos: bool = False, youtube_video_downloads_folder: str = 'StreamripDownloads', **kwargs)¶

Download the video using ‘youtube-dl’.

Parameters

parent_folder (str) –
download_youtube_videos (bool) – True if the video should be downloaded.
youtube_video_downloads_folder – Folder to put videos if

downloaded. :type youtube_video_downloads_folder: str :param kwargs:

load_meta(*args, **kwargs)¶

Return None.

Dummy method.

Parameters

args –
kwargs –

tag(*args, **kwargs)¶

Return None.

Dummy method.

Parameters

args –
kwargs –

class streamrip.media.Tracklist(iterable=(), /)¶

A base class for tracklist-like objects.

Implements methods to give it dict-like behavior. If a Tracklist subclass is subscripted with [s: str], it will return an attribute s. If it is subscripted with [i: int] it will return the i’th track in the tracklist.

convert(codec='ALAC', **kwargs)¶

Convert every item in self.

Deprecated. Use _download_and_convert_item instead.

Parameters

codec –
kwargs –

download(**kwargs)¶

Download all of the items in the tracklist.

Parameters: kwargs –

download_message()¶

Get the message to display after calling Tracklist.download.

Return type: str

static essence(album: str) → str¶

Ignore text in parens/brackets, return all lowercase.

Used to group two albums that may be named similarly, but not exactly the same.

classmethod from_api(item: dict, client: streamrip.clients.Client)¶

Create an Album object from an API response.

Parameters

resp (dict) – response dict
source (str) – in (‘qobuz’, ‘deezer’, ‘tidal’)

get(key: Union[str, int], default=None)¶

Get an item if key is int, otherwise get an attr.

Parameters: key – If it is a str, get an attribute. If an int, get the item

at the index. :type key: Union[str, int] :param default:

static get_cover_obj(cover_path: str, container: str, source: str)¶

Return an initialized cover object that is reused for every track.

Parameters

cover_path (str) – Path to the image, must be a JPEG.
quality (int) – quality ID

Return type

Union[Picture, APIC]

set(key, val)¶

For consistency with Tracklist.get.

Parameters

key –
val –

class streamrip.media.Album(client: streamrip.clients.Client, **kwargs)¶

Represents a downloadable album.

Usage:

>>> resp = client.get('fleetwood mac rumours', 'album')
>>> album = Album.from_api(resp['items'][0], client)
>>> album.load_meta()
>>> album.download()

classmethod from_api(resp: dict, client: streamrip.clients.Client)¶

Create an Album object from an API response.

Parameters

resp (dict) –
client (Client) –

load_meta(**kwargs)¶: Load detailed metadata from API using the id.

property title: str¶

Get the title of the album.

Return type: str

class streamrip.media.Playlist(client: streamrip.clients.Client, **kwargs)¶

Represents a downloadable playlist.

Usage: >>> resp = client.search(‘hip hop’, ‘playlist’) >>> pl = Playlist.from_api(resp[‘items’][0], client) >>> pl.load_meta() >>> pl.download()

classmethod from_api(resp: dict, client: streamrip.clients.Client)¶

Return a Playlist object from an API response.

Parameters

resp (dict) – a single search result entry of a playlist
client (Client) –

load_meta(**kwargs)¶

Send a request to fetch the tracklist from the api.

Parameters

new_tracknumbers (bool) – replace the tracknumber with playlist position
kwargs –

property title: str¶

Get the title.

Return type: str

class streamrip.media.Artist(client: streamrip.clients.Client, **kwargs)¶

Represents a downloadable artist.

Usage: >>> resp = client.get(‘fleetwood mac’, ‘artist’) >>> artist = Artist.from_api(resp[‘items’][0], client) >>> artist.load_meta() >>> artist.download()

download(**kwargs)¶

Download all items in self.

Parameters: kwargs –

classmethod from_api(item: dict, client: streamrip.clients.Client, source: str = 'qobuz')¶

Create an Artist object from the api response of Qobuz, Tidal, or Deezer.

Parameters

resp (dict) – response dict
source (str) – in (‘qobuz’, ‘deezer’, ‘tidal’)

load_meta(**kwargs)¶: Send an API call to get album info based on id.

property title: str¶

Get the artist name.

Implemented for consistency.

Return type: str

class streamrip.media.Label(client: streamrip.clients.Client, **kwargs)¶

Represents a downloadable Label.

load_meta(**kwargs)¶: Load metadata given an id.

Welcome to streamrip’s documentation!¶

Indices and tables¶

Clients¶

Media¶

streamrip

Navigation

Related Topics