Table of Contents
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:
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:
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
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.
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.
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):
Figure 5: Settings relevant WWISEROOT and WWISESDK environment variables.
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.