Version

menu_open
Wwise SDK 2022.1.11
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::Notifications::ObjectMedia and override the AK::Wwise::Plugin::Notifications::ObjectMedia::NotifyPluginMediaChanged() method.

class MyPluginBackend
{
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 );

Override the function NotifyPluginMediaChanged to be notified when the plug-in data changes. NotifyPluginMediaChanged is triggered by any modifications to the media source.

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

If the plug-in definition file uses CanReferenceDataFile, you must convert your imported original WAV media at runtime to an appropriate format for the real-time component.

To implement conversion functions, 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>
const GUID& in_guidPlatform,
const BasePlatformID& in_basePlatform,
const AkOSChar* in_szSourceFile,
const AkOSChar* 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::error_code ec;
std::filesystem::copy(
in_szSourceFile,
in_szDestFile,
std::filesystem::copy_options::overwrite_existing,
ec
);
if (ec)
{
}
}
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 (the plug-in XML file), ensure that the CanReferenceDataFile element is 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.

Audiokinetic namespace.
@ AK_Fail
The operation failed.
Definition: AkTypes.h:202
@ ConversionFailed
Definition: Utilities.h:192
AKRESULT
Standard function call result.
Definition: AkTypes.h:199
char AkOSChar
Generic character string.
Definition: AkTypes.h:60
uint8_t AkUInt8
Unsigned 8-bit integer.
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:46
CPluginInfo PluginInfo
Definition: PluginDef.h:982
Wwise API for general Audio Plug-in's backend.
Definition: AudioPlugin.h:133
ConversionResult
Conversion error code.
Definition: PluginDef.h:141
virtual void NotifyPluginMediaChanged()
This function is called by Wwise when any of the plug-in media changes.
uint32_t AkUInt32
Unsigned 32-bit integer.
HashParams::HashType Compute(const void *in_pData, typename HashParams::SizeType in_dataSize)
Definition: AkFNVHash.h:105
static const AkPluginParamID ALL_PLUGIN_DATA_ID
Definition: IAkPlugin.h:683
Defines the parameters of an audio buffer format.
Definition: AkCommonDefs.h:62

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