Looper

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.

Highlights

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

Install

brew tap program247365/tap
brew install looper

Apple Silicon gets a prebuilt binary. For Intel, building from source, or Linux, see Installation.

Quick start

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, p for history, q to quit. More examples and keybindings in Usage & Keys.

Documentation

Guide	What's inside
Installation	Homebrew, build from source, runtime dependencies
Usage & Keys	Every source, playlists, controls, the history panel
Spotify	Login, playback, 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

Requirements

• macOS or Linux
• yt-dlp + ffmpeg for YouTube / SoundCloud / HypeM (auto-installed by Homebrew)
• Spotify needs neither — just a Premium account and a one-time login

License

MIT · Built in Rust with ratatui · kbr.sh/looper