update readme

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
+A keyboard-driven music player for the terminal, written in QuickBASIC (QB64).
-QuickBASIC (QB64). It plays audio files and M3U playlists directly from the
+It plays audio files and M3U playlists directly from the command line, featuring
-command line, with a minimal two-line display showing playback state.
+a minimal two-line display showing playback state and an IPC remote control
+interface.
 
 ## Features
 
-- Plays individual audio files or M3U playlists
+- Plays individual audio files or M3U playlists.
-- Real-time progress bar and time display (elapsed or remaining)
+- Real-time progress bar and time display (elapsed or remaining).
-- Volume control and seeking via arrow keys
+- Volume control and seeking via arrow keys.
-- Shuffle and repeat modes
+- Shuffle and repeat modes.
-- Cross-platform: works on Linux, macOS, and Windows
+- **Client/Server IPC Architecture**: Control a running instance of `cimp` from
-- Unicode-aware display
+  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] <file|playlist> [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 <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
-# Play a single file
 cimp song.mp3
+```
 
-# Play a playlist shuffled at 80% volume
+### Remote control examples (Run from a separate terminal)
-cimp -s -v 80 playlist.m3u
 
-# Play multiple files with repeat
+#### Pause the music
-cimp -r track1.ogg track2.ogg track3.ogg
+
+```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                          |
@@ -86,12 +136,18 @@ both compilers:
 ## Files
 
 | File          | Description                                                                             |
-| ------------- | ---------------------------------------------------------------------------- |
+| ------------- | --------------------------------------------------------------------------------------- |
-| `cimp.bas`    | Main player — QB64-PE source                                                 |
+| `cimp.bas`    | Main player — QB64-PE source handling client/server states and UI                       |
-| `terminkey.h` | C library for cross-platform raw keyboard input and terminal width detection |
+| `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.
+
+```
+```