osu-play 1.0.7 → 1.2.0

package/README.md

@@ -12,58 +12,112 @@
 > Listen to your favourite [osu!lazer](https://lazer.ppy.sh) beatmaps as a
 > spotify playlist from the terminal
 
-## Installation
+## Requirements
 
-### Requirements
+- Node.js `20+`
+- `mpv` available on your `PATH`
+- An osu!lazer install with beatmaps available locally
 
-- [Node.js](https://nodejs.org/en/) (v18 or higher)
-- [osu!lazer](https://lazer.ppy.sh/home/download) with some beatmaps to listen
-  to 😉
-- That's it!
+If you're developing locally, Realm's native bindings are still the one awkward part of this stack. Use the repo's `setup` script so Bun install and the Realm repair step happen in the right order.
 
-### Quick start
+## Installation
 
-- Try out the latest release without installing anything:
 
-  ```sh
-  npx osu-play # using npm
-  pnpm dlx osu-play # using pnpm
-  ```
+```bash
+npm install -g osu-play
+```
 
-- Install the latest release globally:
+Or run it without a global install:
 
-  ```sh
-  npm i -g osu-play # using npm
-  pnpm i -g osu-play # using pnpm
-  ```
+```bash
+npx osu-play
+```
 
 ## Usage
 
-The `osu-play` command can be used with the following options:
-
-```sh
-➜  korigamik git:(main) ✗ osu-play --help
-Play music from your osu!lazer beatmaps from the terminal
-Usage: osu-play [options]
-
-Options:
-      --help            Show help                                      [boolean]
-      --version         Show version number                            [boolean]
-  -r, --reload          Reload lazer database         [boolean] [default: false]
-      --exportPlaylist  Export playlist to a file                       [string]
-  -d, --osuDataDir      Osu!lazer data directory
-                            [string] [default: "/home/origami/.local/share/osu"]
-  -c, --configDir       Config directory
-                            [string] [default: "/home/origami/.config/osu-play"]
-  -l, --loop            Loop the playlist on end      [boolean] [default: false]
+### CLI
+
+```bash
+# Launch the TUI player
+osu-play
+
+# Export a playlist file
+osu-play --exportPlaylist playlist.txt
+
+# Loop the playlist
+osu-play --loop
 ```
 
-This package can be used as a library or as a cli application. To use the lazer
-database interaction in your applicatoins import the `osu-play` package and
-start using it!
+### TUI Controls
+
+- `Up/Down` or `j/k`: Move through the playlist
+- `Left/Right` or `h/l`: Seek backward or forward by 5 seconds
+- `Enter`: Play the selected track
+- `Space`: Pause or resume playback
+- `n` / `p`: Next or previous track
+- `PageUp` / `PageDown`: Jump faster through the playlist
+- `r`: Toggle looping
+- `s`: Stop playback
+- `q`: Quit
+- `/`: Enter search mode
+- Type in search mode: Jump the selection by track title
+- `Backspace`: Edit the search query
+- `Enter`: Leave search mode and keep the current query
+- `Esc`: Leave search mode, or clear the current query outside search mode
+
+### API
 
 ```ts
-import { lazer } from "osu-play";
+import { getLazerDB, getRealmDBPath } from "osu-play";
+
+const realmPath = getRealmDBPath({ osuDataDir: "/path/to/osu" });
+const db = await getLazerDB(realmPath);
+```
+
+## Options
+
+- `--reload, -r`: Deprecated and ignored
+- `--exportPlaylist`: Export the discovered track paths to a file instead of launching the TUI
+- `--osuDataDir, -d`: Override the osu!lazer data directory
+- `--configDir, -c`: Deprecated and ignored
+- `--loop, -l`: Restart from the beginning when playback reaches the end
+- `--help, -h`: Show help
+
+## Development
+
+Bun `1.3+` is required only for development and contributing; it is not needed to run the published CLI via `npm install -g` or `npx osu-play`.
 
-const realm = getLazerDB();
+```bash
+bun run setup
+bun run dev
+bun run check
 ```
+
+Useful day-to-day commands:
+
+```bash
+bun run dev
+bun run dev -- --loop
+bun run dev -- --exportPlaylist playlist.txt
+bun run test
+bun run package
+```
+
+If you hit a Realm native-binding error like `realm.node` missing or Node failing to load Realm:
+
+```bash
+bun install
+bun run repair:realm
+```
+
+If `osu-play` fails with an `mpv` startup or IPC error, make sure `mpv` is installed and available on your shell `PATH`.
+
+`bun run package` builds the distributable files and creates a local npm tarball with `bun pm pack`.
+
+osu-play now reads osu!lazer's live `client.realm` directly in read-only mode instead of copying it into a separate app directory.
+
+Standalone Bun executables are intentionally not part of the release flow right now. The current Realm dependency uses native bindings, and Bun's standalone executable support does not yet cover that path cleanly enough for this app.
+
+## License
+
+MIT