Sound Manager: Managing Sound Parameters

This tutorial demonstrates how you manage sounds.

Warm-up

Become familiar with the Sound Manager API basics by learning about:

Setting the Sound Session Type
Set a sound session type for your application.
Managing Volume Control
Control the volume of your application.
Querying Sound Devices
Query sound device information.

Follow-up

Once we have learned the basics of the Sound Manager API, we can now move on to more advanced tasks, including:

Managing Sound Manager Session Parameters
Obtain and set basic sound session parameters, such as volume and sound type of the actual sound sessions.

Setting the Sound Session Type

To set your application sound session type and monitor session changes:

To use the functions and data types of the Sound Manager API (in mobile and wearable applications), include the <sound_manager.h> header file in your application:
```
#include <sound_manager.h>
```
Set the sound session type.
Set the application sound session type using the sound_manager_set_session_type() function. The function sets the type of your sound session across the system.

The sound_session_type_e enumeration (in mobile and wearable applications) defines the available sound session types.
```
int error_code;
 
error_code = sound_manager_set_session_type(SOUND_SESSION_TYPE_MEDIA);
```

Subscribe to the session change notifications.

To be informed when a sound session change has occurred, define the sound_session_interrupted_cb() callback function:

static void sound_session_interrupted_cb(sound_session_interrupted_code_e code, void *user_data) 
{
   if (code == SOUND_SESSION_INTERRUPTED_BY_MEDIA)
      // Session has been interrupted by media application, handle accordingly
   if (code == SOUND_SESSION_INTERRUPTED_COMPLETED)
      // Interruption completed, handle accordingly
}

To register the callback function, call sound_manager_set_session_interrupted_cb() with a callback and the data which passes the user data:
```
error_code = sound_manager_set_session_interrupted_cb(_sound_session_interrupted_cb, NULL);
```

Managing Volume Control

To control your application volume:

To use the functions and data types of the Sound Manager API (in mobile and wearable applications), include the <sound_manager.h> header file in your application:
```
#include <sound_manager.h>
```

Subscribe to the volume change notifications.

Define the sound_manager_volume_changed_cb() callback function, which is called every time the sound volume changes. Register the callback function using the sound_manager_set_volume_changed_cb() function. When the volume changes and the callback function is invoked, use the callback to see which sound type has changed and what the new volume level is.

#define MBUF 128
 
int error_code;
 
static void _sound_manager_volume_changed_cb(sound_type_e type, unsigned int volume, void* user_data)  
{
   char buf[MBUF] = {0, };
 
   snprintf(buf, MBUF, "(%d) type volume changed to (%d)", type, volume);
   dlog_print(DLOG_INFO, "Sound Manager", "Volume Changed : %s", buf);
}

error_code = sound_manager_set_volume_changed_cb(_sound_manager_volume_changed_cb, NULL);

Get the maximum and current volume.
To get the current volume, call the sound_manager_get_volume() function with the sound type and the int value where the function places the current volume. You can call this function for every sound media type. To get the maximum volume, call the sound_manager_get_max_volume() function with similar parameters.
```
int ret;
sound_session_type_e type = SOUND_SESSION_TYPE_MEDIA;

int max_vol = 0;

ret = sound_manager_get_max_volume(type, &max_vol);

int cur_vol = 0;

ret = sound_manager_get_volume(type, &cur_vol);
```
Set a new volume.
To set a new volume level, call the sound_manager_set_volume() function. In the following example code, the first parameter is the sound type and the second parameter is a value received from the slider in the application UI, with which the user sets the volume value.
```
int ret;
sound_session_type_e type = SOUND_SESSION_TYPE_MEDIA;
int value;

// Make sure the value is within the system max volume by using the sound_manager_get_max_volume() function 

ret = sound_manager_set_volume(type, value);
```

Querying Sound Devices

To query for information:

To use the functions and data types of the Sound Manager API (in mobile and wearable applications), include the <sound_manager.h> header file in your application:
```
#include <sound_manager.h>
```

To query the information of the connected sound devices:

To access sound devices and their information:

Set the mask.

Define a combination of masks to narrow down the sound devices whose information you need.

int ret;
int _ret;
sound_device_mask_e mask = SOUND_DEVICE_IO_DIRECTION_OUT_MASK | 
                           SOUND_DEVICE_IO_DIRECTION_BOTH_MASK | 
                           SOUND_DEVICE_STATE_ACTIVATED_MASK;

Get a sound device list handle and device handle.
To query the desired sound device information, you need a connected sound device list, and the sound device handle. Use the sound_manager_get_current_device_list() function to get the list handle of the currently connected sound devices. Use this handle as an input parameter for the sound_manager_get_next_device() and sound_manager_get_prev_device() functions to get each sound device handle.
```
sound_device_list_h list;
sound_device_h device;
sound_device_type_e type;
sound_device_io_direction_e direction;

ret = sound_manager_get_current_device_list(mask, &list);
```

Get sound device information.

With the sound device handle, you can query the sound device information (there is a dedicated function for each type of information: device type, IO direction, ID, name, and state). With the query functions, use the sound device handle as the first parameter (input), and the device information type enumerator as the second parameter (output).

The following example shows the sequential progress of getting information of sound device type and IO direction.

while ((_ret = sound_manager_get_next/prev_device(list, &device)) != SOUND_MANAGER_ERROR_NONE) 
{
   ret = sound_manager_get_device_type(device, &type);
 
   if (type == SOUND_DEVICE_BLUETOOTH) 
   {
      // Sound device type is Bluetooth, handle accordingly
   } 
   else if (type == SOUND_DEVICE_AUDIO_JACK) 
   {
      ret = sound_manager_get_device_io_direction(device, &direction);
   }
   if (direction == BOTH)
   {
      // The sound device has both headphone and mic, handle accordingly
   } 
   else 
   {
      // Handle accordingly
   }
}
if (_ret == SOUND_MANAGER_ERROR_NO_DATA) 
{
   // End of the available devices, handle accordingly
}

To monitor the device connection changes:

To receive a notification whenever the sound device connection state changes, define the sound_device_connected_cb callback function.

static void _sound_device_connected_cb(sound_device_h device, bool is_connected, void* user_data) 
{
   int ret;
   sound_device_type_e type;

   if (is_connected) 
   {
      ret = sound_manager_get_device_type(device, &type);
      if (type == SOUND_DEVICE_BLUETOOTH) 
      {
         // Sound device type is Bluetooth, handle accordingly
      } 
      else 
      {
         // Handle accordingly
      }
   } 
   else 
   {
      ret = sound_manager_get_device_type(device, &type);
      if (type == SOUND_DEVICE_BLUETOOTH) 
      {
         // Sound device type is Bluetooth, handle accordingly
      } 
      else 
      {
         // Handle accordingly
      }
   }
}

To register the callback function, call the sound_manager_set_device_connected_cb() with the defined callback and data which passes the user data. Use the mask to narrow down the callback information.
```
mask = SOUND_DEVICE_IO_DIRECTION_OUT_MASK | SOUND_DEVICE_IO_DIRECTION_BOTH_MASK;

ret = sound_manager_set_device_connected_cb(mask, _sound_device_connected_cb, NULL);
```
Remember that the initial state of the connected sound device is deactivated.

To monitor the device information changes:

To receive a notification whenever the sound device information changes, define the sound_device_information_changed_cb callback function.

static void _sound_device_information_changed_cb(sound_device_h device, 
                                                 sound_device_changed_info_e changed_info, 
                                                 void* user_data) 
{
   int ret;
   sound_device_type_e type;
   sound_device_state_e state;
   sound_device_io_direction_e direction;

   ret = sound_manager_get_device_type(device, &type);
   if (type == SOUND_DEVICE_BLUETOOTH) 
   {
      if (changed_info  == SOUND_DEVICE_CHANGED_INFO_STATE) 
      {
         ret = sound_manager_get_device_state(device, &state);
         if (state == SOUND_DEVICE_STATE_DEACTIVATED) 
         {
            // Bluetooth device has been deactivated, handle accordingly
         } 
         else 
         {
            // Handle accordingly
         }
      } 
      else 
      {
         ret = sound_manager_get_device_io_direction(device, &direction);
         if (direction == SOUND_DEVICE_IO_DIRECTION_OUT) 
         {
            // IO direction of the Bluetooth device is now out, handle accordingly
         } 
         else 
         {
            // Handle accordingly
         }
      }
   } 
   else 
   {
      // Handle accordingly
   }
}

To register the callback function, call the sound_manager_set_device_information_changed_cb() with the defined callback and data which passes the user data. Use the mask to narrow down the callback information.

mask = SOUND_DEVICE_IO_DIRECTION_OUT_MASK | SOUND_DEVICE_IO_DIRECTION_BOTH_MASK;

ret = sound_manager_set_device_information_changed_cb(mask, 
                                                      _sound_device_information_changed_cb, NULL);

Managing Sound Manager Session Parameters

To obtain and modify basic sound session parameters:

To use the functions and data types of the Sound Manager API (in mobile and wearable applications), include the <sound_manager.h> header file in your application:
```
#include <sound_manager.h>
```
Store the parameter data.
The session parameters are stored in the following enumeration structures:
- sound_session_type_e (in mobile and wearable applications)
- sound_session_option_for_during_play_e (in mobile and wearable applications)
- sound_session_option_for_starting_e (in mobile and wearable applications)
- sound_session_option_for_resumption_e (in mobile and wearable applications)

Detect interruptions.

To detect and track session status changes, register a callback function:

sound_manager_set_session_interrupted_cb(_sound_session_interrupted_cb, NULL);

Define the callback function content. The sound_session_interrupted_code_e enumeration (in mobile and wearable applications) defines the available interruption sources.

void _sound_session_interrupted_cb(sound_session_interrupted_code_e code, void * userdata)
{
   dlog_print(DLOG_INFO, LOG_TAG, "Interrupt code: %d\n", code);

   dlog_print(DLOG_INFO, LOG_TAG,
           "SOUND_SESSION_INTERRUPTED_COMPLETED %d | "\
           "SOUND_SESSION_INTERRUPTED_BY_MEDIA %d | "\
           "SOUND_SESSION_INTERRUPTED_BY_CALL %d | "\
           "SOUND_SESSION_INTERRUPTED_BY_EARJACK_UNPLUG %d | "\
           "SOUND_SESSION_INTERRUPTED_BY_RESOURCE_CONFLICT %d | "\
           "SOUND_SESSION_INTERRUPTED_BY_ALARM %d | "\
           "SOUND_SESSION_INTERRUPTED_BY_EMERGENCY %d | "\
           "SOUND_SESSION_INTERRUPTED_BY_NOTIFICATION %d\n\n",

           SOUND_SESSION_INTERRUPTED_COMPLETED,
           SOUND_SESSION_INTERRUPTED_BY_MEDIA,
           SOUND_SESSION_INTERRUPTED_BY_CALL,
           SOUND_SESSION_INTERRUPTED_BY_EARJACK_UNPLUG,
           SOUND_SESSION_INTERRUPTED_BY_RESOURCE_CONFLICT,
           SOUND_SESSION_INTERRUPTED_BY_ALARM,
           SOUND_SESSION_INTERRUPTED_BY_EMERGENCY,
           SOUND_SESSION_INTERRUPTED_BY_NOTIFICATION);
}

Manage the session type.

To get a valid sound session, the Tone Player API (in mobile and wearable applications) is used in this tutorial. For more information, see the Tone Player Tutorial.

To determine and change the session type, use the following functions:

#include <tone_player.h>
int id;
sound_session_type_e type;

tone_player_start(TONE_TYPE_ANSI_DIAL, SOUND_SESSION_TYPE_MEDIA, 10000, &id);

sound_manager_get_session_type(&type);

dlog_print(DLOG_INFO, LOG_TAG, "-Session type %d :\n"
   "SOUND_SESSION_TYPE_MEDIA %d | "\
   "SOUND_SESSION_TYPE_ALARM %d | "\
   "SOUND_SESSION_TYPE_NOTIFICATION %d | "\
   "SOUND_SESSION_TYPE_EMERGENCY %d \n",
   type,
   SOUND_SESSION_TYPE_MEDIA,
   SOUND_SESSION_TYPE_ALARM,
   SOUND_SESSION_TYPE_NOTIFICATION,
   SOUND_SESSION_TYPE_EMERGENCY);

sound_manager_set_session_type(SOUND_SESSION_TYPE_NOTIFICATION);

Manage the session options.

To determine the sound session behavior after an interruption or start, or during the playback, use the following functions:

sound_session_option_for_starting_e start;
sound_session_option_for_during_play_e play;
sound_session_option_for_resumption_e res;

sound_manager_get_media_session_option(&start, &play);
sound_manager_get_media_session_resumption_option(&res);

sound_manager_set_media_session_option(SOUND_SESSION_OPTION_PAUSE_OTHERS_WHEN_START,
                                       SOUND_SESSION_OPTION_INTERRUPTIBLE_DURING_PLAY);

sound_manager_set_media_session_resumption_option(SOUND_SESSION_OPTION_RESUMPTION_BY_SYSTEM_OR_MEDIA_PAUSED);

Clean up.
When the interrupt callback is no longer needed, deregister it:
```
sound_manager_unset_session_interrupted_cb();
```