cimp

console interface music player

A keyboard-driven music player for the terminal, written in QuickBASIC (QB64). It plays audio files and M3U playlists directly from the command line, featuring a minimal two-line display showing playback state and an IPC remote control interface.

Features

• Plays individual audio files or M3U playlists.
• Real-time progress bar and time display (elapsed or remaining).
• Volume control and seeking via arrow keys.
• Shuffle and repeat modes.
• Client/Server IPC Architecture: Control a running instance of cimp from another terminal window or script.
• Cross-platform: works on Linux, macOS, and Windows.
• Unicode-aware display with support for full-width character width matching.

Building

1. Clone the repository:

git clone https://code.oscorp.dk/visionmercer/cimp.git
cd cimp

2. Open cimp.bas in QB64 and compile, or compile via the terminal:

qb64 -x cimp.bas

Usage

cimp [options] <file|playlist> [file2 ...]

Pass one or more audio files or .m3u playlists. At least one file is required unless sending a remote control command.

Global & Server Options

These flags control the primary player instance when launched.

Flag	Long form	Description
-v <n>	--volume <n>	Set initial volume (0–100, default: 100)
-s	--shuffle	Shuffle the playlist on start
-r [1]	--repeat [1]	Repeat all (-r) or repeat one (-r 1)
-n	--nooutput	Run silently with no display

Remote Control (Client Mode) Commands

If cimp is already running in a terminal, running it again with any of the following arguments will send an instruction to the active player instead of starting a new one:

Command	Description
--play	Resume playback
--pause	Pause playback
--stop	Stop playback
--next	Skip to the next track
--prev	Skip to the previous track
-v <n> / --volume <n>	Remotely adjust volume (0–100)
--shuffle	Reshuffle the current playlist queue
--repeat	Set player to repeat all
--repeat-1	Set player to repeat current track
--add <file>	Append a new file or playlist to the active queue
--playlist	Fetch and print the current playback queue from the server
--quit	Remotely close the running player instance

Examples

Play a single file normally

cimp song.mp3

Remote control examples (Run from a separate terminal)

Pause the music

cimp --pause

Lower the volume to 20%

cimp --volume 20

Add another track to the background player's active queue

cimp --add extra_track.flac

View the active playlist queue

cimp --playlist

Keybindings

When interacting directly with the player interface terminal, use these keys:

Key	Action
↑ / ↓	Volume up / down
← / →	Seek backward / forward 5 seconds
Space / c	Toggle pause / resume
b	Next track
z	Previous track (or restart if past 2s)
x	Restart current track
v	Stop playback
s	Reshuffle playlist
t	Toggle time display (remaining ↔ elapsed)
q / Esc	Quit

Supported Audio Formats

All formats supported by QB64/QB64PE are supported by cimp, as QB64 handles the decoding. The following formats are supported by the most recent versions of both compilers:

mod, xm, s3m, it, mid, mp3, ogg, and flac

Files

File	Description
cimp.bas	Main player — QB64-PE source handling client/server states and UI
terminkey.h	C library for cross-platform raw keyboard input, IPC pipes/sockets, and terminal sizing

Notes

• IPC Backend: On Windows, IPC relies on Named Pipes (\\.\pipe\cimp_ipc). On Linux/macOS, it binds to a local Unix Domain Socket at /tmp/cimp_ipc_<uid>.sock.
• M3U paths can be absolute or relative to the playlist file's directory.
• Volume adjustment is non-linear for a more natural response and better control at lower ranges.