Behavior of Virtual Voice

Samples Directory

/CRIWARE/SDK/pc/samples/criatomex/virtual_voice

Sample Description

Atom library uses a "Voice" to play back wave data.
Voice is an object which reads data, decodes sound, and performs playback.
Since one Voice is used to play back one wave data as a rule, the number of wave data that can be played back in application is limited to the number of Voices.

[Note]
Since the number of Voices can be specified when creating a Voice Pool, maximum number of simultaneous Voices can be freely controlled by application.
However, memory size and CPU load increase in accordance with the number of Voices used, so you should reduce the number of Voices to an acceptable level by the application.
In addition, in platforms where Voices use hardware voice, it is not possible to create Voices beyond hardware limit.

In addition to Voice, Atom library uses a virtual voice object called "virtual voice".
Virtual voice is an object which manages parameters, playback time, and Voices used for sound output.
Usually, since virtual voice works with Voice as a set, users do not have to know the existence of virtual voice. By changing Voice allocation method, it is possible to use virtual voices as virtual sound sources which do not have a Voice.

Default Behavior of Virtual Voice

By default, Atom library uses virtual voice and Voice as a set for playback.

For example, when the sound data is set to an AtomEx player and the criAtomExPlayer_Start function is called, AtomEx player allocates required number of virtual voices and Voices.
In doing so, sound is played back if both virtual voices and Voices could be allocated, but specified data is not played back if either could not be allocated.

[Note]
Since any number of virtual voices can be allocated when initializing the library, unless playback requests are issued beyond the number specified at library's initialization time, attempts to get virtual voice should fail.
In addition, even if allocation of Voices has failed, stub playback ID is returned. So, you do not change action depending on whether playback is possible or not.

Using Virtual Voice as Virtual Sound Source

When creating an AtomEx player, by setting voice_allocation_method of CriAtomExPlayerConfig to ::CRIATOMEXPLAYER_RETRY_VOICE_ALLOCATION, AtomEx player starts playback using only virtual voice when Voice cannot be allocated when starting playback.

Since the Voice has not been allocated, it will play back the sound; however, the parameter modification logging and the playback position management will be kept by virtual voice.
(Unlike when stub playback ID is returned, playback time can be acquired by the criAtomExPlayback_GetTime function.)

In addition, virtual voice periodically checks for free Voice during playback and get a Voice as soon as the one is freed.
Therefore, for the sound played back using the AtomEx player created with ::CRIATOMEXPLAYER_RETRY_VOICE_ALLOCATION specified, even if a Voice cannot be acquired when starting playback or Voice has been taken off by priority control, it player can resume playback when a Voice is freed later.

[Note]
When virtual voice succeeded in acquiring Voice again, it tries to resume playback at the position considering the time elapsed since playback has started as well as possible.
However, in codecs which do not support seek playback, or when the Voice was taken off before playback (when in CRIATOMEXPLAYBACK_STATUS_PREP state), sound data is played back from the start.
In addition, since there is a delay due to buffering for sound in streaming playback, there may be a gap between elapsed time and resuming position.

Following is a code to change Voice allocation method.

CriAtomExPlayerConfig player_config;
 
/* Set initial value to player creation configuration structure */
criAtomExPlayer_SetDefaultConfig(&player_config);
 
/* Change Voice allocation method */
/* Note: Player created with CRIATOMEXPLAYER_RETRY_VOICE_ALLOCATION specified       */
/*       resumes playback when a Voice is released  */
/*       even after a Voice was taken off from it.              */
player_config.voice_allocation_method = CRIATOMEXPLAYER_RETRY_VOICE_ALLOCATION;
 
/* Create a player */
app_obj->player = criAtomExPlayer_Create(&player_config, NULL, 0);

Although the sample allocates only one Voice, it handles pseudo three sounds: loop BGM, Voice, and SE.

The loop BGM is started to play as soon as the sample is invoked.
By playing back Voice or SE using button operation, a Voice which is playing loop BGM is taken off and the Voice or SE is played back. When its playback has finished, playback of the loop BGM resumes.

Attention

If you push the button too many times, virtual voice is exhausted and warning is displayed on the debugger, and loop BGM stops.

Return: List of Sample Programs