Python soundcloud

The JavaScript SDK lets you easily integrate SoundCloud into your website or webapp.

Basic Use

To start using the SDK just add this script to your HTML and initialize the client with your own and optionally your in case you want to use authentication:

You can also install the SDK via NPM now: .

Once that's done you are all set and ready to use the SoundCloud API. For example getting a user's latest track:

The JavaScript SDK is open source and can be found on Github. If you are looking for example applications, have a look at the examples on this page.

Authentication

To use the authentication you have to host a file on your server and set it as the in your app settings and when initializing the SDK. This file needs to contain just a few lines:

You initiate the connect flow by calling . Once your users are authenticated and authorized, your app is allowed to use the HTTP methods SC.post, SC.put and SC.delete to create comments, liking a track or updating user profiles. The following example shows how to follow a user, after connecting the current user:

Relevant methods: SC.connect, SC.post, SC.put, SC.delete

API

The SDK provides easy access to all HTTP endpoints through the SC.get, SC.post, SC.put and SC.delete methods.

For a list of available endpoints, check the API Reference.

Streaming

Streaming tracks from the SDK is powered by the same player that is also used on soundcloud.com to ensure the best playback experience.

The player has all basic methods to control the playback flow like , , , , etc.

Relevant methods: SC.stream

Recording

The SDK uses getUserMedia, Web Workers and the Web Audio API to record from a user's computer, so make sure to check if the user's browser supports all of it (1, 2, 3) before you start recording. This example will record 5 seconds and play it back right away:

In addition to recording from the user's computer, the SDK also supports recording from an arbitrary AudioNode by passing it to the Recorder's constructor. Check out the documentation and the examples for more information.

Relevant methods: SC.Recorder

Uploading

You can upload recordings and files using the SDK's method. This method requires the user's browser to support FormData (supported in all modern browsers and IE10+, 1).

Uploads can take a while and it makes sense to inform the user about the progress. For this reason, returns the original request as well so that you can calculate the progress yourself.

Relevant methods: SC.upload

Embedding

The function is a wrapper for the SoundCloud oEmbed endpoint.

It takes the URL you want to embed as an argument, and an optional options object that can contain an element that should be replaced by the embed code. All of the object's properties will be passed as parameters to the oEmbed endpoint. For example , , or . The options are described in detail in the oEmbed documentation.

Or:

Relevant methods: SC.oEmbed

Examples

If you want to check out more SDK usage examples, head over to the API Guide. It shows how to use API methods in all available SDKs.

An example of an application that is using a combination of several SDK methods can be found on Github. It records a user's microphone and uploads it together with an artwork that is generated from the user's webcam. (no Flash required!)

Promises

The SDK uses Promises for most of its methods. They provide a way to easily compose API calls and offer a sane way to handle the various errors that can occur.

Promises can be chained by using their method and errors can be handled in a handler. If you are new to Promises, check out this introductory blog artice on HTML5 rocks: html5rocks.com/en/tutorials/es6/promises.

In order to conform with the ES6 standard, the SDK uses es6-promise which shims the object on systems where it is not available. We also expose the library via SC.Promise, so that you can use methods like or even if your user's browser is not supporting Promises yet.

Relevant methods: SC.Promise

API Documentation

SC.initialize(options)

Initializes the SDK.

Parameters:

• :
  • : You application's client id
  • (optional): Only needed if you want to authenticate users
  • (optional): If you want to reuse an access token

SC.connect(options)

Initiate the OAuth2 connect flow.

Parameters:

• :
  • : override the before set client id.
  • : the redirect URI as defined in your app settings.
  • : additional OAuth2 scopes (default: "*")

Returns: A promise that will resolve with a session data object

SC.get(path, [params])

Execute a GET request.

Parameters:

• : the path to the requested resource e.g. '/users/183'
• : an object of additional parameters to pass in the request.

Returns: A promise that will resolve with the requested resource

SC.post(path, [params])

Execute a POST request.

Parameters:

• : the path to the requested resource e.g. '/me/followings'
• : an object of additional parameters to pass in the request body.

Returns: A promise that will resolve with the requested resource

SC.put(path, [params])

Execute a PUT request.

Parameters:

• : the path to the requested resource e.g. '/me'
• : an object of additional parameters to pass in the request body.

Returns: A promise that will resolve with the requested resource

SC.delete(path)

Execute a DELETE request.

Parameters:

• : the path to the requested resource

Returns: A promise that will resolve when the resource has been deleted

SC.upload(options)

Uploads a file or a recording to SoundCloud

Parameters:

• :
  • : a Blob of the file or the recording (see recorder.getWAV()).
  • : a title for the recording.
  • : a progress callback.
  • It also accepts all other params for upload requests, such as or (see API Reference for a full list).

Returns: A promise that will resolve when the resource has been uploaded. It also contains a reference to the original request (see Uploading)

SC.resolve(url)

Resolves a SoundCloud URL to a JSON representation of the requested resource

Parameters:

• : a URL to a track, playlist or user on SoundCloud.

Returns: A promise that will resolve with a JSON object

SC.oEmbed(url, [params])

Will lookup the embed code for the passed URL (track, set or user) using oEmbed

Parameters:

• : a URL to a track, set or user on SoundCloud.
• : additional parameters for oEmbed. See oEmbed docs. In addition to that, it accepts an property that will replace the HTML element with the widget.

Returns: A promise that will resolve with the oEmbed info for the resource

SC.stream(trackPath, [secretToken])

Creates a player for this stream

Parameters:

• : the path of the track to be streamed e.g. /tracks/293
• : a secret token for the track

Returns: A promise that will resolve with a player for the track

SC.Recorder(options)

The constructor function which returns an instance of the Web Audio Recorder (has to be called with )

Parameters:

• :
  • : You can pass an AudioContext if you want to reuse it
  • : Pass a source if you want to record from an AudioNode

recorder.start()

Starts recording from the user's computer or the that was passed into the constructor

Requires the Web Audio API, Web Workers and getUserMedia to be available in the user's browser

recorder.stop()

Stops the current recording

recorder.play()

Plays back what was just recorded

Returns: The AudioNode that is used to play the sound

recorder.getWAV()

Returns: A promise that resolves with a WAV Blob of the current recording

recorder.getBuffer()

Returns: A promise that resolves with an AudioBuffer of the current recording

recorder.saveAs(filename)

Downloads the recorded WAV to the user's computer

Parameters:

• : The desired name of the file

recorder.delete()

Stops and deletes the recording

SC.Promise

The promise prototype that is used in the SDK internally (es6-promise). Use it to create your own promises or to use methods like Promise.all or Promise.race.

Player (methods & events)

Methods

You can use the methods below to control the player that is returned from SC.stream

• : Starts to play the sound. Returns a Promise that resolves when playback starts, and may reject if the browser refuses playback.
• : Pauses the player
• : Seeks to the position in the song (in milliseconds). Returns a Promise that resolves when the seek completes, or may reject if the seek is not possible.
• : Returns the current position (in milliseconds)
• : Sets the volume (from 0 to 1)
• : Returns the current volume
• : Returns the duration (in milliseconds)
• : Returns true whilst the player is buffering
• : Returns true whilst the intended state is to be playing. This flips with and calls.
• : Returns true whilst the player is actually playing
• : Returns true if the player is dead because of an error
• : Returns true if the player is dead
• : Returns 'playing', 'paused', 'loading', 'ended', 'error' or 'dead'
• : Kill the player. Call this when you do not need it anymore.
• : Subscribes the handler to the given event

Events

You can subscribe to the events below by using the player's method.

• : when audio controller changes state (e.g. from pause to play). Possible values: 'playing', 'paused', 'loading', 'ended', 'error' or 'dead'
• : when method is called
• : when playback actually starts, the first time
• : when playback starts, the second time onwards
• : if a play request is rejected by the browser
• : when playback is paused
• : when sound is finished
• : when method is called
• : when a seek completes
• : when a seek is rejected for some reason
• : when there's no available streams for a sound, as it is not allowed to be played in the user's territory.
• : when buffering starts
• : when buffering stops
• : when an error occurs
• : when playback position is updated
• : when we failed fetching stream information
• : when no supported protocol could be found
• : when we failed to connect to an endpoint due to missing transport or request timeout

DEPRECATED - NO LONGER MAINTAINED

This repository is no longer maintained by the SoundCloud team due to capacity constraints. We're instead focusing our efforts on improving the API & the developer platform. Please note, at the time of updating this, the repo is already not in sync with the latest API changes.

We recommend the community to fork this repo in order to maintain the SDK. We'd be more than happy to make a reference on our developer that the developers can use different SDKs build by the community. In case you need to reach out to us, please head over to https://github.com/soundcloud/api/issues

soundcloud-python

A friendly wrapper around the Soundcloud API.

Installation

To install soundcloud-python, simply:

Or if you're not hip to the pip:

Basic Use

To use soundcloud-python, you must first create a Client instance, passing at a minimum the client id you obtained when you registered your app:

The client instance can then be used to fetch or modify resources:

Authentication

All OAuth2 authorization flows supported by the Soundcloud API are available in soundcloud-python. If you only need read-only access to public resources, simply provide a client id when creating a Client instance:

If however, you need to access private resources or modify a resource, you will need to have a user delegate access to your application. To do this, you can use one of the following OAuth2 authorization flows.

Authorization Code Flow

The Authorization Code Flow involves redirecting the user to soundcloud.com where they will log in and grant access to your application:

Note that redirect_uri must match the value you provided when you registered your application. After granting access, the user will be redirected to this uri, at which point your application can exchange the returned code for an access token:

User Credentials Flow

The User Credentials Flow allows you to exchange a username and password for an access token. Be cautious about using this flow, it's not very kind to ask your users for their password, but may be necessary in some use cases:

Examples

Resolve a track and print its id:

Upload a track:

Start following a user:

Update your profile description:

Proxy Support

If you're behind a proxy, you can specify it when creating a client:

The proxies kwarg is a dictionary with protocols as keys and host:port as values.

Redirects

By default, 301 or 302 redirects will be followed for idempotent methods. There are certain cases where you may want to disable this, for example:

Will print a tracks streaming URL. If was omitted, a binary stream would be returned instead.

Running Tests

To run the tests, run:

Success!

Contributing

Contributions are awesome. You are most welcome to submit issues, or fork the repository.

soundcloud-python is published under a BSD License.

Industry Standard Compliance

SOC 2, HIPAA/BAA, EU/US Privacy Shield Framework, Open ID Certified.

Built by Security Experts

Continuously reviewed and tested by external security experts. Strong password encryption and hashing algorithms, at rest and in transit.

What Our Customers Say

Continuously reviewed and tested by external security experts. Strong password encryption and hashing algorithms, at rest and in transit.

Availability & trust

Uptime time in 3 different regions.

Learn More

Host Anywhere

Deploy On-Premises or on Cloud on your data center or Auth0’s one.

This is a Soundcloud API library that doesn't require a client ID to function. It's basic, it can really only fetch tracks and playlists, but doesn't require the user to go through the soundcloud app approval process.

Now works again! Soundcloud please stop changing how your site works :)

I once applied for API access and was approved. I used this access for months until it was revoked for some reason and all my emails and new applications were ignored. I decided to create a library that allows me to do Soundcloud API stuff without an approved application.

• Supports asyncio
• Does not require a client ID
• Fetches and writes mp3 metadata (Album artist, title, artwork)
• Can fetch entire playlists of tracks

This library is installable as a pip package.

This library uses programming and algorithms to find a client ID that can be used to access the Soundcloud API.

Saving an mp3 to a file.

This will write the ID3 tags for album artist, track title AND will embed the album artwork into the mp3.

Fetch a playlist

Asyncio Support

Fetch a playlist

Write Album Name or Track Number

This library cannot download tracks that are not marked "Downloadable".

"Downloadable" tracks have an MP3 representation while non-"Downloadable" ones only have HLS representations. I would like to add HLS assembly to this library in the future.

Please report any and all bugs using the issues tab.

Feel free to request new features too.

Sure, submit a pull request.