your terminal, your vibe — a beautiful, feature-rich Spotify TUI player written in Rust.

Vibes is a terminal-based UI (TUI) client for Spotify designed with aesthetics and functionality in mind. Built with Rust, Ratatui, and Crossterm, it delivers a smooth, native-feeling music experience directly in your terminal.

Whether you're coding, writing, or just browsing, Vibes provides an immersive interface complete with animated equalizers, dynamic playback controls, and a vibrant neon-dark theme. Say goodbye to heavy desktop applications and control your music lightning-fast from your keyboard.

• Rust 1.75+ installed via rustup.
• Spotify Premium account (Note: Spotify API enforces Premium for playback control).
• Docker (Optional, but highly recommended for the local Redis token cache).

To access the Spotify API, you need your own client credentials.

1. Go to the Spotify Developer Dashboard.
2. Click Create app.
3. Fill in the App Name and Description (e.g., "Vibes Terminal").
4. Under Redirect URIs, add exactly: http://127.0.0.1:8989/login.
5. Save your app and navigate to the Settings page.
6. Copy the Client ID and Client Secret.

Clone the repository and create a .env file in the root directory:

git clone https://github.com/yourusername/vibes.git
cd vibes
touch .env

Paste your credentials into the .env file:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8989/login
REDIS_URL=redis://127.0.0.1:6379
RUST_LOG=vibes=info

Vibes uses Redis to securely cache your Spotify login token so you don't have to log in every time you open the app.

docker compose up -d

cargo run

When building the release binary, you must ensure that the .env file is located in the same directory where you execute the binary, or that the environment variables are exported globally.

# Compile optimized build
cargo build --release

# Copy the .env file next to the binary (so it can read your credentials)
cp .env target/release/

# Run the binary directly
cd target/release
./vibes

On the first run, Vibes will automatically open your default web browser asking you to grant permissions to your Spotify account. Click Agree. The browser will redirect to localhost:8989 and the terminal will automatically log you in.

Having issues? Here are the most common problems and how to fix them.

• Cause: Your saved Spotify token has expired or is invalid.
• Fix: The app is designed to auto-refresh tokens. However, if the error persists, open your terminal and clear the cache using Redis, or simply delete the token:

  docker exec -it vibes-redis-1 redis-cli del vibes:spotify_token

  Restart cargo run and log in through the browser again.

• Cause: Spotify API requires an "active device" to trigger playback, but doesn't consider the API itself a physical player.
• Fix: Open the official Spotify app on your phone, desktop, or web browser. Play any song for 1 second, then pause it. Now your device is "active", and you can control it from Vibes.

• Cause: You started playing a single song manually via the Spotify app, so the active Spotify queue context is empty.
• Fix: Start playing a song directly from within the Vibes app (e.g., press Enter on a song in Search or Liked Songs). Vibes automatically feeds the next 50 tracks to Spotify, immediately fixing the queue and enabling the Next/Prev buttons.

• Cause: Your terminal emulator does not fully support Unicode or strict monospace fonts.
• Fix: Ensure you are using a modern terminal (like iTerm2, Alacritty, Kitty, or Windows Terminal) and a patched Nerd Font (e.g., FiraCode Nerd Font). Expand your terminal window to ensure sidebar elements aren't squished.

• Cause: Missing dependencies or outdated Rust version.
• Fix: Run rustup update to ensure you are on Rust 1.75 or newer. Also, ensure you don't have broken Cargo.lock files; try cargo clean and run again.

• Logs location: If the app crashes, it writes an error trace to /tmp/vibes.log.
• View logs: Run tail -f /tmp/vibes.log in another terminal window while running the app to see live API activity and error notices.

Vibes runs purely on asynchronous Rust (tokio), separating UI rendering (ratatui) from API network calls (rspotify).

src/
├── main.rs          # Entry point, terminal setup, panic hook
├── app/             # Main event loop, global state, UI dispatch
├── spotify/         # Spotify API wrappers, OAuth caching, pagination
├── ui/              # Render logic, neon theme, dynamic layouts
├── events/          # Keyboard mapping
├── cache/           # Redis local token store
└── config/          # Dotenv configuration

MIT