Version
menu_open

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

Wwise Authoring Plug-in

Managing Plug-in Media

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.

Cette page a-t-elle été utile ?

Besoin d'aide ?

Des questions ? Des problèmes ? Besoin de plus d'informations ? Contactez-nous, nous pouvons vous aider !

Visitez notre page d'Aide

Décrivez-nous de votre projet. Nous sommes là pour vous aider.

Enregistrez votre projet et nous vous aiderons à démarrer sans aucune obligation !

Partir du bon pied avec Wwise