Embedding the Player

In this guide:

What’s an Embedded Player?

The embedded player is a player you can include into your own website or blog. It consists of an HTML snippet that you can add to your website that, once executed, replaces a link with the player. The easiest way to configure a player and generate the markup needed to embed it is through our CMS. However, some may need to manually generate this markup - the following documentation is for them.

If I Were You

Two Ways to Embed a Player

There are two different ways to embed a player:

  1. Using a tiny JS loader (recommended)
  2. Directly embedding an <iframe> tag

Embedding Via a Tiny JS Loader

The recommended way to embed a player is to place one or more HTML anchors <a> into the page, each with its own set of custom data attributes (described below), and a tiny JavaScript file that parses the player’s anchors and replaces them with the player itself. This is the recommended method as it’s more flexible and performant compared to the alternative, and should be used whenever you can embed a JS file into the hosting page.

To embed a player, you should place an HTML anchor element in your page:

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="user_id=1" data-width="100%" data-height="200px">Listen to my podcast</a>

And a JS script tag right before the end of your </body>:

<script async src="https://widget.spreaker.com/widgets.js"></script>

The anchor accepts some custom data attributes that give you the freedom to configure many aspects of the player itself.

Attribute Required Description
data-resource Yes The primary episode you want to display in the player. It can be a single episode data-resource="episode_id=EPISODE-ID", a show’s latest episode data-resource="show_id=SHOW-ID", or a user’s latest episode data-resource="user_id=USER-ID".
data-width No Player’s width (can be in % or px).
data-height No Player’s height (can be in % or px).
data-theme No Player’s UI theme. Supported themes are: light (default) and dark.
data-cover No HTTPS URL of the image to display as the player’s background.
data-playlist No Configures how the playlist should be built. It can be data-playlist="false" to disable the playlist, data-playlist="user" to display all of a user’s episodes in the playlist, or data-playlist="show" to display all episodes from all shows in the playlist. The default behavior depends on the data-resource.
data-playlist-continuous No Enables or disables continuous playlist playback. When set as true, it will continuously play every episode in the playlist until it ends.
data-playlist-loop No Enables or disables loop playlist playback when continuous playback is enabled. When set as true and playlist continuous playback is enabled as well, it will loop the playlist continuously (defaults to false).
data-playlist-autoupdate No Enables or disables playlist autoupdate, when a new episode is published. This feature is enabled by default.
data-autoplay No Enables or disables autoplay. When true, the player will start playing automatically as soon as it loads. Autoplay doesn’t work on most mobile browsers. Defaults to false.
data-live-autoplay No When true and a new LIVE is onair, the player will start playing automatically, no matter if data-autoplay is disabled or the player is already playing another episode. Defaults to false.
data-chapters-image No Enables or disables the display of chapters images in the player. Defaults to true.

IMPORTANT: The anchor must have the attribute class="spreaker-player", otherwise it will be ignored by the loader script, and won’t get replaced by the player.

Example: Sharing a single episode, with no playlist

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="episode_id=9146245" data-width="100%" data-height="200px">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Example: Sharing a show’s latest episode, with a playlist

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="show_id=1391532" data-width="100%" data-height="200px">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Example: Sharing a user’s latest episode, with a playlist

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="user_id=8100025" data-width="100%" data-height="200px">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Example: Sharing a user’s latest episode, with no playlist

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="user_id=8100025" data-width="100%" data-height="200px" data-playlist="false">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Example: Sharing a specific episode, with a playlist displaying all the episodes of a show

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="episode_id=9146245" data-width="100%" data-height="200px" data-playlist="show">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Directly Embedding an iFrame

In some circumstances, it may occur that you’ll need to embed the player in a page that doesn’t allow JavaScript files. In these cases, you can directly embed the <iframe> instead:

<iframe src="https://widget.spreaker.com/player?show_id=1391532" width="100%" height="200px" frameborder="0"></iframe>

To configure the player, you can pass a set of options as query string parameters. The following parameters are supported:

Parameter Required Description
episode_id or show_id or user_id Yes The primary episode you want to display in the player. It can be a single episode episode_id=EPISODE-ID, a show’s latest episode show_id=SHOW-ID, or a user’s latest episode user_id=USER-ID.
theme No Player’s UI theme. Supported themes are: light (default) and dark.
cover_image_url No HTTPS URL of an image to display as the player’s background.
playlist No Configures how the playlist should be built. It can be playlist=false to disable the playlist, playlist=user to display all of a user’s episodes in the playlist, or playlist=show to display all of a show’s episodes in the playlist.
playlist-continuous No Enables or disables continuous playlist playback. When set as true, it will continuously play all episodes in the playlist until it ends.
playlist-loop No Enables or disables loop playlist playback when continuous playback is enabled. When set as true and playlist continuous playback is enabled as well, it will loop the playlist continuously (defaults to false).
playlist-autoupdate No Enables or disables the playlist autoupdate, when a new episode is published. This feature is enabled by default.
autoplay No Enables or disables autoplay. When true, the player will start playing automatically as soon as it loads. Autoplay doesn’t work on most mobile browsers. Defaults to false.
live-autoplay No When true and a new LIVE is onair, the player will start playing automatically, no matter if autoplay is disabled or the player is already playing another episode. Defaults to false.
chapters-image No Enables or disables the display of chapters images in the player. Defaults to true.

Example: Sharing a single episode, without a playlist

<iframe src="https://widget.spreaker.com/player?episode_id=9146245" width="100%" height="200px" frameborder="0"></iframe>

Example: Sharing a show’s latest episode, without a playlist

<iframe src="https://widget.spreaker.com/player?show_id=1391532&playlist=false" width="100%" height="200px" frameborder="0"></iframe>

Embedded Player JS API

If you choose to embed the player using the tiny JS loader, you will also have a set of javascript API in the hosting page, through which you can control the player programmatically.

The loader script exposes the SP.getWidget(IFRAME) function to the global scope, that returns an object through which you can control and get the state of the widget player. The following methods are provided on the object returned by SP.getWidget():

Method Type Description
play() Sync Plays the current episode.
pause() Sync Pauses the current episode.
seek(POSITION) Sync Seeks the current episode to POSITION (expressed in milliseconds). This method doesn’t change the playback state, so if it was playing it will continue to play, otherwise it will not start to play.
load(EPISODE-ID) Sync Loads a different episode in the player. The input EPISODE-ID must be an episode already loaded in the playlist.
playPrev() Sync Plays the previous episode in the playlist (if any).
playNext() Sync Plays the next episode in the playlist (if any).
getPosition(CB) Async This method takes in input a callback CB, that will get called with the current playback position, progress and duration: function(position, progress, duration) {}.
getDuration(CB) Async This method takes in input a callback CB, that will get called with the current playback duration: function(duration) {}.
getState(CB) Async This method takes in input a callback CB, that will get called with the current episode and its state: function (episode, state, isPlaying) {}.

Supported browsers: the two-way communication between the hosting page and the embedded player has been implemented using MessageChannel. Modern browsers support it, but some old browsers could not be supported. If a method is called successfully it will return true, otherwise false (on unsupported browsers).

Example: play and pause buttons in the hosting page

<a id="my-widget" class="spreaker-player" href="https://www.spreaker.com/show/1391532" data-resource="show_id=1391532" data-width="100%" data-height="300px"></a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

<button id="cmd-play" class="button secondary small">play()</button>
<button id="cmd-pause" class="button secondary small">pause()</button>

<script>
    window.onload = function() {
        var widget   = SP.getWidget("my-widget");
        var playBtn  = document.getElementById("cmd-play");
        var pauseBtn = document.getElementById("cmd-pause");

        playBtn.addEventListener("click", function() {
            widget.play();
        });

        pauseBtn.addEventListener("click", function() {
            widget.pause();
        });
    });
</script>

Live example

This live example shows how the Embedded Player API works. Please click the following buttons to give it a try and checkout the page’s sources for more information (it’s pretty straightforward):

Getters output will be printed here.

If I Were You

The Embedded Player on WordPress

Spreaker provides a WordPress plugin to easily embed the Spreaker player in your WordPress blog or website.

It basically adds the support for a shortcode in the form [spreaker type=player ...] to your WordPress, replacing all the shortcodes with the related player.

The shortcode supports all the attributes supported by the JS loader without the data- prefix. For example, the resource is specified with the resource attribute (instead of data-resource), the background image with cover (instead of data-cover) and so on.

Example: share a single episode, without playlist

[spreaker type=player resource="episode_id=9146245" width="100%" height="200px"]

Example: share the latest episode by show, with playlist

[spreaker type=player resource="show_id=1391532" width="100%" height="200px"]