Tizen Native API  5.0
Sound Pool

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]poolThe sound pool handle
[in]prev_statePrevious pool state
[in]cur_stateCurrent pool state
[in]user_dataThe 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]poolThe sound pool handle
[in]idUnique stream identifier
[in]prev_statePrevious stream state
[in]cur_stateCurrent stream state
[in]user_dataThe 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

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

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

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

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

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]poolThe sound pool handle
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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

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]poolThe created sound pool handle
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL)
SOUND_POOL_ERROR_OUT_OF_MEMORYNot enough memory to create sound pool
SOUND_POOL_ERROR_INVALID_OPERATIONMaximal amount of sound pools is exceeded (maximum 8 pools allowed)
See also:
sound_pool_destroy()

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]poolThe sound pool handle
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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

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]poolThe sound pool handle will be destroyed
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid operation
Precondition:
Create sound pool handle by calling sound_pool_create()
See also:
sound_pool_create()

Gets the current state of pool.

Since :
4.0
Parameters:
[in]poolThe sound pool handle
[out]stateCurrent state of pool
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid 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]poolThe sound pool handle
[out]volumePool global volume in 0.0~1.0 range
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid 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]poolThe sound pool handle
[in]file_nameThe name of the file that contains sound data
[in]tagUnique string that will be used to identify source
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid 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_MEMORYNot enough memory to allocate source
SOUND_POOL_ERROR_NO_SUCH_FILENo file determined by file_name
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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]poolThe sound pool handle
[in]callbackThe callback that will be called after pool state will be changed. callback will be called synchronously
[in]user_dataThe user data to be passed to the callback
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid 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_pool_state_change_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]poolThe sound pool handle
[in]volumePool global volume in 0.0~1.0 range
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted, or volume isn't in 0.0~1.0 range)
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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]poolThe sound pool handle
[in]idUnique stream identifier
[out]priorityStream 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_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted, or priority is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo 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]poolThe sound pool handle
[in]idUnique stream identifier
[out]stateCurrent state of stream
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted, or state is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo 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]poolThe sound pool handle
[in]idUnique stream identifier
[out]volumeStream volume in 0.0~1.0 range
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted, or volume is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo 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]poolThe sound pool handle
[in]idUnique stream identifier
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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]poolThe sound pool handle
[in]tagUnique string that identifies source
[in]loopNumber of times stream will be repeated (pass 0 if stream should be repeated continuously)
[in]volumeStream volume in 0.0~1.0 range
[in]priorityStream priority (0 = lowest priority). Check sound_pool_stream_set_priority() documentation for details on prioritization rules.
[in]priority_policyStream 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]callbackThe 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_dataThe user data to be passed to the callback
[out]idUnique 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_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid 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_AVAILABLENo sources tagged by tag exist in the pool
SOUND_POOL_ERROR_OUT_OF_MEMORYNot enough memory to allocate new sound stream
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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]poolThe sound pool handle
[in]idUnique stream identifier
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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]poolThe sound pool handle
[in]idUnique stream identifier
[in]priorityStream priority (0 = lowest priority)
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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]poolThe sound pool handle
[in]idUnique stream identifier
[in]volumeStream volume in 0.0~1.0 range
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted, or volume isn't in 0.0~1.0 range)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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]poolThe sound pool handle
[in]idUnique stream identifier
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo streams identified by id exist in the pool
SOUND_POOL_ERROR_INVALID_OPERATIONInvalid 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]poolThe sound pool handle
[in]tagUnique string that identifies the source
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid parameter (pool is NULL or corrupted, tag is NULL)
SOUND_POOL_ERROR_KEY_NOT_AVAILABLENo 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()

Unsets the callback for handling sound pool state change.

Since :
4.0
Parameters:
[in]poolThe sound pool handle
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_POOL_ERROR_NONESuccessful
SOUND_POOL_ERROR_INVALID_PARAMETERInvalid 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()