Version
menu
Wwise SDK 2025.1.0
List of all members | Public Attributes
AkCmd_SeekOnEvent Struct Reference

#include <AkCommandTypes.h>

Public Attributes

AkUniqueID eventID
 Unique ID of the event. More...
 
union {
   AkTimeMs   absolute
 Desired position where playback should restart, in milliseconds. More...
 
   AkReal32   relative
 Desired position where playback should restart, expressed in a percentage of the file's total duration, between 0 and 1.f (see note above about infinite looping sounds) More...
 
} position
 
AkGameObjectID gameObjectID
 (optional) Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects More...
 
AkPlayingID playingID
 (optional) Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID to seek on all active actions of this event ID. More...
 
AkUInt8 isPositionRelative
 Determines whether the position should be interpreted as absolute (milliseconds) or relative (%). More...
 
AkUInt8 seekToNearestMarker
 If non-zero, the final seeking position will be made equal to the nearest marker (see note above) More...
 

Detailed Description

Seeks inside all playing objects that are referenced in Play Actions of the specified Event.

Notes:

  • This works with all objects of the Containers hierarchy, including Music Segments and Music Switch Containers.
  • There is a restriction with sounds that play within a continuous sequence. Seeking is ignored if one of their ancestors is a continuous (random or sequence) container with crossfade or trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless the sound that is currently playing is the first sound of the sequence.
  • Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
  • Sounds/segments are stopped if position is greater than their duration.
  • position is clamped internally to the beginning of the sound/segment.
  • If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker. With objects of the Containers hierarchy, markers are embedded in wave files by an external wave editor. Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking to nearest marker. In the case of interactive music objects (Music Segments, Music Switch Containers, and Music Playlist Containers), user (wave) markers are ignored: seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
  • This method posts a command in the sound engine queue, thus seeking will not occur before the audio thread consumes it (after a call to RenderAudio()).

Notes specific to Music Segments:

  • With Music Segments, position is relative to the Entry Cue, in milliseconds. Use a negative value to seek within the Pre-Entry.
  • Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification in order to restart them if required.
  • In order to restart at the correct location, with all their tracks synchronized, Music Segments take the "look-ahead time" property of their streamed tracks into account for seeking. Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the value that was passed to the method. Use AK::MusicEngine::GetPlayingSegmentInfo() to query the exact position of a segment. Also, the segment will be silent during that time (so that it restarts precisely at the position that you specified). AK::MusicEngine::GetPlayingSegmentInfo() also informs you about the remaining look-ahead time.

Notes specific to Music Switch Containers:

  • Seeking triggers a music transition towards the current (or target) segment. This transition is subject to the container's transition rule that matches the current and defined in the container, so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
  • If the specified time is greater than the destination segment's length, the modulo is taken.

This command can fail for the following reasons:

  • AK_InvalidParameter: eventID is invalid.
  • AK_IDNotFound: Event was not found, or gameObjectID is specified but not a registered game object.
See also

Definition at line 641 of file AkCommandTypes.h.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise