Table of Contents

Wwise SDK 2021.1.1
Adding Media to an Audio Plug-in

The plug-in media system allows a plug-in (effect, source, sink, or mixer) to store binary data files in the project by leveraging the Wwise architecture.

There are many benefits to using plug-in media as opposed to using custom data in the plug-in:

  • Built-in persistence of data
  • Source Control integration (using work-group features)
  • Per platform specific conversion of data allowed
  • End-user selection of SoundBanks to hold the data allowed

Wwise Authoring Plug-in

Managing Plug-in Media

You can request the Object Media service by deriving AK::Wwise::Plugin::RequestObjectMedia in your plug-in backend. This will provide the member m_objectMedia to access the methods of the service. To receive notifications about the object media, such as when it has been changed by the user, derive from AK::Wwise::Plugin::NotificationsObjectMedia and override the AK::Wwise::Plugin::NotificationsObjectMedia::NotifyPluginMediaChanged() method.

class MyPluginBackend : public AK::Wwise::Plugin::AudioPlugin
, public AK::Wwise::Plugin::NotificationsObjectMedia
{
void NotifyPluginMediaChanged() override
{
// React to change
// ...
// Notify Wwise the data needs to be reconverted
m_host.NotifyInternalDataChanged(
true /* in_bMakeProjectDirty */
);
}
};

You can import media files by calling AK::Wwise::Plugin::ObjectMedia::SetMediaSource() . When importing media, it will be copied to the plug-in's "Originals" directory and will be managed completely by Wwise. To add a plug-in media file at index 0:

m_pObjMedia->SetMediaSource( pszFilename, 0, bReplace );

After this is done, you can call AK::Wwise::Plugin::ObjectMedia::InvalidateMediaSource() to request a conversion of the media files.

Override the function NotifyPluginMediaChanged to be notified when the plug-in data changes.

void NotifyPluginMediaChanged() override
{
// React to changes
// ...
// Notify Wwise the data needs to be reconverted
m_pPSet->NotifyInternalDataChanged( AK::IAkPluginParam::ALL_PLUGIN_DATA_ID );
}

Refer to documentation of functions of AK::Wwise::Plugin::ObjectMedia for more information.

Converting the Media for Runtime

You may want to convert your imported original WAV media at runtime to an appropriate format for the real-time component. To implement conversion functions, you need to inherit from AK::Wwise::Plugin::MediaConverter and implement the required functions:

Here is an example implementation of the AK::Wwise::Plugin::MediaConverter functions:

#include <filesystem>
#include <ctype.h>
AK::Wwise::Plugin::ConversionResult MyPlugin::ConvertFile(
const GUID& in_guidPlatform,
const BasePlatformID& in_basePlatform,
const char* in_szSourceFile,
const char* in_szDestFile,
AkUInt32 in_uSampleRate,
AkUInt32 in_uBlockLength,
IProgress* in_pProgress,
IWriteString* io_pError)
{
// Convert the original source to a converted file.
// At minimum, copy the original file to converted
std::filesystem::copy(in_szSourceFile, in_szDestFile);
}
uint32_t MyPlugin::GetCurrentConversionSettingsHash(
const GUID& in_guidPlatform,
AkUInt32 in_uSampleRate,
AkUInt32 in_uBlockLength)
{
AK::FNVHash32 hashFunc;
// Generate a Hash from parameters that have an influence on the conversion.
// Take the source file name.
char szInputFileName[_MAX_PATH];
auto size = m_pObjMedia->GetMediaSourceFileName(szInputFileName, _MAX_PATH);
if (size == 0)
return 0;
for (int i = 0; i < size; ++i)
{
szInputFileName[i] = tolower(szInputFileName[i]);
}
return hashFunc.Compute(szInputFileName, size);
}

Plug-in Definition

In the plug-in definition file (i.e., the plug-in XML file), ensure you have the CanReferenceDataFile element set to true.

<PluginModule>
<EffectPlugin Name="YOUR_PLUGIN" CompanyID="???" PluginID="???">
<PluginInfo MenuPath="???">
<PlatformSupport>
<Platform Name="Windows">
...
<CanReferenceDataFile>true</CanReferenceDataFile>
</Platform>
<Platform Name="XboxOne">
...
<CanReferenceDataFile>true</CanReferenceDataFile>
</Platform>

Runtime Plug-In

Using Plug-in Media at Runtime

In the Sound Engine part of your plug-in, when implementing AK::IAkEffectPlugin, you will receive an AK::IAkEffectPluginContext pointer in the Init(...) function. From the AK::IAkEffectPluginContext, you can call AK::IAkPluginContextBase::GetPluginMedia to obtain the converted media that was packaged in Wwise SoundBanks.

AK::IAkPluginMemAlloc* in_pAllocator, // Memory allocator interface.
AK::IAkEffectPluginContext* in_pFXCtx, // FX Context.
const AkAudioFormat& in_rFormat // Audio input format. )
{
AkUInt8 * pPluginData = NULL;
AkUInt32 uPluginDataSize;
in_pFXCtx->GetPluginMedia( 0, pPluginData, uPluginDataSize );
if ( pPluginData == NULL )
return AK_Fail; // No point in instantiating plug-in without impulse response.
...
}
Note: This example shows how to use effect plug-in media at runtime. However, it could also illustrate how to use another plug-in type, such as a source plug-in. In that case, you would be implementing AK::IAkSourcePlugin and receiving an AK::IAkSourcePluginContext pointer.

Usage in Wwise

Using Plug-in Media in Bus Effects

In Wwise, all bus Effects are stored in the Init.bnk. To minimize the size of the Init.bnk, plug-in media is not automatically added to the Init.bnk. You must manually add the Effect ShareSet or the bus to a separate SoundBank.

@ AK_Fail
The operation failed.
Definition: AkTypes.h:130
@ ConversionSuccess
Definition: PluginDef.h:143
AKRESULT
Standard function call result.
Definition: AkTypes.h:127
virtual void GetPluginMedia(AkUInt32 in_dataIndex, AkUInt8 *&out_rpData, AkUInt32 &out_rDataSize)=0
AKSOUNDENGINE_API AKRESULT Init(const AkCommSettings &in_settings)
#define NULL
Definition: AkTypes.h:47
CPluginInfo PluginInfo
Definition: PluginDef.h:970
Wwise API for general Audio Plug-in's backend.
Definition: AudioPlugin.h:134
uint8_t AkUInt8
Unsigned 8-bit integer.
Definition: AkTypes.h:75
ConversionResult
Conversion error code.
Definition: PluginDef.h:142
virtual void NotifyPluginMediaChanged()
This function is called by Wwise when any of the plug-in media changes.
Definition: HostObjectMedia.h:592
HashParams::HashType Compute(const void *in_pData, typename HashParams::SizeType in_dataSize)
Definition: AkFNVHash.h:104
static const AkPluginParamID ALL_PLUGIN_DATA_ID
Definition: IAkPlugin.h:668
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:77
Defines the parameters of an audio buffer format.
Definition: AkCommonDefs.h:63
Definition: PluginHelpers.h:46