# **Sound Manager Application Guide**
Revision: 0.3alpha
TOYOTA MOTOR CORPORATION
Advanced Driver Information Technology
11th/Dec/2017
* * *
## Table of content
- [Target reader of this document](#Target\ reader\ of\ this\ document)
- [Overview](#Overview)
- [Getting Start](#Getting\ Start)
- [Supported environment](#Supported\ environment)
- [Build](#Build)
- [Configuring](#Configuring)
- [Additional work](#Additional\ work)
- [How to call Sound Manager's APIs from your Application?](#How\ to\ call\ Sound\ Manager\ APIs\ from\ your\ Application?)
- [Supported usecase](#Supported\ usecase)
- [Software Architecture](#Software\ Architecture)
- [API reference](#API\ reference)
- [APIs](#APIs)
- [Events](#Events)
- [Sequence](#Sequence)
- [StartUp](#StartUp)
- [Registration](#Registration)
- [Request Sound Right](#Request\ Sound\ Right)
- [Connect Sound Route](#Connect\ Sound\ Route)
- [Start Sound Streaming](#Start\ Sound\ Streaming)
- [Stop Sound Streaming](#Stop\ Sound\ Streaming)
- [Disconnect Sound Route](#Disconnect\ Sound\ Route)
- [Change Volume](#Change\ Volume)
- [Set Mute State](#Set\ Mute\ State)
- [Release Sound Right](#Release\ Sound\ Right)
- [Audio Domain](#Audio\ Domain)
- [Sample code](#Sample\ code)
- [Limitation](#Limitation)
* * *
## Target reader of this document
Application developer whose software uses sound output.
* * *
## Overview
The sound manager is the service which provides **sound-right management** for multiple sound sources.
This service is based on GENIVI Audio Manager, and this package contains service binding and library for API calling.
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.
In order to understand, the below figure shows the one of typical usecases.
In this example, there are four sound mode.
1. Audio Off
1. Media Player
1. Tel (Ring and talking)
1. TTS (Text To Speech; typically it's used by Navigation sound)
The important points are:
- **There is a priority for each sound source.**
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.)
"Tel" and "TTS" have the same priority. So if TTS event happened on talking, each sound will output from independent speaker.
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.
- **Sound mode transition should be done by Sound Manager not Applications.**
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.
The below links show the example of Sound/Window mode transition.
- [Single window application](Display_Audio_Transition1.html)
This transition assumes target IVI system support only one window on screen. It's a similar transition to CES2017 demo.
- [Dual window application](Display_Audio_Transition2.html)
This transition assumes target IVI system support two window (split screen) on screen.
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".
* * *
## Getting Start
### Supported environment
| Item | Description |
|:------------|:----------------------------------|
| AGL version | Electric Eel |
| Hardware | Renesas R-Car Starter Kit Pro(M3) |
### Build
You can make Sound Manager object files by the following two stage operations.
**Download recipe**
If repo is already done, please start with git clone
```bash
mkdir WORK
cd WORK
repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
repo sync
```
**Bitbake**
```bash
source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
bitbake agl-demo-platform
```
* * *
### Configuring
To use Sound Manager API, an application shall paste the following configuration definition into "config.xml" of application.
```xml
```
* * *
### Additional work
#### **Add Policy file**
To add Sound Manager Domain into policy, put the following file to /etc/audiomanager/control on the target rootfs.
`${SOUNDMANAGER_DIR}/conf/audiomanager-config-sample/configuration.xml`
This is a sample conf