How to Integrate SoundFrame

Relevant Files

To use SoundFrame, you will need the following files:

include/AK/SoundFrame/SF.h and include/AK/SoundFrame/SFObjects.h
These files need to be included for the SoundFrame client.
lib/Debug/SFLib.lib
This file is the debug library for the SoundFrame client.
lib/Release/SFLib.lib
This file is the release library for the SoundFrame client.

The following sample is also available:

samples/SoundFrame/SFTest/*
These files are related to the SoundFrame Test sample application.

Working with SoundFrame

The following example is the basic code structure of the SoundFrame client:

#include <AK/SoundFrame/SF.h>

class SoundFrameClient
    : public AK::SoundFrame::IClient
{
    AK::SoundFrame::ISoundFrame * m_pSoundFrame;
public:

    SoundFrameClient()
        : m_pSoundFrame( NULL )
    {
        AK::SoundFrame::Create( this, &m_pSoundFrame );
        
        if ( m_pSoundFrame )
            m_pSoundFrame->Connect();
    }

    ~SoundFrameClient()
    {
        if ( m_pSoundFrame )
            m_pSoundFrame->Release();
    }

    // SoundFrame::IClient methods

    virtual void OnConnect( bool in_bConnect ) {}
    virtual void OnEventNotif( Notif in_eNotif, AkUniqueID in_eventID ) {}
    virtual void OnDialogueEventNotif( Notif in_eNotif, AkUniqueID in_dialogueEventID ) {}
    virtual void OnSoundObjectNotif( Notif in_eNotif, AkUniqueID in_soundObjectID ) {}
    virtual void OnStatesNotif( Notif in_eNotif, AkUniqueID in_stateGroupID ) {}
    virtual void OnSwitchesNotif( Notif in_eNotif, AkUniqueID in_switchGroupID ) {}
    virtual void OnGameParametersNotif( Notif in_eNotif, AkUniqueID in_gameParameterID ) {}
    virtual void OnTriggersNotif( Notif in_eNotif, AkUniqueID in_triggerID ) {}
    virtual void OnArgumentsNotif( Notif in_eNotif, AkUniqueID in_argumentID ) {}
    virtual void OnEnvironmentsNotif( Notif in_eNotif, AkUniqueID in_environmentID ) {}
    virtual void OnGameObjectsNotif( Notif in_eNotif, AkGameObjectID in_gameObjectID ) {}
}

Caution: In order for SoundFrame to receive messages from the Wwise authoring tool, AK::SoundFrame::ISoundFrame::Connect must create a Window. The function must be called from the same thread as the message pump of the application.

While the client holds SoundFrame, it can use it to interact with Wwise in the following ways:

Working with Wwise Objects

SoundFrame gives you the power to integrate Wwise objects into your applications. With SoundFrame, you can perform tasks such as event playback, switch assignation, and environment setting. The following Wwise objects can be used with SoundFrame:

Events
Dialogue Events
States
Switches
Game Parameters
Triggers
Arguments
Environmental Effects.

Referencing Wwise Objects

When using Wwise objects in your applications, it is important to know how to reference them. There are two ways to reference a Wwise object:

By name: The preferred way for a game that uses SoundBanks containing strings.
By AudioEngine ID: The preferred way for a game that uses SoundBanks without strings.

Integrating Wwise Objects into Your Application

When you want to integrate Wwise objects into your applications, you can enable this functionality using either of the following methods:

Send to SoundFrame command in Wwise (for events only)
Listen to Notif_Push notifications in your IClient::OnEventNotif.
Drag and Drop
Use ISoundFrame::GetDnDType and the various drag and drop process methods in your drag-and-drop handlers.

Working with Attenuation

When your projects include attenuation, it is useful to see the maximum attenuation values that are defined in Wwise displayed in your applications. With SoundFrame, you can display attenuation values and also register for notifications when these values are modified in Wwise.

Displaying the Attenuation

From SoundFrame's perspective, attenuation is a property of a sound object (refer to ISoundObject for more information). To display attenuation values in your application:

From an event, follow the path: IEvent > IActionList > IAction > ISoundObject.

Registering for Attenuation Change Notifications

After you have adapted your application to properly display attenuation values, it is preferable that you register for attenuation change notifications.

To register for attenuation change notifications:

Call AK::SoundFrame::ISoundFrame::ListenAttenuation.

You will then receive notifications of type Notif_Changed in AK::SoundFrame::IClient::OnSoundObjectNotif when attenuation values are modified in Wwise.

To unregister from attenuation change notifications:

Call AK::SoundFrame::ISoundFrame::ListenAttenuation with empty parameters. The attenuation notifications will no longer be sent.

Working with the Sound Engine API

SoundFrame gives you access to most of the Sound Engine API. This enables you to play back Events as well as modify States, Switches, RTPCs, Triggers, and environments in your application. This API lets you simulate real game scenarios directly in Wwise without requiring a working game engine or even having to generate SoundBanks.

Enabling Playback of an Event

If you want users to be able to play back Events from within your applications, you will have to enable Event playback as follows:

Call ISoundFrame::PlayEvents.

Note: When your application goes into Play mode many events will be fired in a long sequence. Therefore, it is recommended to set the playback mode to True using ISoundFrame::SetPlayBackMode during playback. When the playback is done you can set the playback mode back to False. Setting the playback mode to False will stop all playbacks in Wwise.

Modifying Game States and Switches

SoundFrame lets you change the active states and switches in your applications to simulate real game scenarios. The following methods let you do this:

ISoundFrame::SetCurrentState
ISoundFrame::SetCurrentSwitch

Creating Game Objects and Modifying Their Positions

SoundFrame gives you access to methods that let you create or remove game objects and modify their positions in three dimensions. It also lets you define listeners and place them where you want within your applications. To do so, use the following methods:

ISoundFrame::RegisterGameObject
ISoundFrame::UnregisterGameObject
ISoundFrame::SetActiveListeners
ISoundFrame::SetPosition
ISoundFrame::SetListenerSpatialization

Modifying RTPCs, Triggers, and Environments

SoundFrame allows you to modify RTPCs, environments, as well as launch interactive music triggers so that you can create even more realistic game simulations. You can also define the obstruction and occlusion levels of your game objects. To do so, use the following methods:

ISoundFrame::SetRTPCValue
ISoundFrame::PostTrigger
ISoundFrame::SetGameObjectAuxSendValues
ISoundFrame::SetGameObjectOutputBusVolume
ISoundFrame::SetEnvironmentVolume
ISoundFrame::BypassEnvironment
ISoundFrame::SetObjectObstructionAndOcclusion

Working with SoundBanks in SoundFrame

SoundBanks can be created and populated with events manually by the Wwise user in the SoundBank Manager.

However, if you use another application, such as a 3D application or level editor to integrate events into your game, you can generate a SoundBank definition file from that application and then import it in Wwise to automatically create and populate SoundBanks.

SoundBank Definition File Format

A definition file is a text file that lists all the events in your game, classified by SoundBank. The definition file must include the name of the SoundBank and the corresponding event name, separated by a tab. The following illustration demonstrates how a definition file should be written so that it can be read by Wwise.

The definition file can also include special keywords that define the types of project elements that will be packaged in the SoundBanks. The following keywords can be used:

Event: specifies that event information will be packaged with the SoundBank.
Structure: specifies that sound and music structure information will be packaged with the SoundBank.
Media: specifies that audio media files will be packaged with the SoundBank.

In the definition file, one or more of these keywords can be added after the event name, with each one being separated by a tab. If no keywords are included in the definition file, all project elements and media will be packaged in the SoundBank. The following illustration demonstrates how these keywords should be used within a definition file.

If your game is not using strings for event names, you can use any of the following systems to define the events in the definition file:

Hexadecimal
Decimal

The following illustration demonstrates how to define events in a definition file using the four different systems.

Event IDs are available through SoundFrame in various functions:

AK::SoundFrame::IEvent::GetID(): Numeric ID (can be written as hexadecimal or decimal in the definition file)
AK::SoundFrame::IClient::OnEventNotif(): The numeric ID of the event is passed as a parameter

Refer to AK::SoundFrame::IEvent, AK::SoundFrame::IClient and AK::SoundFrame::ISoundFrame for more details.

Importing SoundBank Definition Files in Wwise

SoundBank definition files can either be imported manually, or through SoundFrame.

Importing SoundBank Definition Files through SoundFrame

If your application generates a SoundBank definition file, you can make a call to notify Wwise that a new definition file needs to be imported.

To notify Wwise that a new SoundBank definition file needs to be imported:

Call AK::SoundFrame::ISoundFrame::ProcessDefinitionFiles.

Note: Note that the SoundBanks created by the definition file are located in the default SoundBank Work Unit. To create your SoundBank in a different Work Unit you need to import definition file manually in Wwise.

If your application does not generate a SoundBank definition file, you can make a call to notify Wwise that the SoundBanks need to be regenerated.

To notify Wwise that the SoundBanks need to be regenerated:

Call AK::SoundFrame::ISoundFrame::GenerateSoundBanks.

Importing a SoundBank Definition File Manually

To create or update SoundBanks in Wwise by importing a definition file:

From the SoundBanks tab in the Project Explorer, right click on a Work Unit to open the contextual menu and choose "Import SoundBank Definition ...". The Open dialog box opens.
Navigate to the location where the definition file was created.
Click Open.
The Import Definition Log dialog box opens.
Review the import activity in the log. The import activity can be any one of the following:
- SoundBank Created: A new SoundBank has been created.
- Event Added: A new event has been added to an existing or new SoundBank.
- Event Deleted: An event has been deleted from an existing SoundBank (see the note below for details).
- Event Missing: An event listed in the file no longer exists in the project or has yet to be created.
- No Change Detected: The imported SoundBank is identical to the one already in Wwise.
Click Close.
The SoundBanks that are defined in the definition file are created and/or updated in Wwise.

Note: Wwise remembers if an Event was added manually by a user, or automatically by importing a SoundBank definition file. Only Events that were added by importing a definition file will be removed from the SoundBank during a subsequent definition file importation. Manually added Events will not be removed from the SoundBank even if they are not listed in the definition file.

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 2017.2.10