spotatui: Een terminal music player geschreven in Rust, aangedreven door Ratatui

Over spotatui

spotatui is een community-onderhouden en actief ontwikkelde fork van spotify-tui, die inmiddels op meerdere vlakken is gedivergeerd.

Belangrijkste verschillen

Kenmerk	spotify-tui	spotatui
Spotify-backend	Extern Connect-apparaat (spotifyd, officiële client, ...)	Ingebouwde native client
Bronnen	Spotify	Spotify, YouTube, lokaal, Subsonic, Navidrome, Internetradio, Qobuz, Apple Music (macOS)

Functies

• Meerdere bronnen — Spotify optioneel: Speel muziek af via Spotify, lokale bestanden, een Subsonic/Navidrome-server, internetradio, YouTube, Qobuz of Apple Music (op macOS). De gratis bronnen vereisen geen Spotify-account; druk op d om op elk moment tussen de bronnen te wisselen.
• Native streaming: Speel Spotify-audio direct af zonder dat de officiële app of spotifyd nodig is. spotatui verschijnt als zijn eigen Spotify Connect-apparaat (Premium vereist).
• Gesynchroniseerde songteksten: Regel-voor-regel songteksten die het afspelen volgen.
• Real-time audio-visualizer: Een systeembrede FFT-visualizer (druk op v) die reageert op alles wat wordt afgespeeld, en voor Spotify-tracks het "pitch-view" van de originele spotify-tui.
• Cross-source afspeelwachtrij: Druk op z bij een willekeurige track om deze in de wachtrij te plaatsen. De wachtrij speelt tracks van elke bron af voordat de huidige context wordt hervat.
• Playlist-synchronisatie: Koppel één playlist als hoofdplaylist en spiegel deze naar Spotify, Qobuz, Subsonic of YouTube. Dit gebeurt bij opstarten en via spotatui sync.
• Lua-plugins: Breid spotatui uit met event-hooks, commando's, toetscombinaties, pop-ups en theming.
• Luistergeschiedenis & recap: spotatui houdt een lokale afspeelgeschiedenis bij en kan een deelbare HTML-recap genereren (spotatui history recap).
• Volledige CLI: Het meeste wat de UI doet is scriptbaar, waaronder afspelen, zoeken, playlists en shell-completions. Gebruik spotatui --help.
• Lichtgewicht: Verbruikt ongeveer 78 MB RAM tijdens het streamen, in tegenstelling tot een volledige Electron-client.

Installatie

Spotify is optioneel. Bij de eerste lancering vraagt spotatui welke bron je wilt gebruiken. YouTube, Subsonic/Navidrome, internetradio, lokale bestanden, Qobuz en Apple Music (macOS) werken zonder Spotify-account. Voor de Spotify-bron is een Spotify Premium-account nodig; dit kun je op elk moment toevoegen via het d-menu.

Installatiemethoden

macOS, Linux, WSL (One-line installer): Haalt de prebuilt binary op, verifieert de checksum en plaatst spotatui op je PATH. Rust is niet vereist.

curl -fsSL https://spotatui.com/install.sh | bash

Homebrew (alleen macOS):

brew tap LargeModGames/spotatui
brew install spotatui

Cargo (compileren via crates.io):

cargo install --locked spotatui

Of haal de prebuilt binary op zonder te compileren:

cargo binstall spotatui

Arch Linux (AUR): Prebuilt binary (sneller):

yay -S spotatui-bin

Of bouwen uit bron:

yay -S spotatui

Void Linux (unofficial repo):

echo repository=https://raw.githubusercontent.com/Event-Horizon-VL/blackhole-vl/repository-x86_64 | sudo tee /etc/xbps.d/20-repository-extra.conf
sudo xbps-install -S spotatui

Windows PowerShell (One-line installer):

irm https://spotatui.com/install.ps1 | iex

Of via Winget:

winget install spotatui

NixOS (Flake, aanbevolen): Voeg spotatui toe aan je flake inputs:

inputs = {
  spotatui = {
    url = "github:LargeModGames/spotatui";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

Voeg het pakket toe aan je configuratie:

{ inputs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.spotatui.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

De flake regelt de afhankelijkheden, behalve de audio-backend. Voor ALSA: hardware.alsa.enable = true; Voor PipeWire:

services.pipewire = {
  enable = true;
  alsa.enable = true;
};

GitHub Releases: Je kunt ook pre-built binaries downloaden via de GitHub Releases pagina.

Belangrijke opmerking over bronnen

De prebuilt binaries voor Linux, macOS en Windows (via de installer, GitHub Releases en cargo binstall) en de desktop-app bevatten de extra muziekbronnen: lokale bestanden, Subsonic, internetradio, YouTube en Qobuz (en Apple Music op macOS). YouTube vereist dat yt-dlp is geïnstalleerd (ffmpeg wordt aanbevolen). Een standaard cargo install --locked spotatui bevat deze niet; activeer ze met --features local-files,subsonic,internet-radio,youtube,qobuz (voeg apple-music toe op macOS).

Desktop-app (preview)

spotatui is ook beschikbaar als desktop-app: dezelfde speler in een eigen venster met een Spotify-stijl layout (Home, album- en artiestenpagina's, Je bibliotheek, lyrics). De app gebruikt dezelfde login, instellingen en geschiedenis als de terminal-app; er kan slechts één van de twee tegelijk draaien.

De preview ondersteunt Spotify (Premium vereist), lokale bestanden, Subsonic, internetradio, YouTube, Qobuz en op macOS ook Apple Music. YouTube vereist yt-dlp (ffmpeg aanbevolen).

Beschikbare bestanden per systeem

Systeem	Bestand
Windows 10/11 (64-bit)	spotatui-desktop<version>x64-setup.exe
macOS, Apple Silicon	spotatui<version>aarch64.dmg
macOS, Intel	spotatui<version>x64.dmg
Debian/Ubuntu	spotatui-desktop<version>amd64.deb of _arm64.deb
Fedora	spotatui-desktop-<version>-1.x86_64.rpm of .aarch64.rpm
Overige Linux	spotatui-desktop<version>amd64.AppImage of _aarch64.AppImage

Opstartwaarschuwingen:

• Windows: SmartScreen geeft "Windows protected your PC". Klik op More info, dan op Run anyway.
• macOS: macOS weigert de app de eerste keer te openen. Sluit de dialoog, ga naar Systeeminstellingen > Privacy & Beveiliging en klik op Open Anyway. Als macOS zegt dat de app beschadigd is, voer dan één keer uit: xattr -dr com.apple.quarantine /Applications/spotatui.app.
• Linux: Vereist glibc 2.39 en WebKitGTK 4.1 (Ubuntu 24.04+, Debian 13, Fedora 40+ of Arch). Bij een blank scherm op Wayland met NVIDIA GPU, start de app met GDK_BACKEND=x11 spotatui-desktop.

Snelstart

Start spotatui. Bij de eerste lancering word je gevraagd een bron te kiezen:

1. Spotify (vereist login)
2. YouTube (gratis, vereist yt-dlp binary)
3. Subsonic (gratis, vereist Subsonic/Navidrome server)
4. Internet Radio (gratis)
5. Local Files (gratis)
6. Qobuz (betaald abonnement, login via browser)
7. Apple Music (macOS Music app, vereist Automation-toestemming)

Kies een gratis bron om Spotify volledig over te slaan, of kies Spotify om in te loggen via een pairing-code in de browser. Er is geen developer-app of client ID nodig.

Basisbesturing

• ?: In-app helpmenu met alle toetscombinaties.
• d: Bron- en apparaatselectie openen.
• z: Track in de wachtrij plaatsen (wachtrij openen met Shift+Q).
• /: Zoeken (Enter om te bevestigen, Ctrl+L om query te wissen).
• Spatie: Play/pauze.
• spotatui --help: CLI-hulp.

CLI Voorbeelden

spotatui --completions zsh                                # Shell completions
spotatui play --name "Je Playlist" --playlist --random    # Willekeurig nummer uit playlist spelen
spotatui playback --toggle                                # Play/pauze
spotatui list --liked --limit 50                          # Lijst van gelikte nummers
spotatui history recap --period 30d --output ./recap.html # Luisterrecap genereren

Spotify later toevoegen

Druk op d om de Source & Device picker te openen. Focus op "Source", selecteer Spotify en druk op Enter. Log in via de pairing-code. Native streaming vereist een herstart van de app.

Muziekbronnen

spotatui is een algemene muziekspeler. De bronnen maken gebruik van een eigen audio-engine, waardoor volumeregeling en de visualizer overal hetzelfde werken. Geen van deze bronnen (behalve Spotify en Qobuz) vereist een abonnement.

Bron	Functie	Vereisten
Lokale bestanden	Browse en speel audiobestanden (FLAC, MP3, OGG, WAV, ...)	Niets; stel localmusicpath in
Subsonic	Stream van Subsonic-compatibele servers (Navidrome, Gonic, Airsonic, Funkwhale, ...)	Server-account
Internetradio	Speel icecast/shoutcast streams via radio-browser.info (30k+ stations)	Niets
YouTube	Zoek en speel audio van YouTube; maak lokale playlists	yt-dlp op je PATH (ffmpeg aanbevolen)
Qobuz	Stream Qobuz-bibliotheek in hoge kwaliteit (MP3 320 tot FLAC 24/192)	Betaald Qobuz-account
Apple Music	Browse en zoek in je Music-bibliotheek (alleen macOS)	macOS en Music app; Apple Music login

Specifieke bronconfiguraties

Lokale bestanden

Stel een map in (standaard de OS-muziekmap):

behavior:
  local_music_path: "/home/gebruiker/Music"

Subsonic / Navidrome

behavior:
  subsonic_url: "https://music.example.com"
  subsonic_username: "gebruiker"

Tip: Stel het wachtwoord in via de omgevingsvariabele SPOTATUISUBSONICPASSWORD om plaintext opslag in het config-bestand te voorkomen.

Internetradio

Zoek in-app naar stations en druk op F om ze op te slaan in de zijbalk.

YouTube

Vereist yt-dlp. Zoeken en afspelen zijn anoniem. Lokale playlists worden opgeslagen in youtube_playlists.yml.

Qobuz

Login verloopt via de browser. Tokens worden opgeslagen in qobuz_credentials.yml.

behavior:
  qobuz_quality: 6   # 5 = MP3 320, 6 = FLAC 16/44.1, 7 = FLAC 24/96, 27 = FLAC 24/192

Apple Music (alleen macOS)

spotatui fungeert als remote voor de Music-app. Audio gaat niet door spotatui zelf. De eerste keer moet toestemming worden gegeven voor "Automation" in de systeeminstellingen.

AI DJ

spotatui kan muziek voor je kiezen op basis van je luistergeschiedenis.

1. Via Coding Agent (--features mcp-server): spotatui exposeert de speler en geschiedenis als MCP-tools. Hierdoor kunnen clients zoals Claude Code, Codex of Gemini CLI als DJ optreden.
2. Ingebouwde TUI DJ (--features ai-dj):

• Ctrl-j: DJ-scherm met chat-prompt.
• Ctrl-t: Continue auto-queue.
• Ctrl-y: Sfeer aanpassen.
• Ctrl-o: Alleen tracks die je nog niet hebt.
• Ctrl-g: AI-model kiezen (lokaal via Ollama/LM Studio, API key, of agent CLI).

Native Streaming

spotatui kan Spotify-audio direct afspelen zonder spotifyd of de officiële app. De speler verschijnt als een Spotify Connect-apparaat.

• Vereiste: Spotify Premium account.
• Technologie: Gebruikt een onderhouden fork van librespot om compatibiliteit met Spotify's audio-delivery te garanderen.

Configuratie

Het configuratiebestand bevindt zich op: $XDGCONFIGHOME/spotatui/config.yml of ${HOME}/.config/spotatui/config.yml. Je kunt instellingen ook in-app wijzigen via Alt-,.

Aanpassingen

Bijna alles is aanpasbaar: toetscombinaties, thema's, iconen, labels, sorteervolgorde en layout.

Cover Art: In de instellingen is dithering beschikbaar voor de playbar.

• behavior.coverartdither: true
• behavior.coverartdither_algorithm: keuze uit stucki (standaard), bayer8x8 of atkinson.
• behavior.coverartditherpixelscale: 1 tot 3.

Overige Integraties

Discord Rich Presence

Standaard ingeschakeld. Kan worden uitgeschakeld of aangepast via:

behavior:
  enable_discord_rpc: true
  discord_rpc_client_id: "jouw_client_id"

Anonieme Song Counter

Een opt-in globale teller die bijhoudt hoeveel nummers wereldwijd zijn afgespeeld. Er worden geen persoonlijke gegevens, songnamen of artiesten verzameld. Uitschakelen via enableglobalsong_count: false.

GitHub Profile Widget

Toon wat je luistert op je GitHub-profiel. Maak een account aan op spotatui.com, voeg je sync-token toe in de instellingen en voeg de SVG-link toe aan je profiel-README.

Plugins

spotatui ondersteunt Lua-plugins.

• spotatui plugin add owner/repo
• spotatui plugin list
• spotatui plugin update
• spotatui plugin remove <naam>

Performance

spotatui is zeer lichtgewicht vergeleken met Electron-clients.

Modus	RAM-verbruik
Native Streaming (Basis)	~78 MB
Met gesynchroniseerde lyrics	~78 MB
Met systeembrede visualizer	~80 MB

(Getest op Arch Linux/Hyprland)

Afspeelvereisten

• Niet-Spotify bronnen: Gebruiken de eigen audio-engine van spotatui.
• Apple Music: Gebruikt de macOS Music app.
• Spotify: Vereist een Premium account. Om audio te horen heb je één van de volgende nodig:

1. Native Streaming: Ingebouwd in spotatui (aanbevolen).
2. Officiële Spotify Client: De app open hebben staan.
3. spotifyd: Een lichtgewicht background alternatief.

Audio Visualizer

De visualizer (v) gebruikt real-time FFT-analyse van het systeemaudio:

• Windows: Werkt direct (WASAPI loopback).
• Linux: Werkt direct (PipeWire/PulseAudio monitor).
• macOS: Vereist een virtueel audio-apparaat zoals BlackHole (gratis) of Loopback (betaald).

Wanneer er een Spotify-track speelt, opent v de Spotify Pitch view (gebaseerd op de analyse van Spotify zelf, werkt dus ook als Spotify op een ander apparaat speelt). Gebruik V om te wisselen tussen Cava, Bar Graph en Spotify Pitch.

Migreren van spotify-tui

Als je overstapt van de originele spotify-tui:

1. De binary-naam is gewijzigd van spt naar spotatui.
2. Configuratiepaden zijn gewijzigd naar ~/.config/spotatui/.
3. Je kunt je bestaande config kopiëren:

``bash mkdir -p ~/.config/spotatui cp -r ~/.config/spotify-tui/* ~/.config/spotatui/ ``

Ontwikkeling

Vereisten

• OpenSSL
• Rust
• xorg-dev (voor clipboard support)
• Linux: ALSA + pkg-config

Build-instructies

Clone de repo en voer uit:

cargo run

Bug rapportage

Start de applicatie met --debug om een logbestand te genereren:

spotatui --debug

Logbestanden staan in de temp-directory als spotatui_logs/spotatuilog<pid>.

Roadmap

Het uiteindelijke doel is om vrijwel elke Spotify-functie te implementeren. Hoge prioriteit:

• Scrollen door resultaatpagina's in elk overzicht.