[api] Allow to set volume as a relative step count (#273)

Author: xvello

api/README.md

@@ -17,7 +17,7 @@ All the endpoints will respond with `200` if successful or:
 - `POST /player/next` Skip to next track.
 - `POST /player/prev` Skip to previous track.
 - `POST /player/seek` Seek to a given position in ms specified by `pos`.
-- `POST /player/set-volume` Set volume to a given `volume` value from 0 to 65536.
+- `POST /player/set-volume` Either set volume to a given `volume` value (from 0 to 65536), or change it by a `step` count (positive or negative).
 - `POST /player/volume-up` Up the volume a little bit.
 - `POST /player/volume-down` Lower the volume a little bit.
 - `POST /player/current` Retrieve information about the current track (metadata and time).

api/src/main/java/xyz/gianlu/librespot/api/handlers/PlayerHandler.java

@@ -24,26 +24,48 @@ public PlayerHandler(@NotNull PlayerWrapper wrapper) {
         super(wrapper);
     }
 
-    private static void setVolume(HttpServerExchange exchange, @NotNull Player player, @Nullable String valStr) {
-        if (valStr == null) {
-            Utils.invalidParameter(exchange, "volume");
-            return;
-        }
+    private static void setVolume(HttpServerExchange exchange, @NotNull Player player, @Nullable String valStr, @Nullable String stepStr) {
+        if (valStr != null && stepStr != null) {
+            // Reject requests with both parameters
+            Utils.invalidParameter(exchange, "step", "Cannot be passed alongside volume");
+        } else if (valStr != null) {
+            // Absolute volume change
+            int val;
+            try {
+                val = Integer.parseInt(valStr);
+            } catch (Exception ex) {
+                Utils.invalidParameter(exchange, "volume", "Not an integer");
+                return;
+            }
 
-        int val;
-        try {
-            val = Integer.parseInt(valStr);
-        } catch (Exception ex) {
-            Utils.invalidParameter(exchange, "volume", "Not an integer");
-            return;
-        }
+            if (val < 0 || val > Player.VOLUME_MAX) {
+                Utils.invalidParameter(exchange, "volume", "Must be >= 0 and <= " + Player.VOLUME_MAX);
+                return;
+            }
+
+            player.setVolume(val);
+        } else if (stepStr != null) {
+            // Relative volume change in number of steps
+            int val;
+            try {
+                val = Integer.parseInt(stepStr);
+            } catch (Exception ex) {
+                Utils.invalidParameter(exchange, "step", "Not an integer");
+                return;
+            }
 
-        if (val < 0 || val > Player.VOLUME_MAX) {
-            Utils.invalidParameter(exchange, "volume", "Must be >= 0 and <= " + Player.VOLUME_MAX);
+            if (val > 0) {
+                player.volumeUp(val);
+            } else if (val < 0) {
+                player.volumeDown(Math.abs(val));
+            } else {
+                Utils.invalidParameter(exchange, "step", "Must be non zero");
+                return;
+            }
+        } else {
+            Utils.invalidParameter(exchange, "volume");
             return;
         }
-
-        player.setVolume(val);
     }
 
     private static void load(HttpServerExchange exchange, @NotNull Player player, @Nullable String uri, boolean play) {
@@ -168,7 +190,7 @@ protected void handleRequest(@NotNull HttpServerExchange exchange, @NotNull Sess
                 current(exchange, player);
                 return;
             case SET_VOLUME:
-                setVolume(exchange, player, Utils.getFirstString(params, "volume"));
+                setVolume(exchange, player, Utils.getFirstString(params, "volume"), Utils.getFirstString(params, "step"));
                 return;
             case VOLUME_UP:
                 player.volumeUp();

player/src/main/java/xyz/gianlu/librespot/player/Player.java

@@ -86,13 +86,21 @@ private void initState() {
     // ================================ //
 
     public void volumeUp() {
+        this.volumeUp(1);
+    }
+
+    public void volumeUp(int steps) {
         if (state == null) return;
-        setVolume(Math.min(Player.VOLUME_MAX, state.getVolume() + oneVolumeStep()));
+        setVolume(Math.min(Player.VOLUME_MAX, state.getVolume() + steps * oneVolumeStep()));
     }
 
     public void volumeDown() {
+        this.volumeDown(1);
+    }
+
+    public void volumeDown(int steps) {
         if (state == null) return;
-        setVolume(Math.max(0, state.getVolume() - oneVolumeStep()));
+        setVolume(Math.max(0, state.getVolume() - steps * oneVolumeStep()));
     }
 
     private int oneVolumeStep() {