Adding Media to an Audio Plug-in

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

There are many benefits of 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)
Allow per platforms specific conversion of data
Allow end-user to select which SoundBanks to hold the data

Override the function AK::Wwise::IAudioPlugin::SetPluginObjectMedia and store the pointer for later use. This function will be called at the initialization of the Wwise plug-in (authoring side). By implementing this function, you will receive an interface to a IPluginObjectMedia*, which allows to you to manage media files.

class MyEffect : public AK::Wwise::IAudioPlugin
{
    ...
    virtual void SetPluginObjectMedia( IPluginObjectMedia * in_pObjectMedia )
    {
        m_pObjMedia = in_pObjectMedia;
    }

    AK::Wwise::IPluginObjectMedia * m_pObjMedia;
}

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

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

Later, you can call AK::Wwise::IPluginObjectMedia::InvalidateMediaSource to request a conversion of the media files. Override the function to be notified when the plug-in data changes

virtual void NotifyPluginMediaChanged()
{
    // 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::IPluginObjectMedia for more information.

Converting the Media for Runtime

You may want to convert your media for runtime. To implement conversion functions, you need to inherit from AK::Wwise::IPluginMediaConverter, and implement the required functions (including ConvertFile and GetCurrentConversionSettingsHash) that will allow you to convert your imported original wav to an appropriate format for the real-time component.

class MyEffect : public AK::Wwise::IAudioPlugin , public AK::Wwise::IPluginMediaConverter

Once you implement all functions in AK::Wwise::IPluginMediaConverter, you can override the function GetPluginMediaConverterInterface() to tell Wwise you want to convert your media.

virtual AK::Wwise::IPluginMediaConverter* GetPluginMediaConverterInterface()
{
    return this;
}

Here is an example implementation the AK::Wwise::IPluginMediaConverter functions:

#include "AK\Tools\Common\AkFNVHash.h"
 
AK::Wwise::ConversionResult YourPlugin::ConvertFile( 
    const GUID & in_guidPlatform,
    LPCWSTR in_szSourceFile,
    LPCWSTR in_szDestFile,
    AkUInt32 in_uSampleRate, 
    AkUInt32 in_uBlockLength, 
    AK::Wwise::IProgress* in_pProgress, 
    AK::Wwise::IWriteString* io_pError ) 
{
    // Convert the original source to a converted file
    // At minimum, copy the original file to converted
    ::CopyFile(in_szSourceFile,in_szDestFile, FALSE);
    return AK::Wwise::ConversionSuccess;
}
 
ULONG YourPlugin::GetCurrentConversionSettingsHash( const GUID & in_guidPlatform, AkUInt32 in_uSampleRate ,  AkUInt32 in_uBlockLength ) 
{
    AK::FNVHash32 hashFunc;

    // Generate a Hash from effect parameters that have an influence on the conversion
    // Take the source file name
    CString szInputFileName;
    m_pObjMedia->GetMediaSourceFileName( szInputFileName.GetBuffer( _MAX_PATH ), _MAX_PATH );
    szInputFileName.ReleaseBuffer();
    szInputFileName.MakeLower();
    return hashFunc.Compute( (unsigned char *)(LPCTSTR)szInputFileName, szInputFileName.GetLength()*sizeof(TCHAR) ); 
}

Plug-in Definition

In the Plug-in definition file, ensure you have the CanReferenceDataFile element set to true.

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

Runtime Plug-In

Using Plug-in Media at Runtime

In the real-time component of your plug-in, when implementing AK::IAkEffectPlugin, you will receive an AK::IAkEffectPluginContext pointer in the 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
    ...
}

Usage in Wwise

Using Plug-in Media in Effects Inside Bus

In Wwise, all bus effects are stored in the Init.bnk. To avoid having the Init.bnk too large, the plug-in media is not automatically added to Init.bnk. You will need to manually add the effect shareset, or the bus to a separate soundbank.

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.

Get started with Wwise

Wwise SDK 2015.1.9