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

Parameters:

[in]	type	The sound type of the changed volume
[in]	volume	The new volume value
[in]	user_data	The 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_ducking	The stream ducking handle
[in]	is_ducked	The flag whether it's ducked or not
[in]	user_data	The 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

enum sound_type_e

Enumeration for sound type.

Since :: 2.3

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 2.4)
SOUND_TYPE_MEDIA	Sound type for media
SOUND_TYPE_CALL	Sound type for call (Since 2.4)
SOUND_TYPE_VOIP	Sound type for voip (Since 2.4)
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_ducking	The handle of stream ducking
[in]	duration	The duration for ducking (msec, 0 <= duration <= 3000)
[in]	ratio	The volume ratio when ducked (0.0 <= ratio < 1.0)

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_PERMISSION_DENIED	Permission denied
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_INVALID_STATE	Invalid state
SOUND_MANAGER_ERROR_INTERNAL	Internal 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]	callback	Callback function to indicate change in volume
[in]	user_data	The user data to be passed to the callback function
[out]	id	The callback id

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_INTERNAL	Internal 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_stream	The type of target stream
[in]	callback	The callback function called when ducking state is changed (optional, this can be NULL)
[in]	user_data	The user data to be passed to the callback function (optional, this can be NULL)
[out]	stream_ducking	The handle of stream ducking

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

See also:: sound_manager_destroy_stream_ducking(); sound_manager_is_ducked(); sound_manager_activate_ducking(); sound_manager_deactivate_ducking()

int sound_manager_deactivate_ducking ( sound_stream_ducking_h stream_ducking )

Deactivates ducking, asynchronously.

Since :: 5.5

Privilege Level:: public

Privilege:: http://tizen.org/privilege/volume.set

Parameters:

[in] stream_ducking The handle of stream ducking

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_PERMISSION_DENIED	Permission denied
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_INVALID_STATE	Invalid state
SOUND_MANAGER_ERROR_INTERNAL	Internal 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()

int sound_manager_destroy_stream_ducking ( sound_stream_ducking_h stream_ducking )

Destroys the handle for stream ducking.

Since :: 5.5

Parameters:

[in] stream_ducking The handle of stream ducking

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

See also:: sound_manager_create_stream_ducking(); sound_manager_is_ducked(); sound_manager_activate_ducking(); sound_manager_deactivate_ducking()

int sound_manager_get_current_sound_type ( sound_type_e * type )

Gets the type of the sound being currently played.

Since :: 2.3

Parameters:

[out] type The current sound type

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_NO_PLAYING_SOUND	No playing sound
SOUND_MANAGER_ERROR_INTERNAL	Internal 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

Parameters:

[in]	type	The sound type
[out]	max	The maximum volume level

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid 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

Parameters:

[in]	type	The sound type
[out]	volume	The current volume level

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_INTERNAL	Internal 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_ducking	The handle of stream ducking
[out]	is_ducked	Whether 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_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_INTERNAL	Internal 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()

int sound_manager_remove_volume_changed_cb ( int id )

Removes the volume change callback.

Since :: 3.0

Parameters:

[in] id The id of the callback to remove

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_INTERNAL	Internal 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

Privilege Level:: public

Privilege:: http://tizen.org/privilege/volume.set

Parameters:

[in]	type	The sound type
[in]	volume	The volume level to be set

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_MANAGER_ERROR_PERMISSION_DENIED	Permission denied
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

See also:: sound_manager_get_max_volume(); sound_manager_get_volume()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation