diff options
| -rw-r--r-- | README.md | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..97d88c2 --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +PipeWire Instrument Cluster IPC +=============================== + +This software component provides a communication link between applications +running in the Instrument Cluster container and the host container's PipeWire +daemon. It is useful when IC applications need to suspend sound output from the +host, temporarily, in order to play an emergency sound. + +This component is tailored for use in containerized environments. For use in +an environment where the IC is a different host, additional work may be required. + +## libicipc + +Most of the functionality is implemented as a library, called `icipc`. + +This library implements both the server-side and the client-side. +The server-side is meant to be used by the host, while the client-side is +to be used by the applications running in the IC guest. + +The library implements a generic unix socket based communication mechanism +where a sender (client) can send any data buffer to the receiver (server). +The server is always required to respond. + +``` + client ------- REQUEST --------> server + client <--- REPLY (OK/ERROR) --- server +``` + +The server is also able to track the clients that are connected, individually. +When a client connects or disconnects, the server is notified. + +The protocol used for communication is a binary serialization of data structures, +that aims to be compatible with PipeWire's spa_pod serialization mechanism, +which is used in PipeWire's native protocol. The implementation of this protocol +is kept private, for now, as it is not needed for the simple use case of sending +suspend/resume requests (see below). + +## module-protocol-ic-ipc + +The server-side component is built as a pipewire module, called +`libpipewire-module-protocol-ic-ipc`. It is meant to be executed on +a standalone pipewire instance, using the pipewire configuration file provided: +`pipewire-ic-ipc.conf` + +To start the server manually, execute: +``` +$ pipewire -c /absolute/path/to/pipewire-ic-ipc.conf +``` + +For convenience, systemd `.service` and `.socket` units are provided. + +The server listens on a socket, which can be specified in the +`pipewire-ic-ipc.conf` file as an argument to the module. When launched via +systemd socket activation, the socket is passed on from systemd. + +The path of the socket is determined by the same rules as the ones that PipeWire +uses for its socket. First, the `PIPEWIRE_RUNTIME_DIR` environment variable +is used. Then, `XDG_RUNTIME_DIR`, followed by `HOME`. + +This server can accept two requests from its clients: + + * `SUSPEND`: This sets the `suspend.playback` metadata key on pipewire's + main metadata object, which is then used by the session manager to suspend + playback. + * `RESUME`: This unsets the `suspend.playback` metadata key, reverting the + actions of `SUSPEND` + +When multiple clients send `SUSPEND`, the server keeps track of how many clients +have done this and expects an equal amount of `RESUME` requests before unsetting +the `suspend.playback` metadata key. + +When a client sends `SUSPEND` and then disconnects without sending `RESUME`, +the server considers the disconnection event to be equivalent to a `RESUME` +request. Therefore, clients do not explicitly need to send `RESUME` before +disconnecting. + +## icipc-client + +This is an example client, which is provided for testing & demo purposes. +When launched, it presents a command prompt that accepts 2 commands: + + * `quit` - exits the client + * `send <request_name>` - sends `<request_name>` to the server + +To demo it with `libpipewire-module-protocol-ic-ipc` being the server, use: + + * `send SUSPEND` - suspend playback on the host + * `send RESUME` - resume playback on the host + +## Compilation & Running + +To compile: +``` +$ meson build +$ ninja -C build +``` + +To run tests: +``` +$ ninja -C build test +... or ... +$ meson test -C build +``` + +To perform static code analysis using clang-tidy: +``` +$ ninja -C build clang-tidy +``` + +### Depedencies + + * `libsystemd` is needed when building the library for the server-side + (host-side) in order to integrate with systemd's socket-activation mechanism + +No other dependencies are required. The code builds on top of the standard +C library only. |