Widget JavaScript API

Add the API script to your page once, however many widgets it holds:

<script src="//widget.mixcloud.com/media/js/widgetApi.js"></script>

Then create an object for each widget iframe you want to control:

<script src="//widget.mixcloud.com/media/js/widgetApi.js"></script>
<iframe id="my-widget-iframe" src="..."></iframe>

<script>
    var widget = Mixcloud.PlayerWidget(
        document.getElementById("my-widget-iframe")
    );

    widget.ready.then(function () {
        // Put code that interacts with the widget here.
    });

    // Repeat for each additional widget you want to control.
    var widget2 = Mixcloud.PlayerWidget(
        document.getElementById("my-other-widget-iframe")
    );
</script>

The widget must be visible on the page for the API to work.

Method calls and the ready callback use Promises/A+ compliant promises. Until ready resolves, the object returned by Mixcloud.PlayerWidget has no API on it, so do your work inside the then.

All communication with the iframe goes through window.postMessage and is therefore asynchronous, so every method returns a promise.

load(cloudcastKey, startPlaying)

Load a different show by key — for example /spartacus/lambiance/. Pass startPlaying=true to start playing once it has loaded. Resolves when the new show is loaded.

play()

Start playing, if paused or not yet started.

Browsers block autoplay of media the user hasn't asked for, so play() is not guaranteed to start playback on its own. Trigger it from a play button the user clicks. See Chrome's autoplay policy for the details.

pause()

Pause playback, if playing.

togglePlay()

Pause or resume, depending on the current state.

seek(seconds)

Seek to a number of seconds into the audio. Resolves with true if the seek was allowed and false if it wasn't.

getPosition()

Resolves with the current position, in seconds.

getDuration()

Resolves with the duration, in seconds.

getIsPaused()

Resolves with the current playback state.

Widget options

Set hide_cover, hide_tracklist, mini, hide_artwork or light to true or false.

The getters pass their value to the promise, so read it from the then callback:

widget.getPosition().then(function (position) {
    // "position" is the current position, in seconds.
});

The widget emits progress, buffering, play, pause, ended and error. Listen for any of them the same way:

var widget = Mixcloud.PlayerWidget(myIframe);

function pauseListener() {
    // Called whenever the widget is paused.
}

widget.events.pause.on(pauseListener);

// To stop listening:
widget.events.pause.off(pauseListener);

Swap events.pause for events.buffering and so on to listen for a different event. The progress listener is passed position and duration parameters.

If your page already has a Mixcloud variable in the global namespace, use noConflict to get the API object without overwriting it:

Mixcloud.noConflict(function (mixcloudApiObject) {
    mixcloudApiObject.PlayerWidget(myIframe);
});

window.Mixcloud is restored to whatever it was before the widget API script loaded.