From 52c0e7365983b552713482a69fd6b363f05010c4 Mon Sep 17 00:00:00 2001 From: visionmercer <62051836+visionmercer@users.noreply.github.com> Date: Wed, 24 Jun 2026 12:18:21 +0200 Subject: [PATCH] update readme --- readme.md | 98 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 77 insertions(+), 21 deletions(-) diff --git a/readme.md b/readme.md index b1fffbf..fb2f071 100644 --- a/readme.md +++ b/readme.md @@ -2,25 +2,28 @@ **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. +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 -- Cross-platform: works on Linux, macOS, and Windows -- Unicode-aware display +- 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 +git clone [https://code.oscorp.dk/visionmercer/cimp.git](https://code.oscorp.dk/visionmercer/cimp.git) cd cimp ``` @@ -36,9 +39,12 @@ qb64 -x cimp.bas cimp [options] [file2 ...] ``` -Pass one or more audio files or `.m3u` playlists. At least one file is required. +Pass one or more audio files or `.m3u` playlists. At least one file is required +unless sending a remote control command. -### Options +### Global & Server Options + +These flags control the primary player instance when launched. | Flag | Long form | Description | | -------- | -------------- | ---------------------------------------- | @@ -47,21 +53,65 @@ Pass one or more audio files or `.m3u` playlists. At least one file is required. | `-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 ` / `--volume ` | 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 ` | 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 -# Play a single file cimp song.mp3 +``` -# Play a playlist shuffled at 80% volume -cimp -s -v 80 playlist.m3u +### Remote control examples (Run from a separate terminal) -# Play multiple files with repeat -cimp -r track1.ogg track2.ogg track3.ogg +#### 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 | @@ -85,13 +135,19 @@ both compilers: ## Files -| File | Description | -| ------------- | ---------------------------------------------------------------------------- | -| `cimp.bas` | Main player — QB64-PE source | -| `terminkey.h` | C library for cross-platform raw keyboard input and terminal width detection | +| 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_.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. + +``` +```