Overtone User’s Guide

This is a work in progress. If you find an error, please submit a PR to fix it, or an issue with details of the problem.

This source for this book is hosted on Github.

The examples and code used in this book will try to be as neutral as possible when it comes to choice of text-editor. All modern text editors have some sort of plugin to run and evaluate Clojure code. If you are starting out with the programming language Clojure, you may easily get confused or lost on how to replicate some of the examples in your text editor. Therefore we aim to make all of our examples replicable using nothing but Leiningen in the terminal via lein repl, and assume from the reader basic understanding of the terminal/cmd (if you know how to explore directories and install apps with the terminal, you probably know enough). Leiningen is the most popular build tool in Clojure and is the build tool that glues Overtone’s sources and dependencies together. Overtone does work with alternative build tools like boot, as well as a standalone java jar file, but that and how to integrate Overtone to specific text-editor will not be included in this book.

Please be also aware that topics often overlap. If something isn’t clear, have a look at the chapter titles to see if the concepts you’re trying to understand is explained elswhere in the book.

Overtone has a function to create envelope shapes in a format that Supercollider understands, called simply envelope. For every envelope there needs to be two vectors provided as arguments, levels (y-axis) and durations in seconds (x-axis), since durations specifies the durations of each step, its size will need to be the size of the levels vector minus 1. You can choose an envelope shape by directly specifying each point via :step, or use one of the following keywords to apply a function to your points.

Let’s try a simple example.

This shape will create a straight line from 0 to 0.5 and from 0.5 to 1, with each of the two steps taking 1 second (totalling 2 seconds, which is the default time demo plays an instrument).

To most clearly hear what’s going on here, let’s try to play this line as an upwards glissando(gliding note) from 200Hz to 400Hz and see if this works.

This clearly didn’t sound like glissando, so what’s going on here? We did indeed specify a line from 0 to 1 and multiplied the line by 200 to glide 200Hz ending at 400Hz. By useing :step the envelope makes no attempt bridge the gap between the points we provided it. So as soon as the instrument started we heard 300Hz and halfway through it changed to 400Hz. So what happened to our first point of 200Hz? In those cases where the envelope loops, there’s a chance of distorted hum if the envelope doesn’t begin where it ends, so point 0 on x-axis works as a pivot point and will never be played.

Let’s try again, but this time let’s try to bridge the gap by applying a linear function to the points using :lin.

This sounded much smoother, no jumps but a constantly gliding note for the duration of the two seconds. But to human ears, this linear glide doesn’t sound very linear even though the computer did perfectly good job of executing it linearly. To produce a glissando that a human would sing or perform on a violin, we need to apply a non-linear function to the provided points. Keep in mind our auditory senses are non-linear both for the perception of amplitude and frequency. Where we usually control and measure amplitude on logarithmic scale in decibels, and frequency with note names, midi note number or pitch class sets, all of which are in in squared relationship to the Hz they represent. So for our last attempt glissando, we’ll apply a squared function to points from 0 to 1 in 2 second interval.

Like mentioned, you can use the function envelope to define any arbitrary shape you want via :step and apply various function to a vector of provided points. But most of the time you’ll want to use built-in functions that provide the most commonly used envelope shapes for sound-designing.

Additionally you’ll find in Overtone: adsr-ng, step-shape, linear-shape, exponential-shape, sine-shape, welch-shape, curve-shape, squared-shape and cubed-shape.

All shapes returned by envelope, or the built-in envelope functions which themselves are all built on top of envelope, must be used in combination with env-gen. env-gen is what turns the envelope data into a signal which can be passed around as an operator to other signals, as well as direct argument to various inputs. The first parameter of env-gen is the aforementioned envelope shape itself. The other parameters are as follows gate, level-scale, level-bias, time-scale and action.

A lesser used minimal alternative ugen to env-gen is linen. linen is a linear attack-sustain-release envelope generator that takes only gate and action as extra arguments and runs only on control-rate (see Data Types to understand the various rates) and returns a signal that can be used in the same manner as env-gen.

The following two expressions will be played exactly the same.

Since an envelope can be any modulating signal, we can create an envelope shape using low-frequency-oscillators or LFO for short. A low-frequency-oscillator is typically an oscillator that oscillates at a frequency under the lower limit of human hearing range ~22Hz. In overtone you can find LFO oscillators starting with LF, which include lf-saw, lf-par, lf-pulse, lf-tri and countless more. They differ only from traditional oscillators in that they are not band-limited and are more performant, since they don’t try to anti-aliase high frequencies. When working with LFO’s in most cases, it doesn’t matter if you use band-limited or non-band-limited oscillators, they behave exactly the same on low frequencies.

The following expression plays a sawtooth oscillator for 1 second with even attack and decay time created from the shape of sinewave. Note that we are converting Hertz(1/sec) to seconds, as reference 1Hz takes 1 second to finish 1 cycle. As we are using sinewave shape from sin-osc:kr we are only concerned with the positive values from 0 to 1, which occupy the first half of the sinewave. Therefore we multiply the wanted note duration by 2, so that the signal cuts off exacly before the sinewave goes from 0 to a negative value. The line:kr serves as timeout that frees the synth node after 1 second and hence prevents it from playing the full 4 seconds which the demo time defaults to.

Now if we wanted a sinewave envelope with two peaks, we need to apply abs (asbolute value) on the LFO signal so as not to end up with negative amplitude values. Here we don’t need to cut the sinewave signal in half since applying abs causes the sinewave to become unipolar (from 0 to 1) as opposed to bipolar (from -1 to 1).

We can also shift the sin-osc to become unipolar by using the parameter :add. By adding 1 to a bipolar signal, it will cause a shift from ←1,1> to <0,2>, and since we want to limit our range to be within the sensible amplitude boundaries of <0,1> we need to multiply the signal by 1/2 (or divide it by 2). That can also be achieved by setting the parameter :mul to 0.5 as shown below.

With a sawtooth oscillator we can emulate a linear fadein. Here we also need to convert the bipolar sawtooth-wave signal into unipolar signal.

By providing negative :iphase value we can reverse the signal and get a linear fadeout.

Here are some tutorial videos about envelopes, not related specifically to Overtone, but can give ideas.

Wavetable synthesis with computers, explained at its essence, is the way of creating signal by reading phase values from a table and sending those values in sample-rate to a given audio source (also refered to as Liner Pulse-Code Modulation). In Overtone the phase values are stored between -1 and 1. As opposed to a 16-bit .wav file which stores its values as integers from 0 to 65,535 or −32,768 to 32,767 depending if it’s unsigned or signed integers respectively. Same goes for the audio hardware in your computer, if it’s set to 16-bits resolution, then supercollider will remap the floats between -1 and 1 to an integer range that the audio hardware expects to receive. When refering to phase in this context, can be misleading to newcomers. For oversimplification you can think of phase stored from samples and audio files purely as amplitude, since a signal going from -1 to 1 is playing audio on full amplitude strength. Whereas you may play your Overtone instruments with amplitudes that are in the range of 0 and 1 (there’s no such thing as negative amplitude), supercollider enginge will create a signal that has phase values from -1 to 1 and the audio module will take the signal from Supercollider and remap it to −32,768 to 32,767 (for 16-bit).

That trivial knowledge above is quite irrelevant to our task of makeing wavetables in Overtone, but the connection of phase, amplitude, table and storage of audio is important to understand before we proceed. But let’s create a sinewave table with the following formula \$sum_(n=0)^L=sin(frac{2pin}{L})**A\$. Where L stands for table length (typically a number which is \$2^x\$) and A stands for the amplitude.

With amplitude set to 1, we get a vector representing sinewave which goes from -1 to 1. Let’s turn this into a function that we can user later, where the amplitude is omitted (and hence returns values between -1 and 1). Also let’s return a buffer instead of a vector so we can play our result later on.

Next thing to look out for is the relationship between the sample-rate and table-size. If you imagine the values in the table, which are 1024 being read one by one on the rate of 1/48000 per second (or \$frac{1}{sr}\$). Before 1 second has passed, our table would have been read almost 48 times, creating 48Hz audio signal instead of 1Hz. To compensate for that, we need a simple math to help us even out the relationship between the sample-rate and the table-size by dividing the table-size with the sample-rate. By doing that we can create our first wavetable-oscillator where we can have full control over the frequency of our signal.

Bravissimo Houston! By multiplying the wanted frequency to the ratio between table-size and sample-rate as defined in playback-rate above, we can modify the frequency as we wish. Later in the manual we will discuss samples, where the function play-buf:ar plays a huge role. With the difference that in wavetable synthesis we generate table representing one cycle, therefore we need to loop over the values multiple times a second to create an audible signal, whereas a sample is usually only played once trough.

Now we have to power to generate a vector in Clojure, send it to supercollider-land as a buffer and play back the values stored in the buffer with play-buf:ar. Now let’s proceed.