Tizen Native API  6.0

The Volume API provides functions to check and control volumes.

Required Header

#include <sound_manager.h>

Overview

The Sound Manager Volume API allows you to:

  • check/control output volumes
  • handle a volume changed notification

The Sound Manager has predefined types of sounds.(system, notification, alarm, ringtone, media, call, voip, voice).

Current volume level of each type can be checked with sound_manager_get_volume(). To get the maximum supported volume level of each type, call sound_manager_get_max_volume(). The volume level of each type can be adjusted with sound_manager_set_volume().

The type of currently playing sound may be obtained by calling sound_manager_get_current_sound_type().

Functions

int sound_manager_get_max_volume (sound_type_e type, int *max)
 Gets the maximum volume level supported for a particular sound type.
int sound_manager_set_volume (sound_type_e type, int volume)
 Sets the volume level specified for a particular sound type.
int sound_manager_get_volume (sound_type_e type, int *volume)
 Gets the volume level specified for a particular sound type.
int sound_manager_get_current_sound_type (sound_type_e *type)
 Gets the type of the sound being currently played.
int sound_manager_add_volume_changed_cb (sound_manager_volume_changed_cb callback, void *user_data, int *id)
 Adds a callback function to be invoked when the volume level is changed.
int sound_manager_remove_volume_changed_cb (int id)
 Removes the volume change callback.
int sound_manager_create_stream_ducking (sound_stream_type_e target_stream, sound_stream_ducking_state_changed_cb callback, void *user_data, sound_stream_ducking_h *stream_ducking)
 Creates a handle for stream ducking.
int sound_manager_is_ducked (sound_stream_ducking_h stream_ducking, bool *is_ducked)
 Checks if the stream is ducked.
int sound_manager_activate_ducking (sound_stream_ducking_h stream_ducking, unsigned int duration, double ratio)
 Activates ducking, asynchronously.
int sound_manager_deactivate_ducking (sound_stream_ducking_h stream_ducking)
 Deactivates ducking, asynchronously.
int sound_manager_destroy_stream_ducking (sound_stream_ducking_h stream_ducking)
 Destroys the handle for stream ducking.

Typedefs

typedef struct
sound_stream_ducking_s * 
sound_stream_ducking_h
 Sound stream ducking handle.
typedef void(* sound_manager_volume_changed_cb )(sound_type_e type, unsigned int volume, void *user_data)
 Called when the system volume has changed.
typedef void(* sound_stream_ducking_state_changed_cb )(sound_stream_ducking_h stream_ducking, bool is_ducked, void *user_data)
 Called when the ducking activation or deactivation is finished.

Typedef Documentation

typedef void(* sound_manager_volume_changed_cb)(sound_type_e type, unsigned int volume, void *user_data)

Called when the system volume has changed.

Since :
2.3.1
Parameters:
[in]typeThe sound type of the changed volume
[in]volumeThe new volume value
[in]user_dataThe user data passed from the callback registration function
Precondition:
sound_manager_set_volume() will invoke this callback if you register it using sound_manager_add_volume_changed_cb().
See also:
sound_manager_add_volume_changed_cb()
sound_manager_remove_volume_changed_cb()
typedef struct sound_stream_ducking_s* sound_stream_ducking_h

Sound stream ducking handle.

Since :
5.5
typedef void(* sound_stream_ducking_state_changed_cb)(sound_stream_ducking_h stream_ducking, bool is_ducked, void *user_data)

Called when the ducking activation or deactivation is finished.

Since :
5.5
Remarks:
This function is invoked by the internal thread of the sound manager. Therefore it is recommended not to call functions which update UI in this callback.
stream_ducking is the same handle as the parameter in sound_manager_create_stream_ducking() that registers this callback, so the handle should not be released in this callback.
Parameters:
[in]stream_duckingThe stream ducking handle
[in]is_duckedThe flag whether it's ducked or not
[in]user_dataThe user data passed from the callback registration function
Precondition:
You should register this callback when sound_manager_create_stream_ducking() is called.
See also:
sound_manager_create_stream_ducking()

Enumeration Type Documentation

Enumeration for sound type.

Since :
2.3.1
Enumerator:
SOUND_TYPE_SYSTEM 

Sound type for system

SOUND_TYPE_NOTIFICATION 

Sound type for notifications

SOUND_TYPE_ALARM 

Sound type for alarm

SOUND_TYPE_RINGTONE 

Sound type for ringtones (Since 3.0)

SOUND_TYPE_MEDIA 

Sound type for media

SOUND_TYPE_CALL 

Sound type for call (Since 3.0)

SOUND_TYPE_VOIP 

Sound type for voip (Since 3.0)

SOUND_TYPE_VOICE 

Sound type for voice


Function Documentation

int sound_manager_activate_ducking ( sound_stream_ducking_h  stream_ducking,
unsigned int  duration,
double  ratio 
)

Activates ducking, asynchronously.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/volume.set
Remarks:
If ducking is activated successfully, the volume of all sound streams matched with the target_stream that set in sound_manager_create_stream_ducking() is decreased by ratio for duration. The change applies system-wide.
Parameters:
[in]stream_duckingThe handle of stream ducking
[in]durationThe duration for ducking (msec, 0 <= duration <= 3000)
[in]ratioThe volume ratio when ducked (0.0 <= ratio < 1.0)
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_PERMISSION_DENIEDPermission denied
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INVALID_STATEInvalid state
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
Precondition:
The stream should be unducked before calling this function, otherwise, SOUND_MANAGER_ERROR_INVALID_STATE is returned.
See also:
sound_manager_create_stream_ducking()
sound_manager_destroy_stream_ducking()
sound_manager_is_ducked()
sound_manager_deactivate_ducking()
int sound_manager_add_volume_changed_cb ( sound_manager_volume_changed_cb  callback,
void *  user_data,
int *  id 
)

Adds a callback function to be invoked when the volume level is changed.

Since :
3.0
Parameters:
[in]callbackCallback function to indicate change in volume
[in]user_dataThe user data to be passed to the callback function
[out]idThe callback id
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
Postcondition:
sound_manager_volume_changed_cb() will be invoked.
See also:
sound_manager_remove_volume_changed_cb()
sound_manager_volume_changed_cb()
int sound_manager_create_stream_ducking ( sound_stream_type_e  target_stream,
sound_stream_ducking_state_changed_cb  callback,
void *  user_data,
sound_stream_ducking_h stream_ducking 
)

Creates a handle for stream ducking.

Since :
5.5
Remarks:
stream_ducking should be released using sound_manager_destroy_stream_ducking().
Parameters:
[in]target_streamThe type of target stream
[in]callbackThe callback function called when ducking state is changed (optional, this can be NULL)
[in]user_dataThe user data to be passed to the callback function (optional, this can be NULL)
[out]stream_duckingThe handle of stream ducking
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
See also:
sound_manager_destroy_stream_ducking()
sound_manager_is_ducked()
sound_manager_activate_ducking()
sound_manager_deactivate_ducking()

Deactivates ducking, asynchronously.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/volume.set
Parameters:
[in]stream_duckingThe handle of stream ducking
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_PERMISSION_DENIEDPermission denied
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INVALID_STATEInvalid state
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
Precondition:
The stream should be ducked before calling this function, otherwise, SOUND_MANAGER_ERROR_INVALID_STATE is returned.
See also:
sound_manager_create_stream_ducking()
sound_manager_destroy_stream_ducking()
sound_manager_is_ducked()
sound_manager_activate_ducking()

Destroys the handle for stream ducking.

Since :
5.5
Parameters:
[in]stream_duckingThe handle of stream ducking
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
See also:
sound_manager_create_stream_ducking()
sound_manager_is_ducked()
sound_manager_activate_ducking()
sound_manager_deactivate_ducking()

Gets the type of the sound being currently played.

Since :
2.3.1
Parameters:
[out]typeThe current sound type
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_NO_PLAYING_SOUNDNo playing sound
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
int sound_manager_get_max_volume ( sound_type_e  type,
int *  max 
)

Gets the maximum volume level supported for a particular sound type.

Since :
2.3.1
Parameters:
[in]typeThe sound type
[out]maxThe maximum volume level
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
See also:
sound_manager_set_volume()
sound_manager_get_volume()
int sound_manager_get_volume ( sound_type_e  type,
int *  volume 
)

Gets the volume level specified for a particular sound type.

Since :
2.3.1
Parameters:
[in]typeThe sound type
[out]volumeThe current volume level
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
See also:
sound_manager_get_max_volume()
sound_manager_set_volume()
int sound_manager_is_ducked ( sound_stream_ducking_h  stream_ducking,
bool *  is_ducked 
)

Checks if the stream is ducked.

Since :
5.5
Parameters:
[in]stream_duckingThe handle of stream ducking
[out]is_duckedWhether the stream is ducked or not. true if ducked, false otherwise.
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
See also:
sound_manager_create_stream_ducking()
sound_manager_destroy_stream_ducking()
sound_manager_activate_ducking()
sound_manager_deactivate_ducking()

Removes the volume change callback.

Since :
3.0
Parameters:
[in]idThe id of the callback to remove
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
See also:
sound_manager_add_volume_changed_cb()
int sound_manager_set_volume ( sound_type_e  type,
int  volume 
)

Sets the volume level specified for a particular sound type.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/volume.set
Parameters:
[in]typeThe sound type
[in]volumeThe volume level to be set
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_PERMISSION_DENIEDPermission denied
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
See also:
sound_manager_get_max_volume()
sound_manager_get_volume()