Sound Manager: Managing Sound Parameters

This tutorial demonstrates how you can manage application sound.

Warm-up

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

• Setting the Sound Session Type

  Set the sound session type for your application, and monitor sound session interruptions.

• Controlling the Volume

  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 Session Parameters

  Retrieve and set basic sound session parameters.

Setting the Sound Session Type

To set the sound session type for your application and monitor sound session interruptions:

1. 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>
   

2. Set the sound session type using the sound_manager_set_session_type() function. The parameter defines the sounds session type using the sound_session_type_e enumeration (in mobile and wearable applications).

   int error_code;
   
   error_code = sound_manager_set_session_type(SOUND_SESSION_TYPE_MEDIA);
   

   The function sets the type across the system.

3. To receive a notification whenever the sound session is interrupted:

   1. Register a callback using the sound_manager_set_session_interrupted_cb() function:

      error_code = sound_manager_set_session_interrupted_cb(_sound_session_interrupted_cb, NULL);
      

   2. Define the session interrupt callback. The first parameter defines the interruption source using the sound_session_interrupted_code_e enumeration (in mobile and wearable applications).

      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
      }
      

   3. When no longer needed, unregister the callback:

      error_code = sound_manager_unset_session_interrupted_cb();
      

Controlling the Volume

To control the volume of your application:

1. 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>
   

2. To receive a notification whenever the volume changes:

   1. Register a callback using the sound_manager_set_volume_changed_cb() function:

      error_code = sound_manager_set_volume_changed_cb(_sound_manager_volume_changed_cb, NULL);
      

   2. Define the volume change callback. When the volume changes, use the callback to determine 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);
      }
      

3. To retrieve the current and maximum volume for a sound type:

   • Retrieve the current volume using the sound_manager_get_volume() function. The function takes as parameters the sound type and an integer variable where to return the current volume. You can call this function separately for each sound type.

   • Retrieve the maximum volume using the sound_manager_get_max_volume() function. The function takes similar parameters and works the same way as the sound_manager_get_volume() function.

   int ret;
   sound_session_type_e type = SOUND_SESSION_TYPE_MEDIA;
   
   int cur_vol = 0;
   
   ret = sound_manager_get_volume(type, &cur_vol);
   
   int max_vol = 0;
   
   ret = sound_manager_get_max_volume(type, &max_vol);
   

4. To set the volume level, use 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 level.

   int ret;
   sound_session_type_e type = SOUND_SESSION_TYPE_MEDIA;
   int value;
   
   // Make sure the value is within the system maximum volume
   // by using the sound_manager_get_max_volume() function
   
   ret = sound_manager_set_volume(type, value);
   

Querying Sound Devices

To query sound device information:

1. 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>
   

2. To access the sound device information:

   1. To only access the sound devices whose information you need, define a combination of masks:

      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;
      

   2. Retrieve the sound device list handle and sound device handles.

      To query sound device information, you need a list of currently connected sound devices and a handle for each sound device you want query. To retrieve the list handle, use the sound_manager_get_current_device_list() function. To retrieve the sound device handles, use sound_manager_get_next_device() and sound_manager_get_prev_device() functions with the list handle as a parameter.

      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);
      

   3. Retrieve the sound device information.

      You can query sound device information with a sound device handle. The Sound Manager API provides a dedicated function for each information type: device type, IO direction, ID, name, and state. When calling 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 code shows how to retrieve information about sound device type and IO direction:

      while ((_ret = sound_manager_get_next_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)
         {
            // 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
      }
      

3. To receive a notification whenever the sound device connection state changes:

   1. Register a callback using the sound_manager_set_device_connected_cb() function. Use the mask to filter 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);
      

      Note
      The initial state of the connected sound device is deactivated.

   2. Define the state change callback:

      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)
            {
               // Connected sound device type is Bluetooth, handle accordingly
            }
            else
            {
               // Handle accordingly
            }
         }
         else
         {
            ret = sound_manager_get_device_type(device, &type);
            if (type == SOUND_DEVICE_BLUETOOTH)
            {
               // Disconnected sound device type is Bluetooth, handle accordingly
            }
            else
            {
               // Handle accordingly
            }
         }
      }
      

4. To receive a notification whenever the sound device information changes:

   1. Register a callback using the sound_manager_set_device_information_changed_cb() function. Use the mask to filter 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);
      

   2. Define the information change callback:

      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
         }
      }
      

Managing Sound Session Parameters

To retrieve and set basic sound session parameters:

1. 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>
   

2. To receive a notification whenever the sound session is interrupted:

   1. Register a callback using the sound_manager_set_session_interrupted_cb() function:

      sound_manager_set_session_interrupted_cb(_sound_session_interrupted_cb, NULL);
      

   2. Define the session interrupt callback. The first parameter defines the interruption source using the sound_session_interrupted_code_e enumeration (in mobile and wearable applications).

      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);
      }
      

3. Manage the session type.

   To start a sound session, this use case uses the Tone Player API (in mobile and wearable applications). For more information, see the Tone Player Tutorial.

   To determine and change the session type, use the following functions. The sound_session_type_e enumeration (in mobile and wearable applications) defines the available sound session types.

   #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);
   

4. Manage the session options.

   To specify the sound session behavior at playback start, during playback, and after an interruption, 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);
   

   The sound_session_option_for_starting_e (in mobile and wearable applications), sound_session_option_for_during_play_e (in mobile and wearable applications), and sound_session_option_for_resumption_e (in mobile and wearable applications) enumerations define the available sound session options.

5. After you no longer need the session interrupt callback, unregister it:

   sound_manager_unset_session_interrupted_cb();