From 2610bf62ef76f4120a5f76dd0e5eb1e51538b41b Mon Sep 17 00:00:00 2001 From: Loïc Collignon Date: Thu, 29 Nov 2018 15:29:54 +0100 Subject: Backport of audio documentation from master MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documentation was available only on master. New documentation website is now by branch, so documentation should be available on both branches. Bug: SPEC-1993 Change-Id: I55484d5c1f28ae1e7fa927533b3dd862a03ed207 Signed-off-by: Loïc Collignon --- docs/4a-framework/README.md | 46 ++ 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 | 681 +++++++++++++++++++++ docs/4a-framework/images/agl-audio-arch.png | Bin 0 -> 109234 bytes docs/4a-framework/images/agl-audio-arch.xml | 1 + 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 +++ 21 files changed, 1461 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/agl-audio-arch.png create mode 100644 docs/4a-framework/images/agl-audio-arch.xml 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..c9a7d8f --- /dev/null +++ b/docs/4a-framework/README.md @@ -0,0 +1,46 @@ +# 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/agl-audio-arch.png) + +This detailed diagram shows the interactions between all components. + +![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..05f88f5 --- /dev/null +++ b/docs/4a-framework/images/4a-architecture.svg @@ -0,0 +1,681 @@ + +image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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/agl-audio-arch.png b/docs/4a-framework/images/agl-audio-arch.png new file mode 100644 index 0000000..cda6a2f Binary files /dev/null and b/docs/4a-framework/images/agl-audio-arch.png differ diff --git a/docs/4a-framework/images/agl-audio-arch.xml b/docs/4a-framework/images/agl-audio-arch.xml new file mode 100644 index 0000000..81a983b --- /dev/null +++ b/docs/4a-framework/images/agl-audio-arch.xml @@ -0,0 +1 @@ +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x6zlsvyFZw/cdzkA5tFIGGok2P1UXa/saO0Taq7dTVJ2fD8bNPGzrZeCPo77hdRbmlQFCsPsA+x6XnfLaJxvvOc4Ehe3WGI9MiwPxtInJNN0mcFT7M0Hjyr5M7MJzAkkRB5N+rLa7OKnxYkSc3T/x9fLcvtOJfDWeC+77pFBN+5LT1d+LlaSAs5gkqqFCtUbRAMppPIGSApj/CorLOaXIpE3Zzm5XwcN2CoXURKaoErAUKKCJKEVWU1AoynGYUj2BaOytbfAnFetz1g14do9GnV6uNagL/C6g1NE7oX+c0wlblPKubBawURxulBCFMJ0scFLw35fRWyH1z1WlLFdHDEE+bcu5R3Gr5E86jhABM04kyPVJb2K0WwBk0xE6CpMlwg+ZbfRAo9umUY3cIo8bDeDcHUe3S54VE8mPnk8/HG26faKSPBJ5AeJ9PplkXrJ75PIZg8wQL8sssGBiE8ia4n0+2WR+rbjk8hmtRKrXxbZTVnaHAyt8s4dDI2TPFNscn7C7s9+3vE64sP3KnyA0/DR5BFvkbj1gQ+/TT66hbb103j1x0uqR7ncoOKYcm7VqAr2//OoiRN0ZB49sY4m3qrYn/bBOro6kuI5ZT7ME0WPRt7K6g0fbqsPPy7CW9nO6bxVXf1Be1nzQZVuL+RdTVAcet+8RnvKF9xqnpee4wktq4Ebaj1nqren6isrfoW2fB2aOelZRKXoq03Unl1qWtFVjh34w129AAPTtk8Ttxod0ulEYQ5+OTIo+wvt5wcO63/o6WZDPi4tfjoh7779sQf75j8=dVDLDsIgEPwa7gUSH2eseunJg+e1IBCh2yDGfr40tEESPWwyOzszmSzhwk+nAKPpUCpHWPM0IPFN+IEw1qRJ1B2dzATNhIdoKsUIWl16cKqS3aB/6ICvYXEX7dXKNWHHtoU/K6tNXELoZj9feEu4CIgxIz8J5eaiVn5XOP650jU8qCH+MCRQstNSfYO3Hw==dVDLDsIgEPwa7gUSH2eseunJg+e1IBCh2yDGfr40tEESPWwyOzszmSzhwk+nAKPpUCpHWPM0IPFN+IEw1qRJ1B2dzATNhIdoKsUIWl16cKqS3aB/6ICvYXEX7dXKNWHHtoU/K6tNXELoZj9feEu4CIgxIz8J5eaiVn5XOP650jU8qCH+MCRQstNSfYO3Hw==dVDLDsIgEPwa7gUSH2eseunJg+e1IBCh2yDGfr40tEESPWwyOzszmSzhwk+nAKPpUCpHWPM0IPFN+IEw1qRJ1B2dzATNhIdoKsUIWl16cKqS3aB/6ICvYXEX7dXKNWHHtoU/K6tNXELoZj9feEu4CIgxIz8J5eaiVn5XOP650jU8qCH+MCRQstNSfYO3Hw==7ZzZcqM4FIafxpedYpXhMs7SfTFL12RqlksZFJuOjFyynMTz9CNALJawTdIWkFipShVoh/Ppl3QkM3FvVq9fKVwvfyUxwhPH2ixhTF4m7u3EcSz+z4MeCY6LALsIWEG23Euxhgv0EEGM9pLNYfS0oGSbitx12r+TuCzBtq1GId9QsliyIibw8wj3buLeUEJYcbV6vUE4a2gSN5twfyDWLsumKGVdMkzjxwh403hqQRCDIPwiSniGeCseb+Je/z7/gSJWxGzYrnxw/vLW2eV2hX9JHhFOUn43WyOarBBDlMdgEfy9Dpu9LBOGHtYwyrK+cGPwsCVbYX5n88uIpAzyLLS6xxiuN8k8r9XiIRRFW7pJntEfaJP8V4aSLctquiFpmrVVJM3MgWJRVGVsKy93lUTiGsM5wrPKfjcEk6z6lOQPtGGUPKEycOK4Vv5XxZTmzap4TDBupLzP/7Jw/lT3cJXgHY/4C9EYplAEPxTPYDvivq0iiJNFysMibtb8Jap2Lg2HKEOvjSBh96+IcAPQHU8iYh1PkLgTAIrblwatJazLBqh+mRBuioBFVXQNGr8QrHXkzlG5k3FrQLImScry6v3ZxL+VqCOULcmCpBA3uatZsD47Cwd7dWc4PH+PjQqEPThUNngzNbDhGk36mBy+HTtrTJrkGU3SqEnum+GQNMnpqEmWDjZ8o0kfk8M3a5I/qnkSMNxdCHcgGBN3U8PdhXAXOGPiLjDcXQh3IRgTd6Hh7kK4s0e15ixXMGbRqWXRGb6Vjnc6wjxPCxwt3nkDR38rwWAfBqejB8LWoxSqyzxONmvIouUxKLLHTSKIr8ULmhPGyIpHoDS+pjS39hyT6OmklTtaCMUL9CCagvCcvNzVAbM8gEeUrTpmqA3Z0ggdeBvCV8cgXaCDXnBRUNaio/amCEPGB9a96tuMJ7J+zzpagxPbauekLKJ4EpGrRoC/frhrJBP992A9HmivpyaqKLHmq3rGdyLX4ok3+tOb/kwdSX/cjoORFvlRvePnlh/+pujuH2Hx/ObfTuYflTCVonNcmdx+lAn4VjtBJ5TpLOKhuswpYlua/iwuZI141CyGm2W1xOHRwtTBB8PFHdFAJuPiWmC/iKKVPz2QgamEJZBOrUjpp9bR9BoGvha3uxn4Bpt4V6urUxNvPSOf6gv/YCPfO6XJ6iJNYJg5ttdxjn0WNWhxShs16NNhJ8kB6CYHWg4n2aqn+DLUAHRRg6AfNQhdaaIiC79GNXBUj21f81r0mrCKC36dY3EV+gOTEYxonJDJ8OxuU9izkGHctYNuZEurCt/vNkwAHcNEafqPO0z0s/51wg7i4fS0/g2sAwT1MayovlbjLjlIwvGxxhoGF+DocZf4krABS7P7wzG+3vOtkJ1+YHSkY1x22KN2qa5ew8thFI7i4vWDiyu7YOVT8zpxMd7VQb2robR47njGZaplnqzfuXoegVA1oKkZNYVN4Yi29Lkx5xIKZu8p2JUTgDKgQXC1xs9zXFluuf4vMrmeL+7lPO8cybrMq5ye1vAeOLDvfUKb1IlTeKKgc+1nydusgXO0Xco+m+6DHI7qwf6svazuMgDsdZmp7Z61y/TVG4DNu3vzbx+djkvUk33DDcJe+kbZ4M59Q7RLX99oOfptZiODzUb8jocstWz1luPDBejkwLMR7fvFkrz5llREV50Esk/Q7UcnywZ31cmyXdp00lV3N34jDCn9ovx1TJpFnvzZi/gli+21dCNG1g3RweiRZRl4UUm6+DOLu/0CPpG6nkFM5d+2tB4Ybdsp93WIqboFYoAZGTDyR4GGBUbdAjHAjAwY+YstwwKj7lMYYEYGjPw5jWGBUTcqDDAjA0b+DsawwKhbFQaYkQEjf8BiWGDU/QwDzMiAkb88oREYflt/3LVYhdefo3Xv/gc= \ 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..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 [ []] +``` + +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