spotidry 0.0.10

A boring Spotify CLI client

Spotidry

• Spotidry
• Summary
• Installation
• Setup
  • Spotify API
  • Configuration
  • Tmux Integration
  • Polybar Integration
• Usage
• Roadmap
• Contributions

Summary

Spotidry is a real dry & boring command-line client for Spotify.

My main motivation for this project is to have a simple client that allows me to save the currently-playing song to my Liked Tracks. I also added play/pause/next/previous commands.

One of the best use cases for spotidry is to integrate it into a polybar/tmux/vim status line. You can also map some key-bindings or foot-pedals to send spotidry command.

Below, is a demo video showing some basic spotidry commands, along with a tmux integration.

Installation

It is recommended to install spotidry using uv:

uv tool install -e .

Alternatively, you can install from PyPI:

pip install --user spotidry
spotidry --setup

Note: I have only tested spotidry on Linux.

Development

To set up a local development environment:

1. Clone the repository:

   git clone https://github.com/mikeboiko/spotidry.git
   cd spotidry
   

2. Install the tool in editable mode:

   uv tool install --editable .
   

3. Run type checking:

   uv run basedpyright spotidry
   

Deployment

The deployment process to PyPI and GitHub Releases is automated via GitHub Actions.

Manual Steps

To trigger a new release:

1. Update Changelog: Add release notes for the new version in CHANGELOG.md.
2. Bump Version: Update the version number in spotidry/__init__.py.
3. Commit & Push: Commit these changes and push to the master branch.

Automated Steps

Once the tag is pushed, the GitHub Action will automatically:

1. Build the package (sdist and wheel).
2. Check the package metadata with twine.
3. Create a GitHub Release with the built artifacts and auto-generated notes.
4. Publish the package to PyPI.

Note: Ensure the PYPI_API_TOKEN secret is set in the GitHub repository settings.

Setup

Spotify API

You will need to register your app at My Dashboard to get the credentials necessary to make authorized calls (a client id and client secret). Select the Web API scope.

You can set your redirect URI to something like "http://127.0.0.1:9999"

Configuration

Configure your Spotify API variables in ~/.config/spotidry/spotidry.yaml

client_id: '<ID>'
client_secret: '<SECRET>'
redirect_uri: 'http://127.0.0.1:9999'
output_format: '{play_symbol} {artist_song} {liked_symbol}'

# Optional: scrolling for long titles (meant for 1Hz status lines like tmux/polybar)
max_width: 30
scroll_speed: 0.5
scroll_gap: '   '

# Optional: reuse recent playback data between CLI invocations
status_cache_seconds: 5

The output_format string supports the following placeholders:

• {artist}: Artist name
• {song}: Track title
• {artist_song}: Convenience string of "{artist} - {song}" (and the one that scrolls)
• {play_symbol}: Play/Pause indicator (▶ or ⏸)
• {liked_symbol}: Liked status indicator (❤ or ♡)

Use status_cache_seconds to control how often spotidry asks Spotify for fresh playback data. The default of 5 keeps 1 Hz status bars smooth while limiting Spotify requests to about once every 5 seconds. Increase the value if you still hit rate limits, or set it to 0 to fetch fresh data on every run.

Recent playback data is cached in ~/.cache/spotidry/status_cache.json. If Spotify temporarily returns a rate limit response, spotidry will continue showing the most recent cached status instead of waiting on a long retry.

Tmux Integration

Example for the popular .tmux config:

tmux_conf_theme_status_right='#(flock -n /tmp/spotidry.lock spotidry 2>/dev/null; sleep 1) #{prefix}#{pairing} #{?battery_status, #{battery_status},}#{?battery_bar, #{battery_bar},}#{?battery_percentage, #{battery_percentage},} , %R , %d %b | #{username}#{root} | #{hostname} '

This example redraws once per second for smooth scrolling. With the default status_cache_seconds: 5, Spotify is still refreshed only about once every 5 seconds.

If 1 Hz scrolling is not necessary, increase the shell sleep to reduce API traffic even further.

Polybar Integration

Add the following module to ~/.config/polybar/config.ini

[module/spotidry]
type = custom/script
exec = ~/.local/bin/spotidry
exec-if = test -f ~/.local/bin/spotidry
click-left = ~/.local/bin/spotidry --next 2> /dev/null
click-middle = ~/.local/bin/spotidry --save 2> /dev/null
click-right = ~/.local/bin/spotidry --play 2> /dev/null
interval = 1

This example uses interval = 1 for smooth scrolling. With the default cache settings, Spotify is still refreshed only about once every 5 seconds.

To reduce API traffic further, either raise status_cache_seconds or increase the Polybar interval.

Usage

The first time you run spotidry, you will be prompted to authorize the app in your browser.

Run spotidry --help to see all commands/options.

usage: spotidry [-h] [-v] [-s] [-p] [-n] [--previous]

Spotify CLI client

options:
  -h, --help     show this help message and exit
  -v, --version  show program's version number and exit
  -s, --save     toggle liked track status
  -p, --play     play/pause track
  -n, --next     play next track
  --previous     play previous track/skip to beggining of current track

Note, in order to re-authorize, delete ~/.cache/spotidry.yaml... Yes, I will provide a CLI flag for this eventually.

Roadmap

• Save currently playing song to Liked Tracks
• Add output string customization
• Scrolling Text for Long Titles
• Add volume controls/status
• Add socks/https proxy option

Contributions

Contributions are always welcome!

Feel free to submit an issue or a pull request.