cimp/readme.md

# cimp

**c**onsole **i**nterface **m**usic **p**layer

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:

```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
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

```shell
cimp song.mp3
```

### Remote control examples (Run from a separate terminal)

#### Pause the music

```shell
cimp --pause
```

#### Lower the volume to 20%

```shell
cimp --volume 20
```

#### Add another track to the background player's active queue

```shell
cimp --add extra_track.flac
```

#### View the active playlist queue

```shell
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.

```
```