Comment on page

Apple Music

High level overview

Allow users to authenticate with Apple Music, search for music in Apple Music's catalog, and listen to music.


Technical reference

This plugin includes the following interactions with the ` Apple Music API, via the Web API and the Apple Musickit JS library.

Server Side Workflows

Get a Developer token

Developer tokens can be valid for up to 6 months and are used in two separate places: on the client side and server side of the application. It's best practice to generate a token that expires after a relatively short amount of time on the client side (for the "Developer Token (JWT)" in the Plugins tab) since this token is not secure and could be stolen by a technically sophisticated user.
  • Apple Developer Account Team ID
  • Apple Developer Account Key ID
  • Apple Developer Account Key (file)
  • Number of minutes until token expiration

Element Workflows

There is an Apple Music element which must be added to the page for music playback.

Initialize the element

Before doing any of the other Element Workflows, the element must be initialized with a valid, not-expired Developer token.

Authenticating from the app

After initialized, the user must authenticate with Apple Music (log into their Apple account) in order to listen to any music. This is true even for listening to music samples.

Music playback (play, pause, skip to next song, skip to any position in queue, play next, play later)

A number of actions exist for music playback. The only inputs for these actions are a Song ID for the "Play Next" and "Play Later" actions. The song ID can be gotten from the some Data API calls included with the plugin (see below for more info).
If additional functions are needed (shuffle playback, fast-forwarding playback, adding entire albums to the queue, etc.) then contact [email protected] for more info.

Element States

The element exposes the following states:
  • Is Playing (for playback): true/false
  • Playback State (text), has a number of options (playing, stopped, paused, seeking, loading, etc.)
  • Authorized (true/false)
  • Queued Songs (IDs) (list of texts)
  • Queue Position (number): number of the current song in the queue (after a song plays, it remains in the queue)
  • Now playing (song ID) (text)
  • Current Playback Time (number): seconds since start of current song
  • Current Playback Time Remaining (number): seconds until end of current song
  • Storefront (text): a 2-character code for the country where the user is located. used in the search data API call
  • Music User Token (text): Not currently used, User's token (for user-specific API requests, like checking their library's content)
Please note that the queue will not erase items once they are played, but instead will automatically move onto the next item in the queue.

Data Workflows

Searching for music in Apple Music's catalog

The "Search Catalog" data API will return a list of songs, artists, albums, playlists (and potentially other types? not sure if other types exist).
For the current iteration (August 4 2020) of the plugin, only song IDs will be useful for audio playback, and the "types" field of this workflow should be set to "songs".

Get a song's data by ID

Send a single song's ID to this data API call in order to get data about the song.

Additional resources

For reference, the following pages were helpful in setting up the plugin:
Video walkthrough (august 4):
Creating a Developer Token:
Web API:
MusicKit JS:
For extending the plugin, other projects which use the same Musickit JS API:
Misc. guide (may be useful for implementing other functions):