Using the Heavy Compiler
Getting more Juice from Pure Data on Bela
Sometimes when you’re patching you’ll hit the CPU limit of your Bela board. The first thing we recommend is ensuring your patch is as efficient as possible, but there are some other techniques for reducing CPU usage. You can try using the Heavy compiler which turns your Pure Data patch into efficient C code which can run on Bela.
Table of contents
Reducing CPU load
Before we get started a word of warning: this is not the officially supported way of building Pure Data patches on Bela but rather is how we used to do it in the early days before full libpd support. Although we will try our best to keep Heavy working with Bela, the normal and fully supported workflow for working with PD on Bela is the one we have been using in these tutorials so far.
What is Heavy/hvcc?
Heavy is a framework for generating efficient audio code for use in interactive sound and music applications such games, instruments or installations created by Enzien Audio. It aims to reduce the dependency on low-level programming from a creative standpoint and bridge the gap from idea to production-ready implementation. hvcc is the open source version of the Heavy compiler which was released after Enzien Audio disbanded in 2019.
Working with Heavy
Before using Heavy for the first time you need to download a local copy of the Heavy compiler which can be found here https://github.com/giuliomoro/hvcc/ (requires git, python 3.7 and pip3). From a terminal run this to download on your machine:
git clone https://github.com/giuliomoro/hvcc.git
cd hvcc/
pip3 install -e .
Then get a copy of the Bela repository (dev branch) on your computer and update the code on Bela:
git clone https://github.com/BelaPlatform/Bela.git -b dev
cd Bela
./scripts/update_board -y
Connect your Bela system to your computer with a USB cable. When it’s booted up, access the IDE via http://bela.local in a browser.
scripts/build_pd_hvcc.sh path/to/your/_main.pd -c "-p 64" -p PROJECTNAME
NOTE: after updating the Bela core code (as done above when running update_board), the next time you build any project may take a long time.
ANOTHER NOTE: the first time you build a project created with hvcc, it will take a long time to build. Successive builds will be faster, but still take around 30-40 seconds.
Using flags
Flags allow you to customise the build and runtime behaviour of the project. Flags passed before the path are passed to hvcc, so run hvcc --help to get a list of available options. Flags passed after the path are passed to Bela/scripts/build_project.sh, so run build_project.sh --help to see a list of available options. In this example we build a Pd project with hvcc which we then run with a block size of 64 (-c "-p 64"):
$ ./build_pd_hvcc.sh ../examples/terminal-only/vangelisiser/ -c "-p 64"
For a full list of the available options, run:
$ ./build_pd_hvcc.sh --help
Trill sensors with Heavy
The Trill sensors now work with Heavy. To work with Trill you need to change
[s bela_setTrill]
to
[s bela_setTrill @hv_param]
Using heavylib objects
heavylib is a project by the creators of hvcc which provides Pd abstractions which can be useful for Pd patches with or withouth hvcc: utilities, audio processing units and some almost-compatible re-implementations of Pd objects in such a way that most of their functionalities are preserved and they can be used with hvcc. For instance, [vline~] becomes [hv.vline].
You can get heavylib from here.
When building a patch that requires heavylib (or any other collection of abstractions), pass the path to it with the -p flag to build_pd_hvcc.sh before the project’s path. E.g.: the line below will pass -p path/to/heavylib path/to/file.pd to hvcc and then the generated files will be built with build_project.sh -p PROJECTNAME -c "-p64"
./scripts/build_pd_hvcc.sh -p path/to/heavylib path/to/file.pd -p PROJECTNAME -c "-p64"