API

These are all of the classes in PySoundCloud. Any variable definitions marked [SC] are from SoundCloud’s HTTP API Reference. This may be slightly outdated, and some variables are not referenced there, so I’ve tried to explain them myself. Honestly, I think the developers at SoundCloud don’t even know what half of them do.

SoundCloudData

class pysoundcloud.soundclouddata.SoundCloudData(response: requests.models.Response)
response_content = ''
Variables:
  • response_json – The json from the requests response
  • response_content – The decoded content of the response

SoundCloudLikedTrack

class pysoundcloud.soundcloudlikedtracks.SoundCloudLikedTrack(created_at: str, track: pysoundcloud.soundcloudtrack.SoundCloudTrack)
track = None
Variables:
  • created_at – The date & time a track was liked
  • track – The SoundCloudTrack of the liked track

SoundCloudLikedTracks

class pysoundcloud.soundcloudlikedtracks.SoundCloudLikedTracks(response: requests.models.Response, client_id: str = None)

SoundCloudPlaylist

class pysoundcloud.soundcloudplaylist.SoundCloudPlaylist(data: dict, client_id: str = None, album: bool = False, parent=None)
__init__(data: dict, client_id: str = None, album: bool = False, parent=None) → None
Parameters:
  • data – The json dict from the response
  • client_id – The ID of the client
  • album – Is the playlist actually an album
  • parent –
embeddable_by = ''
Variables:
  • duration – [SC] Duration in milliseconds
  • permalink_url – [SC] URL to the SoundCloud.com page
  • reposts_count – The number of reposts for the playlist
  • genre – [SC] The genre of the playlist
  • permalink – [SC] Permalink of the resource
  • purchase_url – [SC] External purchase link
  • description – [SC] HTML description
  • uri – [SC] API resource URL
  • label_name – [SC] Label name
  • set_type – (Honestly, no clue – please someone help me)
  • public – Is the playlist public
  • track_count – [SC] Number of public tracks
  • user_id – [SC] User ID of the owner
  • last_modified – The timestamp the playlist was last modified
  • license – [SC] Creative common license
  • tracks – All the tracks in the playlist
  • id – The ID of the playlist
  • release_date – (I also don’t know what this is. Maybe the timestamp the playlist was created?)
  • display_date – (I really have no idea what this is)
  • sharing – [SC] Public/private sharing
  • created_at – [SC] timestamp of creation
  • likes_count – The number of likes the playlist has
  • title – The title of the playlist
  • purchase_title – (No clue, and apparently SoundCloud doesn’t know either from their API documentation)
  • managed_by_feeds – (Also not sure, but I guess it says whether or not the playlist is managed by an RSS feed?)
  • artwork_url – The URL for the artwork for the playlist
  • is_album – True if the playlist is an album, false if it is just a playlist
  • user – A SoundCloudUser with the details of the user
  • published_at – (Same as created at? Maybe it’s when a private playlist went public?)
  • embeddable_by – [SC] Who can embed this track or playlist [“all”, “me”, “none”]

SoundCloudPlaylists

class pysoundcloud.soundcloudplaylists.SoundCloudPlaylists(data: dict, client_id: str = None, albums: bool = False, parent=None)
query_urn = ''
Variables:
  • playlists – The playlists
  • next_href – The URL for the next page of results
  • query_urn – The API resource URL for this query

SoundCloudRelatedTracks

class pysoundcloud.soundcloudrelatedtracks.SoundCloudRelatedTracks(data: dict, client_id: str = None)
variant = ''
Variables:
  • tracks – The related tracks
  • next_href – The URL for the next page of results
  • query_urn – The API resource URL for this query
  • variant –

SoundCloudSearchResults

class pysoundcloud.soundcloudsearchresults.SoundCloudSearchResults(response: requests.models.Response, client_id: str = None, parent: pysoundcloud.client.Client = None)
results = []
Variables:
  • response_json – The json dict from the response
  • response_content – The str content from the response
  • url – The url for the search?
  • total_results – The total number of results for the search query
  • next_href – The link to the next page of results
  • results – All the results for the search query

StreamFormat

class pysoundcloud.soundcloudstream.StreamFormat(protocol: str, mime_type: str)
mime_type = ''
Variables:
  • protocol – The protocol of the stream
  • mime_type – The mime type of the stream

SoundCloudStream

class pysoundcloud.soundcloudstream.SoundCloudStream(data: dict, client_id: str = None, track_data: pysoundcloud.trackdata.TrackData = None)
download(location: str = 'downloads/', file_name: str = None, use_better_file_name: bool = True, use_album_data: bool = True, artwork_url: str = None, artwork_crop_to_square: bool = True) → None

Download the stream

Note

When downloading a stream, it also attempts to download metadata and album artwork for it. The artists is the username user who uploaded the track, the title is the track title on SoundCloud and the artwork is whatever is provided with the track. It also does a quick check to see if the track appears in any albums. If it does, then it gets the first album and then gets album info and artwork from there instead.

Parameters:
  • location – The location to download the stream to
  • file_name – The name of the file
  • use_better_file_name – If no file name specified, create one using the username and track title?
  • use_album_data – Use the data of the first album that the track is in
  • artwork_url – The url of the artwork to use
  • artwork_crop_to_square – Should the artwork be cropped to a square? (Not currently used)
Returns:

None
static sanitize_file_name(file_name: str) → str

Sanitizes the file name as to not create any errors on Windows. Hopfully works on other OSes but should be easy to add on to, if not

Parameters:file_name – The file name to sanitize
Returns:The sanitized file name
track_data = None
Variables:
  • url – The url of the stream
  • preset –
  • duration – The duration of the stream (in milleseconds?)
  • snipped –
  • format – The format of the stream
  • quality –
  • client_id – The ID of the client
  • track_data – The data of the track

SoundCloudStreams

class pysoundcloud.soundcloudstreams.SoundCloudStreams
filter(preset: str = None, snipped: bool = False, format_protocol_progressive: bool = None, format_protocol_hls: bool = None, format_mime_type_mpeg: bool = None, format_mime_type_ogg: bool = None, format_codecs_opus: bool = None) → list

Filter the streams by certain parameters

Note

Not all of the parameters are currently implemented

Parameters:
  • preset – Preset string
  • snipped – Should the stream be snipped?
  • format_protocol_progressive – Should the stream protocol be progressive?
  • format_protocol_hls – Should the stream protocol be hls?
  • format_mime_type_mpeg – Should the stream mime type be mpeg?
  • format_mime_type_ogg – Should the stream mime type be ogg?
  • format_codecs_opus – Should the codec be opus?
Returns:

A list with the streams that match the filters
first() → pysoundcloud.soundcloudstream.SoundCloudStream

Get the first stream in the list

Returns:The first SoundCloudStream
last() → pysoundcloud.soundcloudstream.SoundCloudStream

Get the last stream in the list

Returns:The last SoundCloudStream
streams = None
Variables:streams – Contains a list of all the streams

SoundCloudTrack

class pysoundcloud.soundcloudtrack.SoundCloudTrack(data: dict, client_id: str = None, album_index: int = -1, album_name: str = '', playlist_track_index: int = -1, parent=None)
album_name = ''
Variables:
  • comment_count – [SC] Track comment count
  • full_duration – The full duration of the track (in milliseconds)
  • downloadable – Is the track downloadable
  • created_at – [SC] Timestamp of creation
  • description – [SC] HTML description
  • streams – SoundCloudStreams with the available streams for the track
  • title – [SC] Track title
  • duration – [SC] Duration in milliseconds
  • has_downloads_left – (No idea)
  • artwork_url – [SC] URL to a JPEG image
  • public – Is the track public
  • streamable – [SC] streamable via API (boolean)
  • genre – The genre of the track. (Not always an actual genre)
  • id – The integer ID of the track
  • reposts_count – The number of reposts the track has
  • state – [SC] Encoding state (Possible values: “processing”, “failed”, “finished”)
  • label_name – [SC] Label name
  • last_modified – The timestamp the track was last edited?
  • commentable – [SC] Track commentable
  • policy – (No idea)
  • purchase_url – [SC] External purchase link
  • sharing – [SC] Public/private sharing
  • uri – [SC] API resource URL
  • download_count – [SC] Track download count
  • likes_count – The number of likes the track has
  • urn – (No idea)
  • license – [SC] Creative common license
  • purchase_title – (No idea)
  • display_date – (No idea)
  • embeddable_by – [SC] Who can embed this track or playlist
  • release_date – The timestamp the track was published
  • user_id – The ID of the user who posted the track
  • monetization_model – (No idea)
  • waveform_url – URL to the waveform
  • permalink – [SC] permalink of the resource
  • permalink_url – [SC] URL to the SoundCloud.com page
  • user – The SoundCloudUser who uploaded the track
  • playback_count – [SC] track play count
  • track_index – The index of the track in the album
  • album_name – The name of the album

SoundCloudUser

class pysoundcloud.soundclouduser.SoundCloudUser(data: dict, client_id: str = None)
verified = False
Variables:
  • avatar_url – [SC] URL to a JPEG image
  • city – [SC] City
  • comments_count – The number of public comments
  • country_code – The country code of the user
  • created_at – Timestamp the user signed up?
  • description – [SC] Description
  • followers_count – [SC] Number of followers
  • followings_count – [SC] Number of followed users
  • first_name – The user’s first name
  • last_name – The user’s last name
  • full_name – [SC] First and last name
  • groups_count – Number of groups the user is in
  • id – The integer ID of the user
  • last_modified – Timestamp the profile was last edited?
  • likes_count – Number of likes
  • playlist_likes_count – Number of playlists liked
  • permalink – [SC] Permalink of the resource
  • playlist_count – [SC] Number of public playlists
  • reposts_count – Number of reposts
  • track_count – [SC] Number of public tracks
  • uri – [SC] API resource URL
  • urn – (No idea)
  • username – [SC] Username
  • verified – Is the user verified

TrackData

class pysoundcloud.trackdata.TrackData(track_title: str = None, track_subtitle: str = None, track_comments: str = None, track_artists: List[str] = None, album_artist: str = None, album_title: str = None, album_year: int = None, track_number: int = None, genre: str = None, part_of_compilation: bool = False, album_artwork_url: str = None)
album_artwork_url = ''
Variables:
  • track_title – The title of the track
  • track_subtitle – The subtitle of the track
  • track_comments – The comments of the track
  • track_artists – The artists of the track
  • album_artist – The artist of the album
  • album_title – The title of the album
  • album_year – The year the album was released
  • track_number – The track number in the album
  • genre – The genre of the track
  • part_of_compilation –
  • album_artwork_url – The URL of the image for the album artwork