Find Similar Tracks

The Cyanite.ai API offers the functionality to find similar tracks based on a input track.

You can search for similar tracks for any library or spotify track and retreive results from either your Library (LibraryTrack), a Crate (LibraryTrack) or Spotify (SpotifyTrack).

Additionally, it is possible to specify a search criteria, e.g. only return tracks whose BPM is the range of the input track or tracks whose genre matches a specified genre.

The functionalilty is exposed via the Track.similarTracks field.

tip

We assume that you already have a basic understanding GraphQL interfaces and unions. If you are new with GraphQL in general we recommend starting with the official learning resource.

Example Query

Search on

and find

Run using GraphiQL

query SimilarTracksQuery($trackId: ID!) {
  libraryTrack(id: $trackId) {
    __typename
    ... on Error {
      message
    }
    ... on Track {
      id
      similarTracks(target: { spotify: {} }) {
        __typename
        ... on SimilarTracksError {
          code
          message
        }
        ... on SimilarTracksConnection {
          edges {
            node {
              id
            }
          }
        }
      }
    }
  }
}

Example response

{
  "data": {
    "libraryTrack": {
      "__typename": "LibraryTrack",
      "id": "test-id-1",
      "similarTracks": {
        "__typename": "SimilarTracksConnection",
        "edges": [
          {
            "node": {
              "id": "5P8KKoAiwhzZkwcBuyhdUi"
            }
          },
          {
            "node": {
              "id": "6tnnuZ3pgO83D65xIRgEaG"
            }
          },
          {
            "node": {
              "id": "6q64fAbMqCU92HOJcDKm34"
            }
          }
        ]
      }
    }
  }
}

Specifying a Target

The Track.similarTracks field has one required parameter which is the Track.similarTracks(target:) argument of the SimilarTracksTarget! input type.

This argument specifies what kind of search results we want. Currently, it is possible to get results from the library, a crate or spotify.

Target	`Track.similarTracks(target:)` value
library	`{ library: {} }`
crate	`{ crate: { crateId: "$crateId" } }`
spotify	`{ spotify: {} }`

caution

It is only possible to specify one target. Mixing options e.g. { library: {}, spotify: {} } might result in an error.

Specifying the Search Mode

There different methods available for finding similar tracks. By default the segment of the track that is categorized as the most-representative one of the track will be used. In addition it is possible to choose two additional modes via the Track.similarTracks(searchMode:) argument of the SimilarTracksSearchMode type.

Example Document: Specifying a Search Mode

fragment TrackSimilarTracksFragment on Track {
  similarTracks(target: { library: {} }, searchMode: { complete: {} }) {
    __typename
    ... on SimilarTracksError {
      code
      message
    }
    ... on SimilarTracksConnection {
      edges {
        node {
          id
        }
      }
    }
  }
}

Input	Description	`Track.similarTracks(searchMode:)` value
mostRepresentative	Use most representative part of the track.	`{ mostRepresentative: {} }`
complete	Use the complete track.	`{ complete: {} }`
interval	Use a custom part of the track.	`{ interval: { start: 10, end: 20 } }`

caution

The search filter API is subjected to change and is not fully stable yet.

By default no additional filters will be applied and all similar sounding tracks will be returned. Additionally, it is possible to apply filters for narrowing down the selection of returned tracks.

The filters are applied via the Track.similarTracks(experimental_filter:) argument of the experimental_SimilarTracksFilter input type.

Example filters:

Filter	Description	Example `Track.similarTracks(experimental_filter:)` value
BPM	Filter track by BPM (in range of track)	`{ bpm: { input: {} } }`
Genre	Filter track by genre	`{ genre: { input: {} } }`
Key	Filter track by key	`{ key: { input: {} } }`
Voice	Filter track by voice tags	`{ voice: { input: {} } }`
Character	Filter track by character tags	`{ character: { input: {} } }`	Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.
FreeGenre	Filter track by free genre tags	`{ freeGenre: { input: {} } }`	Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.
Instrument	Filter track by instrument tags	`{ instrument: { input: {} } }`	Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.
MoodAdvanced	Filter track by mood advanced tags	`{ moodAdvanced: { input: {} } }`	Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.
Mood	Filter track by mood tags	`{ mood: { input: {} } }`	Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.
Subgenre	Filter track by subgenre tags	`{ subgenre: { input: {} } }`	Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.

The above filters would result only returning tracks which match the BPM, genre, key and voice of the input track. But, it is also possible to specify custom ranges and values for each filter type.

All the filters can be mixed, so it is possible to filter by bpm and additionally also filter by genre or key.

Please note some filters are not available if you have not migrated to Cyanite 2.0.

Example Document: BPM and Key Filter

fragment TrackSimilarTracksFragment on Track {
  similarTracks(
    target: { library: {} }
    experimental_filter: {
      bpm: { range: { start: 160, end: 200 } }
      key: { input: {} }
    }
  ) {
    __typename
    ... on SimilarTracksError {
      code
      message
    }
    ... on SimilarTracksConnection {
      edges {
        node {
          id
        }
      }
    }
  }
}

BPM filter

The experimental_SimilarTracksFilter.bpm field of the input type experimental_SimilarTracksFilterBpm describes a bpm filter.

It is possible to either filter for the bpm of the input track or a custom range:

Filter	Example `Track.similarTracks(experimental_filter:)` value
BPM (input track)	`{ bpm: { input: {} } }`
BPM (custom range)	`{ bpm: { range: { start: 60, end: 140 } } }`

Genre filter

The experimental_SimilarTracksFilter.genre field of the input type experimental_SimilarTracksFilterGenre describes a genre filter.

It is possible to either filter for the genre of the input track or a list of specified genres.

Filter	Example `Track.similarTracks(experimental_filter:)` value
Genre (input track)	`{ genre: { input: {} } }`
Genre (custom list)	`{ genre: { list: ["country", "folk"] }`

The possible genres are described by the MusicalGenre enum type.

Key filter

The experimental_SimilarTracksFilter.key field of the input type experimental_SimilarTracksFilterKey describes a key filter.

It is possible to either filter for a specific key (input track or list of keys) or via the camelot method.

Filter	Example `Track.similarTracks(experimental_filter:)` value
Key (input track)	`{ key: { matching: { input: {} } } }`
Key (custom list)	`{ key: { matching: { list: ["cMajor"] } }`
Camelot (input track)	`{ key: { camelot: { input: {} } } }`
Camelot (custom list)	`{ key: { camelot: { key: "cMajor" } } }`

The possible keys are described by the MusicalKey enum type.

Voice filter

The experimental_SimilarTracksFilter.voice field of the input type experimental_SimilarTracksFilterVoice describes a voice filter.

It is possible to either filter for the voice of the reference input track or a list of specified voice tags. Possible voice tags are specifed by the MusicalVoice type.

Filter	Example `Track.similarTracks(experimental_filter:)` value
Voice (input track as reference)	`{ voice: { input: {} } }`
Voice (custom list e.g. ignore vocals)	`{ voice: { list: ["instrumental"] }`

Character filter

The experimental_SimilarTracksFilter.character field of the input type experimental_SimilarTracksFilterCharacterTags describes a character filter.

It is possible to filter for tracks that have specific character tags. Possible character tags are specified by the CharacterTags type.

Filter	Example `Track.similarTracks(experimental_filter:)` value
Character (input track as reference)	`{ character: { input: {} } }`
Character (custom list)	`{ character: { list: [epic] }`

Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.

FreeGenre filter

The experimental_SimilarTracksFilter.freeGenre field of the input type experimental_SimilarTracksFilterFreeGenreTags describes a free genre filter.

It is possible to filter for tracks that have specific free genre tags.

Filter	Example `Track.similarTracks(experimental_filter:)` value
FreeGenre (input track as reference)	`{ freeGenre: { input: {} } }`
FreeGenre (custom list)	`{ freeGenre: { list: ["rock"] }`

Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.

Instrument filter

The experimental_SimilarTracksFilter.instrument field of the input type experimental_SimilarTracksFilterInstrumentTags describes a instrument filter.

It is possible to filter for tracks that have specific instrument tags. Possible instrument tags are specified by the InstrumentTags type.

Filter	Example `Track.similarTracks(experimental_filter:)` value
Instrument (input track as reference)	`{ instrument: { input: {} } }`
Instrument (custom list)	`{ instrument: { list: [bassGuitar] }`

Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.

MoodAdvanced filter

The experimental_SimilarTracksFilter.moodAdvanced field of the input type experimental_SimilarTracksFilterMoodAdvancedTags describes a mood advanced filter.

It is possible to filter for tracks that have specific mood advanced tags. Possible mood advanced tags are specified by the MoodAdvancedTags type.

Filter	Example `Track.similarTracks(experimental_filter:)` value
MoodAdvanced (input track as reference)	`{ moodAdvanced: { input: {} } }`
MoodAdvanced (custom list)	`{ moodAdvanced: { list: [happy] }`

Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.

Mood filter

The experimental_SimilarTracksFilter.mood field of the input type experimental_SimilarTracksFilterMoodTags describes a mood filter.

It is possible to filter for tracks that have specific mood tags. Possible mood tags are specified by the MoodTags type.

Filter	Example `Track.similarTracks(experimental_filter:)` value
Mood (input track as reference)	`{ mood: { input: {} } }`
Mood (custom list)	`{ mood: { list: [happy] }`

Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.

Subgenre filter

The experimental_SimilarTracksFilter.subgenre field of the input type experimental_SimilarTracksFilterSubgenreTags describes a subgenre filter.

It is possible to filter for tracks that have specific subgenre tags. Possible subgenre tags are specified by the SubgenreTag type.

Filter	Example `Track.similarTracks(experimental_filter:)` value
Subgenre (input track as reference)	`{ subgenre: { input: {} } }`
Subgenre (custom list)	`{ subgenre: { list: [rockAndRoll] }`

Note: This field is exclusive to Cyanite 2.0 and requires additional permissions. Please contact sales@cyanite.ai for more information.

Specify the amount of edges to fetch

By default the Track.similarTracks field will return up to 10 tracks, given they match all the specified filters and there are enough available. It is possible to fetch up to 100 songs by specifying the Track.similarTracks(first:) argument of the Int type.

Example Document: Fetch 100 items

fragment TrackSimilarTracksFragment on Track {
  similarTracks(target: { library: {} }, first: 100) {
    __typename
    ... on SimilarTracksError {
      code
      message
    }
    ... on SimilarTracksConnection {
      edges {
        node {
          id
        }
      }
    }
  }
}

Example Query​

Specifying a Target​

Specifying the Search Mode​

Applying Search Filters​

BPM filter​

Genre filter​

Key filter​

Voice filter​

Character filter​

FreeGenre filter​

Instrument filter​

MoodAdvanced filter​

Mood filter​

Subgenre filter​

Specify the amount of edges to fetch​

Example Query

Specifying a Target

Specifying the Search Mode

Applying Search Filters

BPM filter

Genre filter

Key filter

Voice filter

Character filter

FreeGenre filter

Instrument filter

MoodAdvanced filter

Mood filter

Subgenre filter

Specify the amount of edges to fetch