GraphBrainz Extension: Spotify

Retrieve information about MusicBrainz entities from Spotify using GraphQL, calling the Spotify Web API under the hood. This project has no affiliation with Spotify.

The extension works by finding Spotify URLs in an entity’s URL relationships. The URL relationship must have the streaming music type and point to a Spotify entity of the appropriate type: artist for artists, album for releases, and track for recordings.

Try out the live demo! :bulb: Use the “Docs” sidebar or the documentation below to help construct your query.

Installation

To use this extension, install GraphBrainz, then:

$ npm install graphbrainz-extension-spotify
$ GRAPHBRAINZ_EXTENSIONS='["graphbrainz-extension-spotify"]' graphbrainz

Or, if you are using the middleware directly:

import graphbrainz from 'graphbrainz'

const middleware = graphbrainz({
  // Don't forget to add the other extensions you use, too.
  extensions: ['graphbrainz-extension-spotify']
})

Configuration

This extension can be configured using environment variables:

• SPOTIFY_CLIENT_ID: The Spotify client ID to use. This is required.
• SPOTIFY_CLIENT_SECRET: The Spotify client secret to use. This is required.
• SPOTIFY_BASE_URL: The base URL at which to access the Spotify API. Defaults to https://api.spotify.com/v1/.
• SPOTIFY_CACHE_SIZE: The number of items to keep in the cache. Defaults to GRAPHBRAINZ_CACHE_SIZE if defined, or 8192.
• SPOTIFY_CACHE_TTL: The number of seconds to keep items in the cache. Defaults to GRAPHBRAINZ_CACHE_TTL if defined, or 86400000 (one day).

This extension uses its own cache, separate from the MusicBrainz loader cache.

Example Queries

Get the audio features and related artists for a track (try it):

{
  lookup {
    recording(mbid: "6c128cd9-94da-44fe-b74f-b68079fb1606") {
      spotify {
        title
        previewURL
        audioFeatures {
          acousticness
          danceability
          duration
          energy
          instrumentalness
          keyName
          liveness
          loudness
          mode
          speechiness
          tempo
          timeSignature
          valence
        }
        artists {
          name
          relatedArtists {
            name
            href
          }
        }
      }
    }
  }
}

Schema Types

• Objects
  • Artist
  • Query
  • Recording
  • Release
  • SpotifyAlbum
  • SpotifyArtist
  • SpotifyAudioFeatures
  • SpotifyCopyright
  • SpotifyExternalID
  • SpotifyExternalURL
  • SpotifyImage
  • SpotifyQuery
  • SpotifyRecommendations
  • SpotifyTrack
• Enums
  • SpotifyCopyrightType
  • SpotifyMatchStrategy
  • SpotifyTrackMode

Objects

Artist

:small_blue_diamond: This type has been extended. See the base schema for a description and additional fields.

The artist’s entry on Spotify.

Query

:small_blue_diamond: This type has been extended. See the base schema for a description and additional fields.

Recording

:small_blue_diamond: This type has been extended. See the base schema for a description and additional fields.

The recording’s entry on Spotify.

The strategies to use to match the recording with a Spotify track, in preferential order.

Release

:small_blue_diamond: This type has been extended. See the base schema for a description and additional fields.

The release’s entry on Spotify.

The strategies to use to match the release with a Spotify album, in preferential order.

SpotifyAlbum

An album from Spotify.

The Spotify ID for the album.

The Spotify URI for the album.

A link to the Web API endpoint providing full details of the album.

The name of the album. In case of an album takedown, the value may be empty.

The type of the album, e.g. “Album”, “Single”, “Compilation”.

The artists of the album.

The markets in which the album is available: ISO 3166-1 alpha-2 country codes.

Note that an album is considered available in a market when at least 1 of its tracks is available in that market.

The copyright statements of the album.

Known external IDs for the album.

Known external URLs for this album.

A list of the genres used to classify the album. For example: “Prog Rock”, “Post-Grunge”. (If not yet classified, the array is empty.)

The cover art for the album in various sizes, widest first.

The label for the album.

The popularity of the album. The value will be between 0 and 100, with 100 being the most popular. The popularity is calculated from the popularity of the album’s individual tracks.

The date the album was first released, for example “1981-12-15”. Depending on the precision, the month or day might be missing.

SpotifyArtist

An artist from Spotify.

The Spotify ID for the artist.

The Spotify URI for the artist.

A link to the Web API endpoint providing full details of the artist.

The name of the artist.

Known external URLs for this artist.

A list of the genres the artist is associated with. For example: “Prog Rock”, “Post-Grunge”. (If not yet classified, the array is empty.)

The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist’s popularity is calculated from the popularity of all the artist’s tracks.

Images of the artist in various sizes, widest first.

Spotify catalog information about an artist’s top tracks by country.

An ISO 3166-1 alpha-2 country code.

Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community’s listening history.

SpotifyAudioFeatures

The audio features of a track from Spotify.

A confidence measure from 0.0 to 1.0 of whether the track is acoustic. 1.0 represents high confidence the track is acoustic.

Danceability describes how suitable a track is for dancing based on a combination of musical elements including tempo, rhythm stability, beat strength, and overall regularity. A value of 0.0 is least danceable and 1.0 is most danceable.

The duration of the track in milliseconds.

Energy is a measure from 0.0 to 1.0 and represents a perceptual measure of intensity and activity. Typically, energetic tracks feel fast, loud, and noisy. For example, death metal has high energy, while a Bach prelude scores low on the scale. Perceptual features contributing to this attribute include dynamic range, perceived loudness, timbre, onset rate, and general entropy.

Predicts whether a track contains no vocals. “Ooh” and “aah” sounds are treated as instrumental in this context. Rap or spoken word tracks are clearly “vocal”. The closer the instrumentalness value is to 1.0, the greater likelihood the track contains no vocal content. Values above 0.5 are intended to represent instrumental tracks, but confidence is higher as the value approaches 1.0.

The key the track is in. Integers map to pitches using standard Pitch Class notation, e.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on. See the keyName field if you’d prefer the note as a string.

The key translated from an integer to a name like “C”. (Only one name will be returned, so enharmonic notes like like C♯/D♭ will just return “C♯”.)

Detects the presence of an audience in the recording. Higher liveness values represent an increased probability that the track was performed live. A value above 0.8 provides strong likelihood that the track is live.

The overall loudness of a track in decibels (dB). Loudness values are averaged across the entire track and are useful for comparing relative loudness of tracks. Loudness is the quality of a sound that is the primary psychological correlate of physical strength (amplitude). Values typical range between -60 and 0 db.

Mode indicates the modality (major or minor) of a track, the type of scale from which its melodic content is derived. Major is represented by 1 and minor is 0.

Speechiness detects the presence of spoken words in a track. The more exclusively speech-like the recording (e.g. talk show, audio book, poetry), the closer to 1.0 the attribute value. Values above 0.66 describe tracks that are probably made entirely of spoken words. Values between 0.33 and 0.66 describe tracks that may contain both music and speech, either in sections or layered, including such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like tracks.

The overall estimated tempo of a track in beats per minute (BPM). In musical terminology, tempo is the speed or pace of a given piece and derives directly from the average beat duration.

An estimated overall time signature of a track. The time signature (meter) is a notational convention to specify how many beats are in each bar (or measure).

A measure from 0.0 to 1.0 describing the musical positiveness conveyed by a track. Tracks with high valence sound more positive (e.g. happy, cheerful, euphoric), while tracks with low valence sound more negative (e.g. sad, depressed, angry).

SpotifyCopyright

A copyright statement for an album from Spotify.

The copyright text.

Whether the copyright is for the work itself or the sound recording (performance).

SpotifyExternalID

A value for identifying an entity with some third party.

The identifier type, for example “isrc”, “ean”, “upc”.

The identifier value.

SpotifyExternalURL

A URL for linking to an entity with some third party.

The type of the URL, for example “spotify”.

An external, public URL to the object.

SpotifyImage

A single image from Spotify.

The source URL of the image.

The image width in pixels, if known.

The image height in pixels, if known.

SpotifyQuery

Track recommendations based on seed entities and various parameters.

A list of Spotify IDs for seed artists. Up to 5 seed values may be provided in any combination of seedArtists, seedTracks, and seedGenres.

A comma separated list of any genres in the set of available genre seeds. Up to 5 seed values may be provided in any combination of seedArtists, seedTracks, and seedGenres.

A list of Spotify IDs for seed tracks. Up to 5 seed values may be provided in any combination of seedArtists, seedTracks, and seedGenres.

The target size of the list of recommended tracks. For seeds with unusually small pools or when highly restrictive filtering is applied, it may be impossible to generate the requested number of recommended tracks. Debugging information for such cases is available in the response.

Default: 20. Minimum: 1. Maximum: 100.

SpotifyRecommendations

SpotifyTrack

A track from Spotify.

The Spotify ID for the track.

The Spotify URI for the track.

A link to the Web API endpoint providing full details of the track.

The name of the track.

The audio features of the track.

The album on which the track appears.

The artists who performed the track.

A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.

The disc number (usually 1 unless the album consists of more than one disc).

The track length in milliseconds.

Whether or not the track has explicit lyrics, if known.

Known external IDs for the track.

Known external URLs for the track.

The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.

The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are. Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past.

Duplicate tracks (e.g. the same track from a single and an album) are rated independently.

Artist and album popularity is derived mathematically from track popularity.

Note that the popularity value may lag actual popularity by a few days: the value is not updated in real time.

A link to a 30 second preview (MP3 format) of the track, if available.

The number of the track. If an album has several discs, the track number is the number on the specified disc.

A MusicBrainz recording that corresponds to the track.

The strategies to use to match the track with a MusicBrainz recording, in preferential order.

Enums

SpotifyCopyrightType

The type of copyright.

The copyright.

The sound recording (performance) copyright.

SpotifyMatchStrategy

Strategies for matching MusicBrainz entities to Spotify entities.

The entity will be matched by finding an explicit URL relationship that links to Spotify.

The entity will be matched by searching for Spotify entities by some external ID that is known to both MusicBrainz and Spotify, like an ISRC or UPC barcode. Since this can result in multiple Spotify matches, the most popular will be preferred (if possible), or the first.

SpotifyTrackMode

The potential values for modality (major or minor) of a track.

The major scale.

The minor scale.