diff --git a/docsite/docs/configuration/sources/applemusic.mdx b/docsite/docs/configuration/sources/applemusic.mdx index 89a36121..9be9fea6 100644 --- a/docsite/docs/configuration/sources/applemusic.mdx +++ b/docsite/docs/configuration/sources/applemusic.mdx @@ -29,10 +29,44 @@ The `mediaUserToken` will eventually expire. If Multi-Scrobbler begins throwing #### 2. Authentication -The Apple Music API requires a Developer Token (JWT). Multi-Scrobbler can either automatically **generate** this JWT for you using an Apple Music API key, or you can manually provide a **pre-generated token**. +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. + + While browsing [music.apple.com](https://music.apple.com) with Developer Tools open, inspect the **Network** tab. Look at the request headers for any request made to `amp-api.music.apple.com`. Copy the `authorization` header value (use everything *after* the `Bearer ` prefix). + + ```json + { + "data": { + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsIm...", + "mediaUserToken": "your-media-user-token-here", + "headers": { + "Origin": "https://music.apple.com" + } + } + } + ``` + + :::info[Custom 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` header 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.* + + + + + :::warning[Apple Developer Account Required] + To generate JWTs automatically, you must be enrolled in the paid [Apple Developer Program](https://developer.apple.com/programs/) ($99/year) and create a MusicKit key. If you don't have an account, use the **Browser Token (Free)** tab instead. + ::: To generate JWTs automatically and avoid manual token refreshes, you need an Apple Music API key: @@ -60,31 +94,6 @@ The Apple Music API requires a Developer Token (JWT). Multi-Scrobbler can either ::: - - - If you don't have an Apple Developer account, you can piggyback off the web app's token. - - While browsing [music.apple.com](https://music.apple.com) with Developer Tools open, inspect the **Network** tab. Look at the request headers for any request made to `amp-api.music.apple.com`. Copy the `authorization` header value (use everything *after* the `Bearer ` prefix). - - ```json - { - "data": { - "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsIm...", - "mediaUserToken": "your-media-user-token-here", - "headers": { - "Origin": "https://music.apple.com" - } - } - } - ``` - - :::info[Custom 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` header 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.* - - --- @@ -92,11 +101,12 @@ The Apple Music API requires a Developer Token (JWT). Multi-Scrobbler can either #### 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 `APPLEMUSIC_INTERVAL` low (the default is 60 seconds).* +*For the most accurate scrobble timestamps, it is highly recommended to keep the polling interval (`APPLEMUSIC_INTERVAL`) low (the default is 60 seconds).* ## Configuration Reference @@ -109,7 +119,7 @@ The Apple Music API **does not provide timestamps** for when tracks were played. | `APPLEMUSIC_KEY_ID` | No | | Key ID from your MusicKit key. | | `APPLEMUSIC_TEAM_ID` | No | | Team ID from your Apple Developer account. | | `APPLEMUSIC_KEY_P8` | No | | The contents of your MusicKit `.p8` private key file.| - | `APPLEMUSIC_TOKEN` | No | | A pre-generated JWT (alternative to key properties). | + | `APPLEMUSIC_TOKEN` | No | | The authentication JWT extracted from the browser. | | `APPLEMUSIC_INTERVAL` | No | `60` | Polling interval in seconds. | | `APPLEMUSIC_NAME` | No | | A vanity name different than the ID. | \ No newline at end of file