This topic explains how to add support for Sidechain Mixes to custom Effect plug-ins. For information about how to use Sidechain Mixes with built-in Wwise plug-ins, see Using Sidechain Mixes with Effects.

Defining Sidechain Mixes in Wwise Authoring

In the Authoring part of an audio plug-in, you must configure a Sidechain Mix as a Reference element, as described in Properties Element. The following sample code demonstrates how to add a Sidechain Mix Reference element to the Properties element of the plug-in's XML description.

In order to read the Reference, your plug-in backend must derive from AK::Wwise::Plugin::RequestReferenceSet, which provides an m_referenceSet member to your class, through which you can access services that read the object ShortIDs of any References.

The m_referenceSet includes functions that read additional information from referenced objects, as described in ak_wwise_plugin_host_reference_set_v1. However, for Sidechain Mixes, the most important function is ak_wwise_plugin_host_reference_set_v1::GetReferenceShortId because it retrieves the Short ID of the referenced object. The Short ID is what other APIs in the sound engine use to interact with Sidechain Mixes, so that data must be included during SoundBank serialization.

Note: The Short ID of a Reference is also sent to the sound engine runtime through IAkPluginParam::SetParam, using the AudioEnginePropertyID as the in_lParamID parameter, when Wwise Authoring is connected to a runtime and live editing of the Effect is performed.

Using Sidechain Mixes in the Sound Engine

To interact with Sidechain Mixes during Effect plug-in execution, use the following APIs:

• IAkEffectPluginContext::GetSidechainMixChannelConfig
• IAkEffectPluginContext::SendToSidechainMix
• IAkEffectPluginContext::ReceiveFromSidechainMix

Channel configuration can change without notice during sound engine execution, either through modifications to the Sidechain Mix during live editing or through other sound engine systems such as calls to AK::SoundEngine::SetSidechainMixConfig. Therefore, we recommend that you always call AkEffectPluginContext::GetSidechainMixChannelConfig to read the channel configuration before you send to or receive from the Sidechain Mix.

To send to or receive from a Sidechain mix, you must do the following:

• Initialize an AkAudioBuffer.
• Provide the ShortID of the Sidechain Mix as a parameter.
• Provide an additional, 64-bit identifier as a scope for the Sidechain Mix.

You can use the scope to constrain a Sidechain Mix to a specific listener even if you use the definition across multiple listeners. Built-in Wwise plug-ins define the scope as either the Game Object ID of the voice or bus the plug-in is running on IAkEffectPluginContext::GetGameObjectInfo, or use a value of 0 for a Global scope.

To ensure interoperability with other plug-ins, we recommend that you follow this pattern, although it is not required to do so. For example, you might want to design a custom plug-in to allow a sound designer to target a remote Game Object ID, instead of the voice or bus's local Game Object ID.

Sending to and receiving from a Sidechain Mix also requires an AkAudioBuffer to be properly initialized in order for the operation to succeed.

To send to a Sidechain Mix, the AkAudioBuffer::channelConfig must match the Sidechain Mix's channel configuration and AkAudioBuffer::uMaxFrames must match the sound engine's audio granularity, such as the buffer length returned by IAkGlobalPluginContext::GetMaxBufferLength. After you call IAkEffectPluginContext::SendToSidechainMix, you can immediately destroy the AkAudioBuffer and AkAudioBuffer::pData. IAkEffectPluginContext::SendToSidechainMix internally copies all of the audio data provided, so the audio buffer does not have to stay allocated indefinitely.

Receiving from a Sidechain Mix has similar restrictions on AkAudioBuffer::channelConfig and AkAudioBuffer::uMaxFrames. You must also provide an appropriate memory allocation for AkAudioBuffer::pData before you call IAkEffectPluginContext::ReceiveFromSidechainMix. Calling IAkEffectPluginContext::ReceiveFromSidechainMix copies the Sidechain Mix's audio data to AkAudioBuffer::pData and replaces any existing data. It might be necessary to handle the AK_IDNotFound result because it can be returned if the Sidechain Mix ID is not loaded or registered by the sound engine, or if no data was sent to the Sidechain Mix in a previous sound engine frame. For example, you could zero out the audio buffer and continue with normal execution of the Effect.