Apple Music metadata block

The apple_music block attaches Apple Music’s own metadata for the recognized recording to the match. It mirrors an Apple Music Songs attributes object, so you get a direct Apple Music URL, a 30-second AAC preview, artwork, and the catalog ID without a second call. It is present only when you request it — and only when Apple Music has a match for the recording.

How to request it

In the SDKs, list the provider in the return_metadata option (Python) / returnMetadata (Node):

from audd import AudD

audd = AudD("your-api-token")  # dashboard.audd.io
result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["apple_music"],
)

import { AudD } from "@audd/sdk";

const audd = new AudD({ apiToken: "your-api-token" }); // dashboard.audd.io
const result = await audd.recognize("https://audd.tech/example.mp3", {
  returnMetadata: ["apple_music"],
});

In raw curl, the form field is named return (the SDK option above is the SDK name for the same thing):

curl https://api.audd.io/ \
  -F api_token=your-api-token \
  -F url=https://audd.tech/example.mp3 \
  -F return=apple_music

The market parameter sets the country code for the Apple Music lookup (defaults to us); it changes which catalog entry you get back.

How to access it

The block is the typed apple_music property on the result, and its sub-fields are typed attributes on that model — attribute access, not dict subscripts. Fields beyond the typed ones (composer, work, audio traits, the artwork and previews objects) round-trip through Pydantic’s model_extra in Python / extras in Node.

result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["apple_music"],
)
am = result.apple_music                 # None if not requested / no Apple Music match
if am:
    page = am.url                       # Apple Music page for the track
    title = am.name
    code = am.isrc
    # untyped fields (artwork, previews, playParams, …) via model_extra
    artwork = (am.model_extra or {}).get("artwork")

const am = result.appleMusic;           // undefined if not requested / no match
if (am) {
  const page = am.url;                  // typed-equivalent fields live on the block
  const artwork = am.artwork;           // untyped fields readable via the block / extras
}

A couple of fields need handling:

• artwork.url is a template, not a final image URL: it contains literal {w} and {h} placeholders. Substitute the pixel size you want before using it — e.g. replace {w}x{h} with 300x300 for a 300×300 cover. artwork.width/artwork.height give the maximum available size.
• previews[0].url is a 30-second AAC preview you can play directly. Use it subject to Apple Music’s terms.

Fields

The typed fields on the Apple Music block:

Field	Type	Description
name	string | null	Track title.
artistName	string | null	Artist name.
albumName	string | null	Album the track appears on.
url	string | null	Apple Music page for the track.
isrc	string | null	The recording’s ISRC.
durationInMillis	int | null	Track length in milliseconds.
trackNumber	int | null	Position on the album.
discNumber	int | null	Disc number.
composerName	string | null	Composer.
releaseDate	string | null	Release date (YYYY-MM-DD).

Apple’s response carries more — artwork, previews, playParams, genreNames, hasLyrics, isAppleDigitalMaster, and others. These aren’t typed properties; read them through the block’s model_extra (Python) / extras (Node). For the full attribute list see Apple’s Song attributes reference.

The block and every field can be absent or null — request did not include apple_music, no Apple Music match for the recording, or the provider omitted a field. Always null-check before reading.

Without requesting the block: song_link

You don’t need the apple_music block just to send a user to Apple Music. Every match carries a song_link (a lis.tn URL such as https://lis.tn/NbkVb), and the streaming_url("apple_music") SDK helper (streamingUrl("apple_music") in Node) returns an “open in Apple Music” redirect built from it — no provider block, no added latency:

result.streaming_url("apple_music")   # lis.tn ?apple_music redirect

Request the apple_music block when you need the structured metadata — direct URL, catalog ID, preview, artwork — in your own UI. See the lis.tn song link concept for the redirect convention.

---

Related

• Spotify metadata block
• Deezer metadata block
• MusicBrainz metadata block
• The lis.tn song link
• Provider metadata overview