diff options
Diffstat (limited to 'docs/high-level-api')
| -rw-r--r-- | docs/high-level-api/README.md | 80 | ||||
| -rw-r--r-- | docs/high-level-api/SUMMARY.md | 10 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/4aTools.md | 198 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/AdjustVolumes.md | 9 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/Devices.md | 32 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/HALs.md | 46 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/SUMMARY.md | 9 | ||||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png | bin | 0 -> 170421 bytes | |||
| -rw-r--r-- | docs/high-level-api/TipsAndTricks/images/changeSound.png | bin | 0 -> 123509 bytes | |||
| -rw-r--r-- | docs/high-level-api/book.json | 11 | ||||
| -rw-r--r-- | docs/high-level-api/kickstart.md | 22 | ||||
| -rw-r--r-- | docs/high-level-api/reference.md | 95 |
12 files changed, 512 insertions, 0 deletions
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 <loic.collignon@iot.bzh>", + "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..1edddb3 --- /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 <file> [<device> [<role>]] +``` + +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. + + + +Then drag the cursor to change the sound volume of the corresponding role. + + 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 Binary files differnew file mode 100644 index 0000000..e2e6fe6 --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png diff --git a/docs/high-level-api/TipsAndTricks/images/changeSound.png b/docs/high-level-api/TipsAndTricks/images/changeSound.png Binary files differnew file mode 100644 index 0000000..504f8ce --- /dev/null +++ b/docs/high-level-api/TipsAndTricks/images/changeSound.png 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 |
