osu-play 1.0.6 → 1.1.0

package/README.md

@@ -1,58 +1,91 @@
-# osu!play
+# osu-play
 
-Listen to your favourite [osu!lazer](https://lazer.ppy.sh) beatmaps as a spotify playlist from the terminal
+Play music from your osu!lazer beatmaps from the terminal.
 
-## Installation
+## Requirements
 
-### Requirements
+- Node.js `20+`
+- 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
+# Play music interactively
+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!
+### 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
+- `--osuDataDir, -d`: Override the osu!lazer data directory
+- `--configDir, -c`: Deprecated and ignored
+- `--loop, -l`: Restart from the beginning when the playlist ends
+- `--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 -- --help
+bun run check
 ```
 
+Useful day-to-day commands:
+
+```bash
+bun run dev -- --help
+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
+```
+
+`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