2026-06-01 10:10:50 +02:00
|
|
|
|
# cimp
|
|
|
|
|
|
|
2026-06-01 10:15:27 +02:00
|
|
|
|
**c**onsole **i**nterface **m**usic **p**layer
|
|
|
|
|
|
|
|
|
|
|
|
A lightweight, keyboard-driven music player for the terminal, written in
|
|
|
|
|
|
QuickBASIC (QB64). It plays audio files and M3U playlists directly from the
|
|
|
|
|
|
command line, with a minimal two-line display showing playback state.
|
2026-06-01 10:10:50 +02:00
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
- Cross-platform: works on Linux, macOS, and Windows
|
|
|
|
|
|
- Unicode-aware display
|
|
|
|
|
|
|
|
|
|
|
|
## Building
|
|
|
|
|
|
|
|
|
|
|
|
1. Clone the repository:
|
|
|
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
|
|
git clone https://code.oscorp.dk/visionmercer/cimp.git
|
|
|
|
|
|
cd cimp
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
2. Open `cimp.bas` in QB64 and compile, or compile via the terminal:
|
|
|
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
|
|
qb64 -x cimp.bas
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
|
|
cimp [options] <file|playlist> [file2 ...]
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Pass one or more audio files or `.m3u` playlists. At least one file is required.
|
|
|
|
|
|
|
|
|
|
|
|
### Options
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
|
|
|
|
|
|
|
|
|
|
|
|
### Examples
|
|
|
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
|
|
# Play a single file
|
|
|
|
|
|
cimp song.mp3
|
|
|
|
|
|
|
|
|
|
|
|
# Play a playlist shuffled at 80% volume
|
|
|
|
|
|
cimp -s -v 80 playlist.m3u
|
|
|
|
|
|
|
|
|
|
|
|
# Play multiple files with repeat
|
|
|
|
|
|
cimp -r track1.ogg track2.ogg track3.ogg
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Keybindings
|
|
|
|
|
|
|
|
|
|
|
|
| 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
|
|
|
|
|
|
|
2026-06-01 10:15:27 +02:00
|
|
|
|
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:
|
2026-06-01 10:10:50 +02:00
|
|
|
|
|
|
|
|
|
|
`mod`, `xm`, `s3m`, `it`, `mid`, `mp3`, `ogg`, and `flac`
|
|
|
|
|
|
|
|
|
|
|
|
## Files
|
|
|
|
|
|
|
|
|
|
|
|
| File | Description |
|
|
|
|
|
|
| ------------- | ---------------------------------------------------------------------------- |
|
2026-06-02 21:02:14 +02:00
|
|
|
|
| `cimp.bas` | Main player |
|
2026-06-01 10:10:50 +02:00
|
|
|
|
| `terminkey.h` | C library for cross-platform raw keyboard input and terminal width detection |
|
|
|
|
|
|
|
|
|
|
|
|
## Notes
|
|
|
|
|
|
|
|
|
|
|
|
- M3U paths can be absolute or relative to the playlist file's directory.
|
2026-06-01 10:15:27 +02:00
|
|
|
|
- Volume adjustment is non-linear for a more natural response and better control
|
|
|
|
|
|
at lower ranges.
|
