diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 67 |
1 files changed, 65 insertions, 2 deletions
@@ -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. |