From 1ece285bf18ee872c1d48c97bf24b570c74d2692 Mon Sep 17 00:00:00 2001
From: visionmercer <62051836+visionmercer@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:10:50 +0200
Subject: [PATCH] readme

---
 readme.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..7ef2562
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,96 @@
+# 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 the compiler
+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 (logarithmic-feeling) for a more natural
+  response and better control at lower ranges.