the-lay / ulauncher-spotify-api

Control Spotify clients on any device with ulauncher

ulauncher-spotify-api

ulauncher extension that provides Spotify controls through WebAPI.

Note: some playback features are allowed only for Spotify Premium subscribers (see Troubleshooting below).

Available commands

Motivation

There's a great Ulauncher extension pywkm/ulauncher-spotify. However, ulauncher-spotify uses dbus to control Spotify, exposing a very limited number of Spotify features to the user.

In contrast, this extension makes use of Spotify's Web API through which it is possible to use almost all Spotify features. The aim is to provide direct access to most features that make sense for a command runner.

Installation

Please use the default way to install ulauncher extensions: Preferences -> Extensions -> Add extension -> https://github.com/the-lay/ulauncher-spotify-api. On the first run, the extension will try to install the dependencies automatically.

For various reasons (pip is not installed, hardened permissions, non-standard installations...) automatic installation can fail, and the Ulauncher will report something along the lines of ModuleNotFoundError: No module named 'spotipy'. In that case, first, make sure you have pip installed: pip -V should show a version. If pip binary is not found, please install it, e.g.: sudo apt install pip3. Next, you have to install python dependencies: pip3 install "spotipy==2.16.1" "requests==2.23.0" and then restart Ulauncher.

In case you have multiple Python environments on your system (PyEnv, Conda etc.), please note that you have to install the dependencies to the default system python that Ulauncher uses. Most likely, this will be the command you want: /usr/bin/python3 -m pip install "spotipy==2.16.1" "requests==2.23.0"

Extension's default keyword is sp. When you use the extension for the first time, you will have to go through OAuth authentication and allow access to your Spotify account. After that, you will be able to use the extension.

Note: if you ever want to revoke extension's access, you can do so in the Apps tab of your Spotify settings.

Currently implemented

• Authenticate the user with the Spotify API and automatically refresh access token when expired (sp - first run or when access token is expired)
• Playback functionality: play, pause, next/previous track (sp - default menu)
• Show current playback
• Error handling, gracefully handling most of the API errors
• Initiate playback on different devices (if not playing)
• Switch playback between devices (sp switch)
• Change repeat state (sp repeat)
• Change shuffle state (sp shuffle)
• Search for track/album/artist/playlist (sp album/track/artist/playlist search_query)
• Search without specifying a type (sp search search_query)
• Download images to cache folder and show them in search (and clear cache on extension exit)
• Alt-enter to add track to queue instead of playing now
• PKCE authentication
• Aliases for commands (sp song = sp track, sp s = sp search, sp vol = sp volume)
• Help dialogue (sp ? or sp help)
• History / recently played songs (sp history)
• Spotify volume / mute (sp volume N)

Feature roadmap

• Podcasts functionality (sp podcast)
• Start a radio based on currently playing track (sp radio)

There might be more TODO in github issues.

If you have any suggestions or feel that something is missing, please open a new issue.

Troubleshooting

• Spotipy's authentication workflow sets up a tiny web server to accept back Spotify's access token. By default, port 8080 is used. If it is taken, please select a different one in the extension settings.

• Unfortunately, Spotify does not provide API access for free users for the following actions:

  • Next track (Skip User’s Playback To Next Track)
  • Previous track (Skip User’s Playback To Previous Track)
  • Start/resume playback (Start/Resume a User's Playback)
  • Pause playback (Pause a User's Playback)
  • Set repeat mode (Set Repeat Mode On User’s Playback)
  • Switch device (Transfer a User's Playback)
  • Scroll track (Seek To Position In Currently Playing Track)
  • Set volume (Set Volume For User's Playback)
  • Toggle shuffle (Toggle Shuffle For User’s Playback)
  • Add to queue (Add an item to the end of the user's current playback queue)

  You will see 403 errors if you try to use those as a free user.

ulauncher-spotify-api's Issues

Scale logos down and make styles coherent

The current logo size is too high, 709x709px

The extension crashed because it could not import module spotipy.

Crashes on Linux Mint 20

I recently decided to install ulauncher on my Linux Mint device and installed this extension. Unfortunately, after installing it, I saw that it had crashed. It gave me a command to run which I ran and restarted ulauncher, but unfortunately, it still crashed. It did give me an error message, telling me to check the logs, but I couldn't find where the logs were.

ModuleNotFoundError with spotipy installed.

Steps to reproduce

1. Install module with Extensions (add extensions)
2. Install SpotiPy with pip3 install -r requirements.txt
3. Reinstall module

Environment

Ulauncher version: Extension API v2.0.0
Linux distro: Xubuntu 20.04.1 LTS (Focal Fossa)
Desktop environment: XFCE - PyEnv (using 3.9.0 by default)

Logs

2020-12-09 17:58:59,902 | ERROR | ulauncher.api.server.ExtensionRunner: _run_process() | Extension "com.github.the-lay.ulauncher-spotify-api" exited instantly with code 1
2020-12-09 17:58:59,903 | ERROR | ulauncher.api.server.ExtensionRunner: _run_process() | Extension "com.github.the-lay.ulauncher-spotify-api" failed with an error: ModuleNotFoundError: No module named 'spotipy'

Volume controls are not working when playing on mobile devices

Seems it's impossible to change volume (sp vol X) when playing on mobile devices at all, even in the official client.

We can detect if the current player is of type 'smartphone' and show a warning instead of futily trying to change the volume.

Cant run on debian

After i install the extension via Ulauncher, i get the option to use it when sp is typed, the problem is that it never goes beyond the loading message, not even for the ? command,

Note: Autentication is never asked.

Any thought on what i am doing wrong?

Alias for switch command stop working after restart

I use the switch command a lot, so I made an alias for it, following the instructions in the extension's settings and being careful about spaces. After logging out and in again, or when restarting the launcher, the extension stops reading my alias for that specific command. Artist and Album aliases work as expected.

This is my aliases string
s: search; song: track; art: artist; on: switch; alb: albums

Bump to spotipy 2.16

Spotipy 2.16 has various fixes, including to PKCE authentication that is used here

Add podcasts functionality

Expose settings to ulauncher preferences

• Aliases control
• Authentication webserver port
• Request timeout
• Force clear image cache
• A checkbox to disable cache clearing on extension exit
• Add an option to change shortcut from sp
• Search query response limits

Add a `next` (and maybe `previous`) command.

Hey again 😃

The problem

Sometimes I want to skip a song fast. The loading screen (when the app gets the current status from spotify) in this scenario adds overhead time.

The solution

You do not have to wait for the loaded status to skip a song if you could type sp next (and sp previous) immediately.

@the-lay If it suits you I would prepare a fork. 😉

Volume control

Implement volume control: sp vol N, sp mute

Add ability to start a radio based on the current track

sp radio

Not working for me

Hello, the extension is awsome, unfortunately i can't try it, this is the error:
Message: 'com.github.the-lay.ulauncher-spotify-api'
Error Name: UnhandledError
Type: KeyError

Stacktrace:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/ulauncher/ui/windows/PreferencesUlauncherDialog.py", line 198, in on_scheme_callback
    resp = rt.dispatch(self, scheme_request.get_uri())
  File "/usr/lib/python3/dist-packages/ulauncher/utils/Router.py", line 49, in dispatch
    return callback(context, url_params)
  File "/usr/lib/python3/dist-packages/ulauncher/ui/windows/PreferencesUlauncherDialog.py", line 444, in prefs_extension_update_prefs
    controller = ExtensionServer.get_instance().get_controller(ext_id)
  File "/usr/lib/python3/dist-packages/ulauncher/api/server/ExtensionServer.py", line 76, in get_controller
    return self.controllers[extension_id]
KeyError: 'com.github.the-lay.ulauncher-spotify-api'

Add the currently playing song to saved/liked songs

keyword: sp add

alias: sp like, sp save

Update images and gif

Update images on ulauncher extensions website and the demo gif.
A lot of things were fixed and added since they were recorded.

403 Forbidden

when i try to search for a song; it suggests an open spotify app to play on as following:

and when i press enter this message occurs

OS: Elementary OS Hera 5.1.7 based on Ubuntu 18.04

Can`t running on Fedora 3 [Gtk 4]

Hi! first, congrats for this beautiful extension.

currently im trying to run the extension on Fedora 34 with GTK 4, but im getting this error:

Traceback (most recent call last):
File "/home/juniorfarias/.local/share/ulauncher/extensions/com.github.the-lay.ulauncher-spotify-api/main.py", line 5, in
from ulauncher.api.shared.item.ExtensionResultItem import ExtensionResultItem # noqa
File "/usr/lib/python3.9/site-packages/ulauncher/api/shared/item/ExtensionResultItem.py", line 6, in
from ulauncher.utils.image_loader import load_image
File "/usr/lib/python3.9/site-packages/ulauncher/utils/image_loader.py", line 9, in
from gi.repository import Gtk, Gio, GLib, GdkPixbuf
File "/usr/lib64/python3.9/site-packages/gi/importer.py", line 139, in load_module
raise ImportError(e)
ImportError: Requiring namespace 'Gdk' version '3.0', but '4.0' is already loaded