Adding your own extension to SuperCollider
Recently, I was interested in programming a new extension for SuperCollider. I was left confused by the process! So, here is a blog post on how to add an extension to SuperCollider. Extensions are written in C++. We will not be covering how to write an extension beyond what is needed for this tutorial.
This guide is for Ubuntu 20.04 LTS.
This guide assumes that you have SuperCollider installed (my version is 3.10.0). We will need:
- Python 3
- a tool for creating virtual environments for Python, like
- gcc : you check that gcc is intalled by running
gcc --versionin a Terminal
- git, so that we can clone the SuperCollider repo
- the Terminal and its command line interface
- a text editor
Make sure that you have all the tools ready to go - and let's get started!
Let’s start with a venv
Create a new directory called
supercollider_extensions somewhere on your computer that make sense to you. Let’s initialize a Python virtualenv for this project so that we can install
cookiecutter. Navigate in the Terminal to your
supercollider_extensions folder and run the following command:
python3 - m virtualenv venv
And now, activate the virtual env:
Now that we are in the virtualenv, we can install
We will be using cookiecutter. Install it inside your virtual env by running
pip3 install cookiecutter
We are now ready to generate a SuperCollider extension project with cookiecutter.
Installing SuperCollider source code
"Wait! Isn’t my current installation good enough?"
Yes - but we need a clone of SuperCollider source code on a path that cookiecutter can use.
If you do not have this already, or if you are not sure, navigate to the SuperCollider release page using this link to the SuperCollider release page, version 3.10.0.
Note: This link to more information on getting SuperCollider source code might be useful if you have a different OS or a different version of SuperCollider.
At the bottom of the page, there is a section named Assets; we are on Ubuntu, which means we want the “SuperCollider-3.10.0-Source-linux.tar.bz2” version.
To download the source code, click on its name.
Next step is to extract the files you just downloaded to the
supercollider_extensions folder we created earlier.
Finally, we are going to rename the SuperCollider source code folder to a name that cookiecutter will be able to find:
Generating a project with cookiecutter
In the Terminal, in
supercollider_extensions folder, run the following command:
There will be a questionnaire to help you set up a folder appropriately structured for a SuperCollider extension. Here are my answers:
$ cookiecutter https://github.com/supercollider/cookiecutter-supercollider-plugin You've downloaded /home/z/.cookiecutters/cookiecutter-supercollider-plugin before. Is it okay to delete and re-download it? [yes]: no Do you want to re-use the existing version? [yes]: yes full_path_to_supercollider_source [/home/wendy/supercollider (if you haven't cloned it yet, do that first! Press Ctrl-C to exit this script)]: /home/z/dev/scd/supercollider project_name [Simple Gain]: A simple extension project_namespace [Asimpleextension]: repo_name [asimpleextension]: plugin_name [Asimpleextension]: plugin_description [A simple audio volume gain plugin]: A simple extension. full_name [Wendy Carlos]: The test team github_username [the.test.team]: none email [email@example.com]: firstname.lastname@example.org
To check that this step executed correctly, run the command
ls in a Terminal window: there should be a folder with the name of your extension in it.
Note: the extension project name should start with a capital letter, or else SuperCollider will be unable to find the project.
Code your extension
Now is the time to code your extension! You can do so by changing the
.hpp files in the
Note: I am still new to SuperCollider and C++ so this might not be working the way I think it does… but I have found I had less bugs by using capital letters every time I needed to refer to the name of my extension, in the code.
For this tutorial we will leave the example from cookiecutter as is.
Build the project
We are now ready to build the project!
We will go inside the extension directory and then we will build the project. In the Terminal, do the following:
cd asimplextension mkdir build cd build cmake .. -DCMAKE_BUILD_TYPE=Debug cmake --build . --config Debug
Running this last command might give you debugging comments for your extension. Fix these before continuing.
Installing the extension
(optional) If you added files to the extension while coding…
If you added or removed plugins or files since running cookiecutter for the first time, you might need to regenerate the CMakeLists.txt file.
To do so, run the following in the Terminal, from the
python ../supercollider/tools/cmake_gen/generate_server_plugin_cmake.py --help
Read the options to see which one fits your case. My command looked like this:
python /home/z/dev/supercollider_extensions/supercollider/tools/cmake_gen/generate_server_plugin_cmake.py -P "Asimpleextension" -p "plugins/Asimpleextension" -a "z"
Depending on the changes made while coding your extensions, you might need to adapt it to your needs.
Finding where to install the extension
Open the SuperCollider app.
In a new session, evaluate
Platform.userExtensionDir to obtain the path to the extensions folder of your installation of SuperCollider. Mine is
Back to the
supercollider_extensions/asimplextension folder in the Terminal, run the following commands to install, updating the path with the extensions path we just obtained:
cd build/ cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/home/z/.local/share/SuperCollider/Extensions cmake --build . --config Release cmake --build . --config Release --target install
Are we ... done ? Maybe... ?
CONGRATS: you have installed an extension!
Open the SuperCollider app - you might need to close it first and re-open it so that it loads extensions properly.
In a session file, type
Asimpleextension (or the name of your extension): it should show up automatically.
Congratulations - you made it :) :) :)
I was able to successfully install my extension in SuperCollider by using the following webpages, in order of chronological discovery by yours truly:
- link to Writing Unit Generators on SuperCollider Help: this is where I first started my research
- link to Using Extensions on SuperCollider Help: this gives you the structure of the extension folder and some general information.
- link to Example Plugins on SuperCollider Github: while useful, this page is also deprecated.
- link to the cookiecutter project for SuperCollider plugins, on Github: this is where we start, and we will be coming back to the Example Plugins repo on Github because some information has yet to be ported between the two of them.
Thanks to Daniel Manesh for helping me with some of these steps, and to Shae Matijs Erisson for reviewing this tutorial.