3 title: Sound Manager Developper Guide
5 https://git.automotivelinux.org/apps/agl-service-soundmanager/plain/doc/ApplicationGuide.md?h=master
8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/agl-service-soundmanager-developer-guides-api-services-book.yml -->
10 # **Sound Manager Application Guide**
12 <div align="right">Revision: 0.3alpha</div>
13 <div align="right">TOYOTA MOTOR CORPORATION</div>
14 <div align="right">Advanced Driver Information Technology</div>
15 <div align="right">11th/Dec/2017</div>
19 <div id="Table\ of\ content"></div>
23 - [Target reader of this document](#Target\ reader\ of\ this\ document)
24 - [Overview](#Overview)
25 - [Getting Start](#Getting\ Start)
26 - [Supported environment](#Supported\ environment)
28 - [Configuring](#Configuring)
29 - [Additional work](#Additional\ work)
30 - [How to call Sound Manager's APIs from your Application?](#How\ to\ call\ Sound\ Manager\ APIs\ from\ your\ Application?)
31 - [Supported usecase](#Supported\ usecase)
32 - [Software Architecture](#Software\ Architecture)
33 - [API reference](#API\ reference)
36 - [Sequence](#Sequence)
38 - [Registration](#Registration)
39 - [Request Sound Right](#Request\ Sound\ Right)
40 - [Connect Sound Route](#Connect\ Sound\ Route)
41 - [Start Sound Streaming](#Start\ Sound\ Streaming)
42 - [Stop Sound Streaming](#Stop\ Sound\ Streaming)
43 - [Disconnect Sound Route](#Disconnect\ Sound\ Route)
44 - [Change Volume](#Change\ Volume)
45 - [Set Mute State](#Set\ Mute\ State)
46 - [Release Sound Right](#Release\ Sound\ Right)
47 - [Audio Domain](#Audio\ Domain)
48 - [Sample code](#Sample\ code)
49 - [Limitation](#Limitation)
53 <div id="Target\ reader\ of\ this\ document"></div>
55 ## Target reader of this document
57 Application developer whose software uses sound output.
61 <div id="Overview"></div>
65 The sound manager is the service which provides **sound-right management** for multiple sound sources.
66 This service is based on GENIVI Audio Manager, and this package contains service binding and library for API calling.
67 The reason why this service is based on GENIVI Audio Manager is because GENIVI Audio Manager supports highly strong and flexible sound-right management function.
69 In order to understand, the below figure shows the one of typical usecases.
70 In this example, there are four sound mode.
74 1. Tel (Ring and talking)
75 1. TTS (Text To Speech; typically it's used by Navigation sound)
77 ![Figure: Typical usecase](parts/typical-usecase.png)
79 The important points are:
81 - **There is a priority for each sound source.**
82 In this example, the priority of "Tel" and "TTS" is higher than "MediaPlayer". Therefore when the system got incoming call, all four outputs of MediaPlayer are muted automatically by Sound Manager. And in this timing, Sound Manager will issue the event to Media Player, then Media Player can stop the music. (Because depending on OEM's requirement, "Stop" is required.)
83 "Tel" and "TTS" have the same priority. So if TTS event happened on talking, each sound will output from independent speaker.
84 If on-hook button is touched, Sound Manager will resume previous sound mode. In this example, basically it's MediaPlayer sound. But if TTS still playing, three speaker will output MediaPlayer sound but one speaker will continue to output TTS sound.
85 - **Sound mode transition should be done by Sound Manager not Applications.**
86 Actually application cannot recognize all sound source and its priority, so some centerized manager is required. Sound Manager provides this function. Sound Manager has a database for usecase and priority and in line with this policy Sound Manager controls proper sound mode.
88 The below links show the example of Sound/Window mode transition.
90 - [Single window application](Display_Audio_Transition1.html)
91 This transition assumes target IVI system support only one window on screen. It's a similar transition to CES2017 demo.
92 - [Dual window application](Display_Audio_Transition2.html)
93 This transition assumes target IVI system support two window (split screen) on screen.
95 Of course user can customize shortcut menu, but since it's too many states so this example limits shortcut menu as "Home", "MediaPlayer", "HVAC" and "Navigation".
99 <div id="Getting\ Start"></div>
103 <div id="Supported\ environment"></div>
105 ### Supported environment
107 | Item | Description |
108 |:------------|:----------------------------------|
109 | AGL version | Electric Eel |
110 | Hardware | Renesas R-Car Starter Kit Pro(M3) |
112 <div id="Build"></div>
116 You can make Sound Manager object files by the following two stage operations.
120 If repo is already done, please start with git clone
125 repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
132 source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
133 bitbake agl-demo-platform
138 <div id="Configuring"></div>
142 To use Sound Manager API, an application shall paste the following configuration definition into "config.xml" of application.
145 <feature name="urn:AGL:widget:required-api">
146 <param name="soundmanager" value="ws" />
152 <div id="Additional\ work"></div>
156 #### **Add Policy file**
158 To add Sound Manager Domain into policy, put the following file to /etc/audiomanager/control on the target rootfs.
160 `${SOUNDMANAGER_DIR}/conf/audiomanager-config-sample/configuration.xml`
162 This is a sample configuration.
164 #### **Remove Module router of Pulse Audio**
166 Because the module rounter accesses Audio manager for getting sound right instead of application in CES2017, after you changed your application code for Sound manager, you shall modify the configuration for puluse audio not to load module router.
167 To do this, you shall comment out line.143 of /etc/pulse/default.pa on the target rootfs as below.
170 .ifexists module-router.so
171 #load-module module-router
177 <div id="How\ to\ call\ Sound\ Manager\ APIs\ from\ your\ Application?"></div>
179 ### How to call Sound Manager APIs from your Application?
181 Sound Manager provides a library which is called "libsoundmanager".
182 This library provides function style API calling interface. So you can include libsoundmanager.hpp headerfile, and can link this library.
183 Please also refer sample application and template.
185 See also our [Sample code](#Sample\ code).
189 <div id="Supported\ usecase"></div>
193 1. Active source change
194 - When user choose different audio source with current one, IVI system stop or pause current source and activate new one.
195 - When user connect external device e.g. iPhone, USB memory IVI system change active source automatically to connected one.
196 2. Active source locking
197 - When user is in phone call, IVI restrict to change active source.
198 3. Interrupt source mixing
199 - When car close to cross road IVI system reduce the volume of current source and mix with interrupt source e.g. Navigation Guidance.
201 - User can change the volume of active source or sink.
202 - When user change volume during interruption e.g. Navigation Guidance, IVI system change its volume temporary or permanently.
204 - User can mute/unmute current active source.
206 - When user change active source, IVI system mute/unmute to avoid distortion of sound.
207 7. Volume acceleration
208 - When road noise is increased by speed, IVI system automatically change the volume of active source.
210 - System needs to route sound stream to proper zones. (driver zone, passenger zone, rear seat zone)
212 [See also this page](https://wiki.automotivelinux.org/eg-ui-graphics-req-audiorouting)
216 <div id="Software\ Architecture"></div>
218 ## Software Architecture
220 The architecture of Sound Manager is shown below.
221 Sound Manager is the service designed to be used by multiple applications.
222 Therefore Sound Manager framework consists of two binder layers. Please refer the following figure.
223 The upper binder is for application side security context. The lower binder is for server side security context.
224 Usually an application side binder has some business logic for each application, so the number of binders depend on the number of applications which use Sound Manager.
225 On the other hand, regarding lower binder there is only one module in the system. This binder receives messages from multiple applications (in detail, it comes from upper layer binder).
227 The communication protocols between libsoundmanager and upper binder, upper binder and lower binder, are WebSocket. The protocols between lower binder (soundmanager-binding) and AudioManager is D-Bus.
229 ![software-stack.png](parts/software-stack.png)
233 <div id="API\ reference"></div>
237 "libsoundmanager" and "soundmanager_binding" provides several kinds of APIs, and these APIs basically correspond to GENIVI Audio Manager API. (Some APIs are Sound Manager original functions.)
239 For understanding, GENIVI Audio Manager stands for one core module and three plug-ins.
241 1. AudioManagerDaemon
242 This is a core module of Audio Manager.
243 2. AudioManagerCommandPlugin
244 This is a command interface for Audio Manager.
245 3. AudioManagerController
246 This plug-in can be used for sound-right management.
247 4. AudioManagerRountingPlugin
248 This plug-in abstracts the hardware and software. And sometimes there may be multiple plug-ins.
250 *) [See also GENIVI AudioManager Components](http://docs.projects.genivi.org/AudioManager/audiomanagercomponentspage.html)
252 ![See also GENIVI AudioManager Components](parts/am-component.png)
253 (This figure was copied from GENIVI Web page.)
255 <div id="APIs"></div>
259 - init(int port, const std::string& token)
260 - registerSource(const std::string& sourceName)
261 - connect(int sourceID, int sinkID)
262 - connect(int sourceID, const std::string& sinkName)
263 - disconnect(int connectionID)
264 - ackSetSourceState(int handle, int err)
265 - registerCallback( void (*event_cb)(const std::string& event, struct json_object* event_contents), void (*reply_cb)(struct json_object* reply_contents), void (*hangup_cb)(void) = nullptr)
267 Regarding more detail, please refer doxygen documents.
269 <div id="Events"></div>
273 "libsoundmanager" provides the feature which receives the events which an app subscribes with "subscribe" API.
274 An application can get events to register a callback function with "registerCallback" API.
276 And this event is subscribed automatically. (See below Note)
278 - asyncSetSourceState
280 The below events are available but not mandatory.
283 - removedMainConnection
284 - mainConnectionStateChanged
286 - sinkMuteStateChanged
293 "asyncSetSourceState" is always subscribed in init phase because this is the most important event for audio policy management. This event indicates the approval/disapproval/pause.
295 Regarding more detail, please refer doxygen documents.
299 <div id="Sequence"></div>
302 <div id="StartUp"></div>
306 ![seq_startup.png](parts/seq_startup.svg)
308 <div id="Registration"></div>
312 ![seq_registration.png](parts/seq_registration.svg)
314 <div id="Request\ Sound\ Right"></div>
316 ### Request Sound Right
318 ![seq_requestsoundmode.png](parts/seq_requestsoundmode.svg)
320 <div id="Connect\ Sound\ Route"></div>
322 ### Connect Sound Route
323 ![seq_connectsoundroute.png](parts/seq_connectsoundroute.svg)
325 <div id="Start\ Sound\ Streaming"></div>
327 ### Start Sound Streaming
329 ![seq_startsoundstreaming.png](parts/seq_startsoundstreaming.svg)
331 <div id="Stop\ Sound\ Streaming"></div>
333 ### Stop Sound Streaming
335 ![seq_stopsoundstreaming.png](parts/seq_stopsoundstreaming.svg)
337 <div id="Disconnect\ Sound\ Route"></div>
339 ### Disconnect Sound Route
341 ![seq_disconnectsoundroute.png](parts/seq_disconnectsoundroute.svg)
343 <div id="Change\ Volume"></div>
347 ![seq_changevolume.png](parts/seq_changevolume.svg)
349 <div id="Set\ Mute\ State"></div>
353 ![seq_setmutestate.png](parts/seq_setmutestate.svg)
355 <div id="Release\ Sound\ Right"></div>
357 ### Release Sound Right
359 ![seq_releasesoundmode.png](parts/seq_releasesoundmode.svg)
363 <div id="Audio\ Domain"></div>
367 One of the most important concept of Audio Manager is Audio Domain.
368 To use GENIVI Audio Manager based system, it may be better to understand this concept.
369 The below document should bring good understanding.
371 [GENIVI Audio Manager: Generic Controller Plug-in](http://events.linuxfoundation.org/sites/events/files/slides/AGL_AMM_presentation_A01.pdf)
373 Although strongly recommended to read whole pages, but you can get quick understanding by page.10 to 14.
375 <div id="Sample\ code"></div>
379 You can find samples using Sound Manager as below.
381 - `apps/agl-service-homescreen-2017/sample/template`
382 - `apps/radio (branch=sandbox/knimitz/hmi-framework)`
384 <div id="Limitation"></div>
388 - Sound of application is not automatically muted for now because Audio Manager doesn't stop with current plugins. Just notify stop/pause/play.