Spotify Plugin#

The spotify plugin generates Spotify playlists from tracks in your library with the beet spotify command using the Spotify Search API.

Also, the plugin can use the Spotify Album and Track APIs to provide metadata matches for the importer.

Why Use This Plugin?#

  • You’re a Beets user and Spotify user already.

  • You have playlists or albums you’d like to make available in Spotify from Beets without having to search for each artist/album/track.

  • You want to check which tracks in your library are available on Spotify.

  • You want to autotag music with metadata from the Spotify API.

  • You want to obtain track popularity and audio features (e.g., danceability)

Basic Usage#

First, enable the spotify plugin (see Using Plugins). Then, use the spotify command with a beets query:

beet spotify [OPTIONS...] QUERY

Here’s an example:

$ beet spotify "In The Lonely Hour"
Processing 14 tracks...
https://open.spotify.com/track/19w0OHr8SiZzRhjpnjctJ4
https://open.spotify.com/track/3PRLM4FzhplXfySa4B7bxS
[...]

Command-line options include:

  • -m MODE or --mode=MODE where MODE is either “list” or “open” controls whether to print out the playlist (for copying and pasting) or open it in the Spotify app. (See below.)

  • --show-failures or -f: List the tracks that did not match a Spotify ID.

You can enter the URL for an album or song on Spotify at the enter Id prompt during import:

Enter search, enter Id, aBort, eDit, edit Candidates, plaY? i
Enter release ID: https://open.spotify.com/album/2rFYTHFBLQN3AYlrymBPPA

Configuration#

This plugin can be configured like other metadata source plugins as described in Using Metadata Source Plugins.

Default#

spotify:
    mode: list
    region_filter:
    show_failures: no
    tiebreak: popularity
    regex: []
    search_query_ascii: no
    client_id: REDACTED
    client_secret: REDACTED
    tokenfile: spotify_token.json
    data_source_mismatch_penalty: 0.5
    search_limit: 5
mode (default: list)#

Controls how the playlist is output:

  • list: Print out the playlist as a list of links. This list can then be pasted in to a new or existing Spotify playlist.

  • open: This mode actually sends a link to your default browser with instructions to open Spotify with the playlist you created. Until this has been tested on all platforms, it will remain optional.

region_filter (default: )#

A two-character country abbreviation, to limit results to that market.

show_failures (default: no)#

List each lookup that does not return a Spotify ID (and therefore cannot be added to a playlist).

tiebreak (default: popularity)#

How to choose the candidate if there is more than one identical result. For example, there might be multiple releases of the same album.

  • popularity: pick the more popular candidate

  • first: pick the first candidate

regex (default: [])#

An array of regex transformations to perform on the track/album/artist fields before sending them to Spotify. Can be useful for changing certain abbreviations, like ft. -> feat. For example:

regex:
  - field: albumartist
    search: Something
    replace: Replaced
  - field: title
    search: Something Else
    replace: AlsoReplaced
search_query_ascii (default: no)#

If enabled, the search query will be converted to ASCII before being sent to Spotify. Converting searches to ASCII can enhance search results in some cases, but in general, it is not recommended. For instance, artist:deadmau5 album:4×4 will be converted to artist:deadmau5 album:4x4 (notice ×!=x).

data_source_mismatch_penalty (default: 0.5)#

Penalty applied when the data source of a match candidate differs from the original source of your existing tracks. Any decimal number between 0.0 and 1.0

This setting controls how much to penalize matches from different metadata sources during import. The penalty is applied when beets detects that a match candidate comes from a different data source than what appears to be the original source of your music collection.

Example configurations:

# Prefer MusicBrainz over Discogs when sources don't match
plugins: musicbrainz discogs

musicbrainz:
    data_source_mismatch_penalty: 0.3  # Lower penalty = preferred
discogs:
    data_source_mismatch_penalty: 0.8  # Higher penalty = less preferred

# Do not penalise candidates from Discogs at all
plugins: musicbrainz discogs

musicbrainz:
    data_source_mismatch_penalty: 0.5
discogs:
    data_source_mismatch_penalty: 0.0

# Disable cross-source penalties entirely
plugins: musicbrainz discogs

musicbrainz:
    data_source_mismatch_penalty: 0.0
discogs:
    data_source_mismatch_penalty: 0.0

Tip

The last configuration is equivalent to setting:

match:
    distance_weights:
        data_source: 0.0  # Disable data source matching
source_weight (default: 0.5)#

Deprecated since version 2.5: Use data_source_mismatch_penalty instead.

search_limit (default: 5)#

Maximum number of search results to return.

Obtaining Track Popularity and Audio Features from Spotify#

Spotify provides information on track popularity and audio features that can be used for music discovery.

The spotify plugin provides an additional command spotifysync to obtain these track attributes from Spotify:

  • beet spotifysync [-f]: obtain popularity and audio features information for every track in the library. By default, spotifysync will skip tracks that already have this information populated. Using the -f or -force option will download the data even for tracks that already have it. Please note that spotifysync works on tracks that have the Spotify track identifiers. So run spotifysync only after importing your music, during which Spotify identifiers will be added for tracks where Spotify is chosen as the tag source.

    In addition to popularity, the command currently sets these audio features for all tracks with a Spotify track ID:

    • acousticness

    • danceability

    • energy

    • instrumentalness

    • key

    • liveness

    • loudness

    • mode

    • speechiness

    • tempo

    • time_signature

    • valence