just a clean spotify TUI that actually works!

check out vibechain-api for the machine learning part of this project: vibechain-api

• plays your music 🎵
• shows your playlists 📚
• displays lyrics 📝
• track info that's actually useful 📊
• clean three-panel layout
• doesn't break every 5 minutes
• smart shuffle feature powered using ML

1. get spotify credentials

• hit up spotify developer dashboard
• make an app, get your client id & secret
• set redirect uri to: http://127.0.0.1:8888/callback

2. install this thing

git clone https://github.com/stephenhungg/spotifytui/
cd spotifytui
pipx install .

3. set up your api keys

# copy the template and add your keys
cp .env.example .env

# edit .env with your actual credentials
# SPOTIPY_CLIENT_ID=your_actual_client_id
# SPOTIPY_CLIENT_SECRET=your_actual_client_secret
# GENIUS_ACCESS_TOKEN=your_genius_token  # optional for lyrics

4. run it

spotifytui

that's it.

playback section:

• current track info
• album art (16x16 pixel art cause why not)
• progress bar
• track stats (release year, popularity, etc.)
• get ML analysis on your music taste
• smart shuffle to play the next most likely track based on current mood

playlists section:

• all your spotify playlists
• browse tracks in any playlist
• play individual tracks or whole playlists

lyrics section:

• real lyrics from genius api
• clean formatting (strips out the garbage)

if you want actual lyrics instead of placeholder text:

1. get a genius api token from genius.com/api-clients
2. add it to your .env file: GENIUS_ACCESS_TOKEN=your_token
3. restart the app
4. lyrics will just work

• spotify premium (api limitations unfortunately)
• python 3.8+
• working terminal

• textual - for the TUI magic
• spotipy - spotify api wrapper
• lyricsgenius - lyrics from genius
• pillow - album art processing
• requests - http stuff
• python-dotenv - env file support

"command not found": make sure pipx is in your PATH

auth keeps failing: double-check your redirect URI is exactly http://127.0.0.1:8888/callback

no lyrics: either set up genius token or just vibe with the placeholder

nothing playing: make sure spotify is actually running somewhere

looks broken: your terminal probably doesn't support unicode properly

src/
├── simple_tui.py      # main app
├── spotify_client.py  # spotify api stuff  
└── lyrics_service.py  # genius api stuff

sure, send a PR. keep it simple though.

made for performative neovim users