96 lines
3.1 KiB
Markdown
96 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 the compiler
|
|||
|
|
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 (logarithmic-feeling) for a more natural
|
|||
|
|
response and better control at lower ranges.
|