Framework

MusicKit JS

Add an Apple Music player to your web app.

Overview

MusicKit JS lets users play songs from Apple Music and their Cloud Library inside your JavaScript app. When a user provides permission to access their Apple Music account, your JavaScript app can create playlists, add songs to their library, and play any of the millions of songs in the Apple Music catalog directly in a browser, with no additional plugins.

MusicKit JS Configuration

Some basic setup is required before you begin to use MusicKit JS.

Creating an Apple Music API Token

You use a developer token to authenticate yourself as a trusted developer and member of the Apple Developer Program and to use MusicKit JS. You can find more information about creating an Apple Music API token in Developer Account Help.

Embedding MusicKit JS in Your Webpage

Use the script tag and link to Apple’s hosted version of MusicKit JS:

<script src=“https://js-cdn.music.apple.com/musickit/v1/musickit.js”></script>

Configuring MusicKit JS

You can configure MusicKit JS with a default markup setup to quickly get you started with the library, or with JavaScript to give you more control over the customization of your player.

To configure the library using only markup, use the following meta tags:

<head>
 ...
 <meta name="apple-music-developer-token" content="DEVELOPER-TOKEN">
 <meta name="apple-music-app-name" content="My Cool Web App">
 <meta name="apple-music-app-build" content="1978.4.1">
 ...
</head>

For more control over the library and player, use JavaScript to configure the library:

document.addEventListener('musickitloaded', function() {
  // MusicKit global is now defined
  MusicKit.configure({
    developerToken: 'DEVELOPER-TOKEN',
    app: {
      name: 'My Cool Web App',
      build: '1978.4.1'
    }
  });
});

User Authorization

There are two primary ways to handle authorization in your implementation.

Declarative Markup

Your users can authorize with Apple Music using these authorization buttons. These buttons are bound to id to signal that they should be declared only once.

Use declarative markup to bind handlers to a <button> or an <a> tag that contain an id attribute of apple-music-authorize or apple-music-unauthorize.

When a user activates one of the decorated tags, the corresponding MusicKit JS method is triggered (authorize and unauthorize respectively).

<button id="apple-music-authorize"></button>
<button id="apple-music-unauthorize"></button>

JavaScript Methods

Wrap MusicKit JS methods in the authorize method, which returns a promise. The promise resolves with a valid music user token when the user signs in and gives authorization.

let music = MusicKit.getInstance();

 // This is called with or without authorization: 
 music.player.play();

 // This ensures user authorization before calling play():
 music.authorize().then(function() {
   music.player.play();
 });

 // You can wrap any method to ensure authorization before calling:
 music.authorize().then(function() {
   music.api.library.albums.then(function(cloudAlbums) {
     // user's cloudAlbums
   });
 });

Topics

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.

Accessing MusicKit Features Using JavaScript

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

Using MusicKit

MusicKit

Use the MusicKit namespace to configure MusicKit JS and to access app instances, control music playback, and fetch data from the Apple Music API.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software