Widget API

The SoundCloud Widget API provides JavaScript control over embedded SoundCloud players. It enables playback control, event handling, and widget configuration from the parent page.

• Script URL: https://w.soundcloud.com/player/api.js
• Entry point: SC.Widget(iframeElement|iframeElementID)
• Communication: uses window.postMessage (async getters)

Parameters

Add these parameters to the player URL in the embed code:

<iframe width="100%" height="166" scrolling="no" frameborder="no" allow="autoplay"
  src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/293&amp;{ ADD YOUR PARAMETERS HERE }">
</iframe>

API

Include the Widget API script in your HTML page to access the JavaScript API object.

The script exposes SC.Widget(/*iframeElement|iframeElementID*/) to the global scope, enabling control of the widget from the parent page. SC.Widget accepts a reference to the iframe element or its id.

var iframeElement   = document.querySelector('iframe');
var iframeElementID = iframeElement.id;
var widget1         = SC.Widget(iframeElement);
var widget2         = SC.Widget(iframeElementID);
// widget1 === widget2

Playground

Widget API Playground provides live examples with on-screen results.

Methods

The SC.Widget method returns a widget object with the following public methods:

• bind(eventName, listener) — adds a listener function for the specified eventName. See below for possible event names.
• unbind(eventName) — removes all listener functions previously added for the specified eventName. See below for possible event names.
• load(url, options) — reloads the iframe element with a new widget specified by the url. All previously added event listeners continue working. options is an object that accepts all widget parameters as well as a callback function executed when the new widget is ready. See below for the full list of widget parameters.
• play() — plays the sound.
• pause() — pauses the sound.
• toggle() — toggles the sound.
• seekTo(milliseconds) — jumps to a certain position in a sound.
• setVolume(volume) — sets the widget volume to a value in the range 0-100.
• next() — skips to the next sound (only for multi-sound widgets).
• prev() — skips to the previous sound (only for multi-sound widgets).
• skip(soundIndex) — jumps to the sound at soundIndex, starting from 0 (only for multi-sound widgets).

Getters

Getter methods return a value without modifying widget state. Because parent-page-to-iframe communication uses window.postMessage, values cannot be returned synchronously. Each getter accepts a callback function that receives the return value.

• getVolume(callback) — returns the current volume, in the range of [0, 100].
• getDuration(callback) — returns current sound duration in milliseconds.
• getPosition(callback) — returns current sound position in milliseconds.
• getSounds(callback) — returns the list of sound objects.
• getCurrentSound(callback) — returns current sound object.
• getCurrentSoundIndex(callback) — returns the index of current sound.
• isPaused(callback) — returns whether the widget is paused.

Event Types

All event types are accessible via the SC.Widget.Events object. Use this object when adding or removing event listeners. Event listeners execute in the context of the widget object.

Events fall into two categories: audio and ui.

Audio

• SC.Widget.Events.LOAD_PROGRESS — fired periodically while the sound is loading.
• SC.Widget.Events.PLAY_PROGRESS — fired periodically while the sound is playing.
• SC.Widget.Events.PLAY — fired when the sound begins to play.
• SC.Widget.Events.PAUSE — fired when the sound pauses.
• SC.Widget.Events.FINISH — fired when the sound finishes.
• SC.Widget.Events.SEEK — fired when the user seeks.

Audio events return an object with these properties:

relativePosition - relative current position of the current sound, in the range of [0,1].
loadProgress     - the current value of the loading progress, in the range of [0,1].
currentPosition  - the position of the current sound (in milliseconds).

UI

• SC.Widget.Events.READY — fired when the widget has loaded its data and is ready to accept external calls.
• SC.Widget.Events.CLICK_DOWNLOAD — fired when the user clicks the download button.
• SC.Widget.Events.CLICK_BUY — fired when the user clicks the buy button.
• SC.Widget.Events.OPEN_SHARE_PANEL — fired when the share panel is opened (user clicks "Share" or the last sound ends).
• SC.Widget.Events.ERROR — fired when an error message is displayed.

Resources

See the blog post about the HTML5 Widget API for additional examples.