LargeModGames / spotatui

spotatui > A Spotify client for the terminal written in Rust, powered by Ratatui. > > A community-maintained fork of spotify-tui, actively developed with new features like native streaming, synced lyrics, and real-time audio visualization. Song History Table of Contents • Help Wanted • Performance • Privacy Notice • Migrating from spotify-tui • Installation • Connecting to Spotify • Usage • Native Streaming • Configuration • Discord Rich Presence • Limitations • Deprecated Spotify API Features • Using with spotifyd • Libraries used • Development • Windows Subsystem for Linux • Maintainer • spotatui Contributors • Upstream Contributors (spotify-tui) • Star History • 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 • **Join the community** in Discussions • **Submit a PR** for code, docs, or themes See 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 in 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 before: • The binary name changed from to . • Config paths changed: • Old: • New: You can copy your existing config: 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). Or download pre-built binaries from GitHub Releases. See the Installation Wiki for platform-specific requirements and building from source. Connecting to Spotify Run and follow the on-screen instructions to connect your Spotify account. You'll need to create a Spotify Developer app at the Spotify Dashboard. See the Installation Wiki for step-by-step setup. Usage The binary is named . Running 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 to learn more. See Keybindings Wiki for the full list of keyboard shortcuts. Here are some example to get you excited. Native Streaming spotatui can play audio directly without needing spotifyd or the official Spotify app. Just run 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 for setup details. Configuration A configuration file is located at . See the Configuration Wiki for the full config file reference. You can also configure spotatui in-app by pressing to open Settings. See Themes Wiki 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): You can also override via or disable in the setting or by setting in ~/.config/spotatui/config.yml. 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. 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 ): 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 art…