SC3-plugins

This repository contains the community collection of unit generator plugins for SuperCollider. An installation extends the functionality of SuperCollider by additional UGens that run on scsynth, the SuperCollider audio synthesis server.

Please note that the UGens in this repository are, on average, less stable and well-maintained than the core collection. Use at your own risk!

Note: Extensions for the SuperCollider programming language are different. They are collected within the Quarks packaging system.

To learn how to write your own plugins, see example-plugins and the "Writing UGens" helpfile.

For community discussion and support see the SuperCollider mailing lists and the github issue tracker.

Release Downloads

Compiled releases are available from the GitHub release page. For older versions (2013), see the Sourceforge project page.

Binary install

Copy the contents of the tarball/dmg to your SuperCollider extensions folder. Find it with evaluating

Platform.userExtensionDir

in SuperCollider. Alternatively, you may install the extensions system-wide by copying to

Platform.systemExtensionDir

Compile from source

Download both the SuperCollider source and the source for this repository:

git clone --recursive https://github.com/supercollider/sc3-plugins.git
git clone --recursive https://github.com/supercollider/supercollider.git

Be sure to use --recursive, or to initialize the submodules after cloning, otherwise you will not have files that are necessary to build the project.

Like SuperCollider, sc3-plugins uses cmake. Execute the following commands in the directory where you cloned sc3-plugins; replace /path/to/sc/ with the path to the SuperCollider source directory. That will probably be ../../supercollider if you cloned both repositories in the same working directory.

mkdir build && cd build
cmake -DSC_PATH=/path/to/sc/ ..
cmake --build . --config Release
# to install the plugins
cmake --build . --config Release --target install

If no SC_PATH is provided the build system assumes the SuperCollider include files are in /usr/include/SuperCollider/.

On macOS, the plugins will end up in sc3-plugins/build/SC3plugins. Copy the SC3plugins folder to your Extensions folder (evaluate Platform.userExtensionDir in SuperCollider to find it).

NOTE: on macOS, if you want to install into CMAKE_INSTALL_PREFIX, you have to specify it by disabling the IN_PLACE_BUILD cmake option which defaults to ON (see below).

Cmake Options

Set install target
- (default on linux /usr/local)
- cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
Install in cmake build folder instead of CMAKE_INSTALL_PREFIX
- (OSX ONLY, default=ON)
- cmake -DIN_PLACE_BUILD=ON
Build the plugins as quarks
- (default 'OFF')
- cmake -DQUARKS=ON ..
Build supernova-plugins
- (default 'OFF')
- cmake -DSUPERNOVA=ON ..
Print all cmake options
- sc3-plugins/build/$ cmake -L ..

Troubleshooting

Build errors

If you get an error while building that files are missing, it probably means that you didn't clone all the SuperCollider submodules. Fix this by running git submodule update --init in the SuperCollider source directory. If you still have the issue afterwards, try clearing your build directory and starting your build from scratch.

Starting over

If something went wrong and you want to start from scratch, delete everything in the build directory that you made:

make uninstall # only if you ran `make install` before
cd ..
rm -r build

Adding plugins to the repository

A SuperCollider plugin is a collection of UGens (and their supporting files) with a shared prefix in their name. If you add a new plugin, please keep to the following pattern:

Add a folder in the source directory named <prefix>UGens where prefix means whichever standard pattern in the file name you have for your UGens. All source files go into this directory and its subdirectories.
SuperCollider-specific files (.sc|.schelp|...) should be located in a subdirectory named sc.
If your plugin makes use of external libraries that should be part of the sc-plugins sources (e.g. via git-submodule), add them to sc3-plugins/external_libraries/. As an example, the GlitchUGens plugin directory lists as:
- source/GlitchUGens/GlitchUGens.cpp
- source/GlitchUGens/sc/GlitchUGens.sc
- source/GlitchUGens/sc/HelpSource/Classes/GlitchBPF.schelp
- source/GlitchUGens/sc/HelpSource/Classes/GlitchBRF.schelp
- source/GlitchUGens/sc/HelpSource/Classes/GlitchHPF.schelp
- source/GlitchUGens/sc/HelpSource/Classes/GlitchRHPF.schelp
Add your folder to the PLUGIN_DIRS list in sc3-plugins/source/CMakeLists.txt.
For the Quark-installable option, there is a SuperCollider script called Generate_Quark.scd in sc3-plugins/quarks/. Evaluating it indexes the base directory of the extensions for each UGen, and Help-file in each plugin directory. It then creates a help file for your plugin that lists all classes and help files, as well as a .quark file for your plugin in the build/DIRECTORY folder.

Packaging

How to create a DiskImage (OSX)

To create an OSX DiskImage, follow these steps on an OSX machine:

mkdir build && cd build
cmake -DSC_PATH=/path/to/sc/ -DOSX_PACKAGE=1 ..
make && make install

The DiskImage will be generated in ./sc3-plugins/build/build_osx containing

a License.txt,
this README.txt, and
the SC3plugins folder.
Note: the quarks DIRECTORY-folder is also included by default.

How to create a tarball/zip-file

mkdir build && cd build
cmake -DSC_PATH=/path/to/sc/ ..
cpack -G TGZ # `-G ZIP` also works

The package will end up in sc3-plugins/build.

List of plugins

An auto-generated list of what plugins are available in this repository, linking to the autogenerated helpfiles:

yaxu/sc3-plugins