#3981 add webcam subsystem

docs/Features/Notifications.md

@@ -21,10 +21,16 @@ Gnome-shell: \
 
 ***
 
-## Debugging
+## Technical
+
+Please refer to [the notifications subsystem](../Subsystems/Notifications.md).
+<details>
+  <summary>Debugging</summary>
+
 * start both the client and server with the debug command line flags: `-d notify,dbus`
 * you can also test notifications forwarding using the dbus interface or xpra control, ie:
   ```shell
   xpra control :100 send-notification "hello" "world" "*"
   ```
   will send the message to all clients.
+</details>

docs/Features/Webcam.md

@@ -35,7 +35,9 @@ You can enable the webcam from the client's system tray menu, or using the comma
 * MS Windows client builds have very unreliable support
 
 
-## Debugging
+## Technical
+
+For further reference, see [the webcam subsystem](../Subsystems/Webcam.md).
 <details>
   <summary>Diagnostics</summary>
 

docs/README.md

@@ -62,6 +62,11 @@
 See [Multicast DNS](./Network/Multicast-DNS.md) and [Encryption](./Network/Encryption.md): [AES](./Network/AES.md), [SSL](./Network/SSL.md), [SSH](./Network/SSH.md)
 </details>
 
+## Technical
+* [network protocol](./Network/Protocol.md)
+* [subsystems](./Subsystems)
+* [security](./Usage/Security.md)
+
 ---
 
 ## [Build](./Build/README.md)

docs/Subsystems/README.md

@@ -1,14 +1,17 @@
 # Subsystems
 
-This documentation refers to individual protocol features,
+This documentation refers to individual [protocol](../Network/Protocol.md) features,
 it links to the implementation and technical documentation for each subsystem.
 
 Most modules are optional, see [security considerations](../Usage/Security.md).
 
+## Concepts
+
 * Client Module: feature implementation loaded by the client, it interfaces with the corresponding "Client Connection Module" on the server side
-* Client Connection Module: for each connection to a client, the server will instantiate this module
+* Client Connection Module: for each connection to a client, the server will instantiate a handler
 * Server Module: feature implemented by the server, it may interact with multiple "Client Connection Modules"
 
+
 | Subsystem                           | [Client Module](../../xpra/client/mixins/)                   | [Server Module](../../xpra/server/mixins)          | [Client Connection Module](../../xpra/server/source/)    | User Documentation                                      |
 |-------------------------------------|--------------------------------------------------------------|----------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------|
 | [Audio](./Audio.md)                 | [audio](../../xpra/client/mixins/audio.py)                   | [audio](../../xpra/server/mixins/audio.py)         | [audio](../../xpra/server/source/audio.py)               | [audio feature](../Features/Audio.md)                   |

docs/Subsystems/Webcam.md

@@ -0,0 +1,47 @@
+# ![Webcam](../images/icons/webcam.png) Webcam
+
+For usage related information, see [webcam feature](../Features/Webcam.md).
+
+
+## Implementations
+
+| Component         | Link                                                              |
+|-------------------|-------------------------------------------------------------------|
+| client            | [xpra.client.mixins.webcam](../../xpra/client/mixins/webcam.py)   |
+| client connection | [xpra.server.source.webcam](../../xpra/server/source/webcam.py)   |
+| server            | [xpra.server.mixins.webcam](../../xpra/server/mixins/webcam.py)   |
+
+
+## Capabilities
+
+The client exposes a single `webcam` boolean capability.  
+The server exposes the following attributes using the  `webcam` capability prefix:
+* `enabled` boolean
+* `encodings` list of strings - encodings supported: only `png` or `jpeg` are guaranteed to be supported
+* `devices` integer - the number of virtual video devices available
+
+
+## Network Packets
+
+| Packet Type           | Arguments                                                      | Direction        |
+|-----------------------|----------------------------------------------------------------|------------------|
+| `webcam-start`        | `device_id`, `width`, `height`                                 | client to server |
+| `webcam-ack`          | `unused`, `frame_no`, `width`, `height`                        | server to client |
+| `webcam-frame`        | `device_id`, `frame_no`, `encoding`, `width`, `height`, `data` | client to server |
+| `webcam-stop`         | `device_no`                                                    |
+
+`device_id`, `frame_no`, `width` and `height` are always integers, `encoding` is a string.
+
+The `device_id` must be smaller than the number of virtual video `devices`.
+
+
+### Flow
+
+* client requests `webcam-start`
+* the server responds with a `webcam-ack` for `frame_no` 0, the `width` and `height` may be different from the one requested
+* the client can then send a `webcam-frame` for `frame_no` 1
+* the server responds with a `webcam-ack` for each frame it receives
+* the client must wait for the `webcam-ack` before sending the next frame
+* whenever the client decides to stop forwarding the webcam, it must send a `webcam-stop` packet
+
+If any of these steps fail, a `webcam-stop` packet must be sent to the peer.