A terminal music player that loops anything — local files, YouTube, SoundCloud, HypeM, and Spotify — with a real-time visualizer and native Now Playing integration for macOS.
Drop in a file or paste a URL and looper plays it on repeat in a clean ratatui
terminal UI: a live FFT scatter visualizer, album art, history, favorites, and
full macOS/Linux media-key support. Put on a track, hit fullscreen, stay in the
zone.
- Play from anywhere — local files, YouTube (incl. live), SoundCloud, HypeM, and Spotify tracks, playlists, and albums
- Real-time visualizer — a log-spaced FFT scatter with a fullscreen mode (
f) - Loops the way you want — single tracks forever; playlists and albums play through, then repeat
- Native Now Playing — album art, artist, and album in macOS Control Center / lock screen and Linux MPRIS, plus play/pause/next/previous media keys
- Software volume —
-/+trim playback in ~2 dB steps below your hardware's coarse volume steps, persisted per machine - Remembers everything — SQLite-backed history and favorites, with optional cross-device sync
- Offline-first and resilient — a fast local DB, cached downloads, automatic Spotify reconnect, and graceful handling of dead links
brew tap program247365/tap brew install looper
Apple Silicon gets a prebuilt binary. For Intel, building from source, or Linux, see Installation.
looper # browse your history; Enter to replay looper play --url ~/music/focus.mp3 # a local file, on loop looper play --url "https://www.youtube.com/watch?v=xAR6N9N8e6U"
Spotify (Premium) takes a one-time browser login:
looper spotify login
looper play --url "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"Press f for fullscreen, space to pause, -/+ for volume, p for
history, q to quit. More examples and keybindings in
Usage & Keys.
Want in-app Spotify search (/ to find and loop a song, album, or playlist)?
That takes a free Spotify API app of your own — one-time setup in
Spotify → Search.
The history browser — bare looper opens here. Every track and playlist
you've played, sortable by favorites, last played, or time played; Enter
replays anything, s stars a favorite.
Resolving a SoundCloud link — remote tracks get an in-TUI loading scene with progress instead of raw log output.
| Guide | What's inside |
|---|---|
| Installation | Homebrew, build from source, runtime dependencies |
| Usage & Keys | Every source, playlists, controls, the history panel |
| Spotify | Login, playback, in-app search setup, and how librespot streaming works |
| Now Playing & Media Keys | The OS media-session integration |
| How Playback Works | The yt-dlp model, caching, and quirks |
| Cross-Device Sync | Share history across machines via a cloud folder |
| Development | Build, test, and release |
- macOS or Linux
yt-dlp+ffmpegfor YouTube / SoundCloud / HypeM (auto-installed by Homebrew)- Spotify needs neither — just a Premium account and a one-time login
MIT · Built in Rust with ratatui · kbr.sh/looper