Improving SYNTH_DESIGN.md

Development
1

Hi there, I have now added my first synthdefs to SP and I would like to collect here some of the lessons learned, I hope with the help of some others who have also written SC material for SP. The idea is to later on take the lessons and merge them into SYNTH_DESIGN.md. I have stolen some GitHub comments that Sam and Ethan. Here we go:

Sonic Pi Synth Design

Compiled synthdefs are really small files, so we could easily throw in 100s more synths designs without much affect on the app download size. Adding new synths adds new sounds and more fun to Sonic Pi, and adding them is really granular, as they can be designed and operated quite independently. The only drawback in synthdef design is that you actually have to enter a new and somewhat different world of programming, using SuperCollider (or Overtone) to write synth definitions.

If you consider writing synthdefs you won’t have to start from scratch. SuperCollider has a strong community and there are tons of synthdefs out there that can be adapted to Sonic Pi. There are also some examples in the Sonic Pi source code. If you consider contributing synthdefs, you should keep the following in mind:

  • You can get a lot of boiler plate from existing synthdefs. At the top of the file you find the way SP synthdefs take arguments, and if applicable, how they are made slidable.

  • In Sonic Pi, synths receive an argument called out_bus. At the end of your synthdef you should output a stereo signal to this out_bus.

  • Sonic Pi requires synths to have an envelop that self-kills the synth on completion. This is normally accomplished by using an EnvGen with doneAction: 2. Also, use reasonable default values for the envelope (and the rest), so that e. g. a simple play 60 generates a tone in SP.

  • Sonic Pi uses what could be called deterministic randomisation which some may know from simulation programs: Rather than using a conventional randomisation function that produces unpredictable pseudo-random values on each run, Sonic Pi draws its random values from a noise file. These values look random, but they aren’t. The advantage is that you always get the same value sequence when you run Sonic Pi, even on a different computer, so SP tunes sound identical on all platforms. In consequence, synthdefs shouldn’t use any of the SuperCollider randomisation UGens, as this breaks the deterministic properties of Sonic Pi. If you need randomisation, then you should read the selected random buffer. You may consider taking a look at Winwood lead, which uses SP randomness.

  • If your synth uses a resonant filter, keep in mind that resonance values in Sonic Pi synths typically range between 0 and 1 (i. e., exclusively) and that in SP a value near 1 means a lot of resonance while near zero means no resonance. This is a good choice, but it is inconsistent with SuperCollider’s RLPF rq param which yields the opposite. If you use resonance, invert the parameter value with linlin.

  • Try to be consistent with SPs units. Most of the time options that are measured in units of time are measured in beats. In particular, this is the case for options that adapt when the BPM change. If this is not case, e. g. for LFO frequency, Hz is a valid unit. Make sure to point this out in the docs.

  • Try to be consistent with SP option names. E. g. the parameter used for resonance in SuperCollider is called rq, while SP uses res.

  • Submit both the synthdef source file and compiled file. On submission, your file should have a line containing .writeDefFile("/Users/sam/Development/RPi/sonic-pi/etc/synthdefs/compiled/"); near its end.

  • Include documentation of your synth in synthinfo.rb. Do not forget the version to be added which, if all works out, will be the next release, not the current :slight_smile: Also note, that you need the class definition as well as an entry in @@synth_infos.

  • Synthdef licenses must be compatible with SP’s license scheme, and they must be open source, of course. MIT is the default, so if your synthdef is under this license, there is nothing special to be done. In case of a different OS license, e. g. GPL, a notice is required in LICENSE.md. Do not put license information anywhere else in the docs.

  • Finally, drop a line about what you have done into CHANGELOG.md.

Some notes on testing:

There is of kow no automated way of testing synthdefs in Sonic Pi, and some tests may not work without a human ear, anyway. Here are some suggestions what could and should be done, before submitting a synthdef PR to GitHub:

  • Do a simple play 60 without your synth (i. e., using a the default :sine synth) and using your new synth. Your synth should play sound of similar pitch and loudness level. After playing the sound, Sonic should notify that the run is completed, that all runs are completed, and write => Pausing SuperCollider Audio Server.

  • Check all your option parameters: Does your synth respond to all the options as expected? In particular, are they modulatable, and do they slide as expected?

… more to come

6 Likes
2

Looking good so far!
A couple of clarifications: it’s not strictly necessary to use Supercollider language to make new SynthDefs (as Sonic Pi will quite happily play any built with Overtone) - though when deciding, Supercollider language is slightly more powerful/flexible, and (I think) easier to work with. Also, the out-bus argument is actually spelt with an underscore, as out_bus :slight_smile:

3

Thanks! I have changed to out_bus and made a reference to Overtone. The latter will also be addressed when merging this to SYNTH_DESIGN.md.

1 Like