// Overview

About isi-music

isi-music is a terminal audio player for Spotify streaming and local file playback, built in Rust. It replaces resource-heavy desktop clients with a native TUI that runs in any terminal emulator - fast, lightweight, and keyboard-centric.

Performance Specs

Metric	Value	Notes
RAM Usage	36 to 44 MB	Scales with track duration
CPU (no cover art)	~0.3%	Minimal overhead during playback
CPU (with cover art)	~0.8%	Slight increase for image rendering
Threads	25 to 27	Async tokio workers, lightweight
Test Hardware	Ryzen 4600G + WezTerm	6-core / 12-thread APU

Tested on AMD Ryzen 4600G (6C/12T) with WezTerm terminal emulator.

memory

Why RAM scales

The audio buffer runs in memory for speed, much faster than reading from the file protocol. Longer tracks mean a larger buffer, so memory usage grows with track duration.

developer_board

25+ threads? Not a lot.

Tokio runtime, audio decoding, Spotify API calls, UI rendering: everything is async. Each thread is lightweight and idle most of the time. This is normal for a Rust async app.

speed

Sub-1% CPU

Even with cover art rendering, isi-music stays under 1% CPU. Rust + ratatui + async = minimal resource footprint. Your terminal stays responsive.

// Setup

Installation

Prerequisites: Nerd Font

A Nerd Font is required for proper album art and UI rendering.

bash


                    $ mkdir -p ~/.local/share/fonts

                    $ unzip NerdFont.zip -d ~/.local/share/fonts

                    $ fc-cache -fv

Download

bash


                    $ curl -L https://github.com/glrmrissi/isi_music/releases/latest/download/isi-music-linux-x86_64 -o isi-music

                    $ chmod +x isi-music

                    $ sudo mv isi-music /usr/local/bin/

powershell


                    PS> Invoke-WebRequest -Uri .../isi-music-windows-x86_64.exe

                    PS> mkdir "$env:LOCALAPPDATA\Programs\isi-music" -Force

                    PS> move isi-music.exe "$env:LOCALAPPDATA\Programs\isi-music\"

Linux Audio Dependencies

Distro	Command
Debian / Ubuntu	`sudo apt install libasound2t64 libpulse0`
Arch Linux	`sudo pacman -S alsa-lib libpulse`
Fedora	`sudo dnf install alsa-lib pulseaudio-libs`

// Customize

Configuration

config.toml

All config lives under ~/.config/isi-music/ on Linux and %APPDATA%\isi-music\ on Windows.

toml


                [spotify]

                client_id = "your_client_id_here"


                [local]

                music_dir = "~/Music"


                [lastfm]

                api_key = "your_lastfm_api_key"

                api_secret = "your_lastfm_api_secret"

                session_key = "obtained_via_setup-lastfm"


                [discord]

                enabled = true


                [musixmatch]

                musixmatch_api_key = "your_musixmatch_api_key"


                [ui]

                show_cover_images = true

                show_visualizer = false

                compact_mode_default = false

                show_breadcrumb = true

                autoplay = true


                [options]

                hot_reload = true

                smtc_enabled = true

                media_keys_enabled = true

Theme

Create ~/.config/isi-music/theme.toml to customize colors and layout.

toml


                  border_active = "#00d4ff"

                  border_inactive = "#ffffff"

                  highlight_bg = "#004b7a"

                  text_primary = "#ffffff"

                  accent_color = "#ffeb3b"

                  background = "#141414"

                  text_secondary = "#888888"

                  status_bar = "#1e1e1e"

Variable	Purpose
border_active	Focused panel borders
border_inactive	Unfocused borders
highlight_bg	Selected list items
text_primary	Titles, primary text
accent_color	Progress bars, icons
background	Root background fill
text_secondary	Subtle text, timestamps
status_bar	Bottom status bar

Run isi-music setup for 8 color presets that preserve your existing layout settings.

// Keyboard

Keybindings

Vim-inspired keybindings with customizable keybinds via keybinds.toml. Keep your hands on the keyboard - no mouse required.

Playback

Key	Action
`Space`	Play / Pause
`n` / `p`	Next / Previous track. With shuffle on, previous goes back through actual play history.
`=` / `-`	Volume up / down
`←` / `→`	Seek backward / forward 5s (hold for 10s)
`5`	Seek to middle of track
`s`	Toggle shuffle
`r`	Cycle repeat (off → queue → track)
`´`	Toggle radio mode
`Alt+R`	Get recommendations
`l`	Like current track
`a`	Add track to queue
`Delete`	Remove selected item from queue
`o`	Sort tracks

Navigation

Key	Action
`Tab` / `Shift+Tab`	Next / Previous panel
`↑` / `↓` or `k` / `j`	Navigate within a panel
`Ctrl+↑` / `Ctrl+↓`	First / last item
`M`	Jump to middle of list
`Enter`	Play selected / open album or artist
`Esc`	Back / Close search / Exit fullscreen
`/`	Search
`Ctrl+F`	Quick search
`c`	Jump to playing track
`1` / `2` / `3` / `4`	Focus library / playlists / tracks / queue
`PageUp` / `PageDown`	Scroll up / down

Playlist & Display

Key	Action
`A`	Add to playlist
`D`	Remove from playlist
`Alt+D`	Delete playlist
`z`	Toggle fullscreen player
`m`	Toggle compact mode
`v`	Toggle visualizer
`y`	Toggle lyrics
`d`	Toggle debug overlay (CPU, memory, logs)
`Shift+B`	Toggle breadcrumb
`t`	Open settings panel
`:`	Command prompt
`Ctrl+Y`	Copy track link
`?`	Open help panel
`q` / `Ctrl+C`	Quit

// Library

Local Files

isi-music can play local audio files without a Spotify account. Point it at your music directory in config.toml:

toml


                [local]

                music_dir = "~/Music"

Supported formats: MP3, FLAC, OGG, WAV, AIFF. Navigate to Local Files in the library panel and press Enter to scan. The first scan extracts metadata and embedded cover art, cached in SQLite for instant loads. Mix local and Spotify tracks in the same queue: isi-music routes each track to the appropriate player automatically.

// Client ID Required

Spotify Setup

The February 2026 Spotify Web API changes require a Client ID for all API requests.

Go to the Spotify Developer Dashboard and click "Create app"
Set the Redirect URI to http://127.0.0.1:8888/callback
Copy the Client ID and run isi-music setup-spotify

The setup command performs a single unified authentication that chains the Web API OAuth (PKCE) and the streaming OAuth (librespot) in one flow. You only need to authorize once through the browser. The Web API refresh token is saved immediately after the first step, so it persists even if the streaming connection fails and you can retry the streaming part without re-authorizing the Web API.

// Linux Desktop

MPRIS2 Integration

isi-music registers on D-Bus as org.mpris.MediaPlayer2.isi_music, enabling media keys, Waybar widgets, and playerctl. MPRIS works in both TUI and daemon modes.

Waybar Config

toml


                "mpris": {

                  "format": "{player_icon} {title} -- {artist}",

                  "player-icons": { "isi_music": "" },

                  "status-icons": { "playing": ">", "paused": "||" }

                }

Hyprland Media Keys

conf


                bind = , XF86AudioPlay, exec, playerctl play-pause

                bind = , XF86AudioNext, exec, playerctl next

                bind = , XF86AudioPrev, exec, playerctl previous

// Scrobble

Last.fm

Run isi-music setup-lastfm to configure. The wizard prompts for your API credentials and opens your browser for authorization.

Track starts: track.updateNowPlaying
Track reaches 50% or 4 minutes: track.scrobble

// Social

Discord Rich Presence

Enable in config.toml:

toml


                [discord]

                enabled = true

Optional: use a custom app ID with app_id = "your_custom_app_id". Your status shows "Listening to [Track] by [Artist]".

// Headless

Daemon Mode

Keep playback running in the background, controlled from the command line.

bash


                $ isi-music --daemon

                $ isi-music --play spotify:playlist:37i9dQZF1DXcBWIGoYBM5M

                $ isi-music --liked

                $ isi-music --ls

                $ isi-music --play-id 2

                $ isi-music --toggle

                $ isi-music --next

                $ isi-music --prev

                $ isi-music --vol+

                $ isi-music --status

                $ isi-music --quit-daemon

Logs at ~/.cache/isi-music/isi-music.log. Clear with isi-music --clear-logs. Daemon mode currently supports Spotify playback only.

// Help

Troubleshooting

Local files showing "Unknown Artist"

Delete the SQLite cache and covers, then restart:

bash

rm ~/.local/share/isi-music/library.db
rm -rf ~/.cache/isi-music/covers/

Album art not showing

Ensure your terminal supports true color: echo $COLORTERM
Verify a Nerd Font is installed and configured
Check that embedded artwork exists in your audio files

MPRIS not working

Ensure D-Bus is running and DBUS_SESSION_BUS_ADDRESS is set.

// Build from Source

Development

Requires Rust 1.88+ (edition 2024).

bash


                  $ git clone https://github.com/glrmrissi/isi_music.git

                  $ cd isi_music

                  $ sudo apt install libasound2-dev libpulse-dev libdbus-1-dev pkg-config

                  $ cargo build --release

                  $ cargo test

Run with debug logging: RUST_LOG=isi_music=debug cargo run