From 75e26b091f6aae38c9edb069c173bcb04ae3ffd1 Mon Sep 17 00:00:00 2001 From: Loïc Collignon Date: Mon, 10 Sep 2018 10:36:46 +0200 Subject: Updated documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated documentation up to date and using the gitbook format. Change-Id: Ie5d6a3bb489b9a9a95e21f5edd05bdd77bff5816 Signed-off-by: Loïc Collignon --- docs/4a-framework/README.md | 42 +++++ docs/4a-framework/SUMMARY.md | 5 + docs/4a-framework/book.json | 11 ++ docs/4a-framework/components.md | 49 +++++ docs/4a-framework/concepts.md | 37 ++++ docs/4a-framework/images/4a-architecture.svg | 155 ++++++++++++++++ docs/4a-framework/images/apps-architecture.svg | 119 +++++++++++++ docs/high-level-api/README.md | 80 +++++++++ docs/high-level-api/SUMMARY.md | 10 ++ docs/high-level-api/TipsAndTricks/4aTools.md | 198 +++++++++++++++++++++ docs/high-level-api/TipsAndTricks/AdjustVolumes.md | 9 + docs/high-level-api/TipsAndTricks/Devices.md | 32 ++++ docs/high-level-api/TipsAndTricks/HALs.md | 46 +++++ docs/high-level-api/TipsAndTricks/SUMMARY.md | 9 + .../TipsAndTricks/images/MixerBaseMenu.png | Bin 0 -> 170421 bytes .../TipsAndTricks/images/changeSound.png | Bin 0 -> 123509 bytes docs/high-level-api/book.json | 11 ++ docs/high-level-api/kickstart.md | 22 +++ docs/high-level-api/reference.md | 95 ++++++++++ 19 files changed, 930 insertions(+) create mode 100644 docs/4a-framework/README.md create mode 100644 docs/4a-framework/SUMMARY.md create mode 100644 docs/4a-framework/book.json create mode 100644 docs/4a-framework/components.md create mode 100644 docs/4a-framework/concepts.md create mode 100644 docs/4a-framework/images/4a-architecture.svg create mode 100644 docs/4a-framework/images/apps-architecture.svg create mode 100644 docs/high-level-api/README.md create mode 100644 docs/high-level-api/SUMMARY.md create mode 100644 docs/high-level-api/TipsAndTricks/4aTools.md create mode 100644 docs/high-level-api/TipsAndTricks/AdjustVolumes.md create mode 100644 docs/high-level-api/TipsAndTricks/Devices.md create mode 100644 docs/high-level-api/TipsAndTricks/HALs.md create mode 100644 docs/high-level-api/TipsAndTricks/SUMMARY.md create mode 100644 docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png create mode 100644 docs/high-level-api/TipsAndTricks/images/changeSound.png create mode 100644 docs/high-level-api/book.json create mode 100644 docs/high-level-api/kickstart.md create mode 100644 docs/high-level-api/reference.md (limited to 'docs') diff --git a/docs/4a-framework/README.md b/docs/4a-framework/README.md new file mode 100644 index 0000000..90de65b --- /dev/null +++ b/docs/4a-framework/README.md @@ -0,0 +1,42 @@ +# AGL Advanced Audio Architecture (4a) + +## Abstract + +4a is an audio framework made to handle automotive use cases like stream +priority and interruptions. It does **not** deal with the audio by itself but +rather with the policies and signaling around it. This means that 4a must be +used in conjunction with an other API that is in charge of the audio stuff, +like **alsa** or **pulseaudio**. + +## Architecture + +### Global architecture + +![applications architecture diagram](images/apps-architecture.svg) + +This diagram shows the global architecture that any application playing audio +should follow. As a developer, when you want to play audio, you rely on APIs +such as alsa, pulseaudio or higher level API(s). To play audio you usually have +some kind of device URI that you have to open in order to write audio data to +it. + +4a does **not** change anything about that. You still have to do all of this. 4a +provides permissions, signals and policies. This means that all compliant +applications have to ask 4a for a 'role' when they want to play audio. If 4a +grants them the permission, it returns a device URI that applications have to +open. + +Nothing prevent an application to directly open a device, but in this case no +policies can be applied and access permissions are handled by system policies. + +### 4a Architecture + +![4a's architecture diagram](images/4a-architecture.svg) + +Even if applications only deal with the high level API, 4a is made of multiple +components that rely on each other. + +The high level API uses the hal-manager to list enabled HALs then it uses +directly those HALs. + +HALs rely directly on drivers and/or softmixer. diff --git a/docs/4a-framework/SUMMARY.md b/docs/4a-framework/SUMMARY.md new file mode 100644 index 0000000..413454c --- /dev/null +++ b/docs/4a-framework/SUMMARY.md @@ -0,0 +1,5 @@ +# Summary + +* [Architecture](README.md) +* [Concepts](concepts.md) +* [Components](components.md) \ No newline at end of file diff --git a/docs/4a-framework/book.json b/docs/4a-framework/book.json new file mode 100644 index 0000000..43eb2f0 --- /dev/null +++ b/docs/4a-framework/book.json @@ -0,0 +1,11 @@ +{ + "title": "AGL Advanced Audio Architecture (4A)", + "subtitle": "4A Framework", + "description": "This is the 4A framework documentation", + "keywords": "Audio, 4a, AGL, Development, Iotbzh", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "September 2018", + "version": "1.0", + "pdf_filename": "AGL_4A_Framework" +} \ No newline at end of file diff --git a/docs/4a-framework/components.md b/docs/4a-framework/components.md new file mode 100644 index 0000000..2709d60 --- /dev/null +++ b/docs/4a-framework/components.md @@ -0,0 +1,49 @@ +# Components + +4a framework is made of several components which provide features to each other. +The High Level API component is the only one that exports a public API. This +means that, as an application developer you only need to care about the High +Level API. + +## High level API + +This is the publicly exported API. It exposes one verb for each audio roles, +plus **get_roles** to get the list of audio roles. + +This component manages audio roles and applies permissions, signaling and +policies. Because each role is a unique verb, it means that each role can have +its own smack label. + +It makes use of the **4a-hal-manager** to list all HALs and their +configurations. Then it uses directly the enabled HALs. + +## 4a-hal-manager + +This component is responsible for HALs detection, initialization and state +management. + +## 4a-hal-* + +This block represents all the different HALs. You can load multiple HALs +provided that they don't interfere with each other. +HALs can be provided by two means: + +* Built directly by the **4a-hal-manager** using it's controller and json files. +* External HAL (like the unicens one), that have to register themselves to the + **4a-hal-manager**. + +HALs manage audio streams and zones. The streams are bound to audio roles. + +## 4a-softmixer + +This component abstracts the real devices to virtual ones and provides some +basic mixing capabilities for devices that don't have this feature builtin. +It exposes streams named like the audio roles. + +This component can be used by HALs, but this is not mandatory. + +HALs can either : + +* use 4a-softmixer (for example when hardware doesn't provide mixing feature), + or +* take advantage from the hardware to provide the mixing capabilities. diff --git a/docs/4a-framework/concepts.md b/docs/4a-framework/concepts.md new file mode 100644 index 0000000..dba024d --- /dev/null +++ b/docs/4a-framework/concepts.md @@ -0,0 +1,37 @@ +# Concepts + +A user application requests to open an audio role, which is bound to a stream, +which is bound to a zone. This allows the application to only care about the +audio role. + +For example, a navigation application can request the **navigation** role, which +is bound to the **navigation** stream defined by the HAL. This stream is bound +to the **driver** zone, which is the closest speaker to the driver. + +## Roles + +The high level API allows applications to open roles such as **emergency**, +**navigation** or **multimedia**. A role is bound to a stream, which is +basically a device URI. When a role is opened, then the policy engine is +notified and executes an interrupt on every other opened role with a lower +priority. An interrupt is a policy engine function that can change the volume, +mute or unmute, change the stream's state. + +This behaviour allows the policy engine to take actions like lowering the radio +volume when an application wants to play something on the emergency role. + +## Streams + +A stream is basically a device URI that you can open to write audio data. For +example, it can be "hw:2,0,1", which means that you have to use this as an alsa +device URI. + +## Zones + +Multiple speakers are spread around inside a vehicule, they are named depending +on their position, like **front-center**, **front-left**, **front-right**, +**rear-left**, **rear-right**, etc... + +Zones are an abstraction of positional audio. A zone is made of one or more +speakers and describes logical audio areas like **driver**, **front**, **rear**, +etc. diff --git a/docs/4a-framework/images/4a-architecture.svg b/docs/4a-framework/images/4a-architecture.svg new file mode 100644 index 0000000..1554e8e --- /dev/null +++ b/docs/4a-framework/images/4a-architecture.svg @@ -0,0 +1,155 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 4a-hal-* + + + 4a-hal-* + + + + + + + + HARDWARE + + + + + + + + Drivers + + + + + + + + APPLICATIONS + + + + + + + + 4a-softmixer + + + + + + + + 4a-high-level + + + + + + + + 4a-hal-manager + + + + + + + + \ No newline at end of file diff --git a/docs/4a-framework/images/apps-architecture.svg b/docs/4a-framework/images/apps-architecture.svg new file mode 100644 index 0000000..4dca8b5 --- /dev/null +++ b/docs/4a-framework/images/apps-architecture.svg @@ -0,0 +1,119 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + HARDWARE + + + + + + + + APPLICATIONS + + + + + + + + Audio lib + + + + + + + + 4a + + + + + + + + \ No newline at end of file diff --git a/docs/high-level-api/README.md b/docs/high-level-api/README.md new file mode 100644 index 0000000..0120216 --- /dev/null +++ b/docs/high-level-api/README.md @@ -0,0 +1,80 @@ +# High Level API + +The High Level API provides an abstraction of audio roles. + +## Configuration + +Here is a sample configuration. + +```json +{ + "$schema": "http://iot.bzh/download/public/schema/json/ctl-schema.json", + "metadata": { + "uid": "4a-policy", + "version": "0.1", + "api": "4a-policy", + "require": [], + "info": "Basic Audio Policy Control for Audio-4a - Sample 1", + "author": "Loïc Collignon ", + "date": "2018-05-25" + }, + "onload": [], + "controls": [], + "events": [], + "roles":[ + { + "uid": "radio", + "description": "Radio (tuner)", + "priority": 0, + "stream": "radio_stream" + }, + { + "uid": "multimedia", + "description": "Multimedia content (e.g. media player, etc.)", + "priority": 0, + "stream": "multimedia" + }, + { + "uid": "emergency", + "description": "Safety-relevant or critical alerts/alarms", + "priority": 100, + "stream": "emergency", + "interrupts":[ + { + "type": "ramp", + "args": { "uid": "ramp-slow", "volume": 30} + } + ] + }, + { + "uid": "navigation", + "name": "navigation", + "description": "Navigation instructions (GPS, directions, etc.)", + "priority": 25, + "stream": "navigation", + "interrupts":[ + { + "type": "ramp", + "args": { "uid": "ramp-slow", "volume": 30} + } + ] + } + ] +} +``` + +Each defined roles should have a stream associated. This stream will be +provided by HALs. If no HAL provides the stream, then the audio role will have +no device URI. If multiple HALs provide the same stream, a race condition +occurs, the first HAL found will be used, the next will be ignored. + +A higher value means a higher priority. In this sample, the **emergency** role +has a higher priority than the **navigation**. + +>**NOTE:** In this sample there is only one stream per role and it's named +>after the corresponding role, but none of this is mandatory. + +## Policy engine + +Policy engine is provided as a controller plugin for the high level API. +Currently, the sample policy engine only support the **ramp** interruption. diff --git a/docs/high-level-api/SUMMARY.md b/docs/high-level-api/SUMMARY.md new file mode 100644 index 0000000..ff21d0b --- /dev/null +++ b/docs/high-level-api/SUMMARY.md @@ -0,0 +1,10 @@ +# Summary + +* [Abstract](README.md) +* [Kickstart](kickstart.md) +* [Reference](reference.md) +* [Tips & Tricks](TipsAndTricks/SUMMARY.md) + * [Adjust Volumes](TipsAndTricks/AdjustVolumes.md) + * [4a-tools](TipsAndTricks/4aTools.md) + * [Devices](TipsAndTricks/Devices.md) + * [HALs](TipsAndTricks/HALs.md) diff --git a/docs/high-level-api/TipsAndTricks/4aTools.md b/docs/high-level-api/TipsAndTricks/4aTools.md new file mode 100644 index 0000000..f1bff4b --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/4aTools.md @@ -0,0 +1,198 @@ +# 4a-tools + +4a-tools is a set of simple scripts that can be used to test and troubleshoot +4a framework. + +## 4a-status + +4a-status gives a diagnostic whether 4a-framework is supposed to be working or +not. + +```bash +user@machine$ 4a-status +---- Audio cards detected ---- +card 0: Loopback +card 1: Intel + +---- snd-aloop driver availability ---- +SUCCESS: Built into the kernel + +---- 4a service status ---- +SUCCESS: Service is currently running! +``` + +If any error is shown then there is no way that 4a-framework can work. +Not running services do trigger only a warning because you may have started the +service's binding manually and the script cannot detect this. +If you don't, this must be considered as an error, because 4a-framework +obviously cannot work when bindings are not running. + +```bash +---- Audio cards detected ---- +card 0: Loopback +card 1: Intel + +---- snd-aloop driver availability ---- +SUCCESS: Built into the kernel + +---- 4a service status ---- +WARNING: Service is not currently running! +It can be started using the following command: +systemctl restart *agl-service-audio-4a*.service +``` + +## 4a-api + +This script lets you call 4a's APIs to test bindings and get some infos. + +### Ping API + +Pinging an API let you know that the binding providing this API is running and +ready. + +```bash +user@machine$ 4a-api api smixer ping +Detected systemd unit file! +Port detected: 1025 +ON-REPLY 1:smixer/ping: OK +{ + "response":3, + "jtype":"afb-reply", + "request":{ + "status":"success" + } +} +``` + +### List HALs + +You can list availables HALs using the following command: + +```bash +user@machine$ 4a-api hals +Detected systemd unit file! +Port detected: 1025 +ON-REPLY 1:4a-hal-manager/loaded: OK +{ + "response":[ + "4a-hal-intel-qemu" + ], + "jtype":"afb-reply", + "request":{ + "status":"success", + "info":"Requested data" + } +} +``` + +If the returned list is empty, this means that no HAL is loaded and ready. In +such a case you won't be able to use 4a-framework because this means that there +is no device to play audio on. + +To get more information about a HAL, you can call its **info** verb: + +```bash +user@machine$ 4a-api api 4a-hal-intel-qemu info +Detected systemd unit file! +Port detected: 1025 +ON-REPLY 1:4a-hal-intel-qemu/info: OK +{ + "response":{ + "streams":[ + { + "name":"multimedia", + "cardId":"hw:0,0,2" + }, + { + "name":"navigation", + "cardId":"hw:0,0,3" + }, + { + "name":"emergency", + "cardId":"hw:0,0,4" + } + ], + "playbacks":[ + { + "name":"playback", + "mixer-name":"INTEL-QEMU:playback" + } + ], + "captures":[ + { + "name":"capture", + "mixer-name":"INTEL-QEMU:capture" + } + ] + }, + "jtype":"afb-reply", + "request":{ + "status":"success", + "info":"Requested data" + } +} +``` + +This allows you to get which device is bound to which stream. +Please note these are stream names, not roles names. +In addition, multiples HALs can provide the same stream. +In the current implementation, it results in a race condition: 4a-framework +will be using the first HAL providing the stream. + +### List roles + +This lets you get the list of available audio roles. +Only roles with a bound device are listed here, because roles without a device +are pretty much unusable. + +```bash +user@machine$ 4a-api roles +Detected systemd unit file! +Port detected: 1025 +ON-REPLY 1:ahl-4a/get_roles: OK +{ + "response":[ + "radio", + "multimedia", + "emergency", + "navigation" + ], + "jtype":"afb-reply", + "request": { + "status":"success" + } +} +``` + +## 4a-play + +4a-play lets you play some audio file on a specified device, with an optional +audio role. + +```bash +4a-play [ []] +``` + +Where *file* is the path to the file to play, *device* is the device to play on +and and *role* is the 4a audio role to open (multimedia for example). + +The specified role should be the one that is bound to the specified device, +however the script is not able to detect it so there is no control about this. +The role is opened before playing the audio file, and closed after playing is +over. + +So for example: + +```bash +4a-play Happy_MBB_75.ogg hw:2,0,0 multimedia +``` + +>**NOTE**: For now you have to specify the device and the role. Future versions +>of this script may detect devices and roles relations so that you will be able +>to omit either role or device. +> +>The device that usually matches "multimedia" is "hw:0,0,2" (for more details +>please read the [HALs](HALs.md) section). + +>**NOTE**: Some media files (WAV, MP3 and OGG) are provided with 4a-tools for +>testing purpose and can be used as reference assets. diff --git a/docs/high-level-api/TipsAndTricks/AdjustVolumes.md b/docs/high-level-api/TipsAndTricks/AdjustVolumes.md new file mode 100644 index 0000000..2d8fca2 --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/AdjustVolumes.md @@ -0,0 +1,9 @@ +# Adjust volumes + +On the main menu, hit the "Mixer" icon. + +![Main Menu Interface](images/MixerBaseMenu.png) + +Then drag the cursor to change the sound volume of the corresponding role. + +![Mixer Interface](images/changeSound.png) diff --git a/docs/high-level-api/TipsAndTricks/Devices.md b/docs/high-level-api/TipsAndTricks/Devices.md new file mode 100644 index 0000000..9e1c0cd --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/Devices.md @@ -0,0 +1,32 @@ +# List available devices + +To list the available devices, as well as their subdevices, you can use the +**aplay** command. + +```bash +user@machine$ aplay -l +**** List of PLAYBACK Hardware Devices **** +card 0: Loopback [Loopback], device 0: Loopback PCM [Loopback PCM] + Subdevices: 8/8 + Subdevice #0: subdevice #0 + Subdevice #1: subdevice #1 + Subdevice #2: subdevice #2 + Subdevice #3: subdevice #3 + Subdevice #4: subdevice #4 + Subdevice #5: subdevice #5 + Subdevice #6: subdevice #6 + Subdevice #7: subdevice #7 +card 0: Loopback [Loopback], device 1: Loopback PCM [Loopback PCM] + Subdevices: 8/8 + Subdevice #0: subdevice #0 + Subdevice #1: subdevice #1 + Subdevice #2: subdevice #2 + Subdevice #3: subdevice #3 + Subdevice #4: subdevice #4 + Subdevice #5: subdevice #5 + Subdevice #6: subdevice #6 + Subdevice #7: subdevice #7 +card 1: Intel [HDA Intel], device 0: Generic Analog [Generic Analog] + Subdevices: 0/1 + Subdevice #0: subdevice #0 +``` diff --git a/docs/high-level-api/TipsAndTricks/HALs.md b/docs/high-level-api/TipsAndTricks/HALs.md new file mode 100644 index 0000000..4c2ead6 --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/HALs.md @@ -0,0 +1,46 @@ +# HALs + +HALs are known as json files in 4a, they are stored in +**/usr/libexec/agl/4a-hal**. + +Enabled HALs can be found in the **etc** subfolder, and disabled HALs in +**etc.available**. + +You can enable and disable HALs just by moving the corresponding json file from +one folder to the other. + +Example: + +```bash +user@machine$ ls etc etc.available/ +etc: +hal-4a-csl-cm106-8ch-usb.json + +etc.available/: +hal-4a-2ch-generic-usb.json hal-4a-intel.json +hal-4a-ensoniq.json hal-4a-jabra.json +hal-4a-intel-minnow.json hal-4a-rcar-m3.json +hal-4a-intel-qemu.json hal-4a-rcar-m3kf.json + +user@machine$ mv etc/hal-4a-csl-cm106-8ch-usb.json etc.available +user@machine$ mv etc.available/hal-4a-2ch-generic-usb.json etc + +user@machine$ ls etc etc.available/ +etc: +hal-4a-2ch-generic-usb.json + +etc.available/: +hal-4a-csl-cm106-8ch-usb.json hal-4a-intel.json +hal-4a-ensoniq.json hal-4a-jabra.json +hal-4a-intel-minnow.json hal-4a-rcar-m3.json +hal-4a-intel-qemu.json hal-4a-rcar-m3kf.json + +user@machine$ sync +user@machine$ reboot +``` + +>NOTE: Even if multiple HAL are allowed, you have to make sure that they don't +>provide the same streams, because it will cause a race condition in the high +>level API. The first HAL providing the stream is used, any other are ignored. +> +>Also, the hardware used by enabled HALs should be available. diff --git a/docs/high-level-api/TipsAndTricks/SUMMARY.md b/docs/high-level-api/TipsAndTricks/SUMMARY.md new file mode 100644 index 0000000..6ae5ff6 --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/SUMMARY.md @@ -0,0 +1,9 @@ +# Tips & Tricks + +In this section you'll find useful tips and tricks to help you in case of +trouble. + +* [Adjust Volumes](AdjustVolumes.md) +* [4a-tools](4aTools.md) +* [Devices](Devices.md) +* [HALs](HALs.md) \ No newline at end of file diff --git a/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png b/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png new file mode 100644 index 0000000..e2e6fe6 Binary files /dev/null and b/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png differ diff --git a/docs/high-level-api/TipsAndTricks/images/changeSound.png b/docs/high-level-api/TipsAndTricks/images/changeSound.png new file mode 100644 index 0000000..504f8ce Binary files /dev/null and b/docs/high-level-api/TipsAndTricks/images/changeSound.png differ diff --git a/docs/high-level-api/book.json b/docs/high-level-api/book.json new file mode 100644 index 0000000..7f8bb85 --- /dev/null +++ b/docs/high-level-api/book.json @@ -0,0 +1,11 @@ +{ + "title": "AGL Advanced Audio Architecture (4A)", + "subtitle": "High Level API", + "description": "This is the 4A High Level API documentation", + "keywords": "Audio, 4a, AGL, Development, Iotbzh", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "September 2018", + "version": "1.0", + "pdf_filename": "AGL_4A_HighLevelAPI" +} \ No newline at end of file diff --git a/docs/high-level-api/kickstart.md b/docs/high-level-api/kickstart.md new file mode 100644 index 0000000..15e1874 --- /dev/null +++ b/docs/high-level-api/kickstart.md @@ -0,0 +1,22 @@ +# Kickstart + +As an application developer, when you play audio, you have to use a device URI. +Instead of using the default one, guessing one by listing them or even +hardcoding it, you should call **ahl-4a/[role]** with **open** as action. + +The role to open should be defined in a configuration file or hardcoded. If you +hardcode it, please consider to at least define it at one known place so that it +can be easily changed. + +As opening a role may fail, you should test if it returns a success and a device +URI. Both of them should be tested because it's perfectly fine to have a role +without a device URI from 4a point of view (no device is bound to the role thus +no audio can be played in this case). + +Once you have finished to play audio, you should call **ahl-4a/[role]** with +**close** as action. This is important to allow other applications to use the +role when you are not using it. + +You may also want to handle events of the window manager to know if you +application is displayed or not, and open/close accordingly the role you are +using. diff --git a/docs/high-level-api/reference.md b/docs/high-level-api/reference.md new file mode 100644 index 0000000..ed58705 --- /dev/null +++ b/docs/high-level-api/reference.md @@ -0,0 +1,95 @@ +# Reference + +## Verbs + +### ahl-4a/get_roles + +Get the list of available audio roles. By default it returns the list of roles +that are bound to a stream. To get a list of all defined roles, regardless if +they are bound to a stream or not, you can pass the following parameter. + +```json +{ + "verbose": true +} +``` + +### ahl-4a/[role] + +Replace [role] by the role's name. For example **ahl-4a/multimedia**. + +This verb allows the control of the audio role. The action executed depends on +the parameter. + +#### Open + +```json +{ "action": "open" } +``` + +Request to open the role. + +On success it returns the device URI to open. This action fails if the role is +already opened. + +When a role is opened, it triggers the first interruption, if any, of the policy +engine. + +The policy engine executes the interruption for each opened audio role with a +lower priority. + +#### Close + +```json +{ "action": "close" } +``` + +Request to close the role. + +On success it closes the role. You can only close roles that you opened before. +An error will occur if you try to close a role that an other application has +opened. + +#### Volume + +```json +{ + "action": "volume", + "value": 80 +} +``` + +Request to get or set the volume. + +Value can be absolute or relative. Use a string as value to use relative, like +**"+10"** or **"-20"**. To get the volume you can use **"+0"** as value. + +#### Mute + +```json +{ + "action": "mute" +} +``` + +Mute the volume of this. + +#### Unmute + +```json +{ + "action": "unmute" +} +``` + +Unmute the volume of this role. + +#### Interrupt + +```json +{ + "action": "interrupt" +} +``` + +Ask the policy engine to execute an interruption. \ No newline at end of file -- cgit 1.2.3-korg