Blog homepage

Update on Wwise Support in Heavy

Audio Programming

Table of Contents

Intro

Heavy, or hvcc, is a tool that converts Pure Data patches into different compiled formats, like VST or Daisy firmware. Originally from Enzien Audio, this project is currently being actively developed by Wasted Audio.

Wwise support needed a refresh for quite some time and it's exactly what I've done recently. Apart from upgrading Wwise generator to Audiokinetic's new Plugin API, I've also added support for more channel configurations (5.1, 7.1, and 7.1.4), as well as an ability to post events from within a plugin. In this article, I'll go over new features with examples how to set them up.

One additional change was in how source code is generated. Instead of generating a Visual Studio project directly, a project in a format expected by Audiokinetic's Development Tools is produced instead. This simplifies matters for end-users and, as a bonus, allows to package plugins into bundles that can be installed from the Audiokinetic Launcher, which makes distribution a breeze.

I'll be using a brilliant Pure Data fork called plugdata for all examples, as it has a 'compile mode' which warns about using objects that are not supported by Heavy. In the future, I may also add support for building Wwise plugins straight from plugdata.

Installation and Usage

Hvcc is a Python tool that can be installed from command line:

pip install hvcc

This will install an hvcc command in the terminal. For example, this prints documentation:

hvcc -h

You'll also need to install Visual Studio with correct dependencies. Either 2019 or 2022 versions will work, but the latter only works with Wwise versions higher than 2022.1.5. Which exact components to install is listed in the documentation, so I'll just limit myself to dropping a screenshot of my VS2019 installation as an example:

wwise_hvcc_vs2019

Figure 1: List of Visual Studio packages that I have installed on my computer; you can probably ignore any .NET and UWP packages.

New Features Rundown

 

Support for More Channel Configurations

Previously, it was only possible to build either mono or stereo plugins. With new changes, it's now possible to build 5.1, 7.1, and 7.1.4 configurations for both, source and effect, plugins. Which one to build, will be defined by the number of channels declared in [adc~] and [dac~] objects.

wwise_hvcc_multichannel

Figure 2: On the left - 5.1 volume control effect. On the right - 7.1 55 Hz oscillator with volume control.

Unfortunately, Heavy plugins cannot change channel configuration on the fly when output device changes, so to use them on a bus, the bus must be set to required configuration. Wwise will downmix or upmix the signal as needed. Plugins will print an error when initialised on a bus with unsupported configuration.

wwise_hvcc_bus_config

Figure 3: Busses that have multi-channel effect plugins must set their configuration explicitly.

Posting Arbitrary Events and Setting RTPCs

This update now allows triggering arbitrary Wwise events from within a Heavy plugin via send objects, similarly to how it was possible to output RTPCs. You can even make control-only plugins, though technically they'll be compiled as mono source plugins that always output silence. Such plugins can either compute statistics on incoming parameters and set a new RTPC, or you can even turn incoming RTPCs into events to implement reactive audio systems. A figure below shows how such send objects are annotated for this purpose.

Note, Wwise Authoring doesn't load events and their data at startup. That means, posting events from a plugin running in the Authoring will fail with Event ID not found error. To work around this, just play the event in question in the Events tab once to force Wwise to load its associated data.

wwise_hvcc_control_only

Figure 4: A control-only patch that turns Param1 value change into a trigger that posts Play_Test_Sound event, and computes the average of Param1 and Param2 and sets it as Param_Avg RTPC on the same game object.

Packaging Plugin for Audiokinetic Launcher

As Heavy generates project format compatible with Audiokinetic's build tools, it's now possible to bundle your plugins into a package that can be installed from the Audiokinetic Launcher. It makes it very easy to distribute custom plugins to others, and it's even possible to include builds for different platforms. The Heavy documentation provides a step by step guide how to do this, and I won't be repeating it here.

There is one thing to keep in mind. Currently, your plugin must follow a format the same way Audiokinetic numbers Wwise version. E.g. if you target Wwise 2022.1, then your plugin must have a version number of 2022.1.X.Y. If you don't like this behaviour, then just modify target Wwise version in the bundle_template.json file that was generated when converting Pure Data patch.

To make life easier and follow instruction as is, WWISEROOT and WWISESDK environment variables should be set correctly via the Audiokinetic Launcher (Set Environment Variables… button):

wwise_hvcc_envvars

Figure 5: Settings relevant WWISEROOT and WWISESDK environment variables.

Outro

This was a short update on Wwise things in Heavy. If you have any suggestions or feature requests, please, drop them to Wasted Audio Discord or GitHub.

And if you never used Heavy before, I'd recommend checking a series of blog posts "How Sound Designers Use PureData + Heavy" by Chenzhong Hou here on Audiokinetic blog for an extended introduction. Special thanks to Ben McCullough for his post on this blog earlier this year about their experience with making a multi-channel effect plugin with Heavy – his article provided inspiration to add support for more channel configurations.

Eugene Cherny

Audio Programmer

Eugene Cherny

Audio Programmer

Audio programmer, currently working in games industry. Have a little bit of experience in art and academia.

https://eugn.ch/

LinkedIn

Comments

Leave a Reply

Your email address will not be published.

More articles

Wwise Convinces Audio Programmers

Six of the industry’s top audio programmers talk about the advantages of using Wwise, including ease...

25.4.2016 - By Audiokinetic

Introducing the Wwise Authoring API

You know that Wwise has an API for its audio engine, but wouldn’t it be nice if the authoring...

21.2.2017 - By Bernard Rodrigue

The Soundscape of Suara: An Audio-Reactive Action Game

Suara is a 3D action arcade game that takes place on the surface of audio-reactive geometric worlds....

1.5.2018 - By Greg Dixon & Nicholas Gulezian

A New Multiband Compressor Plug-in for Wwise: Polyspectral MBC joins the Audiokinetic Community Partner Program!

Polyspectral MBC is a new multi-band compressor plug-in for Wwise. I’m excited to be releasing it...

26.6.2018 - By Ethan Fenn

Connecting Wwise and REAPER: Part 1 - WAAPI Transfer

WAAPI Transfer is not new, but I feel like there is not enough talk about it. It is an open source...

19.2.2019 - By Nikola Lukić

WAAPI for Wwise 2023.1

Wwise 2023.1 includes the largest Wwise Authoring API (WAAPI) update since the introduction of the...

20.7.2023 - By Bernard Rodrigue

More articles

Wwise Convinces Audio Programmers

Six of the industry’s top audio programmers talk about the advantages of using Wwise, including ease...

Introducing the Wwise Authoring API

You know that Wwise has an API for its audio engine, but wouldn’t it be nice if the authoring...

The Soundscape of Suara: An Audio-Reactive Action Game

Suara is a 3D action arcade game that takes place on the surface of audio-reactive geometric worlds....