Skip to content

usage.md

Latest commit

 

History

History
138 lines (102 loc) · 4.32 KB

usage.md

File metadata and controls

138 lines (102 loc) · 4.32 KB
Raw

← Back to README

Usage & Keys

Default startup

looper

Opens the playlist-history browser with no active playback. Press Enter on a row to start playing it. To skip the browser and jump straight into playback, use looper play --url ....

Local files

looper play --url "/path/to/your/song.mp3"

YouTube

looper play --url "https://www.youtube.com/watch?v=xAR6N9N8e6U"

YouTube Live

Livestream URLs are detected automatically and played as a continuous stream (no full download, no loop counter — a red ● STREAMING badge replaces the usual ● PLAYING label).

looper play --url "https://www.youtube.com/watch?v=YmQ7jRgf4f0"

That example is Anthropic's Claude FM channel — music for thinking and building.

SoundCloud

looper play --url "https://soundcloud.com/odesza/line-of-sight-feat-wynne-mansionair"

HypeM

looper play --url "https://hypem.com/track/2gq0d/CHVRCHES+-+Clearest+Blue"

Playlists

looper play --url "https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI"

Single tracks loop forever; playlists and albums play each track once, then loop the whole collection.

Spotify

Spotify needs a one-time browser login and a Premium account. See Spotify for setup and details.

looper spotify login
looper play --url "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"

Controls

Key Action
Enter Replay the selected track from the history browser
Space Pause / resume
Left / Right Seek backward / forward 5 seconds
Click / drag progress bar Scrub to any position (commits on release)
- / + Volume down / up (~2 dB per press, shown as Vol n% in the footer)
n / b Next / previous track (playlist mode)
l Loop the current playlist track (press again to disarm; n/b resume the playlist)
f Toggle fullscreen visualizer
s Toggle favorite for the current track
p / Esc Toggle the played-songs panel
/ Open Spotify search
q / Ctrl-C Quit

Seeking (arrow keys or progress-bar drag) is available for local files and cached downloads. Live or stream-first sources ignore seek input.

Volume is software gain on the player itself, so it works for every source — including Spotify — and steps finer than the coarse hardware increments many USB audio devices expose. The level persists per machine (in ~/.config/looper/volume) and carries across tracks and restarts.

Hardware/OS media keys (play/pause/next/previous) also work while looper is in the background — see Now Playing & Media Keys.

Played-songs panel

Bare looper opens directly into playlist history. During playback the panel is hidden by default and opens over the minimal UI.

Key Action
j / k Move selection down / up
h / l Change sort field
r Reverse sort direction
s Toggle favorite for the selected row
d Delete the selected row (y to confirm)
Enter Replay the selected track
p / Esc Close the panel

Sort fields: time played, last played, favorites, platform, title, times played.

Spotify search

/ opens a Spotify catalog search from the playback screen or the history browser. It needs a one-time setup — your own free Spotify API app in SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET — see Spotify → Search; without it the overlay shows the setup steps. Type a query and press Enter; results are grouped into SONGS, ARTISTS, ALBUMS, and PLAYLISTS.

Key Action
j / k Move selection down / up
gg / G Jump to first / last result
/ Edit the query again
Enter Play the selection (song loops; album/playlist plays through); on an ARTISTS row, browse the artist's full discography instead
Esc Close search

Text search is relevance-ranked, so an artist's own releases compete with everything else matching the words — Enter on the ARTISTS row is how you get the complete list of their albums, singles & EPs, and compilations. / + Enter re-runs the search to go back.

While the search overlay is open it captures all keys — q types a letter instead of quitting (Ctrl-C still works).