153 lines
5.4 KiB
Markdown
153 lines
5.4 KiB
Markdown
# 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.
|
||
|
||
```
|
||
```
|