As the input is expected to be from a variety of sources, each with differing tagging practices, matching is a bit beyond hitting the Spotify search endpoint and taking the top hit. The search endpoint is pretty sensitive to extraneous terms, so this module attempts to trim excess tokens from fields pre-query, casting a wide net and scoring/filtering search results client-side for best-match. In addition, we can't expect every track to be within the Spotify catalog, so scoring thresholds determine when it's acceptable to fail, rejecting the existence of a match.
npm install --save @claygregory/spotify-matcher
const SpotifyMatcher = ;const spotify = ;spotify;
The match object will contain artist, album, and track information, based on internal scoring. One or more of the fields may not be provided, if a suitable match was not found. A complete match object takes the form:
Scores are based on the Jaro-Winkler similarity between the Spotify field name, and a processed version of provided field information that attempts to address common tagging mismatch concerns.
Access Token and Options
The module operates with relatively sane defaults, and does not require a Spotify access token for small match jobs. However, a Spotify OAuth2 token may be provided, for a higher rate limit from Spotify.
const spotify = access_token options;
access_token is either a string, or a function to provide the token per-request (for example, to handle refreshing as needed on long-running match jobs). This library does not provide any OAuth access flow handling, that's on you.
The options object supports the following configuration(s), defaults as below:
cache_requests: true // Internally cache API responses for lifetime of instance?market: 'US' // Spotify market (to avoid tracks not available to you)rate_limit_ms: 200 // API rate limitscore_threshold: // per field edit-distances to accept as matchalbum: 065artist: 090track: 070composite: 080score_weights: // weight of each field when computing composite scorealbum: 075artist: 1track: 1
A test file of sample inputs and expected responses is provided in
test-performance/tests.tsv, especially with regard to potential fail cases. Running
npm run perf will process this file and provide performance results. Additions to this file welcome (US market IDs, please)!
See the included LICENSE for rights and limitations under the terms of the MIT license.