[Proposal] Control panel

CLIENT.md

@@ -20,10 +20,10 @@ You can base yourself on the `rx-paired.config.example.json` file:
 cp rx-paired.config.example.json rx-paired.config.json
 ```
 
-### The `deviceDebuggerUrl`
+### The `serverUrl`
 
 In that new `rx-paired.config.json` file, you'll need to set one URL: the
-`deviceDebuggerUrl`.
+`serverUrl`.
 
 This will be the WebSocket address `RxPaired-server` is listening to for
 `RxPaired-client` connections and messages.
@@ -69,3 +69,161 @@ At last, you have two choices in how to deploy that script:
   to manually deploy the whole script yourself on your applications manually.
 
 In both cases, `RxPaired-inspector` will give you all the necessary instructions.
+
+## Commands
+
+RxPaired allows to remotely send a "command" to interact with one of the players
+running on the device.
+
+Those commands allow to perform actions such as seeking, pausing, reloading the
+content etc.
+
+Note that this is completely optional. It just allows to improve the inspector
+by allowing it to control playback remotely.
+
+### List of available commands
+
+The list of available commands are:
+
+- `stop`: Stop playback for the current playing content, if one.
+
+- `pause`: Pause playback for the current playing content, if one is playing.
+
+- `resume`: Resume playback for the current playing content, if one is paused.
+
+- `mute`: Mute audio volume in the associated player.
+
+- `unmute`: Unmute audio volume in the associated player.
+
+- `seekAbsolute`: Set the playback position to a particular value in seconds
+  given in argument. Only apply if a content is currently playing on that
+  player.
+
+- `seekRelative`: Set the playback position relatively to the one currently
+  playing, by exploiting the signed floating point value in argument (indicated
+  as a number of seconds). Only apply if a content is currently playing on that
+  player.
+
+- `setPlaybackRate`: Modify the playback speed in the associated player to the
+  given value.
+
+- `setWantedBufferAhead`: Modify the amound of buffer pre-loaded by default when
+  loading a content. The corresponding value
+
+- `reload`: If a content is currently playing, re-load that content at roughly
+  the same position. If no content is currently playing on that player but a
+  content was previously playing on it, re-load that previous content at roughly
+  its last played position.
+
+A player can implement any subset of these commands, or all of them.
+The more commands are implemented, the more it can be controlled by RxPaired's
+inspector.
+
+### Declaring/removing a player with its commands
+
+To declare a new player instance and its associated commands, the client script
+creates a `__RX_PAIRED_PLAYERS__` object globally (defined in `window`).
+
+This object has two methods:
+
+- `add`, to add a new player. This function should be called when your player
+  is instantiated and will declare the available commands.
+
+- `remove`, to remove a previously-added player. This function should be called
+  when your player is diposed, to free its resources.
+
+`add` is a function which takes an object containing the following propoerties:
+
+- `version` (`number`): Has to be set to `1`
+
+- `name` (`string`): The preferred name to refer to the player that is currently
+  being added. Will be shown in the inspector.
+
+- `key` (`object`): Unique reference that will also be used to remove that
+  player through the `remove` function.
+
+- `commands` (`Object`): Object where the keys are command names as `string` and
+  the values are the `function` implementations for those commands.
+
+  Those implementations may be called with arguments (it makes sense
+  particularly for commands like `seekRelative`, `seekAbsolute`,
+  `setPlaybackRate` etc.).
+  Those arguments will always be under an `Array` of `string` type.
+  If a `number` is wanted, it will need to be converted from a string to a
+  number.
+
+  The length of that array should also be checked and the input, as it may come
+  from the network, should always be validated.
+
+`remove` is a function that should be called when the player is destroyed /
+disposed. It takes the same `key` you provided to `add` as a unique argument.
+
+### Example
+
+Here's an example implementation, taking the RxPlayer as reference:
+
+```js
+/**
+ * Add the commands for a new RxPlayer instance.
+ * @param {RxPlayer} player
+ */
+function registerPlayerForRxPaired(player) {
+  globalScope.__RX_PAIRED_PLAYERS__?.add({
+    version: 1,
+    name: "RxPlayer",
+    key: player,
+    commands: {
+      seekAbsolute(args) {
+        const pos = +args[0];
+        if (!isNaN(pos)) {
+          player.seekTo(pos);
+        }
+      },
+      seekRelative(args) {
+        const pos = +args[0];
+        if (!isNaN(pos)) {
+          player.seekTo({ relative: pos });
+        }
+      },
+      setPlaybackRate(args) {
+        const pr = +args[0];
+        if (!isNaN(pr)) {
+          player.setPlaybackRate(pr);
+        }
+      },
+      setWantedBufferAhead(args) {
+        const wba = +args[0];
+        if (!isNaN(wba)) {
+          player.setWantedBufferAhead(wba);
+        }
+      },
+      mute() {
+        player.mute();
+      },
+      unmute() {
+        player.unMute();
+      },
+      reload() {
+        player.reload();
+      },
+      pause() {
+        player.pause();
+      },
+      resume() {
+        player.play();
+      },
+      stop() {
+        player.stop();
+      },
+    },
+  });
+}
+
+/**
+ * Free resources associated to a previously-created RxPlayer instance.
+ * @param {RxPlayer} player
+ */
+function unregisterPlayerForRxPaired(player) {
+  globalScope.__RX_PAIRED_PLAYERS__?.remove(player);
+}
+```

SERVER.md

@@ -262,6 +262,34 @@ Various messages may be sent by the server through that WebSocket connection:
       If `history` has the same length, then it may be that older logs
       have been removed from it to respect that limit.
 
+- **Player registration**: Notify that a new player can be remotely controlled
+  on that WebSocket and announce which commands are available.
+
+  - `type` (string): Always set to `"register-player"`. This allows the server
+    and inspectors to identify that this is a "Player registration" message.
+
+  - `value` (object): Object with the following keys:
+
+    - `playerId` (string): Unique identifier that should be used when
+      interacting with that player through "Command" messages.
+
+    - `commands` (Array.\<string\>): Available "commands" implemented for that
+      player. Example of commands: `stop`, `reload`, `pause` etc.
+
+      The list of possible commands are listed in the [CLIENT.md](./CLIENT.md)
+      file.
+
+- **Player de-registration**: Notify that a previously registered player
+  (through a "Player registration" message) is not available anymore.
+
+  - `type` (string): Always set to `"unregister-player"`. This allows the server
+    and inspectors to identify that this is a "Player de-registration" message.
+
+  - `value` (object): Object with the following keys:
+
+    - `playerId` (string): Unique identifier used when sending the "Player
+      registration" message for that player.
+
 - **Evaluation results**: An inspector can send JavaScript code to be executed
   on the device, those are called "evaluations" by the RxPaired-server.
 
@@ -368,6 +396,32 @@ through that route the following types of messages:
   the message an inspector should send after receiving a `ping` message
   through that same connection.
 
+- **Command**: Those messages allow an inspector to remotely control a specific
+  player on the device (e.g. to pause playback, seek, change tracks etc.)
+  provided that device advertised those capabilities through "Player
+  registration" messages.
+
+  An inspector may know which players are available and which commands on each
+  of them are available by listening to "Player registration" and "Player
+  de-registration" message the server sent to it on that same connection.
+
+  "Command" messages as sent by the inspector are UTF-8 encoded JSON with the
+  following keys:
+
+  - `type` (string): Always set to `"command"`. This allows the server and
+    device to identify that this is a "Command" message.
+
+  - `value` (object): Object with the following keys:
+
+    - `playerId` (string): Identify the player on which that command should be
+      executed. This is the same identifier than one advertised through a
+      "Player registration" message.
+
+    - `command` (string): The command to execute on that player. This is a
+      `string` that should have been previously advertised in the
+      correspondinding "Player registration" message for that `playerId`
+      (present in the array under the key `commands` on that message).
+
 - **Evaluation**: Those messages allow an inspector to ask the device to
   execute some JavaScript code present in this message.
 
@@ -515,6 +569,26 @@ Messages may be sent by the server through that WebSocket connection:
   (such as servers) might automatically decide to close the connection
   otherwise.
 
+- **Command**: Those messages originates from the RxPaired-inspector and allows
+  it to interact with a player on this device (e.g. to pause playback, seek,
+  change tracks etc.).
+
+  "Command" messages are UTF-8 encoded JSON with the following keys:
+
+  - `type` (string): Always set to `"command"`. This allows to identify that
+    this is a "Command" message.
+
+  - `value` (object): Object with the following keys:
+
+    - `playerId` (string): Identify the player on which that command should be
+      executed. This is the same identifier than one advertised through a
+      previous "Player registration" message from that device.
+
+    - `command` (string): The command to execute on that player. This is a
+      `string` that should have been previously advertised in the
+      correspondinding "Player registration" message for that `playerId`
+      (present in the array under the key `commands` on that message).
+
 - **Evaluation**: Those messages originates from an RxPaired-inspector and
   allows it to execute some JavaScript code present in this message.
 
@@ -564,7 +638,35 @@ Messages may be sent by the server through that WebSocket connection:
   the message an inspector should send after receiving a `ping` message
   through that same connection.
 
-- **Evaluation results**: When an instruction, through an Evaluation message
+- **Player registration**: Notify that a new player can be remotely controlled
+  on that WebSocket and announce which commands are available.
+
+  - `type` (string): Always set to `"register-player"`. This allows the server
+    and inspectors to identify that this is a "Player registration" message.
+
+  - `value` (object): Object with the following keys:
+
+    - `playerId` (string): Unique identifier that should be used when
+      interacting with that player through "Command" messages.
+
+    - `commands` (Array.\<string\>): Available "commands" implemented for that
+      player. Example of commands: `stop`, `reload`, `pause` etc.
+
+      The list of possible commands are listed in the [CLIENT.md](./CLIENT.md)
+      file.
+
+- **Player de-registration**: Notify that a previously registered player
+  (through a "Player registration" message) is not available anymore.
+
+  - `type` (string): Always set to `"unregister-player"`. This allows the server
+    and inspectors to identify that this is a "Player de-registration" message.
+
+  - `value` (object): Object with the following keys:
+
+    - `playerId` (string): Unique identifier used when sending the "Player
+      registration" message for that player.
+
+- **Evaluation results**: When an instruction, through an "Evaluation message"
   of that same WebSocket connection, executes with success, the device should
   send back a corresponding "Evaluation result" message described here.