Skip to main content

Apple Music

This Source monitors your Apple Music listening history via the official Apple Music API and scrobbles new activity to your configured Clients.

Because of how the Apple Music API works, Multi-Scrobbler (MS) requires two different tokens to function: a Media User Token (identifies your personal account) and an Authentication Token (authorizes API access).

1. Getting a Media User Token​

The mediaUserToken is required to access your recently played history. You can extract it directly from the Apple Music web app:

  1. Visit music.apple.com in your browser and log in.
  2. Open your browser's Developer Tools (usually F12 or ⌘ + ⌥ + I).
  3. Navigate to the Application tab (Chrome/Edge) or Storage tab (Safari/Firefox).
  4. Expand Cookies in the left sidebar and select https://music.apple.com.
  5. Find the cookie named media-user-token and copy its value (it typically starts with 0.).
Token Expiry

The mediaUserToken will eventually expire. If Multi-Scrobbler begins throwing authentication errors in the logs, simply repeat these steps to obtain and configure a fresh token.

2. Authentication​

To authorize API access, Multi-Scrobbler requires an Authentication Token (JWT). Because the official Apple Music API is designed for developers, there are two ways to provide this token depending on your situation:

  • Browser Token (Free & Most Common): Best for 99% of users. You can easily extract a temporary token from the Apple Music web player without needing an Apple Developer account.
  • MusicKit Key (Requires Paid Apple Developer Account): If you happen to be enrolled in the paid Apple Developer Program ($99/year), you can provide a private key to automatically generate permanent tokens.

Choose your preferred method below:

Since most users don't have a paid developer account, extracting the token from the web player is the standard approach.

Behind the scenes, the Apple Music website makes a lot of background requests, which can make finding the right token confusing. To filter out the noise and grab the exact token we need, follow the steps for your browser below:

Chrome, Edge & Firefox
  1. Visit music.apple.com and log in.
  2. Open Developer Tools (F12 or Ctrl+Shift+I / ⌘ + ⌥ + I) and navigate to the Network tab.
  3. In the filter box at the top left, paste exactly: https://amp-api.music.apple.com/v1/me/account (Label 1).
  4. Click the Fetch/XHR filter button to hide irrelevant requests (Label 2).
  5. Reload the page (Label 3).
  6. Under the "Name" column, click the request starting with account?meta= (Label 4).
  7. In the panel that opens, scroll down to the Request Headers section.
  8. Find the authorization header. Copy the long string of text after the Bearer prefix (Label 5).

Chrome Network Tab Instructions

Safari

Before you can extract the token in Safari, you must enable developer tools.

  1. Open Safari Settings (⌘ + ,), navigate to the Advanced tab, and check "Show features for web developers" at the very bottom.

Safari Advanced Settings

  1. Visit music.apple.com and log in.
  2. Open the Web Inspector (⌘+⌥+I or Develop > Show Web Inspector) and navigate to the Network tab.
  3. In the filter bar on the left side of the inspector, paste exactly: https://amp-api.music.apple.com/v1/me/account (Label 1).
  4. Reload the page (Label 2).
  5. Click the account request that appears in the Name list (Label 3).
  6. In the details sidebar, look under the Request section for the Authorization header. Copy the long string of text after the Bearer prefix (Label 4).

Safari Network Tab Instructions


Once you have your token, add it to your configuration file along with the origin header:

applemusic.json
{
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsIm...",
        "mediaUserToken": "your-media-user-token-here",
        "origin": "https://music.apple.com"
    }
}
Origin Header Required

When using a JWT extracted from the browser, Apple requires the request to match the domain it was issued to. You must include the origin field in your config as shown above.

Note: Browser-generated JWTs are valid for a maximum of 35 days and must be updated manually when they expire.

How Multi-Scrobbler handles Apple Music quirks​

Timestamp Estimation​

The Apple Music API does not provide timestamps for when tracks were played. Multi-Scrobbler estimates play times by taking the current time and subtracting track durations backwards:

  • The most recent track is assumed to have finished playing now.
  • Each older track is estimated to have played duration seconds before the previous one.

For the most accurate scrobble timestamps, it is highly recommended to keep the polling interval (APPLEMUSIC_INTERVAL) low (the default is 60 seconds).

Duplicate Play Recovery​

The Apple Music history API strictly deduplicates tracks. Instead of showing the same song multiple times in a row, it simply bumps the re-played track back to the #1 spot and removes the older entry.

For example, if you listen to Song A → Song B, your history is [Song B, Song A]. If you then listen to Song A again, the API returns [Song A, Song B] (Song A was bumped to the top).

If Multi-Scrobbler polled when the top track was Song A, and polls again after it's bumped back to the top, the top track appears functionally unchanged. This usually confuses standard scrobblers into ignoring the update entirely. By default, MS correctly detects this "top-rebound" pattern, extracts the intermediate tracks that were squeezed in (Song B), and scrobbles Song A again as a re-listen.

Note: Because of this strict deduplication, "pure loops" (listening to Song A continuously on repeat without playing anything else in between) cannot be tracked. The history list never changes shape, so MS has no way of knowing it was played again.

If you ever experience false positives (tracks being scrobbled that you didn't actually re-listen to), you can disable this recovery behavior with "recoverUnchangedTopHistory": false in your config options or by setting the APPLEMUSIC_RECOVER_UNCHANGED_TOP_HISTORY=false env var.

Album name normalization​

The Apple Music API appends - EP or - Single to the album name for EPs and singles. These suffixes are not part of the official names of the album and can cause issues when trying to scrobble or match metadata.

By default, Multi-Scrobbler strips these suffixes out so only the official name is used.

If you do not want this behavior it can be disabled with ENV APPLEMUSIC_NORMALIZE_ALBUM=false or File/AIO option "normalizeAlbum": false.

Stripping Suffix with User Stage

If you still want this stripping functionality but with more control over how it is applied you can use a User Stage.

Here is an example of creating a User Stage to only strip suffixes for a specific scrobble client:

Example
config.json
{
  // ...
  "transformers": [
    {
      "type": "user",
      "name": "AppleAlbumStip",
      "defaults": {
        "album": [
          "/ - (EP|Single)$/i"
        ]
      }
    }
  ]
}
applemusic.json
{
  {
    "id": "myAppleMusic",
    "name": "My Apple Music",
    "data": {
      // ...
    },
    "options": {
      "normalizeAlbum": false
    }
  }
}
lastfm.json
[
  {
    "name": "Foxx LFM Client",
    "id": "myLastFmClient",
    "enable": true,
    "configureAs": "client",
    "data": {
      "apiKey": "a89cba1569901a0671d5a9875fed4be1",
      "secret": "ec42e09d5ae0ee0f0816ca151008412a",
      "redirectUri": "http://localhost:9078/lastfm/callback"
    },
    "options": {
      "playTransform": {
        "preCompare": [
          {
            "type": "user",
            "name": "AppleAlbumStip",
          }
        ]
      }
    }
  }
]

Configuration Reference​

Configuration Type

This is configuration for the ENV Config Type.

Environment VariableRequired?DefaultDescription
APPLEMUSIC_IDYesA unique ID for this source.
APPLEMUSIC_MEDIA_USER_TOKENYesThe media-user-token extracted from the browser.
APPLEMUSIC_KEY_IDNoKey ID from your MusicKit key.
APPLEMUSIC_TEAM_IDNoTeam ID from your Apple Developer account.
APPLEMUSIC_KEY_P8NoThe contents of your MusicKit .p8 private key file.
APPLEMUSIC_TOKENNoThe authentication JWT extracted from the browser.
APPLEMUSIC_INTERVALNo60Polling interval in seconds.
APPLEMUSIC_ORIGIN_HEADERNoOrigin header for API requests, e.g. https://music.apple.com. Required when using a browser token.
APPLEMUSIC_RECOVER_UNCHANGED_TOP_HISTORYNotrueApple Music deduplicates its history by bumping re-played tracks to the top. If you listen to Song A → Song B → Song A, the history changes from [A] to [A, B] (bumping A). MS detects this "top-rebound" to recover the intermediate play (B) and the re-listen (A). Disable this only if you see incorrect duplicate scrobbles.
APPLEMUSIC_NORMALIZE_ALBUMNotrueStrips extraneous - EP and - Single suffixes from album names
APPLEMUSIC_NAMENoA vanity name different than the ID.