The Sound Pool API provides functions for easy sound management such as grouping sounds in pools, play, pause, resume, stop operations of sound streams and controlling stream/pool states.

Required Header

#include <sound_pool.h>

Overview

The Sound Pool module provides a set of functions to manipulate sounds in application. It allows easy loading, grouping, playing, and controlling the sound streams playback; changing parameters of sound streams such as volume, number of repeats (loops), and priorities also. Sound pool is aimed to control short sounds which can be grouped by some criteria (game level, or character, application audio theme, etc).
Module includes three main entities: sound pool, sound source and sound stream.
Sound pool is a collection of sounds. It can be defined as isolated environment where sound streams can be managed. When pool is created, it has to be filled by the sound sources. Sources can be defined as audio data which can be loaded from files. When you load the source from file to pool, audio data is loaded from this file and cached in the memory. After this it is possible to play sound streams using this cached data. Multiple sound streams can be played simultaneously using different or the same sources. Stream can be defined as an instance of sound source. Stream exists from the moment when play command is called till the end of until playback is finished or stop command is called.
The Sound Pool module supports multiple sound pools management. Pools can be activated/deactivated. When deactivation is performed, all playing streams corresponding to the pool gets suspended state. When pool is activated, then all suspended streams are resumed. Also, it is possible to change volume of the pool which affects all the streams in the pool.

Functions
int	sound_pool_create (sound_pool_h *pool)
	Creates a sound pool instance that can be used for sound sources loading/unloading.
int	sound_pool_destroy (sound_pool_h pool)
	Destroys a sound pool and cleans allocated memory.
int	sound_pool_load_source_from_file (sound_pool_h pool, const char file_name, const char tag)
	Loads sound source data from a file to the pool.
int	sound_pool_unload_source (sound_pool_h pool, const char *tag)
	Unloads source from the pool.
int	sound_pool_activate (sound_pool_h pool)
	Changes the current state of a pool to SOUND_POOL_STATE_ACTIVE.
int	sound_pool_deactivate (sound_pool_h pool)
	Changes the current state of a pool to SOUND_POOL_STATE_INACTIVE.
int	sound_pool_set_volume (sound_pool_h pool, float volume)
	Sets the pool's global volume parameter.
int	sound_pool_get_volume (sound_pool_h pool, float *volume)
	Gets the pool's global volume parameter.
int	sound_pool_get_state (sound_pool_h pool, sound_pool_state_e *state)
	Gets the current state of pool.
int	sound_pool_set_state_changed_cb (sound_pool_h pool, sound_pool_state_changed_cb callback, void *user_data)
	Sets the callback for handling sound pool state change.
int	sound_pool_unset_state_changed_cb (sound_pool_h pool)
	Unsets the callback for handling sound pool state change.
int	sound_pool_stream_play (sound_pool_h pool, const char tag, unsigned loop, float volume, unsigned priority, sound_pool_stream_priority_policy_e priority_policy, sound_pool_stream_state_changed_cb callback, void user_data, unsigned *id)
	Plays a source by tag.
int	sound_pool_stream_pause (sound_pool_h pool, unsigned id)
	Pauses a stream by id.
int	sound_pool_stream_resume (sound_pool_h pool, unsigned id)
	Resumes a stream by id.
int	sound_pool_stream_stop (sound_pool_h pool, unsigned id)
	Stops a stream by id.
int	sound_pool_stream_set_volume (sound_pool_h pool, unsigned id, float volume)
	Sets the stream's volume parameters by stream id.
int	sound_pool_stream_get_volume (sound_pool_h pool, unsigned id, float *volume)
	Gets the stream's volume parameters by stream id.
int	sound_pool_stream_set_priority (sound_pool_h pool, unsigned id, unsigned priority)
	Sets the stream's priority parameter by stream id.
int	sound_pool_stream_get_priority (sound_pool_h pool, unsigned id, unsigned *priority)
	Gets the stream's priority parameter by stream id.
int	sound_pool_stream_get_state (sound_pool_h pool, unsigned id, sound_pool_stream_state_e *state)
	Gets the current state of stream by id.
Typedefs
typedef void(*	sound_pool_state_changed_cb )(sound_pool_h pool, sound_pool_state_e prev_state, sound_pool_state_e cur_state, void *user_data)
	Called when the sound pool state is changed.
typedef void(*	sound_pool_stream_state_changed_cb )(sound_pool_h pool, unsigned id, sound_pool_stream_state_e prev_state, sound_pool_stream_state_e cur_state, void *user_data)
	Called when the sound pool stream state is changed.
typedef void *	sound_pool_h
	Sound pool handle type.

Typedef Documentation

typedef void* sound_pool_h

Sound pool handle type.

Since :: 4.0

typedef void(* sound_pool_state_changed_cb)(sound_pool_h pool, sound_pool_state_e prev_state, sound_pool_state_e cur_state, void *user_data)

Called when the sound pool state is changed.

Since :: 4.0

Remarks:: pool is the object for which the callback was set.

Parameters:

[in]	pool	The sound pool handle
[in]	prev_state	Previous pool state
[in]	cur_state	Current pool state
[in]	user_data	The user data passed from the code where sound_pool_set_state_changed_cb() was called.

Precondition:: Create sound pool handle by calling sound_pool_create(); Call sound_pool_set_state_changed_cb()

See also:: sound_pool_create(); sound_pool_set_state_changed_cb(); sound_pool_state_e

typedef void(* sound_pool_stream_state_changed_cb)(sound_pool_h pool, unsigned id, sound_pool_stream_state_e prev_state, sound_pool_stream_state_e cur_state, void *user_data)

Called when the sound pool stream state is changed.

Since :: 4.0

Remarks:: pool is the object for which the callback was set.

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier
[in]	prev_state	Previous stream state
[in]	cur_state	Current stream state
[in]	user_data	The user data passed to the callback

Precondition:: Create sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start source playback by calling sound_pool_stream_play()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play(); sound_pool_stream_state_e

Enumeration Type Documentation

enum sound_pool_error_e

Enumeration for Tizen Sound Pool error.

Since :: 4.0

Enumerator:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	Key not available
SOUND_POOL_ERROR_OUT_OF_MEMORY	Out of memory
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation
SOUND_POOL_ERROR_NOT_PERMITTED	Not permitted
SOUND_POOL_ERROR_NO_SUCH_FILE	File not found

enum sound_pool_state_e

Enumeration of sound pool state.

Since :: 4.0

Enumerator:

SOUND_POOL_STATE_ACTIVE	Sound pool active state: streams can be played
SOUND_POOL_STATE_INACTIVE	Sound pool inactive state: streams can't be played

enum sound_pool_stream_priority_policy_e

Enumeration of sound pool stream priority policy.

Since :: 4.0

Enumerator:

SOUND_POOL_STREAM_PRIORITY_POLICY_MUTE	Stream priority policy is mute
SOUND_POOL_STREAM_PRIORITY_POLICY_SUSPENDED	Stream priority policy is suspended

enum sound_pool_stream_state_e

Enumeration of sound pool stream state.

Since :: 4.0

Enumerator:

SOUND_POOL_STREAM_STATE_NONE	Stream state isn't determined
SOUND_POOL_STREAM_STATE_PLAYING	Stream state is playing
SOUND_POOL_STREAM_STATE_PAUSED	Stream state is paused
SOUND_POOL_STREAM_STATE_STOPPED	Stream state is stopped
SOUND_POOL_STREAM_STATE_FINISHED	Stream state is finished
SOUND_POOL_STREAM_STATE_SUSPENDED	Stream state is suspended

Function Documentation

int sound_pool_activate ( sound_pool_h pool )

Changes the current state of a pool to SOUND_POOL_STATE_ACTIVE.

Since :: 4.0

Remarks:: When activation is performed, all suspended streams with highest priority in the pool will resume their playback. Paused streams will remain their state.

Parameters:

[in] pool The sound pool handle

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation or sound pool is already in SOUND_POOL_STATE_ACTIVE state

Precondition:: Create a sound pool handle by calling sound_pool_create()

See also:: sound_pool_create(); sound_pool_get_state(); sound_pool_deactivate(); sound_pool_state_e

int sound_pool_create ( sound_pool_h * pool )

Creates a sound pool instance that can be used for sound sources loading/unloading.

Up to 8 sound pools can be created. Several pools can be active at the same time. Streams can be in playing state only when pool is active. Memory is allocated for sound pool. User should aware that creation of more number of pools means more memory is allocated.

Since :: 4.0

Remarks:: When pool has been created, pool state is SOUND_POOL_STATE_INACTIVE. To activate the pool use sound_pool_activate() function. When no longer needed, pool should be destroyed with sound_pool_destroy().

Parameters:

[out] pool The created sound pool handle

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL)
SOUND_POOL_ERROR_OUT_OF_MEMORY	Not enough memory to create sound pool
SOUND_POOL_ERROR_INVALID_OPERATION	Maximal amount of sound pools is exceeded (maximum 8 pools allowed)

See also:: sound_pool_destroy()

int sound_pool_deactivate ( sound_pool_h pool )

Changes the current state of a pool to SOUND_POOL_STATE_INACTIVE.

Since :: 4.0

Remarks:: When deactivation is performed, all playing streams in the pool will be suspended (change state to SOUND_POOL_STREAM_STATE_SUSPENDED). Paused streams will remain in their state.

Parameters:

[in] pool The sound pool handle

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation or sound pool is already in `SOUND_POOL_STATE_INACTIVE` state

Precondition:: Create a sound pool handle by calling sound_pool_create(); pool has to be in SOUND_POOL_STATE_ACTIVE state

See also:: sound_pool_create(); sound_pool_get_state(); sound_pool_activate(); sound_pool_state_e

int sound_pool_destroy ( sound_pool_h pool )

Destroys a sound pool and cleans allocated memory.

Stops all streams and unloads all sources associated with pool.

Since :: 4.0

Remarks:: pool should be destroyed with sound_pool_destroy().

Parameters:

[in] pool The sound pool handle will be destroyed

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Create sound pool handle by calling sound_pool_create()

See also:: sound_pool_create()

int sound_pool_get_state	(	sound_pool_h	pool,
		sound_pool_state_e *	state
	)

Gets the current state of pool.

Since :: 4.0

Parameters:

[in]	pool	The sound pool handle
[out]	state	Current state of pool

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, tag is NULL)

Precondition:: Create a sound pool handle by calling sound_pool_create()

See also:: sound_pool_create(); sound_pool_state_e

int sound_pool_get_volume	(	sound_pool_h	pool,
		float *	volume
	)

Gets the pool's global volume parameter.

Since :: 4.0

Parameters:

[in]	pool	The sound pool handle
[out]	volume	Pool global volume in 0.0~1.0 range

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, or volume is NULL)

Precondition:: Create a sound pool handle by calling sound_pool_create()

See also:: sound_pool_create()

int sound_pool_load_source_from_file	(	sound_pool_h	pool,
		const char *	file_name,
		const char *	tag
	)

Loads sound source data from a file to the pool.

After calling this routine the source can be accessed by its tag.

Since :: 4.0

Remarks:: Input data can be either raw or encoded. Each of loaded sources must have unique tag It is synchronous operation.

Parameters:

[in]	pool	The sound pool handle
[in]	file_name	The name of the file that contains sound data
[in]	tag	Unique string that will be used to identify source

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, file_name is NULL, tag is NULL or tag/file_name* length* is too long)
SOUND_POOL_ERROR_OUT_OF_MEMORY	Not enough memory to allocate source
SOUND_POOL_ERROR_NO_SUCH_FILE	No file determined by file_name
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Create a sound pool handle by calling sound_pool_create()

Postcondition:: Unload source from the pool by calling sound_pool_unload_source()

See also:: sound_pool_create(); sound_pool_destroy(); sound_pool_unload_source()

int sound_pool_set_state_changed_cb	(	sound_pool_h	pool,
		sound_pool_state_changed_cb	callback,
		void *	user_data
	)

Sets the callback for handling sound pool state change.

Since :: 4.0

Parameters:

[in]	pool	The sound pool handle
[in]	callback	The callback that will be called after pool state will be changed. callback will be called synchronously
[in]	user_data	The user data to be passed to the callback

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, or callback is NULL)

Precondition:: Create a sound pool handle by calling sound_pool_create()

Postcondition:: Use sound_pool_unset_state_changed_cb() function to unset the callback

See also:: sound_pool_create(); sound_pool_state_changed_cb()

int sound_pool_set_volume	(	sound_pool_h	pool,
		float	volume
	)

Sets the pool's global volume parameter.

Volume of all streams related to the pool will be scaled in accordance to global pool volume parameter (i.e. [stream real volume] = [global volume] * [stream volume], where [stream volume] is the volume parameter of arbitrary stream).

Since :: 4.0

Parameters:

[in]	pool	The sound pool handle
[in]	volume	Pool global volume in 0.0~1.0 range

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, or volume isn't in 0.0~1.0 range)
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Create a sound pool handle by calling sound_pool_create()

See also:: sound_pool_create()

int sound_pool_stream_get_priority	(	sound_pool_h	pool,
		unsigned	id,
		unsigned *	priority
	)

Gets the stream's priority parameter by stream id.

Since :: 4.0

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier
[out]	priority	Stream priority (0 = lowest priority). Check sound_pool_stream_set_priority() documentation for details on prioritization rules.

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, or priority is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No streams identified by id exist in the pool

Precondition:: Create a sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start stream playback by calling sound_pool_stream_play()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play()

int sound_pool_stream_get_state	(	sound_pool_h	pool,
		unsigned	id,
		sound_pool_stream_state_e *	state
	)

Gets the current state of stream by id.

Since :: 4.0

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier
[out]	state	Current state of stream

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, or state is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No streams identified by id exist in the pool

Precondition:: Create sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start stream playback by calling sound_pool_stream_play()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play(); sound_pool_stream_state_e

int sound_pool_stream_get_volume	(	sound_pool_h	pool,
		unsigned	id,
		float *	volume
	)

Gets the stream's volume parameters by stream id.

Since :: 4.0

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier
[out]	volume	Stream volume in 0.0~1.0 range

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, or volume is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No streams identified by id exist in the pool

Precondition:: Create a sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start stream playback by calling sound_pool_stream_play()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play()

int sound_pool_stream_pause	(	sound_pool_h	pool,
		unsigned	id
	)

Pauses a stream by id.

Sets stream state to SOUND_POOL_STREAM_STATE_PAUSED.

Since :: 4.0

Remarks:: Stream state has to be SOUND_POOL_STREAM_STATE_PLAYING.

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation or stream is in the state which is not allowed for pause operation

Precondition:: Create a sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start stream playback by calling sound_pool_stream_play()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play()

int sound_pool_stream_play	(	sound_pool_h	pool,
		const char *	tag,
		unsigned	loop,
		float	volume,
		unsigned	priority,
		sound_pool_stream_priority_policy_e	priority_policy,
		sound_pool_stream_state_changed_cb	callback,
		void *	user_data,
		unsigned *	id
	)

Plays a source by tag.

Creates stream with id that can be used to change parameters and get additional information. Sets stream state to SOUND_POOL_STREAM_STATE_PLAYING. If a callback is set with sound_pool_stream_play(), and another callback is set with sound_pool_stream_set_state_changed_cb(), the second callback will overwrite the first one.

Since :: 4.0

Remarks:: Resultant stream volume will depend on global pool volume.

Parameters:

[in]	pool	The sound pool handle
[in]	tag	Unique string that identifies source
[in]	loop	Number of times stream will be repeated (pass 0 if stream should be repeated continuously)
[in]	volume	Stream volume in 0.0~1.0 range
[in]	priority	Stream priority (0 = lowest priority). Check sound_pool_stream_set_priority() documentation for details on prioritization rules.
[in]	priority_policy	Stream priority policy. (SOUND_POOL_STREAM_PRIORITY_POLICY_MUTE - Mute) (SOUND_POOL_STREAM_PRIORITY_POLICY_SUSPENDED - Suspended) If priority_policy is set to Mute, the stream will be playing with mute even in the presence of high priority stream and it will not be Suspended.
[in]	callback	The callback that will be called after stream state will be changed, or NULL if this callback call isn't needed. If callback is set, then it will be called asynchronously.
[in]	user_data	The user data to be passed to the callback
[out]	id	Unique stream identifier that can be used to change parameters and get additional information

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, tag is NULL, volume is out of 0.0~1.0 range, or id is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No sources tagged by tag exist in the pool
SOUND_POOL_ERROR_OUT_OF_MEMORY	Not enough memory to allocate new sound stream
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Create sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file()

Postcondition:: When playback is finished normally (i.e. sound_pool_stream_stop() will be not used for stream termination) state will be changed to SOUND_POOL_STREAM_STATE_FINISHED and memory will be cleared from the stream allocated resources automatically

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_set_volume(); sound_pool_get_volume()

int sound_pool_stream_resume	(	sound_pool_h	pool,
		unsigned	id
	)

Resumes a stream by id.

Sets stream state to SOUND_POOL_STREAM_STATE_PLAYING.

Since :: 4.0

Remarks:: Stream state has to be SOUND_POOL_STREAM_STATE_PAUSED.

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation or stream is in the state which is not allowed for resume operation

Precondition:: Create a sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start stream playback by calling sound_pool_stream_play(); Pause stream playback by calling sound_pool_stream_pause()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play(); sound_pool_stream_pause()

int sound_pool_stream_set_priority	(	sound_pool_h	pool,
		unsigned	id,
		unsigned	priority
	)

Sets the stream's priority parameter by stream id.

Since :: 4.0

The below rules are applicable for streams with priority policy SOUND_POOL_STREAM_PRIORITY_POLICY_SUSPENDED. Only streams with highest priority in the active Sound Pool can be played. If at least one stream with highest priority enters SOUND_POOL_STREAM_STATE_PLAYING state, then all streams currently being played with lower priorities will be transferred to the SOUND_POOL_STREAM_STATE_SUSPENDED state. If there are no more playing streams in a given priority group (group of streams with the same priority), then all previously suspended streams in the group with one level lower priority will be resumed.

For example, if we have N suspended streams in 'LOW' group, M suspended streams in 'MEDIUM' group and K playing streams in 'HIGH' group. Then the following rules are valid: When all K streams in HIGH priority group will be finished, paused, or stopped and Sound Pool is in active state, only then M streams from MEDIUM priority group will be resumed. When all M+K streams from HIGH and MEDIUM priority groups are finished, paused or stopped and Sound Pool is in active state, only then N streams from LOW priority group will be resumed. Transferring at least one stream from higher priority group will lead to suspending of all the streams from lower priorities group(s).

Priorities don't take any effect in inactive Sound Pools. But after pool activation, all mentioned rules will be applied.

If stream priority policy is set to mute SOUND_POOL_STREAM_PRIORITY_POLICY_MUTE, all above rules are not valid for the stream and it will be played with mute even in the presence of high priority steams. streams.

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier
[in]	priority	Stream priority (0 = lowest priority)

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Create a sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start stream playback by calling sound_pool_stream_play()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play()

int sound_pool_stream_set_volume	(	sound_pool_h	pool,
		unsigned	id,
		float	volume
	)

Sets the stream's volume parameters by stream id.

Since :: 4.0

Remarks:: Resultant stream volume will depend on global pool volume.

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier
[in]	volume	Stream volume in 0.0~1.0 range

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, or volume isn't in 0.0~1.0 range)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Create a sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start stream playback by calling sound_pool_stream_play()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play(); sound_pool_set_volume; sound_pool_get_volume

int sound_pool_stream_stop	(	sound_pool_h	pool,
		unsigned	id
	)

Stops a stream by id.

Sets stream state to SOUND_POOL_STREAM_STATE_STOPPED. After stream was stopped it can not be resumed and id value becomes invalid. Moreover, stream will never gets SOUND_POOL_STREAM_STATE_FINISHED state as it will be terminated after this function call.

Since :: 4.0

Parameters:

[in]	pool	The sound pool handle
[in]	id	Unique stream identifier

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATION	Invalid operation or stream is in the state which is not allowed for stop operation

Precondition:: Create sound pool handle by calling sound_pool_create(); Load source to pool by calling sound_pool_load_source_from_file(); Start stream playback by calling sound_pool_stream_play()

See also:: sound_pool_create(); sound_pool_load_source_from_file(); sound_pool_stream_play()

int sound_pool_unload_source	(	sound_pool_h	pool,
		const char *	tag
	)

Unloads source from the pool.

Cleans memory. This operation is synchronous.

Since :: 4.0

Remarks:: The usage of tag name that was associated with unloaded source has no effect. It can be reused as well.

Parameters:

[in]	pool	The sound pool handle
[in]	tag	Unique string that identifies the source

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted, tag is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLE	No sources tagged by tag exist in the pool

Precondition:: Create a sound pool handle by calling sound_pool_create(); Load source to the pool by calling sound_pool_load_source_from_file()

See also:: sound_pool_create(); sound_pool_load_source_from_file()

int sound_pool_unset_state_changed_cb ( sound_pool_h pool )

Unsets the callback for handling sound pool state change.

Since :: 4.0

Parameters:

[in] pool The sound pool handle

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

Return values:

SOUND_POOL_ERROR_NONE	Successful
SOUND_POOL_ERROR_INVALID_PARAMETER	Invalid parameter (pool is NULL or corrupted)

Precondition:: Create a sound pool handle by calling sound_pool_create(); Set state change callback by calling sound_pool_set_state_changed_cb()

See also:: sound_pool_create(); sound_pool_set_state_changed_cb()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation