97 lines
3.1 KiB
Markdown
97 lines
3.1 KiB
Markdown
# cimp
|
||
|
||
**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.
|
||
|
||
## 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
|
||
|
||
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 |
|
||
| `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.
|
||
- Volume adjustment is non-linear for a more natural response and better control
|
||
at lower ranges.
|