Wwise SDK 2023.1.9

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
:   public AK::Wwise::Plugin::AudioPlugin
,   public AK::Wwise::Plugin::RequestObjectMedia
,   public AK::Wwise::Plugin::Notifications::ObjectMedia
,   public AK::Wwise::Plugin::RequestHost
{
    void NotifyPluginMediaChanged() override
    {
        // React to change
        // ...
 
        // Notify Wwise the data needs to be reconverted
        m_host.NotifyInternalDataChanged(
            AK::IAkPluginParam::ALL_PLUGIN_DATA_ID,
            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:

class MyPlugin
:   public AK::Wwise::Plugin::AudioPlugin,
,   public AK::Wwise::Plugin::MediaConverter

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

#include <AK/Tools/Common/AkFNVHash.h>
#include <filesystem>
#include <ctype.h>
 
AK::Wwise::Plugin::ConversionResult MyPlugin::ConvertFile(
    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)
    {
        return AK:Wwise::Plugin::ConversionFailed;
    }
    return AK::Wwise::Plugin::ConversionSuccess;
}
 
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.

AKRESULT RunTimeEffect::Init(
    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.

Definition: AkWwiseSDKVersion.cs:31

AK_Fail

@ AK_Fail

The operation failed.

Definition: AkTypes.h:134

AkFNVHash.h

AK.Wwise::Plugin::V1::Notifications::ObjectMedia_

Definition: HostObjectMedia.h:521

AK.Wwise::ConversionFailed

@ ConversionFailed

Definition: Utilities.h:192