spotify-mini

A lightweight, terminal-based Spotify controller written in Go. Designed for Arch Linux + Hyprland + Waybar.

Prerequisites

1. Spotify Premium (Required for API control).

2. Spotify Developer App:

   • Go to Spotify Dashboard.

   • Create an App.

   • Set Redirect URI to: http://localhost:8000/callback

   • Save your Client ID and Client Secret.

Installation

1. Build the binary:

   go build -o spotify-mini ./cmd
   mkdir -p ~/.local/bin
   mv spotify-mini ~/.local/bin/
   

2. Create the Wrapper Script: Create ~/.local/bin/spotify-waybar.sh and make it executable (chmod +x).

   #!/bin/bash
   
   # SET YOUR KEYS HERE
   export SPOTIFY_ID="your_client_id_here"
   export SPOTIFY_SECRET="your_client_secret_here"
   
   BIN="$HOME/.local/bin/spotify-mini"
   
   case "$1" in
       "daemon")
           exec "$BIN" -mode daemon
           ;;
   
       "status")
           # Waybar reads from the file generated by the daemon
           if [ -f /tmp/spotify-mini.json ]; then
               cat /tmp/spotify-mini.json
           else
               echo '{"text": "..."}'
           fi
           ;;
   
       "-cmd")
           # Keybinds (next, prev, toggle)
           "$BIN" -cmd "$2"
           ;;
   
       "ui")
           # TUI Popup
           # Ensure 'mini-spotify' matches Hyprland class rule
           kitty --class mini-spotify -e "$BIN" -mode ui
           ;;
   esac
   

Configuration

1. Hyprland (~/.config/hypr/hyprland.conf)

Start the daemon and set window rules for the popup.

# Start Daemon on Login
exec-once = ~/.local/bin/spotify-waybar.sh daemon

# Window Rules (Adjust 'move' coordinates for your screen)
windowrulev2 = float, class:^(mini-spotify)$
windowrulev2 = size 400 500, class:^(mini-spotify)$
windowrulev2 = move 1500 50, class:^(mini-spotify)$
windowrulev2 = pin, class:^(mini-spotify)$

# Keeps focus on the window until closed
windowrulev2 = stayfocused, class:^(mini-spotify)$
# q quits the app btw

# Keybinds for audio keys 
bindl = , XF86AudioNext, exec, ~/.local/bin/spotify-waybar.sh -cmd next
bindl = , XF86AudioPrev, exec, ~/.local/bin/spotify-waybar.sh -cmd prev
bindl = , XF86AudioPlay, exec, ~/.local/bin/spotify-waybar.sh -cmd toggle

# Keybinds for no audio keys
bind =  SUPER , n , exec, ~/.local/bin/spotify-waybar.sh -cmd next
bind =  SUPER , b , exec, ~/.local/bin/spotify-waybar.sh -cmd prev
bind =  SUPER , p , exec, ~/.local/bin/spotify-waybar.sh -cmd toggle

2. Waybar (~/.config/waybar/config)

Add the module. The interval can be 2 because it just reads a local file.

"custom/spotify": {
    "exec": "~/.local/bin/spotify-waybar.sh status",
    "interval": 2,
    "return-type": "json",
    "on-click": "~/.local/bin/spotify-waybar.sh ui",
    "tooltip": true,
    "max-length": 15 # Maximum characters to show on waybar
}

First Run

1. Run the UI manually once to authenticate:

   ~/.local/bin/spotify-waybar.sh ui
   

2. It will open your browser. Login and accept.

3. The token is saved to ~/.config/spotify-mini/token.json.

4. Restart Hyprland (or run the daemon command manually) to start the background service.