# 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.