Integration Details - GetSourcePlayPosition

Introduction

In certain circumstances, the game engine requires information about the current playback position of a particular sound. For example, games that support rendering video and audio contents in a synchronous manner must query the playback position of sounds to render game visuals appropriately. If this has to be done on a frame-by-frame basis (such as to synchronize lip movement and dialog), then playback position queries are preferable over markers. Another advantage of playback position queries is that the source files do not need to be edited. The AK::SoundEngine::GetSourcePlayPosition() method returns the time elapsed on an event's first sound playback.

Note: Markers are useful for signalling specific events happening in a sound file, as opposed to small increments in sound playback.

Integration

To be able to query the playback position of a source, you must pass the AK_EnableGetSourcePlayPosition flag to the AK::SoundEngine::PostEvent() method. This informs the sound engine that the source associated with this event should be given special consideration because AK::SoundEngine::GetSourcePlayPosition() can be called at any time for this AkPlayingID.

You can then call the AK::SoundEngine::GetSourcePlayPosition() method by passing the AkPlayingID received from the call to AK::SoundEngine::PostEvent() to get the current playback position of the source being played.

Example

The following piece of code illustrates the AK::SoundEngine::GetSourcePlayPosition() method's usage:

(...)
static AkPlayingID g_markersPlayingID = 0;
(...)

(...)

g_markersPlayingID = AK::SoundEngine::PostEvent( AK::EVENTS::PLAY_MARKERS_TEST, GAME_OBJECT_ID_MARKERS,
    AK_EnableGetSourcePlayPosition, NULL, NULL );

(...)

AkTimeMs uPosition = 0;
// Somewhere in your game loop (happens periodically):
AK::SoundEngine::GetSourcePlayPosition( g_markersPlayingID, &uPosition );
// Now handle lip synchronization by using uPosition

Limitations

• When an event contains multiple play actions, GetSourcePlayPosition() returns the position of the first source played by the target of the first play action occurring at time 0. When this source stops, the source whose position is returned is undefined.

• Continuous (random or sequence) containers return the position of the sound that is currently playing. When there are many sounds, the source whose position is returned is undefined. In crossfade or sample-accurate transitions, the next source returns its position only when the previous source has finished playing.

• When used with extrapolation, looping sources may overshoot the loop end for a short period of time when the loop occurs.

• Some virtual voices are killed when their priority falls under a certain threshold. When this happens, you might receive an error code from AK::SoundEngine::GetSourcePlayPosition(). You should always check the return value when calling AK::SoundEngine::GetSourcePlayPosition().

• Dynamic pitch changes may result in slightly offset playback positions for a short period of time during the transition.

See also:

• Integration Details - Events
• AK::SoundEngine::PostEvent()
• AK::SoundEngine::GetSourcePlayPosition()