Article

Accessing MusicKit Features Using JavaScript

Add a music player, Apple Music content, and media controls to your web content using JavaScript methods.

Overview

After configuring and authorizing MusicKit JS in your web content, you can add functionality for the player using JavaScript.

Access a configured MusicKit JS instance by calling getInstance.

Create a playback queue with the contents of an album, and start playback (ensuring authorization) using the following code:

let music = MusicKit.getInstance();

// Set the playback queue to a specific album, and play
music.setQueue({
  album: '1025210938'
});

// Playback Controls
music.play();
music.pause();
music.stop();

To play media, there must be, at a minimum, a MusicKit.Player instance that contains a MusicKit.Queue instance with a single MusicKit.MediaItem object.

Initialize a Playback Queue with Albums and Playlists

You can initialize a playback queue by using the setQueue method, either with individual media items, or with an album or playlist.

To set a queue using an album's URL:

let music = MusicKit.getInstance();
let url = 'https://itunes.apple.com/us/album/hamilton-original-broadway-cast-recording/1025210938';
music.setQueue({ url: url }).then(function(queue) {
  // Queue is instantiated and set on music player.
});

To set a queue using a playlist's URL:

let music = MusicKit.getInstance();
let url = 'https://itunes.apple.com/us/playlist/pl.d133de76fb4f4ccf98846231899874c0';
music.setQueue({ url: url }).then(function(queue) {
  // Queue is instantiated and set on music player.
});

Initialize a Playback Queue with Apple Music API Identifiers

You can also initialize a playback queue using an album identifier or a playlist identifier.

To set a queue using an album identifier:

let music = MusicKit.getInstance();
music.setQueue({ album: '1025210938' }).then(function(queue) {
  // Queue is instantiated and set on music player.
});

To set a queue using a playlist identifier:

let music = MusicKit.getInstance();
music.setQueue({ playlist: 'pl.d133de76fb4f4ccf98846231899874c0' }).then(function(queue) {
  // Queue is instantiated and set on music player.
});

Access Apple Music Content

After setting up your player, you can access Apple Music content using two different APIs.

Apple Music API

The Apple Music API gives you access to the entire Apple Music catalog of media items.

You can access the MusicKit.API through the api property on a configured MusicKit JS instance.

let music = MusicKit.getInstance();
let album = music.api.album(1025210938);

In order to play media, at a minimum, there must be a MusicKit.Player instance that contains a MusicKit.Queue instance which contains a single MusicKit.MediaItem object.

You can initialize a playback queue by using the setQueue method.

Cloud Library API

The Cloud Library gives you access to all the media items saved by a user from Apple Music to their Cloud Library.

You can access the Cloud Library API through the library property in the MusicKit.API in a configured MusicKit JS instance.

let music = MusicKit.getInstance();
let album = music.library.api.album(1025210938);

Add API Query Parameters

Both the MusicKit.API and MusicKit.Library methods accept an optional dictionary of query parameters. Keys defined in the dictionary are serialized as key-value pairs. This dictionary is passed directly to the Apple Music API.

let music = MusicKit.getInstance();
let results = music.api.search('james brown', { limit: 2, types: 'artists,albums' });
// Loads https://api.music.apple.com/v1/catalog/us/search?term=james+brown&limit=2&types=artists,albums

See Also

Getting Started

Adding MusicKit Features Using HTML

Add a music player, Apple Music content, and media controls to your web content using declarative markup elements.