MusicKit on the Web

https://js-cdn.music.apple.com/musickit/v3/docs/
Admin
MusicKit on the Web is a JavaScript library that enables web developers to integrate Apple Music...
Tokens:56,761
Snippets:858
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get MusicKit Instance

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit--page&viewMode=story

Access the configured MusicKit Instance singleton. `configure()` must have been called first, otherwise this will return `undefined`.

```javascript
const music = MusicKit.getInstance();
```

--------------------------------

### skipToNextItem

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-musickit-instance--page

Starts playback of the next item in the playback queue. This method returns a Promise that resolves with void.

```APIDOC
## skipToNextItem

### Description
Starts playback of the next item in the playback `queue`.

### Method
`skipToNextItem`

### Response
#### Success Response (void)
Returns a Promise that resolves with void.
```

--------------------------------

### skipToNextItem

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Starts playback of the next item in the playback queue.

```APIDOC
## skipToNextItem

### Description
Starts playback of the next item in the playback `queue`.

### Method
`skipToNextItem`

### Response
#### Success Response (Promise<void>)
Returns a Promise that resolves when the next item starts playing.
```

--------------------------------

### skipToNextItem

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page&viewMode=story

Starts playback of the next item in the playback queue. This method returns a Promise that resolves with void.

```APIDOC
## skipToNextItem

### Description
Starts playback of the next item in the playback `queue`.

### Method
`skipToNextItem(): Promise<void>`
```

--------------------------------

### Artwork Object Example

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=using-album-art-and-images--page&viewMode=story

An example of an Artwork object structure as returned by the Apple Music API.

```json
"artwork": {
    "width": 3000,
    "height": 3000,
    "url": "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/33/fd/32/33fd32b1-0e43-9b4a-8ed6-19643f23544e/21UMGIM26092.rgb.jpg/{w}x{h}bb.jpg",
    "bgColor": "675f9a",
    "textColor1": "f3f6fb",
    "textColor2": "fbeaf0",
    "textColor3": "d7d8e8",
    "textColor4": "decedf"
}
```

--------------------------------

### Queue and play a music video

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Fplaying-music-videos--page

Use the setQueue method with the musicVideo content type and call play to start playback.

```javascript
const music = MusicKit.getInstance();

await music.setQueue({ musicVideo: '1565280313' });
await music.play();
```

--------------------------------

### skipToPreviousItem

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Starts playback of the previous item in the playback queue.

```APIDOC
## skipToPreviousItem

### Description
Starts playback of the previous item in the playback `queue`.

### Method
`skipToPreviousItem`

### Response
#### Success Response (Promise<void>)
Returns a Promise that resolves when the previous item starts playing.
```

--------------------------------

### Async Loop to Fetch All Playlist Tracks and Initiate Playback

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=paginated-requests--page

An example of an asynchronous loop that continuously fetches pages of playlist tracks using the 'next' property until all data is retrieved. It then initiates playback of the collected tracks.

```javascript
const pageSize = 25;
const playlistId = 'pl.9b8a976ba78741d9925e6e9a050703de';
const urlPath = `/v1/catalog/{{storefrontId}}/playlists/${playlistId}/tracks`;
const tracks = [];
const music = MusicKit.getInstance();

let hasNextPage = true;
while (hasNextPage) {
  const queryParameters = {
    // Page size is always consistent
    limit: pageSize,

    // The length of the list of objects
    // is also the index of the next object,
    // assuming we started with the 0th object
    offset: tracks.length,
  };

  // Make a request for the next page
  const { data: { data: dataForPage = [], next } } = await music.api.music(urlPath, queryParameters);

  // Push the results to the cumulative array of objects
  tracks.push(...dataForPage);

  // Cast the `next` property to a boolean, where `undefined`
  // becomes `false`, but any URL value would be `true`
  //
  // When this is `false`, then the loop stops
  hasNextPage = !!next;
}

// Outside of the loop, `tracks` now contains results from all pages

// Initiate playback of the `tracks`
await music.setQueue({ items: tracks });
await music.play();
```

--------------------------------

### skipToPreviousItem

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-musickit-instance--page

Starts playback of the previous item in the playback queue. This method returns a Promise that resolves with void.

```APIDOC
## skipToPreviousItem

### Description
Starts playback of the previous item in the playback `queue`.

### Method
`skipToPreviousItem`

### Response
#### Success Response (void)
Returns a Promise that resolves with void.
```

--------------------------------

### skipToPreviousItem

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page&viewMode=story

Starts playback of the previous item in the playback queue. This method returns a Promise that resolves with void.

```APIDOC
## skipToPreviousItem

### Description
Starts playback of the previous item in the playback `queue`.

### Method
`skipToPreviousItem(): Promise<void>`
```

--------------------------------

### play

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Starts or resumes playback of the current media item. Note that this action may fail if the user has not yet interacted with the player, as browsers often restrict audio playback initiation without user consent.

```APIDOC
## play

### Description
Initiates playback of the `nowPlayingItem`.

**Note:** This could result in an error if the user has not interacted with the player yet, as most browsers prevent audio playback without user interaction.

### Method Signature
`play(): void`
```

--------------------------------

### play

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-musickit-instance--page

Initiates or resumes playback of the current media item. Note that user interaction might be required in some browsers to start playback.

```APIDOC
## play

### Description
Initiates playback of the `nowPlayingItem`.
Note: This could result in an error if the user has not interacted with the player yet, as most browsers prevent audio playback without user interaction.

### Method Signature
`play(): void`
```

--------------------------------

### MusicKit Instance Properties

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page&viewMode=story

Properties of the MusicKit instance that allow you to get information about the current playback state, control playback settings, and access related objects.

```APIDOC
## MusicKit Instance Properties

### `api`
**Type:** `MusicKitAPI`
See Accessing Content via the Apple Music API for more information.

### `bitrate`
**Type:** `MusicKit.PlaybackBitrate`
The bit rate for the media player. The bit rate is set automatically based on the client, but can be overridden by the app to a value from the enum `MusicKit.PlaybackBitrate`. Setting this property will affect the item played _next_ , not the currently playing item.
This property does not necessarily represent the actual bit rate of the item being played, only the target bit rate when the player selects the stream to play.
**Example**
```javascript
const music = MusicKit.getInstance();

// Instruct MusicKit to prefer the high-bit rate assets, when available
music.bitrate = MusicKit.PlaybackBitrate.HIGH;
```

### `currentPlaybackDuration`
**Type:** `Number` _read-only_
The duration of the `nowPlayingItem`, in seconds.

### `currentPlaybackProgress`
**Type:** `Number` _read-only_
Progress percentage between `0` and `1` indicating the current play head position for the `nowPlayingItem`. Useful for showing a playback progress bar UI, for instance.

### `currentPlaybackTime`
**Type:** `Number` _read-only_
The current position of the play head for the `nowPlayingItem`, in seconds.

### `currentPlaybackTimeRemaining`
**Type:** `Number` _read-only_
The current remaining playback time for the `nowPlayingItem`, in seconds.

### `isAuthorized`
**Type:** `Boolean` _read-only_
This is set to `true` after the user successfully signs in and authorizes the application via the `authorize()` method, or upon configuring the MusicKit instance if the user had previously authorized your application.

### `isPlaying`
**Type:** `Boolean` _read-only_
Indicates whether the player is in the playing state.

### `nowPlayingItem`
**Type:** `MediaItem` or `undefined` _read-only_
This is the `MediaItem` that is currently playing from the `Queue`.
This property will change when playback of a `Queue` starts, but will not unset on pause. It will change to the next item in the `Queue` once that item starts playing.

### `nowPlayingItemIndex`
**Type:** `Number` _read-only_
The index of the `nowPlayingItem` in the current playback `Queue`.

### `playbackRate`
**Type:** `Number`
The speed of playback, which is set directly on the `HTMLMediaElement` as the `HTMLMediaElement.playbackRate` property. The default rate is `1.0`, but this can be set to a value higher or lower to control the speed of playback. Different browsers will have different upper and lower bounds for this value.

### `playbackState`
**Type:** `MusicKit.PlaybackStates` _read-only_
The current playback state of the media player. See the Enum `MusicKit.PlaybackStates` for more information and the possible values.

### `previewOnly`
**Type:** `Boolean`
When a user with a valid Apple Music subscription authorizes your app, MusicKit will allow full playback of content from the Apple Music catalog. If the app does not have user authorization, then playback is restricted to non-DRM preview assets, which are snippets of the full media.
You can set this property to `true` to restrict MusicKit to playing only the preview assets, even when full playback is available. Setting this to `false` will not force full playback, but will instead return to the default behavior of determining what asset to play based on the user’s authorization and Apple Music Subscription status.

### `queue`
**Type:** `Queue` _read-only_
The current playback queue of the music player.

### `queueIsEmpty`
**Type:** `Boolean`
Indicates whether the current playback `queue` is empty.

### `repeatMode`
**Type:** `MusicKit.PlayerRepeatMode`
Set this to an Enum value from `MusicKit.PlayerRepeatMode` to control the repeat behavior during playback.
**Example**
```javascript
const music = MusicKit.getInstance();

// Setting to mode `all` will repeat the current queue after
// we play through it entirely
music.repeatMode = MusicKit.PlayerRepeatMode.all;
```
```

--------------------------------

### Configure MusicKit instance

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fstory%2Fget-started--page

Initialize MusicKit by calling MusicKit.configure within the musickitloaded event listener. Replace DEVELOPER-TOKEN with your actual signed developer token.

```javascript
document.addEventListener('musickitloaded', async function () {
  // Call configure() to configure an instance of MusicKit on the Web.
  try {
    await MusicKit.configure({
      developerToken: 'DEVELOPER-TOKEN',
      app: {
        name: 'My Cool Web App',
        build: '1978.4.1',
      },
    });
  } catch (err) {
    // Handle configuration error
  }

  // MusicKit instance is available
  const music = MusicKit.getInstance();
});
```

--------------------------------

### Accessing the Queue with setQueue

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Freference-javascript-queue--page

Demonstrates how to initialize a queue using setQueue and access the resulting MediaItems.

```javascript
const music = MusicKit.getInstance();

const queue = await music.setQueue({ album: '1025210938' });

console.log(queue.items); // log the MediaItems in the queue
```

--------------------------------

### Get Next Page URL using 'next' Property

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=paginated-requests--page

Shows how to use the 'next' property in an API response to get the URL for the subsequent page of results. The 'next' property is present when more data is available.

```javascript
const playlistId = 'pl.9b8a976ba78741d9925e6e9a050703de';
const urlPath = `/v1/catalog/{{storefrontId}}/playlists/${playlistId}/tracks`;

const { data: { next } } = await music.api.music(urlPath, { limit: 10 });

console.log(next); // '/v1/catalog/us/playlists/pl.9b8a976ba78741d9925e6e9a050703de/tracks?offset=10'
```

--------------------------------

### Configure MusicKit v1 vs v3

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Ftech-notes-migrating-to-v3--page

Shows the transition from synchronous to asynchronous configuration in MusicKit.

```javascript
const music = MusicKit.configure({})
```

```javascript
const music = await MusicKit.configure({})
```

--------------------------------

### Configure MusicKit v1 vs v3

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=tech-notes-migrating-to-v3--page

Illustrates the change in the `configure` method signature from an synchronous call in v1 to an asynchronous Promise-based call in v3. You should await the promise before calling `MusicKit.getInstance()` in v3.

```javascript
const music = MusicKit.configure({})
```

```javascript
const music = await MusicKit.configure({})
```

--------------------------------

### Set Queue Content by URL

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Freference-javascript-queue--page

Shows how to initialize a queue using a direct Apple Music URL reference.

```javascript
const music = MusicKit.getInstance();

const playlistURL = 'https://music.apple.com/us/playlist/pl.d133de76fb4f4ccf98846231899874c0';
await music.setQueue({ url: playlistURL });
```

--------------------------------

### Configure MusicKit on the Web

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit--page

Use the `configure` method to initialize MusicKit with your developer token and application details. This is a required step before accessing MusicKit functionalities.

```javascript
MusicKit.configure({
  developerToken: "YOUR_DEVELOPER_TOKEN",
  app: {
    name: "My Music App",
    build: "1.0.0"
  }
});
```

--------------------------------

### MusicKit.configure

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit--page&viewMode=story

Configures MusicKit on the web and returns a Promise that resolves with the configured MusicKit Instance. It requires a developer token and application details.

```APIDOC
## MusicKit.configure

### Description
Configures MusicKit on the web. This method must be called before accessing the MusicKit instance.

### Method
`configure(config: MusicKitConfiguration): Promise<MusicKitInstance>`

### Parameters
#### `config` (MusicKitConfiguration) - Required
  * `developerToken` (String) - Required
  * `app` (Object) - Required
    * `app.name` (String) - Required - The name of your application during the authorization flow.
    * `app.build` (String) - Optional - Current build number or version of your app.
    * `app.icon` (String) - Optional - A URL to the image used to represent your application during the authorization flow.
  * `bitrate` (MusicKit.PlaybackBitrate) - Optional - Can be used to target a bit rate for playback.
  * `storefrontId` (String) - Optional - The value used for the `{{storefrontId}}` token in the `path` argument of the Passthrough API method.

### Return Value
Returns a Promise that resolves with the configured MusicKit Instance.
```

--------------------------------

### MusicKit.configure

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit--page

Configures MusicKit on the Web and returns a Promise that resolves with the configured MusicKit Instance. It requires a developer token and application details.

```APIDOC
## MusicKit.configure

### Description
Configures MusicKit on the Web. This method is essential for initializing the MusicKit instance with your application's credentials and settings.

### Method
`configure(config: MusicKitConfiguration): Promise<MusicKitInstance>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (MusicKitConfiguration) - Required
  - **developerToken** (String) - Required
  - **app** (Object) - Required
    - **app.name** (String) - Required - The name of your application during the authorization flow.
    - **app.build** (String) - Optional - Current build number or version of your app.
    - **app.icon** (String) - Optional - A URL to the image used to represent your application during the authorization flow.
  - **bitrate** (MusicKit.PlaybackBitrate) - Optional - Can be used to target a bit rate for playback.
  - **storefrontId** (String) - Optional - The value used for the `{{storefrontId}}` token in the `path` argument of the Passthrough API method.

### Request Example
```javascript
MusicKit.configure({
  developerToken: "YOUR_DEVELOPER_TOKEN",
  app: {
    name: "My Music App",
    build: "1.0.0"
  }
}).then(instance => {
  // Use the MusicKit instance
});
```

### Response
#### Success Response (200)
- **MusicKitInstance** - The configured MusicKit instance.
```

--------------------------------

### MusicKit.configure

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-musickit--page

Configures MusicKit on the web and returns a Promise that resolves with the configured MusicKit Instance. It requires a developer token and application details.

```APIDOC
## MusicKit.configure

### Description
Configures MusicKit on the web. This method must be called before accessing the MusicKit instance.

### Method
`configure(config: MusicKitConfiguration): Promise<MusicKitInstance>`

### Parameters
#### `config` (MusicKitConfiguration) - Required

  * `developerToken` (String) - Required
  * `app` (Object) - Required
    * `name` (String) - Required - The name of your application during the authorization flow.
    * `build` (String) - Optional - Current build number or version of your app.
    * `icon` (String) - Optional - A URL to the image used to represent your application during the authorization flow.
  * `bitrate` (MusicKit.PlaybackBitrate) - Optional - Can be used to target a bit rate for playback.
  * `storefrontId` (String) - Optional - The value used for the `{{storefrontId}}` token in the `path` argument of the Passthrough API method.

### Return Value
Returns a Promise that resolves with the configured MusicKit Instance.
```

--------------------------------

### MusicKit.getInstance

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit--page

Accesses the singleton MusicKit Instance. This method should be called after `configure()` has been successfully executed.

```APIDOC
## MusicKit.getInstance

### Description
Accesses the configured MusicKit Instance singleton. Ensure `configure()` has been called prior to invoking this method.

### Method
`getInstance(): MusicKitInstance`

### Parameters
None

### Request Example
```javascript
const music = MusicKit.getInstance();
```

### Response
#### Success Response (200)
- **MusicKitInstance** - The singleton MusicKit Instance. Returns `undefined` if `configure()` has not been called.
```

--------------------------------

### MusicKit.getInstance

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit--page&viewMode=story

Accesses the singleton MusicKit Instance. This method should only be called after `configure()` has been successfully invoked.

```APIDOC
## MusicKit.getInstance

### Description
Accesses the configured MusicKit Instance singleton. Ensure `configure()` has been called prior to using this method.

### Method
`getInstance(): MusicKitInstance`

### Return Value
Returns the singleton MusicKit Instance. Returns `undefined` if `configure()` has not been called.

### Example
```javascript
const music = MusicKit.getInstance();
```
```

--------------------------------

### Access the Cloud Library API

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Faccessing-music-content--page

Access user-saved media by calling endpoints starting with v1/me/library. Ensure the user is authorized before making these requests.

```javascript
const music = MusicKit.getInstance();
// You should check authorization before accessing user's iCloud Music Library:
await music.authorize();
const result = await music.api.music('v1/me/library/albums');
```

--------------------------------

### MusicKit.getInstance

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-musickit--page

Accesses the singleton MusicKit Instance. This method should be called after `configure()` has been successfully invoked.

```APIDOC
## MusicKit.getInstance

### Description
Accesses the configured MusicKit Instance singleton. `configure()` must have been called first.

### Method
`getInstance(): MusicKitInstance`

### Return Value
Returns the singleton MusicKit Instance. Returns `undefined` if `configure()` has not been called.

### Example
```javascript
const music = MusicKit.getInstance();
```
```

--------------------------------

### Check Authorization for Playback and Data Access

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Fuser-authorization--page

Demonstrates how to handle media playback and library access, distinguishing between content that requires authorization and previews that do not.

```javascript
const music = MusicKit.getInstance();

// Music previews can be played without authorization:
await music.play();

// To play the full length of a song, check authorization before calling play():
await music.authorize();
await music.play();

// You should check authorization before accessing user's iCloud Music Library:
await music.authorize();
const { data: result } = await music.api.music('v1/me/library/albums');
// User's iCloud Music Library Albums
console.log(result.data);
```

--------------------------------

### Listen for Now Playing Item Will Change

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-events--page&viewMode=story

Use this event to get notified just before the currently playing media item is about to change. It provides access to the upcoming item's attributes.

```javascript
const music = MusicKit.getInstance();
music.addEventListener('nowPlayingItemWillDidChange', ({ item }) => {
  const { name, artistName } = item.attributes;
  console.log(`Will change to playing ${name} ${artistName}`);
});
```

--------------------------------

### Authorize MusicKit Instance

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Fuser-authorization--page

Initiates the sign-in and authorization flow for the user. If the user is already authorized and the token is valid, it resolves immediately.

```javascript
const music = MusicKit.getInstance();
await music.authorize();
```

--------------------------------

### changeToMediaItem

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page&viewMode=story

Starts playing a specific MediaItem from the queue immediately, identified by either a MediaItem instance or its ID. Similar to `changeToMediaAtIndex`, this can trigger playback and may require user interaction.

```APIDOC
## changeToMediaItem

### Description
Begins playing a specific `MediaItem` in the `queue` immediately.

**Note:** This method will trigger playback, even if the player is currently paused. This could result in an error if the user has not interacted with the player yet, as most browsers prevent audio playback without user interaction.
See also `setQueue`

### Method Signature
`changeToMediaItem(descriptor: MediaItem | String): Promise<void>`

### Parameters
* `descriptor` (MediaItem | String) - Required. The descriptor can be a `MediaItem` instance or the `id` of a specific item in the `queue`.
```

--------------------------------

### changeToMediaItem

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Starts playing a specific media item from the queue immediately, identified by either a MediaItem object or its ID. Similar to `changeToMediaAtIndex`, this can trigger playback and may require user interaction.

```APIDOC
## changeToMediaItem

### Description
Begins playing a specific `MediaItem` in the `queue` immediately.

**Note:** This method will trigger playback, even if the player is currently paused. This could result in an error if the user has not interacted with the player yet, as most browsers prevent audio playback without user interaction.
See also `setQueue`

### Method Signature
`changeToMediaItem(descriptor: MediaItem | String): Promise<void>`

### Parameters
* `descriptor` (MediaItem | String) - The descriptor can be a `MediaItem` instance or the `id` of a specific item in the `queue`.
```

--------------------------------

### MusicKitInstance.playNext(options)

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Freference-javascript-queue--page

Adds a specific item to the queue to play immediately after the current item.

```APIDOC
## MusicKitInstance.playNext(options)

### Description
Updates the current queue to add a specific media item after the currently playing one.

### Parameters
- **options** (QueueOptions) - Required - An object containing the content to add.

### Example
```javascript
const music = MusicKit.getInstance();
await music.playNext({ song: '1561837008' });
```
```

--------------------------------

### changeToMediaAtIndex

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page&viewMode=story

Starts playing the MediaItem at the specified index in the current queue immediately. This method will trigger playback even if the player is paused and may result in an error if user interaction is required.

```APIDOC
## changeToMediaAtIndex

### Description
Begins playing the MediaItem at the specified index in the `queue` immediately.

**Note:** This method will trigger playback, even if the player is currently paused. This could result in an error if the user has not interacted with the player yet, as most browsers prevent audio playback without user interaction.

### Method Signature
`changeToMediaAtIndex(index: Number): Promise<void>`

### Parameters
* `index` (Number) - Required. The index position of the `MediaItem` in the `queue` to begin playing.
```

--------------------------------

### changeToMediaAtIndex

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Starts playing the media item at a specific index in the current queue. This method will initiate playback even if the player is paused, but may result in an error if user interaction is required for audio playback.

```APIDOC
## changeToMediaAtIndex

### Description
Begins playing the MediaItem at the specified index in the `queue` immediately.

**Note:** This method will trigger playback, even if the player is currently paused. This could result in an error if the user has not interacted with the player yet, as most browsers prevent audio playback without user interaction.

### Method Signature
`changeToMediaAtIndex(index: Number): Promise<void>`

### Parameters
* `index` (Number) - The index position of the `MediaItem` in the `queue` to begin playing.
```

--------------------------------

### music.authorize()

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Fuser-authorization--page

Initiates the sign-in and authorization flow for the user. If the user is already authorized and the token is valid, the promise resolves immediately.

```APIDOC
## music.authorize()

### Description
Opens the sign-in and authorization flow to allow the app to access the user's Apple Music data and full media playback. If the user has previously authorized the app and the Music User Token (MUT) is valid, the method resolves without opening the flow.

### Method
`await music.authorize()`

### Usage Example
```javascript
const music = MusicKit.getInstance();
await music.authorize();
```
```

--------------------------------

### Cloud Library API Request

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=accessing-music-content--page&viewMode=story

Access a user's Cloud Library by making requests to Apple Music Web Service API methods starting with `v1/me/library`. User authorization is required before making these calls.

```javascript
const music = MusicKit.getInstance();
// You should check authorization before accessing user's iCloud Music Library:
await music.authorize();
const result = await music.api.music('v1/me/library/albums');
```

--------------------------------

### All recommendations

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-api--page

Fetch all recommendations for the user.

```APIDOC
## GET /v1/me/recommendations

### Description
Fetch all recommendations for the user.

### Method
GET

### Endpoint
/v1/me/recommendations

### Parameters
#### Query Parameters
- **l** (string) - Optional - Localization parameter (e.g., 'en-us').

### Request Example
```javascript
const queryParameters = { l: 'en-us' };
await music.api.music(`/v1/me/recommendations`, queryParameters);
```
```

--------------------------------

### Listen for the `musickitloaded` Event

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=get-started--page&viewMode=story

MusicKit on the Web loads asynchronously. Use this event listener to ensure the `MusicKit` global is available before interacting with it.

```javascript
document.addEventListener('musickitloaded', async function () {
  // MusicKit global is now defined.
});
```

--------------------------------

### Fetch All Recommendations

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-api--page

Fetches all recommendations for the user.

```APIDOC
## GET /v1/me/recommendations

### Description
Fetch all recommendations.

### Method
GET

### Endpoint
/v1/me/recommendations

### Parameters
#### Query Parameters
- **l** (string) - Optional - The language code for the response.

### Request Example
```javascript
const queryParameters = { l: 'en-us' };
await music.api.music(`/v1/me/recommendations`, queryParameters);
```
```

--------------------------------

### Fetch First and Second Pages of Playlist Tracks

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=paginated-requests--page

Demonstrates fetching the first page of results with a specified limit and then fetching the second page by using the offset parameter.

```javascript
const playlistId = 'pl.9b8a976ba78741d9925e6e9a050703de';
const urlPath = `/v1/catalog/{{storefrontId}}/playlists/${playlistId}/tracks`;

// Fetch first page of results, limiting the size of the page
const { data: { data: pageOneData = [] } } = await music.api.music(urlPath, { limit: 10 });

// Fetch the second page, which is starting with the object in the index
// position that is after the last item in the previous page (0-based)
const { data: { data: pageTwoData = [] } } = await music.api.music(urlPath, { limit: 10, offset: 10 });
```

--------------------------------

### Fetch All Recommendations

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-api--page&viewMode=story

Fetches all recommendations for the user.

```APIDOC
## GET /v1/me/recommendations

### Description
Fetches all recommendations.

### Method
GET

### Endpoint
/v1/me/recommendations

### Parameters
#### Query Parameters
- **l** (string) - Optional - Language code for the response.

### Request Example
```javascript
const queryParameters = { l: 'en-us' };
await music.api.music(`/v1/me/recommendations`, queryParameters);
```
```

--------------------------------

### Fetch Search Hints - MusicKit JS

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-api--page

Fetch search term suggestions based on a query. Requires a storefront ID and locale.

```javascript
const queryParameters = { term: 'Taylor Swift', l: 'en-us' };
await music.api.music('/v1/catalog/{{storefrontId}}/search/hints', queryParameters);
```

--------------------------------

### Async Configuration in MusicKit v3

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=tech-notes-migrating-to-v3--page&viewMode=story

In MusicKit v3, MusicKit.configure() is now asynchronous and returns a Promise. You should await this promise before using MusicKit.getInstance().

```javascript
const music = await MusicKit.configure({})
```

--------------------------------

### Fetch All Recommendations

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-api--page

Retrieve all recommendations for the user. Localization can be specified using the 'l' query parameter.

```javascript
const queryParameters = { l: 'en-us' };
await music.api.music(`/v1/me/recommendations`, queryParameters);
```

--------------------------------

### MusicKitInstance.setQueue(options)

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Freference-javascript-queue--page

Sets the queue for the MusicKit instance using content identifiers or URLs and playback configuration.

```APIDOC
## MusicKitInstance.setQueue(options)

### Description
Updates the current playback queue with new content and playback settings.

### Parameters
- **options** (QueueOptions) - Required - An object containing content selection and playback configuration.

#### Content Options
- **album / albums** (string/array) - Optional - Album ID(s).
- **musicVideo / musicVideos** (string/array) - Optional - Music Video ID(s).
- **playlist / playlists** (string/array) - Optional - Playlist ID(s).
- **song / songs** (string/array) - Optional - Song ID(s).
- **url** (string) - Optional - A URL reference to a media item or container.

#### Playback Options
- **repeatMode** (PlayerRepeatMode) - Optional - Sets the repeat mode for the instance.
- **startPlaying** (boolean) - Optional - Whether to start playback immediately (default: false).
- **startTime** (number) - Optional - Seek time in seconds for the first item (default: 0).

### Example
```javascript
const music = MusicKit.getInstance();
await music.setQueue({ 
  playlist: 'pl.d133de76fb4f4ccf98846231899874c0', 
  startPlaying: true 
});
```
```

--------------------------------

### Set MusicKit Playback Bitrate

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Freference-javascript-musickit-instance--page

Demonstrates how to retrieve the MusicKit instance and set the preferred playback bitrate using the MusicKit.PlaybackBitrate enum.

```javascript
const music = MusicKit.getInstance();

// Instruct MusicKit to prefer the high-bit rate assets, when available
music.bitrate = MusicKit.PlaybackBitrate.HIGH;
```

--------------------------------

### MusicKit JS Methods

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Freference-javascript-musickit--page

Methods for managing user sessions, playback queues, and media control.

```APIDOC
## MusicKit JS Methods

### SignIn
Initiates the user authentication flow for MusicKit.

### SetQueue
Sets the playback queue for the player.
- **Content Type**: album, musicVideo, playlist, song, station, station (live)

### Play
Starts playback of the current queue.

### Pause
Pauses the current playback.

### Stop
Stops the current playback.
```

--------------------------------

### Set Queue from Playlist URL

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-queue--page

Use `setQueue` with a URL to create a new queue from the content referenced by the URL. This abstracts the need to know the content type beforehand.

```javascript
const music = MusicKit.getInstance();

const playlistURL = 'https://music.apple.com/us/playlist/pl.d133de76fb4f4ccf98846231899874c0';
await music.setQueue({ url: playlistURL });
```

--------------------------------

### Set Queue from Playlist ID and Play Next Song

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-queue--page

Use `setQueue` with a playlist ID to create a new queue and `playNext` with a song ID to add a song to the current queue.

```javascript
const music = MusicKit.getInstance();

// Create a new queue from a playlist
await music.setQueue({ playlist: 'pl.d133de76fb4f4ccf98846231899874c0', startPlaying: true });

// Update the current queue to add a song after the currently playing one
await music.playNext({ song: '1561837008' });
```

--------------------------------

### MusicKit JS Queue Management

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fstory%2Freference-javascript-musickit--page

Methods for configuring the playback queue.

```APIDOC
## MusicKit Queue Methods

### Description
Methods to set the queue content for the MusicKit player.

### Method
- **setQueue(options)**

### Parameters
- **options** (object) - Required - Configuration object containing:
  - **items** (array) - The list of items to add to the queue.
  - **type** (string) - The content type of the queue (e.g., 'album', 'musicVideo', 'playlist', 'song', 'station', 'station (live)').
```

--------------------------------

### Fetch Next Page Directly Using 'next' URL

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=paginated-requests--page

Illustrates using the 'next' property's value directly to fetch the next page of data. Note that the 'limit' parameter might need to be re-specified if a non-default page size is desired.

```javascript
const playlistId = 'pl.9b8a976ba78741d9925e6e9a050703de';
const pageOneUrl = `/v1/catalog/{{storefrontId}}/playlists/${playlistId}/tracks`;

const { data: { data: pageOneData, next: pageTwoUrl } } = await music.api.music(pageOneUrl, { limit: 10 });
const { data: { data: pageTwoData } } = await music.api.music(pageTwoUrl, { limit: 10 });
```

--------------------------------

### Make a Catalog Request using api.music()

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-api--page

Use the `api.music()` method to fetch data from the Apple Music API catalog. The `{{storefrontId}}` token is automatically replaced with the user's current storefront. This method handles JWT and MUT headers.

```javascript
const music = MusicKit.getInstance();

// {{storefrontId}} is replaced with the current user’s storefront automatically
const result = await music.api.music('/v1/catalog/{{storefrontId}}/albums/1025210938');
```

--------------------------------

### Listen for MusicKit Configuration

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-events--page&viewMode=story

Add an event listener to the MusicKit instance to be notified when the instance has been configured.

```javascript
const music = MusicKit.getInstance();
music.addEventListener('configured', () => {
 console.log('MusicKit is not configured');
});
```

--------------------------------

### Storybook Troubleshooting Checklist

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fstory%2Freference-api--page

Follow these steps to resolve issues when a story fails to load in the Storybook environment.

```text
- Are you sure a story with that id exists?
- Please check your stories field of your main.js config.
- Also check the browser console and terminal for error messages.
```

--------------------------------

### Fetch Storefront by ID

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-api--page

Fetches a single storefront using its unique identifier and an optional locale.

```APIDOC
## Fetch Storefront by ID

### Description
Fetches a storefront using its identifier.

### Method
GET

### Endpoint
/v1/storefronts/{storefrontId}

### Parameters
#### Path Parameters
- **storefrontId** (string) - Required - The identifier of the storefront.

#### Query Parameters
- **l** (string) - Optional - The locale for the response (e.g., 'en-us').

### Request Example
```javascript
const storefrontId = '123456789';
const queryParameters = { l: 'en-us' };
await music.api.music(`/v1/storefronts/${storefrontId}`, queryParameters);
```
```

--------------------------------

### authorize

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Freference-javascript-musickit-instance--page

Initiates the user authorization process.

```APIDOC
## authorize()

### Description
See User Authorization for more information. Returns a Promise that resolves with a string representing the user, or undefined if authorization fails or is canceled.
```

--------------------------------

### Fetch Storefronts

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-api--page

Fetches one or more storefronts using their identifiers. You can provide an array of IDs and an optional locale.

```APIDOC
## Fetch Storefronts

### Description
Fetches one or more storefronts using their identifiers.

### Method
GET

### Endpoint
/v1/storefronts

### Parameters
#### Query Parameters
- **ids** (string[]) - Required - A list of storefront identifiers.
- **l** (string) - Optional - The locale for the response (e.g., 'en-us').

### Request Example
```javascript
const queryParameters = { ids: ['1233456789', '987654321'], l: 'en-us' };
await music.api.music(`/v1/storefronts`, queryParameters);
```
```

--------------------------------

### authorize

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page&viewMode=story

Initiates the user authorization process, returning a Promise that resolves with a string representing the user or undefined if authorization fails or is canceled.

```APIDOC
## authorize

### Description
See User Authorization for more information.

### Method Signature
`authorize(): Promise<String | void>`

### Return Value
Returns a Promise that resolves with a string representing the user. If authorization fails or is canceled by the user, the resolved value is `undefined`.
```

--------------------------------

### Play Music Previews and Full Tracks

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=user-authorization--page

Demonstrates playing music previews without authorization. For full-length playback or accessing the user's iCloud Music Library, authorization must be obtained first. This snippet shows checking authorization before playing full tracks and accessing library data.

```javascript
const music = MusicKit.getInstance();

// Music previews can be played without authorization:
await music.play();

// To play the full length of a song, check authorization before calling play():
await music.authorize();
await music.play();

// You should check authorization before accessing user's iCloud Music Library:
await music.authorize();
const { data: result } = await music.api.music('v1/me/library/albums');
// User's iCloud Music Library Albums
console.log(result.data);
```

--------------------------------

### changeUserStorefront

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Freference-javascript-musickit-instance--page

Changes the user storefront.

```APIDOC
## changeUserStorefront(storefrontId)

### Description
Changes the user storefront.

### Parameters
- **storefrontId** (String) - Required - The id of the storefront to use.
```

--------------------------------

### authorize

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Initiates the user authorization process, returning a Promise that resolves with a string representing the authorized user or undefined if authorization fails or is canceled.

```APIDOC
## authorize

### Description
Initiates the user authorization process. See User Authorization for more information.

### Method Signature
`authorize(): Promise<String | void>`

### Return Value
Returns a Promise that resolves with a string representing the user. If authorization fails or is canceled by the user, the resolved value is `undefined`.
```

--------------------------------

### Fetch Multiple Storefronts

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-api--page

Retrieve multiple storefronts by providing an array of their IDs. Specify the locale for the response.

```javascript
const queryParameters = { ids: ['1233456789', '987654321'], l: 'en-us' };
await music.api.music(`/v1/storefronts`, queryParameters);
```

--------------------------------

### Configure MusicKit on the Web

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=get-started--page&viewMode=story

Configure MusicKit on the Web using your developer token and app details. This code should be placed within the `musickitloaded` event listener.

```javascript
document.addEventListener('musickitloaded', async function () {
  // Call configure() to configure an instance of MusicKit on the Web.
  try {
    await MusicKit.configure({
      developerToken: 'DEVELOPER-TOKEN',
      app: {
        name: 'My Cool Web App',
        build: '1978.4.1',
      },
    });
  } catch (err) {
    // Handle configuration error
  }

  // MusicKit instance is available
  const music = MusicKit.getInstance();
});
```

--------------------------------

### `playAt`

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Inserts MediaItem(s) at a specific position in the current queue.

```APIDOC
## `playAt`

### Description
Inserts the MediaItem(s) defined by `QueueOptions` at the position indicated in the current `queue`.

### Method Signature
`playAt(position: Number, options: QueueOptions): Promise<Queue | void>`

### Parameters
* `position` (Number) - The index position in the `queue` to insert the new MediaItem(s) at. Position `0` is the first item in the `queue`.
* `options` (QueueOptions) - See `QueueOptions` for more information.

### Return Value
Returns a Promise that resolves with the updated `Queue`, or `void` if playback is not supported.
```

--------------------------------

### Play Media

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Initiates playback of the `nowPlayingItem`. Note that this may result in an error if the user has not interacted with the player, as browsers often prevent audio playback without user interaction.

```javascript
music.play();
```

--------------------------------

### Fetch Activities - MusicKit JS

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-api--page

Fetch one or more activities using their identifiers. Requires a storefront ID and locale.

```javascript
const queryParameters = { ids: ['1233456789', '987654321'], l: 'en-us' };
await music.api.music(`/v1/catalog/{{storefrontId}}/activities`, queryParameters);
```

--------------------------------

### Charts

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=%2Fstory%2Freference-javascript-api--page

Fetch chart information for a given storefront.

```APIDOC
## Charts

### Description
Fetch chart information for a given storefront.

### Method
GET

### Endpoint
`/v1/catalog/{storefrontId}/charts`

### Parameters
#### Query Parameters
- **types** (string) - Required - Comma-separated list of chart types (e.g., 'most-played').
- **l** (string) - Optional - Localization language code (e.g., 'en-us').
```

--------------------------------

### Specify video container with ID

Source: https://js-cdn.music.apple.com/musickit/v3/docs?path=%2Fdocs%2Fplaying-music-videos--page

Add an HTML element with the id 'apple-music-video-container' to serve as the video container.

```html
<div id="apple-music-video-container"></div>
```

--------------------------------

### Accessing MusicKit API v1 vs v3

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=tech-notes-migrating-to-v3--page

Demonstrates the API access change. In v1, API calls were made through `music.api`. In v3, the API method is a passthrough to the Apple Music API, requiring a full endpoint path.

```javascript
music.api.album(1025210938)
```

```javascript
music.api.music('v1/catalog/{{storefrontId}}/albums/1025210938')
```

--------------------------------

### `playNext`

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-musickit-instance--page

Inserts MediaItem(s) immediately after the currently playing item.

```APIDOC
## `playNext`

### Description
Inserts the MediaItem(s) defined by `QueueOptions` immediately after the `nowPlayingItem` in the current `queue`.

### Method Signature
`playNext(options: QueueOptions, clear?: Boolean): Promise<Queue | void>`

### Parameters
* `options` (QueueOptions) - See `QueueOptions` for more information.
* `clear` (Boolean, Optional) - Optionally clear out the remaining queue items. Defaults to `false`.

### Return Value
Returns a Promise that resolves with the updated `Queue`, or `void` if playback is not supported.
```

--------------------------------

### Set Queue with Album ID

Source: https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?id=reference-javascript-queue--page

Sets the playback queue using an album ID and logs the media items in the queue. Ensure MusicKit is initialized before use.

```javascript
const music = MusicKit.getInstance();

const queue = await music.setQueue({ album: '1025210938' });

console.log(queue.items); // log the MediaItems in the queue
```
Tokens:
Raw