# spotatui > A Spotify client for the terminal written in Rust, powered by [Ratatui](https://github.com/ratatui-org/ratatui). > > A community-maintained fork of [spotify-tui](https://github.com/Rigellute/spotify-tui), actively developed with new features like native streaming, synced lyrics, and real-time audio visualization. [![Crates.io](https://img.shields.io/crates/v/spotatui.svg)](https://crates.io/crates/spotatui) [![Upstream](https://img.shields.io/badge/upstream-Rigellute%2Fspotify--tui-blue)](https://github.com/Rigellute/spotify-tui) [![Songs played using Spotatui](https://img.shields.io/badge/dynamic/json?url=https://spotatui-counter.spotatui.workers.dev&query=count&label=Songs%20played%20using%20spotatui&labelColor=0b0f14&color=1ed760&logo=spotify&logoColor=1ed760&style=flat-square&cacheSeconds=600)](https://github.com/LargeModGames/spotatui) [![spotatui Contributors](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/LargeModGames/spotatui/main/.all-contributorsrc&query=%24.contributors.length&label=spotatui%20contributors&color=1ed760&style=flat-square)](#spotatui-contributors) [![Upstream Contributors](https://img.shields.io/badge/upstream_contributors-94-orange.svg?style=flat-square)](#upstream-contributors-spotify-tui) ![Demo](.github/demo.gif) ## Song History ![Song History](https://spotatui-counter.spotatui.workers.dev/chart.svg) ## Table of Contents - [Help Wanted](#help-wanted) - [Performance](#performance) - [Privacy Notice](#privacy-notice) - [Migrating from spotify-tui](#migrating-from-spotify-tui) - [Installation](#installation) - [Connecting to Spotify](#connecting-to-spotify) - [Usage](#usage) - [Native Streaming](#native-streaming) - [Configuration](#configuration) - [Discord Rich Presence](#discord-rich-presence) - [Limitations](#limitations) - [Deprecated Spotify API Features](#deprecated-spotify-api-features) - [Using with spotifyd](#using-with-spotifyd) - [Libraries used](#libraries-used) - [Development](#development) - [Windows Subsystem for Linux](#windows-subsystem-for-linux) - [Maintainer](#maintainer) - [spotatui Contributors](#spotatui-contributors) - [Upstream Contributors (spotify-tui)](#upstream-contributors-spotify-tui) - [Star History](#star-history) - [Roadmap](#roadmap) ## Help Wanted **spotatui is currently maintained by a solo developer.** More contributors would be hugely appreciated! Here's how you can help: - **Star the repo** to help others discover the project - **Report bugs** or request features in [Issues](https://github.com/LargeModGames/spotatui/issues) - **Join the community** in [Discussions](https://github.com/LargeModGames/spotatui/discussions) - **Submit a PR** for code, docs, or themes See [CONTRIBUTING.md](CONTRIBUTING.md) for more details! ## Performance spotatui is extremely lightweight compared to the official Electron client. | Mode | RAM Usage | | :------------------------------ | :-------- | | **Native Streaming (Base)** | ~78 MB | | **With Synced Lyrics** | ~78 MB | | **With System-Wide Visualizer** | ~80 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. ## Migrating from spotify-tui If you used the original `spotify-tui` before: - The binary name changed from `spt` to `spotatui`. - Config paths changed: - Old: `~/.config/spotify-tui/` - New: `~/.config/spotatui/` You can copy your existing config: ```bash mkdir -p ~/.config/spotatui cp -r ~/.config/spotify-tui/* ~/.config/spotatui/ ``` You may be asked to re-authenticate with Spotify the first time. ## Installation > **Important:** Spotify Premium is required for playback features (native streaming and Web API playback controls). ```bash # Homebrew (macOS only) brew tap LargeModGames/spotatui brew install spotatui # Winget (Windows) winget install spotatui # Cargo cargo install spotatui # Arch Linux (AUR) - pre-built binary (faster) yay -S spotatui-bin # Arch Linux (AUR) - build from source yay -S spotatui # Void Linux (Unoffical Repo) echo repository=https://raw.githubusercontent.com/Event-Horizon-VL/blackhole-vl/repository-x86_64 | sudo tee /etc/xbps.d/20-repository-extra.conf sudo xbps-install -S spotatui ``` ```nix # NixOS (Flake) # Add spotatui to your flake inputs: inputs = { spotatui = { url = "github:LargeModGames/spotatui"; inputs.nixpkgs.follows = "nixpkgs"; }; } # Add the spotatui package from your inputs to your config: { inputs, ...}:{ # Your other configurations environment.systemPackages = with pkgs; [ inputs.spotatui.packages.${pkgs.stdenv.hostPlatform.system}.default ]; } ``` Or download pre-built binaries from [GitHub Releases](https://github.com/LargeModGames/spotatui/releases/latest). See the [Installation Wiki](https://github.com/LargeModGames/spotatui/wiki/Installation) for platform-specific requirements and building from source. ## Connecting to Spotify Run `spotatui` and follow the on-screen instructions to connect your Spotify account. You'll need to create a Spotify Developer app at the [Spotify Dashboard](https://developer.spotify.com/dashboard/applications). See the [Installation Wiki](https://github.com/LargeModGames/spotatui/wiki/Installation#connecting-to-spotify) for step-by-step setup. ## 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. See [Keybindings Wiki](https://github.com/LargeModGames/spotatui/wiki/Keybindings) for the full list of keyboard shortcuts. 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 spotatui can play audio directly without needing spotifyd or the official Spotify app. Just run `spotatui` and it will appear as a Spotify Connect device. - Works with media keys, MPRIS (Linux), and macOS Now Playing - Premium account required See the [Native Streaming Wiki](https://github.com/LargeModGames/spotatui/wiki/Native-Streaming) for setup details. ## Configuration A configuration file is located at `${HOME}/.config/spotatui/config.yml`. See the [Configuration Wiki](https://github.com/LargeModGames/spotatui/wiki/Configuration) for the full config file reference. You can also configure spotatui in-app by pressing `Alt-,` to open Settings. See [Themes Wiki](https://github.com/LargeModGames/spotatui/wiki/Themes) for built-in presets (Spotify, Dracula, Nord, etc.). ### Discord Rich Presence Discord Rich Presence is enabled by default and uses the built-in spotatui application ID, so no extra setup is required. Overrides (optional): ```yaml behavior: enable_discord_rpc: true discord_rpc_client_id: "your_client_id" ``` You can also override via `SPOTATUI_DISCORD_APP_ID` or disable in the setting or by setting `behavior.enable_discord_rpc: false` in ~/.config/spotatui/config.yml. ## Limitations This app uses the [Web API](https://developer.spotify.com/documentation/web-api/) from Spotify, which doesn't handle streaming itself. You have three options for audio playback: 1. **Native Streaming (NEW!)** - spotatui can now play audio directly using its built-in streaming feature. See [Native Streaming](#native-streaming) below. 2. **Official Spotify Client** - Have the official Spotify app open on your computer 3. **Spotifyd** - Use a lightweight alternative like [spotifyd](https://github.com/Spotifyd/spotifyd) If you want to play tracks, Spotify requires that you have a Premium account. With a free account, spotatui can still authenticate and browse your library/search results, but playback actions (play/pause/seek/transfer) will not work in either: - Native Streaming (librespot) - Web API playback control mode ### 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](https://github.com/ExistentialAudio/BlackHole) (free) or [Loopback](https://rogueamoeba.com/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](https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api). ## Using with [spotifyd](https://github.com/Spotifyd/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. 1. Start running the spotifyd daemon. 1. Start up `spotatui` 1. Press `d` to go to the device selection menu and the spotifyd "device" should be there - if not check [these docs](https://github.com/Spotifyd/spotifyd#logging) ## Libraries used - [ratatui](https://github.com/ratatui-org/ratatui) - Terminal UI framework - [rspotify](https://github.com/ramsayleung/rspotify) - Spotify Web API client - [librespot](https://github.com/librespot-org/librespot) - Spotify Connect streaming - [tokio](https://github.com/tokio-rs/tokio) - Async runtime - [crossterm](https://github.com/crossterm-rs/crossterm) - Terminal manipulation - [clap](https://github.com/clap-rs/clap) - CLI argument parsing ## Development 1. [Install OpenSSL](https://docs.rs/openssl/0.10.25/openssl/#automatic) 1. [Install Rust](https://www.rust-lang.org/tools/install) 1. [Install `xorg-dev`](https://github.com/aweinstock314/rust-clipboard#prerequisites) (required for clipboard support) 1. **Linux only:** Install PipeWire development libraries (required for audio visualization) ```bash # 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 # NixOS nix develop github:LargeModGames/spotatui ``` 1. Clone or fork this repo and `cd` to it 1. And then `cargo run` See [CONTRIBUTING.md](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 ```bash 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](https://github.com/LargeModGames)**. Originally forked from [spotify-tui](https://github.com/Rigellute/spotify-tui) by [Alexander Keliris](https://github.com/Rigellute). ## spotatui Contributors **Looking for contributors!** spotatui is actively maintained but could use your help. Whether it's bug fixes, new features, documentation, or testing - all contributions are welcome!
LargeModGames
LargeModGames
πŸ’» πŸ“– 🚧 πŸ€” πŸš‡ ⚠️		 MysteriousWolf
MysteriousWolf
πŸ’»		 rawcode1337
rawcode1337
πŸ’» πŸ›		 copeison
copeison
πŸ“¦		 jacklorusso
jacklorusso
πŸ“–		 H41L33
H41L33
πŸ“–		 LordMZTE
LordMZTE
πŸ’»
Sebastian Sarco
Sebastian Sarco
πŸ’»		 Sergio Tabernero HernΓ‘ndez
Sergio Tabernero HernΓ‘ndez
πŸ’» πŸ“¦		 David Novakovic
David Novakovic
πŸ’»		 Paul
Paul
🎨 πŸ’»		 Arun Felix
Arun Felix
πŸ’» πŸ›		 MaySeikatsu
MaySeikatsu
πŸ’» πŸ“– πŸ“¦		 Lorenzo Bodini
Lorenzo Bodini
πŸ’» 🎨
Vi1i Petal
Vi1i Petal
πŸ’» πŸ›		 Will Sturgeon
Will Sturgeon
πŸ’» πŸ›		 wfinken
wfinken
πŸ’» πŸ›		 Jacob
Jacob
πŸ“¦		 Dominick Lee
Dominick Lee
πŸ’»		 Higor Prado
Higor Prado
πŸ’»		 Vitali Kaplich
Vitali Kaplich
πŸ“–
knth
knth
πŸ’»		 Lorelei Noble
Lorelei Noble
πŸ’»		 Ben Allen
Ben Allen
πŸ’»		 shilicioo
shilicioo
πŸ’»		 Thomas Allan
Thomas Allan
πŸ’»		 Pratyoosh Prakash
Pratyoosh Prakash
πŸ’» πŸ›
*Want to see your name here? Check out our [open issues](https://github.com/LargeModGames/spotatui/issues) or the [Roadmap](#roadmap) below!* --- ## Upstream Contributors (spotify-tui) Thanks to all the contributors who built the original [spotify-tui](https://github.com/Rigellute/spotify-tui) that this project is forked from:
Alexander Keliris
Alexander Keliris
πŸ’» πŸ“– 🎨 πŸ“ πŸ€” πŸš‡ πŸ“¦ πŸ‘€		 Mickael Marques
Mickael Marques
πŸ’΅		 Grzegorz Koperwas
Grzegorz Koperwas
πŸ“–		 Austin Gassert
Austin Gassert
πŸ’»		 Calen Robinette
Calen Robinette
πŸ’»		 M*C*O
M*C*O
πŸš‡
Andrew Chin
Andrew Chin
πŸ’»		 Sam Naser
Sam Naser
πŸ’»		 Micha
Micha
πŸ’»		 neriglissar
neriglissar
πŸ’»		 Timon
Timon
πŸ’»		 echoSayonara
echoSayonara
πŸ’»		 D-Nice
D-Nice
πŸ“– πŸš‡
Grzegorz Pawlik
Grzegorz Pawlik
πŸ’»		 Lennart Bernhardt
Lennart Bernhardt
πŸ’»		 Arnaud Lefebvre
Arnaud Lefebvre
πŸ’»		 tem1029
tem1029
πŸ’»		 Peter K. Moss
Peter K. Moss
πŸ’»		 Geoff Shannon
Geoff Shannon
πŸ’»		 Zachary Mayhew
Zachary Mayhew
πŸ’»
jfaltis
jfaltis
πŸ’»		 Marcel Schramm
Marcel Schramm
πŸ“–		 Fangyi Zhou
Fangyi Zhou
πŸ’»		 Max
Max
πŸ’»		 Sven van der Vlist
Sven van der Vlist
πŸ’»		 jacobchrismarsh
jacobchrismarsh
πŸ’»		 Nils Rauch
Nils Rauch
πŸ’»
Nick Stockton
Nick Stockton
πŸ’» πŸ› 🚧 πŸ’¬ πŸ“–		 Stuart Hinson
Stuart Hinson
πŸ’»		 Sam Calvert
Sam Calvert
πŸ’» πŸ“–		 Jeroen Wijenbergh
Jeroen Wijenbergh
πŸ“–		 Kimberley Cook
Kimberley Cook
πŸ“–		 Audrey Baxter
Audrey Baxter
πŸ’»		 Norman
Norman
πŸ“–
Peter Maatman
Peter Maatman
πŸ’»		 AlexandreS
AlexandreS
πŸ’»		 Finn Vos
Finn Vos
πŸ’»		 Carlos Hernandez
Carlos Hernandez
πŸ“¦		 Pedro Alves
Pedro Alves
πŸ’»		 jtagcat
jtagcat
πŸ“–		 Benjamin Kitor
Benjamin Kitor
πŸ’»
AleΕ‘ Najmann
AleΕ‘ Najmann
πŸ“– πŸ“¦		 Jeremy Stucki
Jeremy Stucki
πŸ’»		 (´⌣`ΚƒΖͺ)
(´⌣`ΚƒΖͺ)
πŸ’»		 Artem Polishchuk
Artem Polishchuk
πŸ“¦		 Chris Sosnin
Chris Sosnin
πŸ’»		 Ben Buhse
Ben Buhse
πŸ“–		 Sean Li
Sean Li
πŸ’»
TimotheeGerber
TimotheeGerber
πŸ’» πŸ“–		 Ferdinand Ratajczak
Ferdinand Ratajczak
πŸ’»		 Sheel Choksi
Sheel Choksi
πŸ’»		 Michael Hellwig
Michael Hellwig
πŸ“–		 Oliver Daniel
Oliver Daniel
πŸ’»		 Drew Fisher
Drew Fisher
πŸ’»		 ncoder-1
ncoder-1
πŸ“–
Macguire Rintoul
Macguire Rintoul
πŸ“–		 Ricardo Holguin
Ricardo Holguin
πŸ’»		 Keisuke Toyota
Keisuke Toyota
πŸ’»		 Craig Astill
Craig Astill
πŸ’»		 Onielfa
Onielfa
πŸ’»		 usrme
usrme
πŸ“–		 Sergey A.
Sergey A.
πŸ’»
Hideyuki Okada
Hideyuki Okada
πŸ’»		 kepae
kepae
πŸ’» πŸ“–		 Γ‰rico Nogueira Rolim
Γ‰rico Nogueira Rolim
πŸ’»		 Alexander Meinhardt Scheurer
Alexander Meinhardt Scheurer
πŸ’»		 OndΕ™ej KinΕ‘t
OndΕ™ej KinΕ‘t
πŸ’»		 Kryan90
Kryan90
πŸ“–		 n-ivanov
n-ivanov
πŸ’»
bi1yeu
bi1yeu
πŸ’» πŸ“–		 May
May
πŸ’»		 Bruno A. MuciΓ±o
Bruno A. MuciΓ±o
πŸ’»		 Finn Hediger
Finn Hediger
πŸ’»		 dp304
dp304
πŸ’»		 Marco Micera
Marco Micera
πŸ“–		 Marco Ieni
Marco Ieni
πŸš‡
ArtΓΊr KovΓ‘cs
ArtΓΊr KovΓ‘cs
πŸ’»		 Antony Kellermann
Antony Kellermann
πŸ’»		 Rasmus Pedersen
Rasmus Pedersen
πŸ’»		 noir-Z
noir-Z
πŸ“–		 David Bailey
David Bailey
πŸ“–		 sheepwall
sheepwall
πŸ’»		 Hwatwasthat
Hwatwasthat
πŸ’»
Jesse
Jesse
πŸ’»		 Sang
Sang
πŸ“–		 Yuuki Takahashi
Yuuki Takahashi
πŸ“–		 Alejandro Angulo
Alejandro Angulo
πŸ’»		 Anton Kostin
Anton Kostin
πŸ“–		 Justin Sexton
Justin Sexton
πŸ’»		 Jiati Le
Jiati Le
πŸ“–
Matthew Cobbing
Matthew Cobbing
πŸ’»		 Milo
Milo
πŸš‡		 Diego Veralli
Diego Veralli
πŸ’»		 Maja Bojarska
Maja Bojarska
πŸ’»
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=LargeModGames/spotatui&type=date&legend=top-left)](https://star-history.com/#LargeModGames/spotatui&type=date&legend=top-left) ## Roadmap The goal is to eventually implement almost every Spotify feature. **High-priority features:** - Scroll through result pages in every view See the [Roadmap Wiki](https://github.com/LargeModGames/spotatui/wiki/Roadmap) for the full API coverage table.