Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/exogen/graphbrainz-extension-spotify

Spotify GraphQL extension for GraphBrainz.
https://github.com/exogen/graphbrainz-extension-spotify

graphbrainz graphql graphql-schema musicbrainz musicbrainz-api spotify spotify-api

Last synced: 23 days ago
JSON representation

Spotify GraphQL extension for GraphBrainz.

Awesome Lists containing this project

README 

        
# GraphBrainz Extension: Spotify



[![npm version](https://img.shields.io/npm/v/graphbrainz-extension-spotify.svg)](https://www.npmjs.com/package/graphbrainz-extension-spotify)

[![license](https://img.shields.io/npm/l/graphbrainz-extension-spotify.svg)](https://github.com/exogen/graphbrainz-extension-spotify/blob/master/LICENSE)



Retrieve information about MusicBrainz entities from [Spotify](https://www.spotify.com/)

using GraphQL, calling the [Spotify Web API](https://developer.spotify.com/documentation/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!][demo]** :bulb: Use the “Docs” sidebar or the

documentation below to help construct your query.



## Installation



To use this extension, install [GraphBrainz](https://github.com/exogen/graphbrainz),

then:



```console

$ npm install graphbrainz-extension-spotify

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

```



Or, if you are using the middleware directly:



```js

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]()):



```graphql

{

  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



  Table of Contents



  * [Objects](#objects)

    * [Artist](#artist)

    * [Query](#query)

    * [Recording](#recording)

    * [Release](#release)

    * [SpotifyAlbum](#spotifyalbum)

    * [SpotifyArtist](#spotifyartist)

    * [SpotifyAudioFeatures](#spotifyaudiofeatures)

    * [SpotifyCopyright](#spotifycopyright)

    * [SpotifyExternalID](#spotifyexternalid)

    * [SpotifyExternalURL](#spotifyexternalurl)

    * [SpotifyImage](#spotifyimage)

    * [SpotifyQuery](#spotifyquery)

    * [SpotifyRecommendations](#spotifyrecommendations)

    * [SpotifyTrack](#spotifytrack)

  * [Enums](#enums)

    * [SpotifyCopyrightType](#spotifycopyrighttype)

    * [SpotifyMatchStrategy](#spotifymatchstrategy)

    * [SpotifyTrackMode](#spotifytrackmode)



### Objects



#### Artist



:small_blue_diamond: *This type has been extended.

See the [base schema](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



spotify

SpotifyArtist



The artist’s entry on Spotify.



#### Query



:small_blue_diamond: *This type has been extended.

See the [base schema](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



spotify

SpotifyQuery!



#### Recording



:small_blue_diamond: *This type has been extended.

See the [base schema](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



spotify

SpotifyTrack



The recording’s entry on Spotify.



strategy

[SpotifyMatchStrategy!]



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](https://github.com/exogen/graphbrainz/docs/types.md) for a description and additional fields.*



Field

Argument

Type

Description



spotify

SpotifyAlbum



The release’s entry on Spotify.



strategy

[SpotifyMatchStrategy!]



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

preferential order.



#### SpotifyAlbum



An album from Spotify.



Field

Argument

Type

Description



albumID

ID!



The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

for the album.



uri

String!



The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

for the album.



href

URLString!



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



title

String



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



albumType

ReleaseGroupType!



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



artists

[SpotifyArtist!]!



The artists of the album.



availableMarkets

[String!]!



The markets in which the album is available: [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/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.



copyrights

[SpotifyCopyright!]!



The copyright statements of the album.



externalIDs

[SpotifyExternalID!]!



Known external IDs for the album.



externalURLs

[SpotifyExternalURL!]!



Known external URLs for this album.



genres

[String!]!



A list of the genres used to classify the album. For example: “Prog Rock”,

“Post-Grunge”. (If not yet classified, the array is empty.)



images

[SpotifyImage!]!



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



label

String



The label for the album.



popularity

Int!



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.



releaseDate

Date



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.



Field

Argument

Type

Description



artistID

ID!



The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

for the artist.



uri

String!



The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

for the artist.



href

URLString!



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



name

String!



The name of the artist.



externalURLs

[SpotifyExternalURL!]!



Known external URLs for this artist.



genres

[String!]!



A list of the genres the artist is associated with. For example:

“Prog Rock”, “Post-Grunge”. (If not yet classified, the array is empty.)



popularity

Int!



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

[SpotifyImage!]!



Images of the artist in various sizes, widest first.



topTracks

[SpotifyTrack!]!



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



market

String!



An [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

country code.



relatedArtists

[SpotifyArtist!]!



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.



Field

Argument

Type

Description



acousticness

Float!



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

Float!



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.



duration

Duration!



The duration of the track in milliseconds.



energy

Float!



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.



instrumentalness

Float!



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.



key

Int!



The key the track is in. Integers map to pitches using standard [Pitch Class

notation](https://en.wikipedia.org/wiki/Pitch_class), 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.



keyName

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♯”.)



liveness

Float!



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.



loudness

Float!



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

SpotifyTrackMode!



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

Float!



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.



tempo

Float!



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.



timeSignature

Float!



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).



valence

Float!



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.



Field

Argument

Type

Description



text

String!



The copyright text.



type

SpotifyCopyrightType!



Whether the copyright is for the work itself or the sound recording

(performance).



#### SpotifyExternalID



A value for identifying an entity with some third party.



Field

Argument

Type

Description



type

String!



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



id

String!



The identifier value.



#### SpotifyExternalURL



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



Field

Argument

Type

Description



type

String!



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



url

URLString!



An external, public URL to the object.



#### SpotifyImage



A single image from Spotify.



Field

Argument

Type

Description



url

URLString!



The source URL of the image.



width

Int



The image width in pixels, if known.



height

Int



The image height in pixels, if known.



#### SpotifyQuery



Field

Argument

Type

Description



recommendations

SpotifyRecommendations!



Track recommendations based on seed entities and various parameters.



seedArtists

[ID!]



A list of [Spotify IDs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

for seed artists. Up to 5 seed values may be provided in any combination

of `seedArtists`, `seedTracks`, and `seedGenres`.



seedGenres

[ID!]



A comma separated list of any genres in the set of [available genre seeds](https://developer.spotify.com/documentation/web-api/reference/browse/get-recommendations/#available-genre-seeds).

Up to 5 seed values may be provided in any combination of `seedArtists`,

`seedTracks`, and `seedGenres`.



seedTracks

[ID!]



A list of [Spotify IDs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

for seed tracks. Up to 5 seed values may be provided in any combination

of `seedArtists`, `seedTracks`, and `seedGenres`.



limit

Int



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



Field

Argument

Type

Description



tracks

[SpotifyTrack!]!



#### SpotifyTrack



A track from Spotify.



Field

Argument

Type

Description



trackID

ID!



The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

for the track.



uri

String!



The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

for the track.



href

URLString!



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



title

String!



The name of the track.



audioFeatures

SpotifyAudioFeatures



The audio features of the track.



album

SpotifyAlbum



The album on which the track appears.



artists

[SpotifyArtist!]!



The artists who performed the track.



availableMarkets

[String!]!



A list of the countries in which the track can be played, identified by

their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

code.



discNumber

Int!



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

disc).



duration

Duration!



The track length in milliseconds.



explicit

Boolean



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



externalIDs

[SpotifyExternalID!]!



Known external IDs for the track.



externalURLs

[SpotifyExternalURL!]!



Known external URLs for the track.



popularity

Int!



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.



previewURL

URLString



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



trackNumber

Int!



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

the number on the specified disc.



musicBrainz

Recording



A MusicBrainz recording that corresponds to the track.



strategy

[SpotifyMatchStrategy!]



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

preferential order.



### Enums



#### SpotifyCopyrightType



The type of copyright.



Value

Description



COPYRIGHT



The copyright.



PERFORMANCE



The sound recording (performance) copyright.



#### SpotifyMatchStrategy



Strategies for matching MusicBrainz entities to Spotify entities.



Value

Description



URL



The entity will be matched by finding an explicit URL relationship that

links to Spotify.



EXTERNALID



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.



Value

Description



MAJOR



The major scale.



MINOR



The minor scale.



[demo]: http://graphbrainz-extension-spotify.herokuapp.com/