Version
menu_open
Wwise SDK 2019.1.11
How to Create Wwise Audio Device Plug-ins (Sink Plug-ins)

Audio Device Plug-in Interface Implementation

Audio device plug-ins are the endpoints of the audio processing chain. Natural Audio devices are the OS sound systems, but there can be more possible outputs if additional hardware or drivers allow it. The role of the sink plug-in is to take the final mixed audio samples and transfer them to the device, in the format the device understands.

Sound Engine Component

On the sound engine side, writing an audio device plug-in consists of implementing the AK::IAkSinkPlugin interface. Only the functions specific to this interface are covered there. Refer to How to Create Wwise Sound Engine Plug-ins for information about interface components shared with other plug-in types ( AK::IAkPlugin interface). Also refer to the provided AkSink plug-in for sample code (Samples).

An audio device is always specified through the plug-in it is using (Audio Device ShareSet) and a specific device ID. This device ID has no meaning for the Wwise sound engine, it is for the sole purpose of the plug-in implementor to discriminate devices where many of the same type exists. It is passed by the game through the AkOutputSettings::idDevice parameter used in AK::SoundEngine::Init and AK::SoundEngine::AddOutput. For example, an audio device plug-in which would access Windows' audio devices could probably see many Windows' devices on a particular computer.

If your device doesn't need to discriminate between multiple devices, you can ignore that parameter. However, if you need to implement this, be aware that you MUST also support the "default device" concept, which is selected when the idDevice parameter is 0. Whether the first available device or a specific device is selected when receiving 0 is up to the plug-in programmer.

When a plug-in is used in the Wwise authoring application, parameters are updated regularly, whether or not the parameter supports RTPCs. This allows the plug-in to support runtime value changes of non-RTPC values if desired for Wwise usage. If you do not want your plug-in to support this at design-time, you should make a copy of the parameter values at initialization time to ensure they remain the same throughout the plug-in's duration.

Wwise Authoring DLL for an audio device plug-in

As any other plug-in, sink plug-ins need an authoring DLL counterpart. Please refer to How to Create a Wwise Plug-in DLL for the basic setup of the Wwise authoring component common to all plug-ins. Additionally, sink plug-ins can have an extra function exported from the DLL: AkGetSinkPluginDevices. This function's purpose is to fill the possible devices a user can select in the authoring tool to test, in the Audio Hardware Preferences dialog. This function is optional. If not implemented, it is expected that the plug-in will initialize to a "default" output when required.

AkGetSinkPluginDevices will be called by Wwise with the plug-in ID, a pre-allocated array of OutputDeviceDescriptor and the maximum size of the array. The maximum length of the device name is AK_MAX_OUTPUTDEVICEDESCRIPTOR (256 characters). You must modify the count (io_uMaxCount) to reflect the number of descriptors correctly filled.

void __stdcall AkGetSinkPluginDevices(unsigned short in_usCompanyID, unsigned short in_usPluginID, AK::Wwise::OutputDeviceDescriptor * io_Devices, unsigned int &io_uMaxCount)
{
if (in_usCompanyID == MY_COMPANY_ID && in_usPluginID == MY_PLUGIN_ID) // Validate the plug-in ID.
{
if (io_uMaxCount > 2) // Make sure there is enough space in the array.
{
wcscpy_s(out_rDesc.name, AK_MAX_OUTPUTDEVICEDESCRIPTOR, L"First Device"); // Copy the name of the first device. (This is visible to the user.)
io_Devices[0].idDevice = 1234; // ID of this device. (Can be anything meaningful for the plug-in; this will get passed back into IAkSinkPlugin::Init.)
wcscpy_s(out_rDesc.name, AK_MAX_OUTPUTDEVICEDESCRIPTOR, L"Second Device"); // Copy the name of the second device. (This is visible to the user.)
io_Devices[1].idDevice = 4567; // ID of this device. (Can be anything meaningful for the plug-in; this will get passed back into IAkSinkPlugin::Init.)
}
}
}

This function must be exported from the DLL, usually by adding a line in the DEF file, as seen below:

LIBRARY "MyPlugin"
EXPORTS
AkCreatePlugin
AkGetSinkPluginDevices
Note: If you want to expose your plug-in in Unity or Unreal, don't forget to create a runtime dynamic library (DLL, SO, DYLIB). This is different from the authoring DLL. See Dynamic Libraries.

Testing your Audio Device plug-in

After implementing the Wwise part of the plug-in (Writing the Wwise Authoring Part of an Audio Plug-in) and the sound engine part, you can test your plug-in following these steps:

  • In your Wwise Project, create an Audio Device ShareSet using your new plug-in. Give the ShareSet a unique name.
  • Generate you banks.
  • Make sure your plug-in was registered in your game code. See Wwise Sound Engine Plug-ins Overview.
  • Specify your audio device ID to be used in the initialization parameters of the sound engine. The ID in the AkOutputSettings is the hash of the name of the Audio Device ShareSet in the project, as given by AK::SoundEngine::GetIDFromString.

For example:

AkInitSettings initSettings;
AkPlatformInitSettings platformInitSettings;
AK::SoundEngine::GetDefaultInitSettings( initSettings );
AK::SoundEngine::GetDefaultPlatformInitSettings( platformInitSettings );
initSettings.settingsMainOutput.audioDeviceShareset = AK::SoundEngine::GetIDFromString("YourNewAudioDeviceSharesetNameHere");
AK::SoundEngine::Init( &initSettings, &platformInitSettings );

Alternatively, you can use your Audio Device plug-in with AK::SoundEngine::AddOutput.

AkOutputSettings outputSettings("YourNewAudioDeviceSharesetNameHere", 0 /*Default device*/)'
AK::SoundEngine::AddOutput(outputSettings);

For more information, refer to the following sections:

AkInitSettings::settingsMainOutput
AkOutputSettings settingsMainOutput
Main output device settings.
Definition: AkSoundEngine.h:224
AkMarkerCallbackInfo::strLabel
const char * strLabel
Label of the marker, read from the file.
Definition: AkCallback.h:120
AK::SoundEngine::Init
AKSOUNDENGINE_API AKRESULT Init(AkInitSettings *in_pSettings, AkPlatformInitSettings *in_pPlatformSettings)
AK::SoundEngine::RegisterGameObj
AKSOUNDENGINE_API AKRESULT RegisterGameObj(AkGameObjectID in_gameObjectID)
AkOutputSettings
Platform-independent initialization settings of output devices.
Definition: AkSoundEngine.h:129
AK.Wwise::OutputDeviceDescriptor::idDevice
AkUInt32 idDevice
Display name of the device. Null terminated. Note that the name can't be more than 256 characters inc...
Definition: AudioPlugin.h:674
AK::SoundEngine::GetDefaultInitSettings
AKSOUNDENGINE_API void GetDefaultInitSettings(AkInitSettings &out_settings)
AkMarkerCallbackInfo::uIdentifier
AkUInt32 uIdentifier
Cue point identifier.
Definition: AkCallback.h:118
AkMarkerCallbackInfo::uPosition
AkUInt32 uPosition
Position in the cue point (unit: sample frames)
Definition: AkCallback.h:119
AK::SoundEngine::GetDefaultPlatformInitSettings
AKSOUNDENGINE_API void GetDefaultPlatformInitSettings(AkPlatformInitSettings &out_platformSettings)
AK::SoundEngine::GetIDFromString
AKSOUNDENGINE_API AkUInt32 GetIDFromString(const char *in_pszString)
AK::SoundEngine::AddOutput
AKSOUNDENGINE_API AKRESULT AddOutput(const AkOutputSettings &in_Settings, AkOutputDeviceID *out_pDeviceID=NULL, const AkGameObjectID *in_pListenerIDs=NULL, AkUInt32 in_uNumListeners=0)
AkOutputSettings::audioDeviceShareset
AkUniqueID audioDeviceShareset
Definition: AkSoundEngine.h:142
AK::SoundEngine::PostEvent
AKSOUNDENGINE_API AkPlayingID PostEvent(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, AkUInt32 in_cExternals=0, AkExternalSourceInfo *in_pExternalSources=NULL, AkPlayingID in_PlayingID=AK_INVALID_PLAYING_ID)

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