// 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–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–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

bash


                    $ brew tap homebrew/cask-fonts

                    $ brew install font-fira-code-nerd-font

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/

bash


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

                    $ chmod +x isi-music

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

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, ~/Library/Application Support/isi-music/ on macOS.

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"

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
`+` / `-`	Volume up / down
`←` / `→`	Seek +/- 5s (hold for +/- 10s)
`s`	Toggle shuffle
`r`	Cycle repeat (off → queue → track)
`/`	Search
`q`	Quit

Navigation

Key	Action
`Tab` / `Shift+Tab`	Next / Previous panel
`↑` / `↓` or `k` / `j`	Navigate within a panel
`Ctrl+↑` / `Ctrl+↓`	First / last item
`Enter`	Play selected / open album or artist
`Esc`	Back / Close search / Exit fullscreen

Playlist & Display

Key	Action
`l`	Like current track
`a`	Add track to queue
`Delete`	Remove selected item from queue
`R`	Toggle radio mode
`z`	Toggle fullscreen player
`m`	Toggle compact mode
`v`	Toggle visualizer
`y`	Toggle lyrics
`?`	Open help panel

// 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

// 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.85+ (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