Music & Playlists

Music & Playlists

This documentation refers to the properties and methods of this interface as accessed only through the "data-bind" html attribute used for interface theming. For information on how to access this interface and its properties using standard javascript code, have a look at our developer documentation.

The music data-bind accessor will give you access to the music player, the playlists, and all of the music that has been loaded by the flex app. It can be used to build themed content around the music and playlists in the app, and also to manipulate the music interface in different ways (such as changing songs, changing playlists, or showing licensing options for a given beat). We'll run through all of its properties to see what data is available and the ways you can use it.

Note: Flex will not process your "data-bind" attributes automatically. Refer to the security implications section of our theming guide for more information on how to enable and use the "data-bind" attribute safely on your website.

Sandbox

Open SandboxWant to get hands on with the flex framework? Use any of the html examples from this guide in our sandbox!


Playing: music.playing() Boolean

This property contains a boolean value (true or false). It will be true if the music player is currently playing music, and false otherwise. It can be used to theme content around whether music is currently playing or not.

Example:
<span data-bind="if: music.playing()"><button data-bind="click: music.pause">Pause</button></span>

In the example above, we use the "if" binding on a <span> element to display a button which will pause the player if it's playing.


Paused: music.paused() Boolean

This property contains a boolean value (true or false). It will be true if the music player is currently paused/stopped, and false otherwise. It can be used to theme content around whether the music is currently paused or not.

Example:
<span data-bind="if: music.paused()"><button data-bind="click: music.play">Play</button></span>

In the example above, we use the "if" binding on a <span> element to display a button which will play the music if it's paused.


Muted: music.muted() Boolean

This property contains a boolean value (true or false). It will be true if the music player volume level is currently muted, and false otherwise. It can be used to theme content around whether the music is currently muted or not.

Example:
<span data-bind="if: music.muted()"><button data-bind="click: music.unmute">Unmute</button></span>
<span data-bind="if: !music.muted()"><button data-bind="click: music.mute">Mute</button></span>

In the example above, we use the "if" binding on a <span> element to display a button which will unmute the volume if it's muted, or a button to mute the volume if it's unmuted.


Volume: music.volume() Float

This property contains a floating value between 0 and 1 which indicates the current volume level of the music player. It can be used to theme content around the current volume level of the music player.

Examples:
Volume: <span data-bind="text: parseInt(music.volume() * 100) + '%'"></span>
<hr data-bind="style: { width: music.volume() * 100 + '%' }">

In the first example, we simply show the volume level in percentage points. In the second example, we are actually using the volume level to control the width of the <hr> (horizontal rule) html element.


Seek Position: music.seekPosition() Float

This property contains a floating value between 0 and 100 which indicates the current music player time position as a percentage of the total song length. It can be used to theme content around the current play head position of the music player.

Examples:
Seek Position: <span data-bind="text: parseInt(music.seekPosition()) + '%'"></span>
<hr data-bind="style: { width: music.seekPosition() + '%' }">

In the first example, we simply show the seek percentage. In the second example, we are actually using the seek position to control the width of the <hr> (horizontal rule) html element.


Active Playlist Info: music.activePlaylist() Object

This property contains the currently active playlist object. This would be the playlist which the now playing beat belongs to. The playlist object contains the following properties:


Title: music.activePlaylist().title String

This property contains the title of the currently active playlist.


Category: music.activePlaylist().category String

This property contains the name of the category the currently active playlist belongs to.


Description: music.activePlaylist().description String

This property contains the description of the currently active playlist.


Producers: music.activePlaylist().producers Array

This property contains an array of the producer id's which the currently active playlist is limited to (if any).

music.activePlaylist().producers[index] String

Each array item is a string value that contains an individual producer id.


Playlist ID: music.activePlaylist().id String

This property contains the system id of the currently active playlist. It can be used as a reference for other accessors.


Is Default: music.activePlaylist().isDefault Boolean

This property contains a boolean value (true/false) which indicates whether this playlist is the default playlist for the app.


Example:
<!-- ko if: music.activePlaylist().id -->
  <h2 data-bind="html: music.activePlaylist().title"></h2>
  <em data-bind="html: music.activePlaylist().category + ' Playlist'"></em>
  <div data-bind="html: music.activePlaylist().description"></div>
  <div data-bind="if: music.activePlaylist().producers.length">
    <h4>Featured Producers</h4>
    <ul data-bind="foreach: music.activePlaylist().producers">
      <!-- ko with: $root.producers.byId()[$data] -->
      <li><span data-bind="text: name"></span></li>
      <!-- /ko -->
    </ul>
  </div>
<!-- /ko -->

In the example above, we use the first "if" binding to wait until our app has a playlist loaded before showing the rest of the contents of this snippet. The example would work without it, but it prevents empty content from showing until the data is ready.

Also, you'll notice that we use the "if" binding another time inside this example to test if the playlist producers array actually has any producers in it (by checking its length property, since it's an array). This condition allows us to only show the featured producers heading and list when there are actually producers associated with the playlist.

One other thing to note in this example is the demonstration of the containerless "with" binding. We use this binding syntax in our example to switch our binding context to the producer object in order to access properties of the producer.


Active Playlist Media: music.activePlaylistItems() Array

This property can be used to build themed content around the currently active playlist. It contains an array of all the beats in the currently active playlist. Each array item is an individual beat object which contains all of the information associated with that beat.


music.activePlaylistItems()[index] Object

Each array item is a beat object which contains all of the same properties as the nowplaying() object. Refer to the now playing theme interface documentation to see all of the beat properties that you can use.


Examples:
<ul data-bind="foreach: { data: music.activePlaylistItems(), as: 'beat' }">
  <li><a href="#" data-bind="html: beat.title, click: $root.music.playMedia"></a></li>
</ul>
<ol data-bind="foreach: { data: music.activePlaylistItems(), as: 'beat' }">
  <li>
    <img data-bind="attr: { src: beat.thumbnail }" />
    <strong data-bind="html: beat.title"></strong>
    <a href="#" data-bind="click: $root.music.playMedia">Play</a>
    <a href="#" data-bind="click: $root.music.showLicenseOptions">Purchase Options</a>
  </li>
</ol>

In the first example, we use the "foreach" binding to cycle through the beats in the currently active playlist, and create a list item for each. Inside the list item, we show a link with the beat title as the link text, and when it is clicked, the beat begins playing in the player.

In the second example, we go a step further by again cycling through the beats with the "foreach" binding, but we also show the thumbnail image inside each list item, and also a separate link to play the beat, and a separate link to show the licensing options for the beat.


All Playlist Keys: music.playlistKeys() Array

This property can be used to build themed content around all of the playlists in the application. It contains an array of all of the playlist ID's currently available in the flex app.


music.playlistKeys()[index] String

Each array item is a string which is the id of an individual playlist. To access the playlist information, use the id as a sub-property of the music.playlists data model.


Example:
<ul data-bind="foreach: music.playlistKeys()">
  <!-- ko with: $root.music.playlists[$data] -->
  <li>
    <span data-bind="html: title"></span>
    <a href="#" data-bind="click: $root.music.changePlaylist">Switch Playlist</a>
  </li>
  <!-- /ko -->
</ul>

All Playlist Info: music.playlists Object

This property can be used to build themed content around a specific playlist in the application. All information about a playlist can be accessed using it's playlist id as a sub-property to this object. You can get a list of all available playlist ids using the music.playlistKeys() data model.


music.playlists[playlistid] Object

Each playlist (accessed by the playlist id), is a playlist object which contains all of the same properties as the music.activePlaylist() data model.


Example:
<!-- ko foreach: { data: music.playlistKeys(), as: 'playlistid' } -->
  <!-- ko with: $root.music.playlists[playlistid] -->
  <div data-bind="if: isDefault">
    Default Playlist: <strong data-bind="html: title"></strong>
    <!-- ko if: playlistid != $root.music.activePlaylist().id -->
    <a href="#" data-bind="click: $root.music.changePlaylist">Switch to Playlist</a>
    <!-- /ko -->
  </div>
  <!-- /ko -->
<!-- /ko -->

We've got a lot going on in this example. The end result is that we show the title of the default playlist in the app, and a link to switch to it (if it's not already the active playlist). First we use a "foreach" binding to cycle through each of the playlists. Then we use a "with" binding to switch into the context of the playlist itself. We follow that with an "if" binding to test if it is the default playlist, and if it is we display the playlist title. Finally, we use another "if" binding to test if the active playlist is different than the default, and if it is, we display a link that will change the playlist back to the default one.

In this example, you can see how multiple bindings can be combined together with different data models in order to build dynamic themed interfaces.


All Playlist Media: music.Playlist Object

This property can be used to build themed content around the actual music which composes any specific playlist in the application. All of the currently loaded beats for a playlist and other playlist information can be accessed using the playlist id as a sub-property to this object.


music.Playlist[playlistid].count() Integer

This method returns the total amount of beats that are part of the playlist, not the amount of beats that have been currently loaded for the playlist.

If you want the count for the amount of beats that have already been loaded for this playlist, then you would use something like music.Playlist[playlistid]().length.


music.Playlist[playlistid]() Array
music.Playlist[playlistid]()[index] Object

Each array item is a beat object which contains all of the same properties as the nowplaying() object. Refer to the now playing theme interface documentation to see all of the beat properties that you can use.


Examples:
<h1>Shopping Cart Beats:</h1>
Total beats loaded:
  <span data-bind="text: music.Playlist['cart']().length"></span><br>
Total beats available:
  <span data-bind="text: music.Playlist['cart'].count()"></span><br>
<ul data-bind="foreach: music.Playlist['cart']()">
  <li>
    <img data-bind="attr: { src: thumbnail }" />
    <strong data-bind="html: title"></strong>
    <a href="#" data-bind="click: $root.music.playMedia">Play</a>
    <a href="#" data-bind="click: $root.music.showLicenseOptions">Purchase Options</a>
  </li>
</ul>

All Playlists (Grouped): music.groupedPlaylists() Array

This property is an array of objects. Each object in the array represents a different grouping of playlists. It can be used to build themed content around the playlists in the application as they are grouped together by category.


music.groupedPlaylists()[index] Object

Each array item is an object which contains data about the group.

Key: music.groupedPlaylists()[index].key String

This property contains the name of the playlist group.


Items: music.groupedPlaylists()[index].items Array

This property is an array of individual playlist objects. It contains all of the playlists included in the group.


music.groupedPlaylists()[index].items[index] Object

Each array item is a playlist object which contains all of the same properties as the music.activePlaylist() data model.


Example:
<div data-bind="foreach: music.groupedPlaylists()">
  <h2>Group: <span data-bind="text: key"></span></h2>
  <ul data-bind="foreach: items">
    <li>
      <h4 data-bind="html: title"></h4>
      <em data-bind="text: $root.music.Playlist[id]().length + ' Beats'"></em>
      <div data-bind="html: description"></div>
    </li>
  </ul>
</div>

In this example, we cycle through each playlist group with a "foreach" binding, and display the name of the group, and a list of the playlists that are in the group. We also show the number of beats which are in each playlist.


Interface Methods

Select Media: music.selectMedia Function

This method can be used on any event handler binding (i.e. "click") within a "foreach" binding of a beats playlist, such as music.activePlaylistItems(). It will select the associated beat from the foreach loop and make it the currently selected beat in the application, but it will not begin playing automatically.

Example:
<ul data-bind="foreach: music.activePlaylistItems()">
  <li><a href="#" data-bind="html: title, click: $root.music.selectMedia"></a></li>
</ul>

Important Note: Whenever you use this method inside of a control flow (i.e. "foreach") binding, you need to refer to the method like this: $root.music.selectMedia. Learn more about binding contexts used in knockout.js.


Play Media: music.playMedia Function

This method can be used on any event handler binding (i.e. "click") within a "foreach" binding of a beats playlist, such as music.activePlaylistItems(). It will select and begin playing the associated beat from the foreach loop.

Example:
<ul data-bind="foreach: music.activePlaylistItems()">
  <li><a href="#" data-bind="html: title, click: $root.music.playMedia"></a></li>
</ul>

Important Note: Whenever you use this method inside of a control flow (i.e. "foreach") binding, you need to refer to the method like this: $root.music.playMedia. Learn more about binding contexts used in knockout.js.


Show All Beat License Options: music.showLicenseOptions Function

This method can be used on any event handler binding (i.e. "click") within a "foreach" binding of a beats playlist, such as music.activePlaylistItems(). It will show a dialog with all of the licensing options and associated information for the beat (including "add to cart" buttons) in the foreach loop.

Example:
<ul data-bind="foreach: music.activePlaylistItems()">
  <li><a href="#" data-bind="html: title, click: $root.music.showLicenseOptions"></a></li>
</ul>

Important Note: Whenever you use this method inside of a control flow (i.e. "foreach") binding, you need to refer to the method like this: $root.music.showLicenseOptions. Learn more about binding contexts used in knockout.js.


Show Individual License Option: music.showLicense Function

This method can be used on any event handler binding (i.e. "click") within the "foreach" binding of the licensing options for a beat object, such as nowplaying().licensing.options. It will show a dialog with all of the information related to the specific license option (including an "add to cart" button) in the foreach loop.

Example:
Purchase options for the currently playing beat:
<ul data-bind="foreach: nowplaying().licensing.options">
  <li>
    <strong data-bind="text: name"></strong> (<span data-bind="text: price"></span>)
    <a href="#" data-bind="click: $root.music.showLicense">More Info</a>
  </li>
</ul>

Important Note: Whenever you use this method inside of a control flow (i.e. "foreach") binding, you need to refer to the method like this: $root.music.showLicense. Learn more about binding contexts used in knockout.js.


Show All Available Playlists: music.showPlaylists Function

This method can be used on any event handler binding (i.e. "click") to show an automatic dialog for the user to select from any of the currently available playlists in the application.

Example:
<a href="#" data-bind="click: music.showPlaylists">Show Available Playlists</a>

Change The Active Playlist: music.changePlaylist Function

This method can be used on any event handler binding (i.e. "click") within the binding context of a playlist object, such as music.playlists[playlistid]. It will change the currently active playlist to that of the context playlist.

Example:
<ul data-bind="foreach: { data: music.playlistKeys(), as: 'playlistid' }">
  <!-- ko with: $root.music.playlists[playlistid] -->
  <li><a data-bind="html: title, click: $root.music.changePlaylist"></a></li>
  <!-- /ko -->
</ul>

Important Note: Whenever you use this method inside of a control flow (i.e. "with") binding, you need to refer to the method like this: $root.music.changePlaylist. Learn more about binding contexts used in knockout.js.


Play: music.play Function

This method can be used on any event handler binding (i.e. "click") to begin play on the music player for whatever beat is currently selected (if the player is not already playing). If the player is already playing, this command will be ignored.

Example:
<a href="#" data-bind="click: music.play">Play</a>

Pause: music.pause Function

This method can be used on any event handler binding (i.e. "click") to pause play on the music player for whatever beat is currently selected (if the player is playing). If the player is already paused, this command will be ignored.

Example:
<a href="#" data-bind="click: music.pause">Pause</a>

Play Next: music.playNext Function

This method can be used on any event handler binding (i.e. "click") to advance to the next beat in the playlist and begin play. If the currently playing beat is already at the end of the playlist, this command will be ignored.

Example:
<a href="#" data-bind="click: music.playNext">Play Next</a>

Play Previous: music.playPrevious Function

This method can be used on any event handler binding (i.e. "click") to rewind to the previous beat in the playlist and begin play. If the currently playing beat is already at the start of the playlist, this command will be ignored.

Example:
<a href="#" data-bind="click: music.playPrevious">Play Previous</a>

Mute: music.mute Function

This method can be used on any event handler binding (i.e. "click") to mute the audio output of the music player. If the audio is already muted, this command will be ignored.

Example:
<a href="#" data-bind="click: music.mute">Mute Audio</a>

Unmute: music.unmute Function

This method can be used on any event handler binding (i.e. "click") to unmute the audio output of the music player. If the audio is already unmuted, this command will be ignored.

Example:
<a href="#" data-bind="click: music.unmute">Unmute Audio</a>