sp is a command-line client for Spotify's dbus interface. Play, pause, skip and search tracks from the comfort of your command line.

sp

#!/usr/bin/env bash

#
# This is sp, the command-line Spotify controller. It talks to a running
# instance of the Spotify Linux client over dbus, providing an interface not
# unlike mpc.
#
# Put differently, it allows you to control Spotify without leaving the comfort
# of your command line, and without a custom client or Premium subscription.
#
# As an added bonus, it also works with ssh, at and cron.
#
# Example:
# $ sp weather girls raining men
# $ sp current
# Album   100 Hits Of The '80s
# Artist  The Weather Girls
# Title   It's Raining Men
# $ sp pause
#
# Alarm clock example:
# $ at 7:45 <<< 'sp bangarang'
#
# Remote example:
# $ ssh vader@prod02.nomoon.ta 'sp imperial march'
#
#
# Copyright (C) 2013 Wander Nauta
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software, to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to permit
# persons to whom the Software is furnished to do so, subject to the following
# conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# The software is provided "as is", without warranty of any kind, express or
# implied, including but not limited to the warranties of merchantability,
# fitness for a particular purpose and noninfringement. In no event shall the
# authors or copyright holders be liable for any claim, damages or other
# liability, whether in an action of contract, tort or otherwise, arising from,
# out of or in connection with the software or the use or other dealings in the
# software.
#

# CONSTANTS

SP_VERSION="0.1"
SP_DEST="org.mpris.MediaPlayer2.spotify"
SP_PATH="/org/mpris/MediaPlayer2"
SP_MEMB="org.mpris.MediaPlayer2.Player"

# SHELL OPTIONS

shopt -s expand_aliases

# UTILITY FUNCTIONS

function require {
  hash $1 2>/dev/null || {
    echo >&2 "Error: '$1' is required, but was not found."; exit 1;
  }
}

# COMMON REQUIRED BINARIES

# We need dbus-send to talk to Spotify.
require dbus-send

# Assert standard Unix utilities are available.
require grep
require sed
require cut
require tr

# 'SPECIAL' (NON-DBUS-ALIAS) COMMANDS

function sp-dbus {
  # Sends the given method to Spotify over dbus.
  dbus-send --print-reply --dest=$SP_DEST $SP_PATH $SP_MEMB.$1 ${*:2} > /dev/null
}

function sp-open {
  # Opens the given spotify: URI in Spotify.
  sp-dbus OpenUri string:$1
}

function sp-metadata {
  # Prints the currently playing track in a parseable format.

  dbus-send                                                                   \
  --print-reply                                  `# We need the reply.`       \
  --dest=$SP_DEST                                                             \
  $SP_PATH                                                                    \
  org.freedesktop.DBus.Properties.Get                                         \
  string:"$SP_MEMB" string:'Metadata'                                         \
  | grep -Ev "^method"                           `# Ignore the first line.`   \
  | grep -Eo '("(.*)")|(\b[0-9][a-zA-Z0-9.]*\b)' `# Filter interesting fiels.`\
  | sed -E '2~2 a|'                              `# Mark odd fields.`         \
  | tr -d '\n'                                   `# Remove all newlines.`     \
  | sed -E 's/\|/\n/g'                           `# Restore newlines.`        \
  | sed -E 's/(xesam:)|(mpris:)//'               `# Remove ns prefixes.`      \
  | sed -E 's/^"//'                              `# Strip leading...`         \
  | sed -E 's/"$//'                              `# ...and trailing quotes.`  \
  | sed -E 's/"+/|/'                             `# Regard "" as seperator.`  \
  | sed -E 's/ +/ /g'                            `# Merge consecutive spaces.`
}

function sp-current {
  # Prints the currently playing track in a friendly format.
  require column

  sp-metadata \
  | grep --color=never -E "(title)|(album)|(artist)" \
  | sed 's/^\(.\)/\U\1/' \
  | column -t -s'|'
}

function sp-eval {
  # Prints the currently playing track as shell variables, ready to be eval'ed
  require sort

  sp-metadata \
  | grep --color=never -E "(title)|(album)|(artist)|(trackid)|(trackNumber)" \
  | sort -r \
  | sed 's/^\([^|]*\)\|/\U\1/' \
  | sed -E 's/\|/="/' \
  | sed -E 's/$/"/' \
  | sed -E 's/^/SPOTIFY_/'
}

function sp-art {
  # Prints the artUrl.

  sp-metadata | grep "artUrl" | cut -d'|' -f2
}

function sp-display {
  # Calls display on the artUrl.

  require display
  display $(sp-art)
}

function sp-feh {
  # Calls feh on the artURl.

  require feh
  feh $(sp-art)
}

function sp-url {
  # Prints the HTTP url.

  TRACK=$(sp-metadata | grep "url" | cut -d'|' -f2 | cut -d':' -f3)
  echo "http://open.spotify.com/track/$TRACK"
}

function sp-clip {
  # Copies the HTTP url.

  require xclip
  sp-url | xclip
}

function sp-http {
  # xdg-opens the HTTP url.

  require xdg-open
  xdg-open $(sp-url)
}

function sp-help {
  # Prints usage information.

  echo "Usage: sp [command]"
  echo "Control a running Spotify instance from the command line."
  echo ""
  echo "  sp play       - Play/pause Spotify"
  echo "  sp pause      - Pause Spotify"
  echo "  sp next       - Go to next track"
  echo "  sp prev       - Go to previous track"
  echo ""
  echo "  sp current    - Format the currently playing track"
  echo "  sp metadata   - Dump the current track's metadata"
  echo "  sp eval       - Return the metadata as a shell script"
  echo ""
  echo "  sp art        - Print the URL to the current track's album artwork"
  echo "  sp display    - Display the current album artwork with \`display\`"
  echo "  sp feh        - Display the current album artwork with \`feh\`"
  echo ""
  echo "  sp url        - Print the HTTP URL for the currently playing track"
  echo "  sp clip       - Copy the HTTP URL to the X clipboard"
  echo "  sp http       - Open the HTTP URL in a web browser"
  echo ""
  echo "  sp open <uri> - Open a spotify: uri"
  echo "  sp search <q> - Start playing the best search result for the given query"
  echo ""
  echo "  sp version    - Show version information"
  echo "  sp help       - Show this information"
  echo ""
  echo "Any other argument will start a search (i.e. 'sp foo' will search for foo)."
}

function sp-search {
  # Searches for tracks, plays the first result.

  require curl

  Q="$@"
  SPTFY_URI=$( \
    curl -s -G --data-urlencode "q=$Q" https://api.spotify.com/v1/search\?type=track \
    | grep -E -o "spotify:track:[a-zA-Z0-9]+" -m 1 \
  )

  sp-open $SPTFY_URI
}

function sp-version {
  # Prints version information.

  echo "sp $SP_VERSION"
  echo "Copyright (C) 2013 Wander Nauta"
  echo "License MIT"
}

# 'SIMPLE' (DBUS-ALIAS) COMMANDS

alias sp-play="  sp-dbus PlayPause"
alias sp-pause=" sp-dbus Pause"
alias sp-next="  sp-dbus Next"
alias sp-prev="  sp-dbus Previous"

# DISPATCHER

# First, we connect to the dbus session spotify is on. This isn't really needed
# when running locally, but is crucial when we don't have an X display handy
# (for instance, when running sp over ssh.)

SPOTIFY_PID="$(pidof -s spotify || pidof -s .spotify-wrapped)"

if [[ -z "$SPOTIFY_PID" ]]; then
  echo "Error: Spotify is not running."
  exit 1
fi

QUERY_ENVIRON="$(cat /proc/${SPOTIFY_PID}/environ | tr '\0' '\n' | grep "DBUS_SESSION_BUS_ADDRESS" | cut -d "=" -f 2-)"
if [[ "${QUERY_ENVIRON}" != "" ]]; then
  export DBUS_SESSION_BUS_ADDRESS="${QUERY_ENVIRON}"
fi

# Then we dispatch the command.

subcommand="$1"

if [[ -z "$subcommand" ]]; then
  # No arguments given, print help.
  sp-help
else
  # Arguments given, check if it's a command.
  if $(type sp-$subcommand > /dev/null 2> /dev/null); then
    # It is. Run it.
    shift
    eval "sp-$subcommand $@"
  else
    # It's not. Try a search.
    eval "sp-search $@"
  fi
fi

This works perfectly. Super handy. Thanks!

finally got my xfce4 pause/next/play key bindings to work with spotify.

Works great! Would there by an easy way to integrate login and logout into this script?

I've created an AUR package for Arch Linux users: https://aur.archlinux.org/packages/sp/

Nice script thank you for that !

How do I install this?

Thank!! 😄

Fantastic script

@wandernauta Thanks so much for this script! I've been using it to debug DBus support in the 1.x Spotify Linux client, it's been a real lifesaver. ;)

This is great, thank you so much!

Great script! Created another script that pauses spotify and then locks my (enlightenment) screen (which is also done over DBus). :D

thanks a bunch - this works great!

still works! thanks!

Excellent script to control Spotify from command line, to make shorcuts con media keys, and even automatize or integrate with Conky. Thank you so much :D

Thanks for the script! I found the search functionality broken due to Spotify deprecating their API, so I forked and fixed it:

https://gist.github.com/duncan-bayne/3f7ef98a15b02b693bf47a03fda79b3a

Excellent stuff! Works like a boss with xbindkeys to replace the media keys on my work keyboard. Thanks so much.

Thanks! :)

Hi, any idea how to find out if spotify is currently playing or in pause state? Metatada does always return the currently active song.
Edit: I found this "solution" ... but it works https://muffinresearch.co.uk/ubuntu-lock-screen-and-pause-spotify/

search does not work for me, it takes a moment and does/says nothing. open does work, though.
It looks like the Metadata API has been discontinued by Spotify so your search function does not work with the most recent version of Spotify for linux. They have a page on migrating from the old 'metadata api' to the new 'web api'

In order for the search to work, you'll have to update line 215 to the new API url @wandernauta.

curl -s -G --data-urlencode "q=$Q" https://api.spotify.com/v1/search\?type=track \

Thanks for this awesome utility!

Thank you, @leothelocust! That works like a charm. I've updated the gist.

Brilliant! 👍

I'm usually on linux, but at my current job I have to use windows (.NET) and I was wondering if anyone knew of a way that I could do this same thing on windows?

Still works!
This allows to have 2 or more keyboard shortcuts to play/pause spotify - by default the standard media keys will work and you can create a new shortcut to do run sp play in keyboard settings > shortcuts > custom shortcuts section and assing it to whatever other keyboard shortcut (useful with Ubuntu notebooks when switching between external keyboard and an integrated one that does not have media keys).

is there a way to save the current song to the library?

Great tool, but I ran into problems with "sp eval" when the title(or any other information) contained double quotes.
In order to get it working I would suggest the following change in the function called sp-eval:

sp-metadata
| grep --color=never -E "(title)|(album)|(artist)|(trackid)|(trackNumber)"
| sort -r
| sed 's/^([^|]*)|/\U\1/'
| sed 's/"/\"/g' \ # ESCAPE THE DOUBLE QUOTES
| sed -E 's/|/="/'
| sed -E 's/$/"/'
| sed -E 's/^/SPOTIFY_/'

You can extend the search via these functions.

function sp-list {
	# Searches for playlists, plays the first result.
	require curl
	Q="$@"
	SPTFY_URI=$( \
		curl -s -G --data-urlencode "q=$Q" https://api.spotify.com/v1/search\?type=playlist \
		| grep -E -o "spotify:user:.*:playlist:[a-zA-Z0-9]+" -m 1 \
	)
	sp-open $SPTFY_URI
}

function sp-album {
	# Searches for albums, plays the first result.
	require curl
	Q="$@"
	SPTFY_URI=$( \
		curl -s -G --data-urlencode "q=$Q" https://api.spotify.com/v1/search\?type=album \
		| grep -E -o "spotify:album:[a-zA-Z0-9]+" -m 1 \
	)
	sp-open $SPTFY_URI
}

function sp-artist {
	# Searches for artists, plays the first result.
	require curl
	Q="$@"
	SPTFY_URI=$( \
		curl -s -G --data-urlencode "q=$Q" https://api.spotify.com/v1/search\?type=artist \
		| grep -E -o "spotify:artist:[a-zA-Z0-9]+" -m 1 \
	)
	sp-open $SPTFY_URI
}

Hello! What about volume control? Does spotify ignore it?

@ivanmilov I am sure the d-bus mpris support is not complete in the spotify client. Most of the methods and variables do not work. I think volume control must be one of them

They also made the authentication mandatory for the api now so all the search functions do not work. It needs a token with authorisation code or client credentials :( Will definitely try and fix this as I figure them out.

@sbmkvp I had a go at the authentication and came up with a working fix. Might not be the greatest one but I just wanted it to get working again. I used the information from here which also links to the site to register your application for your own Client ID and Client Secret.

Edit: Actually if you have a look at my fork of sp, I added your search functions and you just have to fill in the variables at the top with your own ID and Secret and it should work fine.

function sp-search {
  # Searches for tracks, plays the first result.

  require curl
    #send request for token with ID and SecretID encoded to base64->grep take only  token from reply->trim reply down to token-> modified request to include token in header
  Q="$@"
    ST=$(curl -H "Authorization: Basic YOURBASE64ID:SECRETHERE" -d grant_type=client_credentials https://accounts.spotify.com/api/token \
    | grep -E -o "access_token\":\"[a-zA-Z0-9_-]+\"" -m 1 )

    ST2=${ST:15:86}}
  SPTFY_URI=$( \
    curl -H "Authorization: Bearer $ST2" -s -G --data-urlencode "q=$Q" https://api.spotify.com/v1/search\?type=track \
    | grep -E -o "spotify:track:[a-zA-Z0-9]+" -m 1 \
  )

  sp-open $SPTFY_URI
}

Thank you @wandernauta for the cli and @vorbeiei for the search alterations!

I've further revisioned @vorbeiei's verison on my fork of sp to make curl silent when performing searches.

function sp-search {
  # Searches for tracks, plays the first result.

  require curl
    #send request for token with ID and SecretID encoded to base64->grep take only  token from reply->trim reply down to token-> modified request to include token in header
  Q="$@"
    ST=$(curl -H "Authorization: Basic $SP_B64ID" -d grant_type=client_credentials https://accounts.spotify.com/api/token --silent\
    | grep -E -o "access_token\":\"[a-zA-Z0-9_-]+\"" -m 1 )

    ST2=${ST:15:86}}
  SPTFY_URI=$( \
    curl -H "Authorization: Bearer $ST2" -s -G --data-urlencode "q=$Q" https://api.spotify.com/v1/search\?type=track \
    | grep -E -o "spotify:track:[a-zA-Z0-9]+" -m 1 \
  )

  sp-open $SPTFY_URI
}

🎉

@rarrais' version isn't working for me still - it's not returning any sort of error, and after a brief pause, it seems to do nothing.

@boardfish You have to create an app here: https://beta.developer.spotify.com/dashboard/applications and insert your ID and Secret in the file where indicated. (I updated my fork to include the link because it's really not obvious)

The image 'sp display' displays is quite low-res and comes with a Spotify logo down in the corner. This can quite easily be fixed by changing the sp-art function to

function sp-art {
	# Prints the artUrl.

	sp-metadata | grep "artUrl" | cut -d'|' -f2 | sed 's|open.spotify.com|i.scdn.co|g'
}

The images at "i.scdn.co" have a resolution of 300x300 (as opposed to the 180x180 that "open.spotify.com" gives) and doesn't have the logo. :)

This script doesn't work for me, it gives me an error:
Error org.freedesktop.DBus.Error.ServiceUnknown: The name org.mpris.MediaPlayer2.spotify was not provided by any .service files
Does anyone know why?

Hey @wandernauta
I was running into an error using sp eval with artist names or titles containing the '$' character.
example using a song by 'Ty Dolla $ign':
eval $(sp eval) echo $SPOTIFY_ARTIST
the result is 'Ty Dolla ' as the '$ign' is interpreted by bash as a variable.

I have fixed this in my fork by adding an additional line to the eval function that changes the output of eval to use single quotes instead of double quotes. You can merge to fix this for other people. Thank you for creating the original!

@wandernauta thanks for this script
I have revisioned @rarrais version to include @Joself and @parlanmurray's changes, and added some terminal only image viewers
Maybe this should be in a repo, it is exactly what i was looking for, but i found it only by luck.

Sorry for the bother, but how would I go about getting the Album, Artist, and Title separately?

@John-AZ1 If you are only after certain fields, use sp eval. it creates shell variables of the metadata, so you can easily access it.
for example, echo $SPOTIFY_ARTIST would give the artist name after calling sp eval.

I found that using single quotes instead of double quotes yields to problems with songs using a ' in the title, and I think that's more common than songs with a $

Hi, open has stopped working for me. Not sure how long ago, as haven't used this for quite a while, but looking to get it working again.

Basically, when I run
sp open https://open.spotify.com/track/7jEKOH8vD6v6nVYYbYPMVL
The client does indeed open a song list and highlight the right song, but doesn't start playing it.
And sp play doesn't either.

The metadata is showing the right info (see below), but play, next, pause etc do nothing until I manually click the play button in the UI (next to the track, the main play button isn't enabled). Then the sp play/pause etc start working again.

I've just updated the spotify client, so maybe that has something to do with it? Running Version: 1:1.0.80.480.g51b03ac3-13 on linux

sp metadata
trackid|spotify:track:7jEKOH8vD6v6nVYYbYPMVL
length|225693000
artUrl|https://open.spotify.com/image/d0937c0f498e8ccb6cb9d0c5d331d7a78b1eb593
album|Hiphop World - Eastside ? Westside ? Global Hiphop!
albumArtist|Various Artists
artist|One Self feat. DJ Vadim, Yarah Bravo and BluRum 18, One Self
autoRating|0
discNumber|1
title|Bluebird
trackNumber|4
url|https://open.spotify.com/track/7jEKOH8vD6v6nVYYbYPMVL

@rarrais Did the same 👍 thanks alot for this script!

sp search seems to be broken with Spotify 1.0.89.313. It just stops the current song and goes into some sort of blank mode (no song playing):

Thanks for this great script!

Any chance we could get the current song playing progress (either in percent, seconds from beginning or so)?

This worked great with Ubuntu 14, but doesn't work with Ubuntu 18. Anyone else get sp to work with Ubuntu 18.04? Thanks.

how use it with https://bitbucket.org/geertvandeweyer/spotify_recorder ?

As @o1354921 mentioned before, you can get in trouble when using sp-eval and some title contains double quotes.
You can also replace double quotes for simple quotes with:
sed 's/"/\x27/g'

Playerctl works good as well and has extra functionality

https://github.com/acrisci/playerctl

@Valeyard1

This script doesn't work for me, it gives me an error:
Error org.freedesktop.DBus.Error.ServiceUnknown: The name org.mpris.MediaPlayer2.spotify was not provided by any .service files

I got this on nixos; seems the nixpkg spotify does not register itself with dbus.

Is there any chance to have a "like" option to star a song?

Prevent Advertisement from playing

https://gist.github.com/neerajvashistha/a22045093b0d431e903e64e3a98cba5e

has anybody got any success on stream record it? @EsmailELBoBDev2 ?

If anyone is in need of a Debian/Ubuntu Package, I got bored and built a .deb:
https://github.com/NLDev/sp

@neerajvashistha im sorry dude i really not have idea what i mean there xD
EDIT: i even not use bitbucket i assume it 3rd time i click on link from bitbucket so yeah i really not have idea xD

Is there any chance to have a "like" option to star a song?

Would also love that.

@EsmailELBoBDev2 @neerajvashistha

Maybe the question would have fit better in the issues of the spotify stream recorder. But here are some things you should do in order to use it:

• Install ffmpeg
• Install sox
• Download the sp script and make it available in your $PATH (e.g. by moving or symlinkng it to the directory ~/bin in your home directory)
• Don't forget to make sp and stream_recorder.pl executable

You can then use ./stream_recorder.pl --uri=… to start the stream ripper. It should work both with an open.spotify.com-Link and with a filename of a file containing such links.

In my case, my pacrec version was too old and didn't support --monitor-stream but I will experiment more with it once I will have upgraded parec.

About “staring” songs:

@cpazaras @AfroMonkey I used d-feet to inspect the dbus methods of the spotify process. There seem to be no methods for leaving a star/like.

Anybody else getting no dbus reply?
Im on Manjaro, using spotify-adblock.
It worked a week ago on another machine for me. (Same setup)

works after i started my pc today lol

I think the Spotify api changed recently -- the search endpoint request returns a blank value when searching a song. I added an echo statement after the curl command, and the value of $SPTFY_URI is blank. The dbus message format seems to have changed, as the get URL command no longer works either. If I have some time on the weekend, I'll take a stab at updating the script.

Spotify have changed the way their query API works and so now it requires an authentication token to lookup songs. curl -s -G --data-urlencode "q=test" https://api.spotify.com/v1/search\?type\=track returns a { "error": { "status": 401, "message": "No token provided" } }
The new Spotify docs say the token is now required and they have also provided steps on how to get one. Fixing it locally should be pretty straightforward, but making a generic elegant solution would take a bit longer.

Here's a working solution I made for searching songs
https://github.com/BelkaDev/Mustream