spotatui

A Spotify client for the terminal written in Rust, powered by Ratatui.

Note: This is a fork of the original spotify-tui by Rigellute, which is no longer maintained. This fork aims to keep the project alive with updated dependencies and fixes.

A Spotify client for the terminal written in Rust.

⚡ Performance

spotatui is extremely lightweight compared to the official Electron client.

Mode	RAM Usage
Native Streaming (Base)	~48 MB
With Synced Lyrics	~48 MB
With System-Wide Visualizer	~56 MB

Tested on Arch Linux (Hyprland).

Privacy Notice

🔒 Anonymous Global Counter: spotatui includes an opt-in feature that contributes to a global counter showing how many songs have been played by all users worldwide. This feature:

Is completely anonymous - no personal information, song names, artists, or listening history is collected
Only sends a simple increment when a new song starts playing
Is enabled by default but can be opted out at any time
Can be disabled by setting enable_global_song_count: false in ~/.config/spotatui/config.yml

We respect your privacy. This is purely a fun community metric with zero tracking of individual users.

spotatui
Configuration

Migrating from spotify-tui

If you used the original spotify-tui before:

The binary name changed from spt → spotatui.
Config paths changed:
- Old: ~/.config/spotify-tui/
- New: ~/.config/spotatui/

You can copy your existing config:

mkdir -p ~/.config/spotatui
cp -r ~/.config/spotify-tui/* ~/.config/spotatui/

You may be asked to re-authenticate with Spotify the first time.

Installation

Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

Platform	File
Windows 10/11 (64-bit)	`spotatui-windows-x86_64.zip`
Linux (Ubuntu, Arch, Fedora, etc.)	`spotatui-linux-x86_64.tar.gz`
macOS (Intel)	`spotatui-macos-x86_64.tar.gz`
macOS (Apple Silicon M1/M2/M3)	`spotatui-macos-aarch64.tar.gz`

Checksums (.sha256) are provided if you want to verify the download.

Linux Requirements

For audio visualization on Linux, you need PipeWire installed:

# Debian/Ubuntu
sudo apt-get install libpipewire-0.3-0

# Arch Linux (already included with pipewire)
sudo pacman -S pipewirelibssl-dev pkg-config

# Fedora (already included with pipewire)
sudo dnf install pipewire

Note: Most modern Linux distributions already have PipeWire installed by default.

macOS Requirements

For macOS, spotatui uses the portaudio backend for better stability and bluetooth device support (such as AirPods).

portaudio needs to be installed first, via homebrew:

brew install portaudio

Arch Linux (AUR)

For Arch Linux users, spotatui is available in the AUR:

yay -S spotatui
# or
paru -S spotatui

Cargo

If you have Rust installed:

cargo install spotatui

Note (Linux/WSL): If you get a linker 'cc' not found error, install build tools first:
sudo apt install libssl-dev pkg-config

Building from Source

Ensure you have Rust installed.

macOS Prerequisites:

brew install portaudio

Linux Prerequisites:

# Debian/Ubuntu
sudo apt-get install libssl-dev libasound2-dev pkg-config

# Arch Linux
sudo pacman -S openssl alsa-lib pkg-config

# Fedora
sudo dnf install openssl-devel alsa-lib-devel pkg-config

Building:

Clone the repository:

git clone https://github.com/LargeModGames/spotatui.git
cd spotatui

Build and install:

macOS:

cargo install --path . --no-default-features --features telemetry,streaming,portaudio-backend,audio-viz-cpal

Linux/Windows:

cargo install --path .

Or build and run directly:

cargo run --release

Nix:

nix-build

Updating

When a new version of spotatui is available, you'll see a popup notification on startup. To update:

Close spotatui
Run the following command:
```
spotatui update --install
```

This will download and install the latest version automatically. If you install spotatui through your package manager, it is suggested to update through there instead of the command above.

Connecting to Spotify's API

spotatui needs to connect to Spotify’s API in order to find music by name, play tracks etc.

Instructions on how to set this up will be shown when you first run the app.

But here they are again:

Go to the Spotify dashboard
Click Create an app
- You now can see your Client ID and Client Secret
Now click Edit Settings
Add the following Redirect URIs (use 127.0.0.1 instead of localhost as Spotify no longer allows localhost):
- http://127.0.0.1:8888/callback (for API authentication)
- http://127.0.0.1:8989/login (for native streaming - see Native Streaming)
Scroll down and click Save
You are now ready to authenticate with Spotify!
Go back to the terminal
Run spotatui
Enter your Client ID
Enter your Client Secret
Press enter to confirm the default port (8888) or enter a custom port
You will be redirected to an official Spotify webpage to ask you for permissions.
After accepting the permissions, you'll be redirected to localhost. If all goes well, the redirect URL will be parsed automatically and now you're done. If the local webserver fails for some reason you'll be redirected to a blank webpage that might say something like "Connection Refused" since no server is running. Regardless, copy the URL and paste into the prompt in the terminal.

💡 Tip: If the authentication doesn't work after pasting the URL, try changing 127.0.0.1 to localhost in the copied URL before pasting it into the terminal. Some systems may have issues with one format or the other.

And now you are ready to use spotatui 🎉

You can edit the config at anytime at ${HOME}/.config/spotatui/client.yml.

Usage

The binary is named spotatui.

Running spotatui with no arguments will bring up the UI. Press ? to bring up a help menu that shows currently implemented key events and their actions. There is also a CLI that is able to do most of the stuff the UI does. Use spotatui --help to learn more.

Here are some example to get you excited.

spotatui --completions zsh # Prints shell completions for zsh to stdout (bash, power-shell and more are supported)

spotatui play --name "Your Playlist" --playlist --random # Plays a random song from "Your Playlist"
spotatui play --name "A cool song" --track # Plays 'A cool song'

spotatui playback --like --shuffle # Likes the current song and toggles shuffle mode
spotatui playback --toggle # Plays/pauses the current playback

spotatui list --liked --limit 50 # See your liked songs (50 is the max limit)

# Looks for 'An even cooler song' and gives you the '{name} from {album}' of up to 30 matches
spotatui search "An even cooler song" --tracks --format "%t from %b" --limit 30

Native Streaming (Experimental)

spotatui now includes native Spotify Connect support, allowing it to play audio directly on your computer without needing an external player like spotifyd.

Setup

The native streaming feature uses a separate authentication flow. On first run:

Your browser will open to Spotify's authorization page
Important: The redirect URI will be http://127.0.0.1:8989/login - this is different from the main app's callback URL
After authorizing, "spotatui" will appear in your Spotify Connect device list
Credentials are cached so you only need to do this once

How It Works

When streaming is enabled, "spotatui" registers as a Spotify Connect device
You can control playback from the TUI, your phone, or any other Spotify client
Audio plays directly on the computer running spotatui

Notes

Native streaming is enabled by default when built with the streaming feature
Premium account is required for playback
The streaming authentication uses a different client than the main app's API controls

MPRIS D-Bus Integration (Linux)

When using native streaming on Linux, spotatui automatically registers with the MPRIS D-Bus interface, enabling:

Media key support - Play/pause, next, previous via keyboard media keys
Desktop integration - Track info appears in GNOME/KDE media widgets
playerctl compatibility - Control spotatui from the command line:

# Check available players
playerctl -l
# Should show: spotatui

# Control playback
playerctl -p spotatui play-pause
playerctl -p spotatui next
playerctl -p spotatui previous

# View current track metadata
playerctl -p spotatui metadata

MPRIS is enabled by default on Linux builds with native streaming.

Configuration

A configuration file is located at ${HOME}/.config/spotatui/config.yml. (not to be confused with client.yml which handles spotify authentication)

The following is a sample config.yml file:

# Sample config file

# The theme colours can be an rgb string of the form "255, 255, 255" or a string that references the colours from your terminal theme: Reset, Black, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, DarkGray, LightRed, LightGreen, LightYellow, LightBlue, LightMagenta, LightCyan, White.
theme:
  active: Cyan # current playing song in list
  banner: LightCyan # the "spotatui" banner on launch
  error_border: Red # error dialog border
  error_text: LightRed # error message text (e.g. "Spotify API reported error 404")
  hint: Yellow # hint text in errors
  hovered: Magenta # hovered pane border
  inactive: Gray # borders of inactive panes
  playbar_background: Black # background of progress bar
  playbar_progress: LightCyan # filled-in part of the progress bar
  playbar_progress_text: Cyan # song length and time played/left indicator in the progress bar
  playbar_text: White # artist name in player pane
  selected: LightCyan # a) selected pane border, b) hovered item in list, & c) track title in player
  text: "255, 255, 255" # text in panes
  header: White # header text in panes (e.g. 'Title', 'Artist', etc.)

behavior:
  seek_milliseconds: 5000
  volume_increment: 10
  # The lower the number the higher the "frames per second". You can decrease this number so that the audio visualisation is smoother but this can be expensive!
  tick_rate_milliseconds: 250
  # Enable text emphasis (typically italic/bold text styling). Disabling this might be important if the terminal config is otherwise restricted and rendering text escapes interferes with the UI.
  enable_text_emphasis: true
  # Controls whether to show a loading indicator in the top right of the UI whenever communicating with Spotify API
  show_loading_indicator: true
  # Disables the responsive layout that makes the search bar smaller on bigger
  # screens and enforces a wide search bar
  enforce_wide_search_bar: false
  # Contribute to the global song counter (completely anonymous, no PII collected)
  # Set to false to opt out of contributing to the global counter
  enable_global_song_count: true
  # Determines the text icon to display next to "liked" Spotify items, such as
  # liked songs and albums, or followed artists. Can be any length string.
  # These icons require a patched nerd font.
  liked_icon: ♥
  shuffle_icon: 🔀
  repeat_track_icon: 🔂
  repeat_context_icon: 🔁
  playing_icon: ▶
  paused_icon: ⏸
  # Sets the window title to "spotatui - Spotify TUI" via ANSI escape code.
  set_window_title: true

keybindings:
  # Key stroke can be used if it only uses two keys:
  # ctrl-q works,
  # ctrl-alt-q doesn't.
  back: "ctrl-q"

  jump_to_album: "a"

  # Shift modifiers use a capital letter (also applies with other modifier keys
  # like ctrl-A)
  jump_to_artist_album: "A"

  manage_devices: "d"
  decrease_volume: "-"
  increase_volume: "+"
  toggle_playback: " "
  seek_backwards: "<"
  seek_forwards: ">"
  next_track: "n"
  previous_track: "p"
  copy_song_url: "c"
  copy_album_url: "C"
  help: "?"
  shuffle: "ctrl-s"
  repeat: "r"
  search: "/"
  audio_analysis: "v"
  jump_to_context: "o"
  basic_view: "B"
  add_item_to_queue: "z"

In-App Settings

Press Alt-, to open the Settings screen, where you can customize spotatui without editing config files manually.

Settings Categories

Category	Description
Behavior	Seek duration, volume increment, tick rate, icons, toggles
Keybindings	View current keybindings (customization coming soon)
Theme	Color presets and individual color customization

Theme Presets

Choose from 7 built-in theme presets:

Preset	Description
Default (Cyan)	Original spotatui theme
Spotify	Official Spotify green (#1DB954)
Dracula	Popular dark purple/pink theme
Nord	Arctic, bluish color palette
Solarized Dark	Classic dark theme
Monokai	Vibrant colors on dark background
Gruvbox	Warm retro groove colors

Controls

Key	Action
`Alt-,`	Open Settings
`←` / `→`	Switch category tabs
`↑` / `↓`	Navigate settings
`Enter`	Toggle boolean / Cycle preset / Edit value
`Alt-S`	Save changes
`Esc`	Exit Settings

Changes are applied immediately when saved - no restart required!

Limitations

This app uses the Web API from Spotify, which doesn't handle streaming itself. You have three options for audio playback:

Native Streaming (NEW!) - spotatui can now play audio directly using its built-in streaming feature. See Native Streaming below.
Official Spotify Client - Have the official Spotify app open on your computer
Spotifyd - Use a lightweight alternative like spotifyd

If you want to play tracks, Spotify requires that you have a Premium account.

Deprecated Spotify API Features

Note: As of November 2024, Spotify deprecated and removed access to certain API endpoints for new applications. The following features are included in this app but will only work if your Spotify Developer application was created before November 27, 2024:

Audio Visualization (press v): Now uses local real-time FFT analysis of your system audio. The visualization no longer depends on Spotify's deprecated Audio Analysis API.

Platform Support:

Platform	Status	Notes
Windows	✅ Works out of the box	Uses WASAPI loopback
Linux	✅ Works out of the box	Uses PipeWire/PulseAudio monitor devices
macOS	⚠️ Requires setup	Needs a virtual audio device (see below)

macOS Users: macOS doesn't natively expose system audio loopback. To use audio visualization, install a virtual audio device like BlackHole (free) or Loopback (paid). Configure it to capture system audio and set it as your default input device.

Note: The audio visualization is system-wide – it captures all audio playing on your system, not just Spotify. This means it will also react to YouTube videos, games, or any other audio source!

Related Artists: When viewing an artist page, the "Related Artists" section shows similar artists based on Spotify's recommendation algorithm. This feature only works if your Spotify Developer application was created before November 27, 2024.

For more information, see Spotify's announcement about API changes.

Using with spotifyd

Note: If you're using native streaming, you don't need spotifyd!

Follow the spotifyd documentation to get set up.

After that there is not much to it.

Start running the spotifyd daemon.
Start up spotatui
Press d to go to the device selection menu and the spotifyd "device" should be there - if not check these docs

Libraries used

Development

Install OpenSSL
Install Rust
Install xorg-dev (required for clipboard support)

Linux only: Install PipeWire development libraries (required for audio visualization)

# Debian/Ubuntu
sudo apt-get install libpipewire-0.3-dev libspa-0.2-dev

# Arch Linux
sudo pacman -S pipewire

# Fedora
sudo dnf install pipewire-devel

Clone or fork this repo and cd to it
And then cargo run

See CONTRIBUTING.md for pull request guidelines.

Windows Subsystem for Linux

You might get a linking error. If so, you'll probably need to install additional dependencies required by the clipboard package

sudo apt-get install -y -qq pkg-config libssl-dev libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev

Maintainer

Maintained by LargeModGames.

Original author: Alexander Keliris.

Contributors

Thanks goes to these wonderful people (emoji key):

_{LargeModGames} 💻 📖 ⚠️ 🤔 🚇 🚧	_{Alexander Keliris} 💻 📖 🎨 📝 🤔 🚇 📦 👀	_{Mickael Marques} 💵	_{Grzegorz Koperwas} 📖	_{Austin Gassert} 💻	_{Calen Robinette} 💻	_MCO 🚇
_{Andrew Chin} 💻	_{Sam Naser} 💻	_Micha 💻	_neriglissar 💻	_Timon 💻	_echoSayonara 💻	_D-Nice 📖 🚇
_{Grzegorz Pawlik} 💻	_{Lennart Bernhardt} 💻	_{Arnaud Lefebvre} 💻	_tem1029 💻	_{Peter K. Moss} 💻	_{Geoff Shannon} 💻	_{Zachary Mayhew} 💻
_jfaltis 💻	_{Marcel Schramm} 📖	_{Fangyi Zhou} 💻	_Max 💻	_{Sven van der Vlist} 💻	_{jacobchrismarsh} 💻	_{Nils Rauch} 💻
_{Nick Stockton} 💻 🐛 🚧 💬 📖	_{Stuart Hinson} 💻	_{Sam Calvert} 💻 📖	_{Jeroen Wijenbergh} 📖	_{Kimberley Cook} 📖	_{Audrey Baxter} 💻	_Norman 📖
_{Peter Maatman} 💻	_AlexandreS 💻	_{Finn Vos} 💻	_{Carlos Hernandez} 📦	_{Pedro Alves} 💻	_jtagcat 📖	_{Benjamin Kitor} 💻
_{Aleš Najmann} 📖 📦	_{Jeremy Stucki} 💻	_(´⌣`ʃƪ) 💻	_{Artem Polishchuk} 📦	_{Chris Sosnin} 💻	_{Ben Buhse} 📖	_{Sean Li} 💻
_{TimotheeGerber} 💻 📖	_{Ferdinand Ratajczak} 💻	_{Sheel Choksi} 💻	_{Michael Hellwig} 📖	_{Oliver Daniel} 💻	_{Drew Fisher} 💻	_ncoder-1 📖
_{Macguire Rintoul} 📖	_{Ricardo Holguin} 💻	_{Keisuke Toyota} 💻	_{Craig Astill} 💻	_Onielfa 💻	_usrme 📖	_{Sergey A.} 💻
_{Hideyuki Okada} 💻	_kepae 💻 📖	_{Érico Nogueira Rolim} 💻	_{Alexander Meinhardt Scheurer} 💻	_{Ondřej Kinšt} 💻	_Kryan90 📖	_n-ivanov 💻
_bi1yeu 💻 📖	_May 💻	_{Bruno A. Muciño} 💻	_{Finn Hediger} 💻	_dp304 💻	_{Marco Micera} 📖	_{Marco Ieni} 🚇
_{Artúr Kovács} 💻	_{Antony Kellermann} 💻	_{Rasmus Pedersen} 💻	_noir-Z 📖	_{David Bailey} 📖	_sheepwall 💻	_Hwatwasthat 💻
_Jesse 💻	_Sang 📖	_{Yuuki Takahashi} 📖	_{Alejandro Angulo} 💻	_{Anton Kostin} 📖	_{Justin Sexton} 💻	_{Jiati Le} 📖
_{Matthew Cobbing} 💻	_Milo 🚇	_{Diego Veralli} 💻	_{Maja Bojarska} 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Star History

Roadmap

The goal is to eventually implement almost every Spotify feature.

High-level requirements yet to be implemented

Add songs to a playlist
Be able to scroll through result pages in every view

This table shows all that is possible with the Spotify API, what is implemented already, and whether that is essential.

API method	Implemented yet?	Explanation	Essential?
track	No	returns a single track given the track's ID, URI or URL	No
tracks	No	returns a list of tracks given a list of track IDs, URIs, or URLs	No
artist	No	returns a single artist given the artist's ID, URI or URL	Yes
artists	No	returns a list of artists given the artist IDs, URIs, or URLs	No
artist_albums	Yes	Get Spotify catalog information about an artist's albums	Yes
artist_top_tracks	Yes	Get Spotify catalog information about an artist's top 10 tracks by country.	Yes
artist_related_artists	Yes	Get Spotify catalog information about artists similar to an identified artist. Similarity is based on analysis of the Spotify community's listening history.	Yes
album	Yes	returns a single album given the album's ID, URIs or URL	Yes
albums	No	returns a list of albums given the album IDs, URIs, or URLs	No
search_album	Yes	Search album based on query	Yes
search_artist	Yes	Search artist based on query	Yes
search_track	Yes	Search track based on query	Yes
search_playlist	Yes	Search playlist based on query	Yes
album_track	Yes	Get Spotify catalog information about an album's tracks	Yes
user	No	Gets basic profile information about a Spotify User	No
playlist	Yes	Get full details about Spotify playlist	Yes
current_user_playlists	Yes	Get current user playlists without required getting his profile	Yes
user_playlists	No	Gets playlists of a user	No
user_playlist	No	Gets playlist of a user	No
user_playlist_tracks	Yes	Get full details of the tracks of a playlist owned by a user	Yes
user_playlist_create	No	Creates a playlist for a user	Yes
user_playlist_change_detail	No	Changes a playlist's name and/or public/private state	Yes
user_playlist_unfollow	Yes	Unfollows (deletes) a playlist for a user	Yes
user_playlist_add_track	No	Adds tracks to a playlist	Yes
user_playlist_replace_track	No	Replace all tracks in a playlist	No
user_playlist_recorder_tracks	No	Reorder tracks in a playlist	No
user_playlist_remove_all_occurrences_of_track	No	Removes all occurrences of the given tracks from the given playlist	No
user_playlist_remove_specific_occurrenes_of_track	No	Removes all occurrences of the given tracks from the given playlist	No
user_playlist_follow_playlist	Yes	Add the current authenticated user as a follower of a playlist.	Yes
user_playlist_check_follow	No	Check to see if the given users are following the given playlist	Yes
me	No	Get detailed profile information about the current user.	Yes
current_user	No	Alias for `me`	Yes
current_user_playing_track	Yes	Get information about the current users currently playing track.	Yes
current_user_saved_albums	Yes	Gets a list of the albums saved in the current authorized user's "Your Music" library	Yes
current_user_saved_tracks	Yes	Gets the user's saved tracks or "Liked Songs"	Yes
current_user_followed_artists	Yes	Gets a list of the artists followed by the current authorized user	Yes
current_user_saved_tracks_delete	Yes	Remove one or more tracks from the current user's "Your Music" library.	Yes
current_user_saved_tracks_contain	No	Check if one or more tracks is already saved in the current Spotify user’s “Your Music” library.	Yes
current_user_saved_tracks_add	Yes	Save one or more tracks to the current user's "Your Music" library.	Yes
current_user_top_artists	No	Get the current user's top artists	Yes
current_user_top_tracks	No	Get the current user's top tracks	Yes
current_user_recently_played	Yes	Get the current user's recently played tracks	Yes
current_user_saved_albums_add	Yes	Add one or more albums to the current user's "Your Music" library.	Yes
current_user_saved_albums_delete	Yes	Remove one or more albums from the current user's "Your Music" library.	Yes
user_follow_artists	Yes	Follow one or more artists	Yes
user_unfollow_artists	Yes	Unfollow one or more artists	Yes
user_follow_users	No	Follow one or more users	No
user_unfollow_users	No	Unfollow one or more users	No
featured_playlists	No	Get a list of Spotify featured playlists	Yes
new_releases	No	Get a list of new album releases featured in Spotify	Yes
categories	No	Get a list of categories used to tag items in Spotify	Yes
recommendations	Yes	Get Recommendations Based on Seeds	Yes
audio_features	No	Get audio features for a track	No
audios_features	No	Get Audio Features for Several Tracks	No
audio_analysis	Yes	Get Audio Analysis for a Track	Yes
device	Yes	Get a User’s Available Devices	Yes
current_playback	Yes	Get Information About The User’s Current Playback	Yes
current_playing	No	Get the User’s Currently Playing Track	No
transfer_playback	Yes	Transfer a User’s Playback	Yes
start_playback	Yes	Start/Resume a User’s Playback	Yes
pause_playback	Yes	Pause a User’s Playback	Yes
next_track	Yes	Skip User’s Playback To Next Track	Yes
previous_track	Yes	Skip User’s Playback To Previous Track	Yes
seek_track	Yes	Seek To Position In Currently Playing Track	Yes
repeat	Yes	Set Repeat Mode On User’s Playback	Yes
volume	Yes	Set Volume For User’s Playback	Yes
shuffle	Yes	Toggle Shuffle For User’s Playback	Yes

Name		Name	Last commit message	Last commit date
Latest commit History 1,545 Commits
.github		.github
snap		snap
src		src
.all-contributorsrc		.all-contributorsrc
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
default.nix		default.nix
how_to_release.md		how_to_release.md
rustfmt.toml		rustfmt.toml

Folders and files

Latest commit

History

Repository files navigation

spotatui

⚡ Performance

Privacy Notice

Migrating from spotify-tui

Installation

Pre-built Binaries

Linux Requirements

macOS Requirements

Arch Linux (AUR)

Cargo

Building from Source

Updating

Connecting to Spotify's API

Usage

Native Streaming (Experimental)

Setup

How It Works

Notes

MPRIS D-Bus Integration (Linux)

Configuration

In-App Settings

Settings Categories

Theme Presets

Controls

Limitations

Deprecated Spotify API Features

Using with spotifyd

Libraries used

Development

Windows Subsystem for Linux

Maintainer

Contributors

Star History

Roadmap

High-level requirements yet to be implemented

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages