Wwise SDK 2021.1.2
When creating the interactive music for your game, you may need information about the music's beat. You can request this information from the sound engine using music notifications. The beat is determined by the main music segment currently playing. Since segments can have different time signatures, the beat will change based on the music currently playing. When no music is playing, there will be no notifications.
There are two types of music callbacks:
- Music Notifications: inform the callee of current music playback properties.
- Music Playlist Selection: allows the callee to force the selection of a music playlist's next item.
If you want to receive marker notifications about your music, there are specific things you need to be aware of when designing your application:
- When posting a play event that contains music with the beat you want to follow, you can add one or more of the following flags:
If you also want to receive a notification at the end of an event, you should use
AK_MusicSyncBeat since the flags are bitwise exclusive.
- Your callback function must have the following form:
- When your callback function is called, you first need to check what type of notification is passed. For example, if you only want to process
AK_MusicSyncBarnotifications, you should return when any other event type is received.
- Based on the type of notification, you can typecast
in_pCallbackInfointo the appropriate information structure type. For music notifications, it is AkMusicSyncCallbackInfo.
- When requesting multiple music notifications, they will be sent additionally. That means that if you register for both
AK_MusicSyncBarin a 4/4 time signature, you will receive 4 beat notifications per bar + one notification for the bar itself. Time "0" also counts for a beat and a bar and in most cases so does the
AK_MusicSyncEntry. This means that if you register for bars, beats and entry points, you will receive three callbacks back to back when the music starts.
- The tempo can be calculated by using the following formula: Tempo (in BPM) = 60.0 / fBeatDuration
- The upper value of the time signature can be calculated by using the following formula: Upper value = fBarDuration / fBeatDuration. This tells you how many beats per bar there are.
AK_MusicSyncExitwill only be sent if the end of the body of the current segment is reached. If the music switches to another segment before finishing the current one, the
AK_MusicSyncExitnofification will not be sent.
The callback function described above may also be used to manually manage a music playlist's next item selection. This is done by adding the following flag.
Upon reception of this type of event, the callback function must typecast the parameter
in_pCallbackInfo to type AkMusicPlaylistCallbackInfo.
The active playlist node is indicated by the member
playlistID. The sound engine selects the next item in the playlist node to play prior to the callback function call. The selection is contained in the members
uPlaylistItemDone is set to 0 then
uPlaylistSelection determines the next item to play in the playlist node. If
uPlaylistItemDone is not set to 0 then the current playlist node is to end (the parent node will then become the active node). Both members
uPlaylistItemDone may be changed by the callback function.
Currently, notification is sent when the buffer is passed down to the hardware. This means that there is a certain constant delay between when the notification is sent and the moment it actually gets played. This gives your application enough time to gather the information on the marker and process it before the sound associated with that marker is really played.
Note that this delay is platform-dependent.
The callbacks are done from the sound engine's main thread. This means that your application should gather all the information it needs from the notification and return immediately. If any processing needs to be done, it should be performed in a separate thread after the relevant information has been copied from the notification.
If the application holds the thread for too long, the sound engine might fall into an underrun state and the output might stop playing.
- See also
- Integration Details - Events