mopidy-spotify

Mopidy extension for playing music from Spotify.

Status

Warning

Spotify has recently disabled streaming via third-party access tokens, like the one Mopidy-Spotify uses. Current workarounds are to obtain a new credentials.json file using librespot and put that where Mopidy-Spotify expects it. Details at #437.

Warning

Spotify has introduced refresh token expiration as described in this blogpost. In practice this means you'll have to re-authenticate every six months going forward.

Warning

Spotify have recently disabled username and password login for playback (#394) and we now use access token login. You no longer need to provide your Spotify account username or password.

Mopidy-Spotify currently has no support for the following:

• Seeking
• Gapless playback
• Volume normalization
• Saving items to My Music (#108) - possible via web API
• Podcasts (#201) - now possible
• Radio (#9) - unavailable?
• Spotify Connect (#14)

Working support for the following features is currently available:

• Playback
• Search
• Playlists (read-only)
• Top lists and Your Music (read-only)
• Lookup by URI

Dependencies

• A Spotify Premium subscription. Mopidy-Spotify will not work with Spotify Free, just Spotify Premium.

• Mopidy >= 4.0. The music server that Mopidy-Spotify extends.

• gst-plugins-spotify, the GStreamer Rust Plugin for Spotify playback, based on librespot. This plugin is not yet available from apt.mopidy.com. It must be either built from source or Debian packages are available for some platforms.

We currently prefer a forked version of this plugin which provides better logging. Details in release notes here.

Verify the GStreamer spotify plugin is correctly installed:

gst-inspect-1.0 spotifyaudiosrc | grep Version | awk '{print $2}'

Installation

Install by running:

sudo python3 -m pip install --break-system-packages mopidy-spotify

Configuration

Before starting Mopidy, authorize Mopidy-Spotify to access your Spotify library:

mopidy spotify auth web

Open the displayed URL, approve access in Spotify, then paste the result shown by the browser into the terminal. Then start Mopidy. Run the command again if Spotify access expires or is revoked. This authorizes library access, not playback.

Run the command as the same operating-system user that runs Mopidy and with the same configuration. If you run Mopidy as a system service, use:

sudo mopidyctl spotify auth web

Run mopidy spotify logout (or sudo mopidyctl spotify logout for a system service) to clear library authorization and cached playback credentials.

Migrating from the old setup

Existing client_id and client_secret settings in the [spotify] section still work, but depend on an authentication server run by a Mopidy maintainer. We recommend removing both settings and running the authorization command above instead.

Once authorized with the command, Mopidy keeps using that authorization even if client_id and client_secret remain configured. If access expires or is revoked, run the command again; Mopidy will not automatically switch back to the old authentication server.

To switch back, keep both settings configured and run mopidy spotify logout (or sudo mopidyctl spotify logout for a system service). This also clears cached playback credentials. Mopidy uses the old authentication server on the next token refresh. To stay logged out instead, remove both settings as well.

See the authentication docs for storage options and troubleshooting.

Important

Remove any credentials.json file you may have manually created. You must also do this if you need to reauthorize playback.

Configuration values

The following configuration values are available:

• spotify/enabled: If the Spotify extension should be enabled or not. Defaults to true.

• spotify/client_id: Client ID for the old authentication server. We recommend removing this setting and using the authorization command above.

• spotify/client_secret: Client secret for the old authentication server. We recommend removing this setting and using the authorization command above.

• spotify/bitrate: Audio bitrate in kbps. 96, 160, or 320. Defaults to 160.

• spotify/volume_normalization: Whether volume normalization is active or not. Defaults to true.

• spotify/timeout: Seconds before giving up waiting for search results, etc. Defaults to 10.

• spotify/allow_cache: Whether to allow caching. The cache is stored in a "spotify" directory within Mopidy's core/cache_dir. Defaults to true.

• spotify/cache_size: Maximum cache size in MiB. Set to 0 for unlimited. Defaults to 8192.

• spotify/allow_playlists: Whether or not playlists should be exposed. Defaults to true.

• spotify/search_album_count: Maximum number of albums returned in search results. Number between 0 and 50. Defaults to 20.

• spotify/search_artist_count: Maximum number of artists returned in search results. Number between 0 and 50. Defaults to 10.

• spotify/search_track_count: Maximum number of tracks returned in search results. Number between 0 and 50. Defaults to 50.

• spotify/username: Deprecated since v5.0.0. Please remove from your configuration file.

• spotify/password: Deprecated since v5.0.0. Please remove from your configuration file.

Project resources

• Source code
• Issues
• Releases
• Authentication architecture

Development

Set up development environment

Clone the repo using, e.g. using gh:

gh repo clone mopidy/mopidy-spotify

Enter the directory, and install dependencies using uv:

cd mopidy-spotify/
uv sync

Running tests

To run all tests and linters in isolated environments, use tox:

tox

To only run tests, use pytest:

pytest

To format the code, use ruff:

ruff format .

To check for lints with ruff, run:

ruff check .

To check for type errors, use pyright:

pyright .

Making a release

To make a release to PyPI, go to the project's GitHub releases page and click the "Draft a new release" button.

In the "choose a tag" dropdown, select the tag you want to release or create a new tag, e.g. v0.1.0. Add a title, e.g. v0.1.0, and a description of the changes.

Decide if the release is a pre-release (alpha, beta, or release candidate) or should be marked as the latest release, and click "Publish release".

Once the release is created, the release.yml GitHub Action will automatically build and publish the release to PyPI.

Credits

• Original author: Stein Magnus Jodal
• Current maintainer: Nick Steel
• Contributors