audiomixer: README.md: add API documentation

Bug-AGL: SPEC-2473

Signed-off-by: George Kiagiadakis <george.kiagiadakis@collabora.com>
Change-Id: Ic9fbbf6cc1f91f8699a3ba897b3984d8e4ddf244

diff --git a/README.md b/README.md
index 102189c..54b1a0d 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,5 +1,68 @@
 # Audio Mixer Service
 
-Audio mixer binding service for AGL.
+## Overview
 
-This binding exposes PipeWire mixer controls to applications.
+The Audio Mixer service exposes PipeWire mixer controls to applications.
+
+Each of the controls has a *volume* and a *mute* value. *volume* is a floating
+point number between 0.0 and 1.0, while *mute* is an integer that can be
+either 0 or 1.
+
+To receive the list of controls, call the *list_controls* verb. The reply will
+also include the current values for both *volume* and *mute* for each control.
+When the list of controls changes, the *controls_changed* event is emited. The
+receiver is then expected to invalidate its cached state of all the controls
+and call *list_controls* again.
+
+## Verbs
+
+| Name               | Description                             | JSON Parameters                                     |
+| ------------------ |:----------------------------------------|:----------------------------------------------------|
+| subscribe          | subscribe to mixer events               | *Request:* {"event": "volume_changed"}              |
+| unsubscribe        | unsubscribe from mixer events           | *Request:* {"event": "mute_changed"}                |
+| list_controls      | list the available controls             | See the *List controls* section                     |
+| volume             | get/set volume                          | See the *Get/Set Volume/Mute* section               |
+| mute               | get/set mute                            | See the *Get/Set Volume/Mute* section               |
+
+### List controls
+
+* Request: empty
+* Reply: Array of objects of the form **{"control": "Emergency", "volume": "1.0", mute: "0"}**
+
+### Get/Set Volume/Mute
+
+Getting a volume or a mute value can be achieved by calling the appropriate verb
+with a parameter that specifies only the control name: **{"control": "Master"}**
+
+Setting a volume or a mute value can be achived by calling the appropriate verb
+with a parameter that specifies both the control name and the value that you want
+to be set:
+* On the *volume* verb: **{"control": "Multimedia", "value": "0.8"}**
+* On the *mute* verb: **{"control": "Multimedia", "value": "1"}**
+
+In both cases, the reply will include the current value:
+* On the *volume* verb: **{"volume": "0.8"}**
+* On the *mute* verb: **{"mute": "1"}**
+
+## Events
+
+| Name               | Description                             | JSON Payload                                        |
+| ------------------ |:----------------------------------------|-----------------------------------------------------|
+| controls_changed   | the list of available controls changed  | None. Call *list_controls* to get the new controls  |
+| volume_changed     | volume has changed for a control        | {"control": "Multimedia", "volume": "0.65"}         |
+| mute_changed       | mute has changed for a control          | {"control": "Multimedia", "mute": "1"}              |
+
+## Environment variables
+
+| Name               | Description                                       |
+|--------------------|:--------------------------------------------------|
+| XDG_RUNTIME_DIR    | the location of the pipewire socket to connect to |
+
+## Notes regarding the connection to PipeWire
+
+This binding is engineered in such a way so that when PipeWire exits, the
+binding attempts to re-connect to it, possibly restarting PipeWire due to
+socket activation. This re-connection attempt, however, is only done when a
+verb is called. Therefore, if PipeWire for some reason exits and there is no
+call to any verb on this binding afterwards, the binding will not emit
+any events until this happens.