diff --git a/README.md b/README.md index 929f54a..f4450c3 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # vbclient -Java client for the [Voice Box Karaoke](http://voiceboxpdx.com) API. +Java client for the [Voice Box Karaoke](https://voiceboxpdx.com) API. ## Overview -Voice Box Karaoke is a private-room karaoke platform (voiceboxpdx.com). `vbclient` is the Java SDK that wraps its HTTP API — searching the song catalog, managing per-room sessions and queues, posting popups, and controlling room lights. It's used by the [DJ VoxBox] Spring Boot backend. +Voice Box Karaoke is a private-room karaoke platform (voiceboxpdx.com). `vbclient` is the Java SDK that wraps its HTTP API — searching the song catalog, managing per-room sessions and queues, posting popups, controlling room lights and audio, sending current-song commands, validating room codes, handling service calls, and collecting feedback. As of `0.3.0` it covers the full [karaoke API surface](https://vbsongs.com/api/v1/documentation/karaoke.html). It's used by the [DJ VoxBox] Spring Boot backend. ## Requirements @@ -18,19 +18,19 @@ Voice Box Karaoke is a private-room karaoke platform (voiceboxpdx.com). `vbclien com.vpo vbclient - 0.2.0-RELEASE + 0.3.0 ``` ## Usage -All three clients share the same constructor pattern. `root` overrides the API base URL (defaults to `http://voiceboxpdx.com`); `organization` is the 32-character org identifier required for every call. +All clients share the same constructor pattern. `root` overrides the API base URL (defaults to `https://voiceboxpdx.com`); `organization` is the 32-character org identifier required for every call. ```java String org = "00000000000000000000000000000000"; // your 32-char org ID ``` -### SongClient — catalog, favorites, history +### SongClient — catalog, favorites, history, stats ```java SongClient songs = new SongClient(null, org); @@ -39,6 +39,11 @@ Search results = songs.findSongs(new Search("love")); Song song = songs.getSongById(68733); TagList tags = songs.tags(); LanguageList languages = songs.languages(); + +List suggestions = songs.autocomplete("lov"); +List random = songs.roulette(new RouletteRequest()); +SongStats stats = songs.stats(); +songs.requestSong(new SongRequest("Beatles", "Let It Be"), session); ``` ### SessionClient — sessions, popups, lights @@ -65,6 +70,38 @@ queue.addSong(new PlayRequest(/* ... */)); queue.reorder("CQFW", "0", "1"); ``` +### CurrentSongClient — playback and audio controls + +```java +CurrentSongClient current = new CurrentSongClient(null, org); + +current.pause("CQFW"); +current.resume("CQFW"); +current.skip("CQFW"); +current.restart("CQFW"); +current.setAudio("CQFW", 75, 0, null); // volume, pitch_shift, channels +``` + +### RoomClient — room validation and service calls + +```java +RoomClient rooms = new RoomClient(null, org); + +Room room = rooms.getRoom("CQFW"); +ServiceCall call = rooms.getServiceCall("CQFW"); +rooms.setServiceCall(session, "CQFW", ServiceCall.STATE_REQUESTED); +``` + +### FeedbackClient — prompts and submissions + +```java +FeedbackClient feedback = new FeedbackClient(null, org); + +List prompts = feedback.getPrompts(session, "CQFW"); +feedback.submit(session, "CQFW", List.of( + new FeedbackResponse(prompts.get(0).getGuid(), 5, "great room"))); +``` + Room codes (e.g. `"CQFW"`) identify a karaoke room within the organization. ## Build & test @@ -77,4 +114,6 @@ The same command runs on every push and pull request via [GitHub Actions](.githu ## Versioning -`0.2.0-RELEASE` migrated the library to Spring Boot 3.2, Java 17, and JUnit 5. Prior `0.1.x` releases targeted Spring Boot 1.x / Java 7 / JUnit 4. +- `0.3.0` brings the library to full parity with the karaoke API: adds `RoomClient`, `CurrentSongClient`, `FeedbackClient`, and new `SongClient` methods (`autocomplete`, `roulette`, `stats`, `requestSong`), plus profile/queue/search fields that the prior models didn't expose. +- `0.2.0` migrated the library to Spring Boot 3.2, Java 17, and JUnit 5. +- Prior `0.1.x` releases targeted Spring Boot 1.x / Java 7 / JUnit 4.