eviau

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.

Setup

This guide assumes that you have SuperCollider installed (my version is 3.10.0). We will need:

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:

source venv/bin/activate

Now that we are in the virtualenv, we can install cookiecutter.

Installing cookiecutter

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: supercollider.

Generating a project with cookiecutter

In the Terminal, in supercollider_extensions folder, run the following command:

cookiecutter https://github.com/supercollider/cookiecutter-supercollider-plugin

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 [none@site.com]: none@example.com

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 .cpp and .hpp files in the supercollider_extensions/NAME_OF_YOUR_EXTENSION/plugins/NAME_OF_YOUR_EXTENSION folder.

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 supercollider_extensions/EXTENSIONNAME path:

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 /home/z/.local/share/SuperCollider/Extensions.

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 :) :) :)

Resources

I was able to successfully install my extension in SuperCollider by using the following webpages, in order of chronological discovery by yours truly:

Thank you!

Thanks to Daniel Manesh for helping me with some of these steps, and to Shae Matijs Erisson for reviewing this tutorial.