Skip to content

Usage

Jump to bottom
Badgy edited this page Apr 20, 2020 · 2 revisions

Table of Contents

To use Spotirec, simply run it from terminal

$ spotirec

Recommendation schemes

You can pass arguments to specify the what the recommendations should be based on - these are mutually exclusive

$ spotirec -t 
$ spotirec -st
$ spotirec -a
$ spotirec -tc
$ spotirec -stc
$ spotirec -ac
$ spotirec -gc
$ spotirec -gcs
$ spotirec -c

where

  • -t is based off your 5 most played tracks,
  • -st is based off your 5 most recently liked tracks,
  • -a is based off your 5 most played artists,
  • -tc you can define 1-5 of your most played tracks,
  • -stc you can define 1-5 of your 50 most recently liked tracks,
  • -ac you can define 1-5 of your most played artists,
  • -gc you can define 1-5 of your most played valid seed genres,
  • -gcs you can define 1-5 preset genre seeds, and
  • -c you can manually input 1-5 genres, artist uris, or track uris

By default, the script will base recommendations off of your top valid seed genres extracted from your top artists. For this method, pass none of the above 9 arguments.

On all non-custom schemes, i.e. -a, -t, -st, and no-arg, you can specify how many seeds should be included in the recommendation. The value must be in the range 1-5, and the default value is 5

$ spotirec 3
$ spotirec -a 2
$ spotirec -t 4
$ spotirec -st 1

Note that if this option is used with no-arg, it must be the very first argument

Preserving Playlists

By default, Spotirec caches the id of the first playlist created and uses this every time new recommendations are requested, meaning that any old tracks are overwritten. To avoid this and create a new playlist instead, pass the --preserve flag.

Limits

You can add a limit as an integer value with the -l argument

$ spotirec -l 50

This option determines how many tracks should be added to your new playlist. The default value is 100, the minimum value is 1, and the max value is 100.

Presets

You can save the settings for a recommendation with the --save-preset flag followed by a name

$ spotirec -t --save-preset preset_name -l 50 --tune prefix_attribute=value prefix_attribute=value

To load and use a saved preset, pass the --load-preset flag followed by the name of the preset

$ spotirec --load-preset preset_name

To remove one or more saved presets, pass the --remove-presets flag followed by a sequence of preset names

$ spotirec --remove-presets preset_name0 preset_name1 preset_name2

If you forgot which presets you have saved, see printing

Tuning

You can also specify tunable attributes with the --tune flag, followed by any number of whitespace separated inputs on the form prefix_attribute=value

$ spotirec --tune prefix_attribute=value prefix_attribute=value

Prefixes

Prefix Function
max The attribute value serves as a hard ceiling
min The attribute value serves as a hard floor
target The attribute value serves as a target for recommendations. Recommendations will be as close as possible to the value.

Attributes

Attribute Data type Range Recomm. range Function
duration_ms int R+ N/A The duration of the track in milliseconds.
key int 0-11 N/A Pitch class of the track.
mode int 0-1 N/A Modality of the track. 1 is major, 0 is minor.
time_signature int N/A N/A Estimated overall time signature of the track.
popularity int 0-100 0-100 Popularity of the track. High is popular, low is barely known.
acousticness float 0.0-1.0 0.0-1.0 Confidence measure for whether or not the track is acoustic. High value is acoustic.
danceability float 0.0-1.0 0.1-0.9 How well fit a track is for dancing. Measurement includes among others tempo, rhythm stability, and beat strength. High value is suitable for dancing.
energy float 0.0-1.0 0.0-1.0 Perceptual measure of intensity and activity. High energy is fast, loud, and noisy, and low is slow and mellow.
instrumentalness float 0.0-1.0 0.0-1.0 Whether or not a track contains vocals. Low contains vocals, high is purely instrumental.
liveness float 0.0-1.0 0.0-0.4 Predicts whether or not a track is live. High value is live.
loudness float -60-0 -20-0 Overall loudness of the track, measured in decibels.
speechiness float 0.0-1.0 0.0-0.3 Presence of spoken words. Low is a song, high is likely to be a talk show or podcast.
valence float 0.0-1.0 0.0-1.0 Positivity of the track. High value is positive, low value is negative.
tempo float 0.0-220.0 60.0-210.0 Overall estimated beats per minute of the track.

Recommendations may be scarce outside the recommended range.

Blacklists

To blacklist tracks or artists, pass the -b or --blacklist-add argument followed by an arbitrary number of whitespace separated Spotify URIs

$ spotirec -b spotify:track:id spotify:track:id spotify:artist:id
$ spotirec --blacklist-add spotify:track:id spotify:track:id

To remove entries from your blacklist, pass the -br or --blacklist-remove argument followed by an arbitrary number of whitespace separated Spotify URIs

$ spotirec -br spotify:track:id spotify:track:id spotify:artist:id
$ spotirec --blacklist-remove spotify:track:id spotify:track:id

To blacklist the currently playing track, or the artists that created the track, pass the either of the aforementioned arguments followed by either 'current-artists' or 'current-track'

# blacklists current track
$ spotirec -b current-track

# blacklists all performing artists in current track
$ spotirec --blacklist-add current-artists

# removes current track from blacklist
$ spotirec -br current-track

# removes all performing artists in current track from blacklist
$ spotirec --blacklist-remove current-artists

If you forgot which tracks and artists you have blacklisted, see printing

Autoplay

You can also automatically play your new playlist upon creation using the --play flag followed by a name of a saved device - see devices

$ spotirec --play device_name

Devices

You can save devices using the --save-device flag, whereafter you will be prompted to select a device from your currently connected devices, and to input a name that will serve as an identifier

$ spotirec --save-device
Name                   Type
0. Phone               Smartphone
1. Laptop              Computer
Select a device by index [0]: 1
Enter an identifier for your device: laptop
Added device laptop to config

To remove one or more saved devices, pass the --remove-devices flag followed by a sequence of names for devices

$ spotirec --remove-devices device_name0 device_name1 device_name2

If you forgot which devices you have saved, see printing

Saving playlists

You can save playlists using the --save-playlist flag, whereafter you will be prompted to input an identifier for the playlist, and then a URI for the playlist. For further usage of this, see saving tracks

$ spotirec --save-playlist
Please input an identifier for your playlist: test
Please input the URI for your playlist: spotify:playlist:0Vu97Y7WoJgBlFzAwbrZ8h
Added playlist test to config

To remove one or more saved playlists, pass the --remove-playlists flag followed by a sequence of names for playlists

$ spotirec --remove-playlists playlist_name0 playlist_name1 playlist_name2

If you forgot which playlists you have saved, see printing

Saving Tracks

To like the currently playing track, pass the -s argument

$ spotirec -s

To remove the currently playing track from liked tracks, pass the -sr argument

$ spotirec -sr

To add the currently playing track to a specific playlist, pass the --add-to flag followed by a name for a saved playlist, or a playlist URI

$ spotirec --add-to playlist_name
$ spotirec --add-to spotify:playlist:0Vu97Y7WoJgBlFzAwbrZ8h

To remove the currently playing track from a specific playlist, pass the --remove-from flag followed by a name for a saved playlist, or a playlist URI

$ spotirec --remove-from playlist_name
$ spotirec --remove-from spotify:playlist:0Vu97Y7WoJgBlFzAwbrZ8h

Printing

You can print lists of various data contained within your Spotify account and config files using the --print flag followed by any of the following strings, depending on what you would like to print

$ spotirec --print artists
$ spotirec --print tracks
$ spotirec --print genres
$ spotirec --print genre-seeds
$ spotirec --print devices
$ spotirec --print blacklist
$ spotirec --print presets
$ spotirec --print playlists
$ spotirec --print tuning

You can also print various features of a track with the --track-features flag followed by either a URI or 'current' if you want information about the currently playing track. Features include track attributes (as used in tuning) and URIs.

$ spotirec --track-features current
$ spotirec --track-features spotify:track:4uLU6hMCjMI75M1A2tKUQC

Playback

You can change playback to a different device by passing the --transfer-playback device followed by an identifier for a saved device

$ spotirec --transfer-playback phone

Logging

If you want more or less logging in terminal, you can specify this with the following flags

# log only errors and warnings
$ spotirec -q
$ spotirec --quiet

# log errors, warnings, and few relevant info messages
# pass nothing
$ spotirec

# log errors, warnings, and extensive info messages
$ spotirec -v
$ spotirec --verbose

# log errors, warnings, extensive info messages, and relevant data for debugging
$ spotirec --debug

# any of the above, but suppress warnings
$ spotirec --suppress-warnings
$ spotirec -q --suppress-warnings
$ spotirec -v --suppress-warnings
$ spotirec --debug --suppress-warnings

Passing --log will, no matter which of the above flags you have passed, log on --debug level to a file in your config directory. This is also done on errors, no matter the presence of --log.

$ spotirec --log
INFO: saved log to /path/to/.config/spotirec/logs/spotirec_19-3-2020.log
Clone this wiki locally