Minimal CLI media player for local files, URLs, and playlists.

• Install
• Usage
• Keybindings
• Format support
• File browser
• URL support
• Playlist support
• Visualizer
• Install troubleshooting
• License

go install github.com/olivier-w/climp@latest

• Linux amd64, arm64
• macOS amd64 (intel), arm64 (m1,m2,m3,m4,m5)
• Windows amd64

scoop bucket add climp https://github.com/olivier-w/scoop-bucket
scoop install climp

git clone https://github.com/olivier-w/climp.git
cd climp
go build -o climp .

climp
climp song.mp3
climp track.flac
climp my-playlist.m3u
climp https://youtube.com/watch?v=...
climp https://youtube.com/playlist?list=...
climp https://example.com/station.m3u8

• audio: .mp3, .wav, .flac, .ogg
• playlists: .m3u, .m3u8, .pls

Run climp with no arguments to browse and select files interactively.

Play audio from URLs with probe-based routing:

• finite media downloads use yt-dlp
• live streams use ffmpeg (ffmpeg -i <url> -> s16le PCM)
• remote playlist wrappers (.pls, .m3u, .m3u8) are expanded into queue entries

climp https://youtube.com/watch?v=dQw4w9WgXcQ

Requirements:

• yt-dlp is required for finite URL playback and YouTube sources
• ffmpeg is required for live URL playback
• ffmpeg is also required for s (save as MP3) on downloaded URL tracks

Behavior notes:

• finite URL downloads use WAV temp files for fast processing
• if yt-dlp reports no progress for 15 seconds, climp exits instead of hanging
• live streams are non-seekable

Live URL examples:

climp https://example.com/station.m3u8
climp https://example.com/station.m3u
climp https://example.com/stream.aac
climp https://example.com/stream.mp3
climp https://example.com/stream.ogg

When you open a local audio file, climp scans the same directory for supported audio files, sorts them alphabetically, and starts playback at the selected file.

climp song.mp3

climp opens local playlist files directly:

climp my-playlist.m3u
climp my-playlist.m3u8
climp my-playlist.pls

For local playlist files, climp plays valid local media entries and http(s) URL entries. URL entries are probe-routed the same way as direct URL playback. Remote playlist URL entries (.pls, .m3u, .m3u8) are expanded inline in file order. Invalid or unsupported entries are skipped. If no playable entries remain, playback fails with an error.

YouTube playlist and radio URLs are auto-detected. The first track starts immediately while the rest of the playlist is extracted in the background (up to 50 tracks). Upcoming tracks are downloaded one at a time ahead of playback.

climp https://youtube.com/playlist?list=PLxxxxxxxx
climp https://youtube.com/watch?v=xxx&list=RDxxx

Press v to cycle visualizers: VU meter, spectrum, waterfall spectrogram, waveform, lissajous scope, braille, dense, matrix, hatching, and off.

If yt-dlp is installed with pip, Python certificate verification can fail for some setups. Install certificates (replace x with your Python version):

/Applications/Python\ 3.xx.xx/Install\ Certificates.command

If playback fails with ALSA errors such as Unknown PCM default or cannot find card '0', the machine has no usable default audio output device. This is common on headless VMs and containers.

Check detected devices:

aplay -l
aplay -L

Install or enable an audio stack (ALSA, PipeWire, or PulseAudio), or run in a session with audio output available.

Apache-2.0