Version

    Other Documentation

menu_open
Wwise SDK 2018.1.11
Integration Details - MIDI

Introduction

The SDK API provides functions to post MIDI events to the sound engine. The types of MIDI events that may be posted are:

  • note-on event.
  • note-off event.
  • and continuous controller (CC) event.

For MIDI events to produce sound they must have a target synthesizer. The synthesizer is a collection of Wwise objects created by the Wwise user in the project's Actor-Mixer hierarchy. Note-on events will typically play the targeted Actor-Mixer object or one of its descendants. If played, the Actor-Mixer object will stop once it has:

  • reached the end of its source if it is not set to loop,
  • or a corresponding note-off event (same note and channel) is sent to the same target.

Integrating MIDI Events in Your Game

The AK::SoundEngine::PostMIDIOnEvent "PostMIDIOnEvent" function queues MIDI events in the sound engine. The function takes as arguments:

  • the MIDI event.
  • the time at which the event is to take place (relative to the current frame).
  • an event ID.
  • a game object ID.

The sound engine groups posted MIDI events into sequences. Each sequence is identified by the following:

  • a Game Object ID; a function parameter,
  • a Wwise Object ID; obtained from the target object of each play action in the event corresponding to event ID. See Integrating Events for more details regarding Events.

Thus, it is possible to post the same MIDI event(s) to multiple targets simultaneously. For example, suppose we have:

  • event EV1, which has play actions for both Wwise Objects W0 and W1,
  • event EV2, which has a play action for Wwise Object W0.

If we post MIDI event ME1 to EV1 with Game Object GO, then the sound engine will add MIDI event ME1 to the MIDI sequences W0-GO and W1-GO. If we then post MIDI event ME2 to event EV2, the sound engine will add MIDI event ME2 to the MIDI sequence W0-GO.

Calls to AK::SoundEngine::PostMIDIOnEvent add MIDI events to the MIDI sequences. However, no processing is done until the AK::SoundEngine::RenderAudio function has been called. Each call to AK::SoundEngine::RenderAudio processes the message queue, and may produce any number of audio frames; depending on how much time has elapsed since the previous call to RenderAudio. For each frame processed by RenderAudio, the sound engine advances all MIDI sequences by one frame.

Updating MIDI Sequences

It is important that each a MIDI sequence be played by the sound engine at the exact time intended by the application. There are two ways a MIDI sequence may be posted to the sound engine.

If the entire MIDI sequence is known, and it is known that the timing of the MIDI sequence will not change, then the entire MIDI sequence may be posted with one call to AK::SoundEngine::PostMIDIOnEvent.

However if that is not the case, then the MIDI sequence will have to be updated at each frame. The AK::SoundEngine::PostMIDIOnEvent function may be called at any moment, and anywhere in the application. However, calling this function in a thread other than the main audio thread may lead to synchronization issues. Calls to AK::SoundEngine::PostMIDIOnEvent only post the events in the sound engine's message queue. The message queue is processed during a call to AK::SoundEngine::RenderAudio, and such a call may lead to any number of processed audio frames. To ensure proper synchronization, it is recommended that the application register a global callback function as follows:

  • AK::SoundEngine::RegisterGlobalCallback( &MyCallbackFunction, AkGlobalCallbackLocation_PreProcessMessageQueueForRender );

The registered function will be called by the sound engine at each audio frame. The application can use the callback function to keep track of audio frames processed by the sound engine. Thus, posting MIDI events in the callback function will ensure proper synchronization.

Stopping a MIDI Sequence

Call the AK::SoundEngine::StopMIDIOnEvent "StopMIDIOnEvent" function to stop a MIDI sequence. The function accepts an Event ID and a Game Object ID as parameters. Either of these parameters can be set to their invalid values to act as wild cards. Thus, if both Event ID and Game Object ID are set to invalid then all MIDI sequences are stopped.

A call to this function will clear the MIDI sequence(s) and stop any playing sounds.

For examples of integrating MIDI, refer to Quick Start Sample Integration - MIDI.


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