Creating your own effects - clevelandmusicco/HothouseExamples GitHub Wiki
Overview
In the root of the HothouseExamples repository there is a helper script named create_new_proj.py
. You can use this script to "bootstrap" a fresh new effect project, complete with all of the necessary includes, bypass logic, and the minimum files needed for a VS Code project with basic tasks and debug capabilities. Of course, you don't have to use this script; if you've got the knowledge to do everything from scratch, rock on! :metal:
Prerequisites
- Python 3.x - The helper script and the commands on this page have been tested with
Python 3.10.14
andPython 3.12.3
. It's assumed you've aliased one of these versions to the localpython
command, but adjust the commands as needed. (For example,python3.12 create_new_proj.py
might work on your system.)
create_new_proj.py
Using Use the create_new_proj.py
helper script to create a bare effect project in the src
dir:
python create_new_proj.py -h
usage: create_new_proj.py [-h] --proj_name PROJ_NAME
[--your_name YOUR_NAME]
[--your_email YOUR_EMAIL]
options:
-h, --help show this help message and exit
--proj_name PROJ_NAME
Name of the new project in camelCase or PascalCase.
--your_name YOUR_NAME
Your name for use in the license and README.
--your_email YOUR_EMAIL
Your email address for use in the license and README.
[!NOTE]
--your_name
and--your_email
are optional. If they are omitted, the literal stringsYour Name
andyour@email
will be used in the new project code. Specifically, they will appear in the comments of the main.cpp
file and in the generatedREADME.md
.
cd HothouseExamples
python create_new_proj.py --proj_name MyAwesomeEffect \
--your_name "John Developer" \
--your_email [email protected]
You should see output similar to this:
Creating src/MyAwesomeEffect/Makefile ...
Creating src/MyAwesomeEffect/README.md ...
Creating src/MyAwesomeEffect/my_awesome_effect.cpp ...
Creating src/MyAwesomeEffect/.vscode/.cortex-debug.peripherals.state.json ...
Creating src/MyAwesomeEffect/.vscode/.cortex-debug.registers.state.json ...
Creating src/MyAwesomeEffect/.vscode/STM32H750x.svd ...
Creating src/MyAwesomeEffect/.vscode/c_cpp_properties.json ...
Creating src/MyAwesomeEffect/.vscode/launch.json ...
Creating src/MyAwesomeEffect/.vscode/tasks.json ...
Done!
This results in a new directory under src
with this structure:
src/MyAwesomeEffect
├── Makefile
├── my_awesome_effect.cpp
├── README.md
└── .vscode
├── c_cpp_properties.json
├── .cortex-debug.peripherals.state.json
├── .cortex-debug.registers.state.json
├── launch.json
├── STM32H750x.svd
└── tasks.json
Straight away, the project can be compiled and flashed as usual, but until you add your own code, the new effect will just write silence to the output when not bypassed. By default, AudioCallback()
looks something like this (note the TODO
comment):
void AudioCallback(AudioHandle::InputBuffer in, AudioHandle::OutputBuffer out,
size_t size) {
// Stuff omitted for brevity
for (size_t i = 0; i < size; ++i) {
if (bypass) {
// Copy left input to both outputs (mono to dual-mono)
out[0][i] = out[1][i] = in[0][i];
} else {
// TODO: replace silence with something awesome
out[0][i] = out[1][i] = 0.0f;
}
}
}
Build your new effect as you would any other:
cd src/MyAwesomeEffect
make clean
make
Now flash the Hothouse with program-dfu
for USB or program
for JTAG/SWD.
Flash via USB (DFU)
make program-dfu
Flash via JTAG/SWD
make program
Your new effect will also be automatically recognized by the build_examples.py
helper script, and will be built along with all the other examples when running the script.
[!TIP] When executed, the
create_new_proj.py
script copies content from a template project directory while replacing some string tokens along the way. The template project is inresources/_template
and can be customized to your liking.
The README file
The script will give you a README.md
file with a suggested template for describing your effect and how the Hothouse hardware interacts with it. If you specified your name and email with the --your_name
and --your_email
parameters, you'll see them near the top of the file.
README.md in the VS Code Preview window
[!NOTE] This is the preferred format if you plan to submit a pull request for your effect to be included in the HothouseExamples repository!
Tips for programming the Hothouse
This is a living list of tips submitted by customers and some general pointers on getting the most out of the Hothouse.
- Mono-to-mono? Mono-to-stereo? What's all this then? Read about audio modes supported by the Hothouse and see code that implements each mode.
More coming soon...