Skip to content

Getting Started

Jump to bottom Edit New page
Arne Brasseur edited this page Jan 5, 2024 · 21 revisions

Before you start, please note that like many pieces of music software, Overtone has a bit of a learning curve. Don't let that daunt you!

First, you will need to already be somewhat familiar with the following:

  • Using a command line environment for your system. You will need to perform basic UNIX or DOS commands to set up and run Overtone.
  • The Clojure language and environment (e.g. Clojure CLI or Leiningen and the REPL). Overtone is written in Clojure, and having a cursory understanding of the syntax as well as basic data structures such as numbers, symbols, vectors, hashes, and functions will go a long way. Also, while it is possible to merely play around with Clojure within a REPL, in order to create sounds that you can save and play back, you'll need to know how to create a Clojure project with Clojure CLI (deps.edn) or Leiningen (project.clj).
  • Using a text editor or IDE to write code. Overtone can be used with Sublime, Emacs, Vi, Eclipse with CounterClockwise, and other environments.

Besides this, there are other topics that you may wish to study in order to use Overtone effectively:

  • The SuperCollider audio synthesis environment. Overtone is basically a wrapper around SuperCollider, and all of the terminology and function names that it introduces are borrowed from SuperCollider itself.
  • The basics of music theory. There are plenty of YouTube videos you can watch.
  • The basics of sound synthesis.
  • Change. Overtone is constantly under development so it pays to keep up with the latest updates!

You can dive in without being comfortable with all of these topics, but regardless of where you start, understand that it will take time to wrap your head around Overtone and all of the various pieces. Take your time, play, learn, and enjoy the journey. If you have questions, the Google Group is a great resource.

Making your first sounds

We're assuming that you've already installed Overtone, started a REPL and have connected to an scsynth server. If not, visit these pages and come back:

First, from the REPL, we'll define an instrument:

> (definst foo [] (saw 220))

This uses the definst macro to create an instrument that, when played, will generate a saw wave at 220 Hz.

Let's make use of it (warning: you might want to turn down your sound, as this will be at 100% volume!):

> (foo) ; play the synth
#<synth-node[loading]: user/foo 4>      ; returns a synth ID number
> (kill 4) ; kill the synth with ID of 4
> (kill foo) ; or kill all instances of synth foo

As we can see, synth trigger functions return an ID that can be used to modify or kill instances. However, we can also use a reference to the synth itself.

The saw function represents a unit-generator, or ugen (sounds like "you jen"). These are the basic building blocks for creating synthesizers, and they can generate or process both audio and control signals. There are tons of other kinds of ugens besides saw. There is a complete list given on the cheat sheet, but the ones you might find more useful than others in your Overtone journey are:

You can also look up the documentation for any ugen function from the REPL:

> (odoc saw)
-------------------------
overtone.live/saw
([freq])

  [freq 440.0]

  freq - Frequency in Hertz (control rate).

  Band limited sawtooth wave generator

  Categories: Generators -> Deterministic
  Rates: [ :ar ]
  Default rate: :ar

Getting back to our example, the last instrument we created played at an immutable frequency of 220 Hz. To make this customizable, we can have our instrument take an argument:

> (definst bar [freq 220] (saw freq))
> (bar 110)
5
> (kill bar)

We can also trigger multiple synths and kill them all with one kill command:

> (definst baz [freq 440] (* 0.3 (saw freq)))
> (baz 220)
> (baz 660)
> (kill baz) ; stop all running synths

Besides kill, stop is also a good function to remember, as it can save you when you accidentally trigger a bunch of synths and you need to kill the audio fast:

> (foo)
> (bar)
> (baz)
> (stop) ; stop all running synths

Now, when our synth is playing, the saw wave ugen outputs an audio signal. This signal is represented as a continuous stream of floating point values between -1 and 1. But by multiplying this signal by 0.3, we can lower its amplitude, thereby adjusting the volume.

> (definst quux [freq 440] (* 0.3 (saw freq)))
> (quux)

Since our synth instance takes a frequency, we can of course pass a frequency to make a new synth with that frequency. But if we already have a synth and we want to change its parameters on the fly, we can do that with ctl:

> (ctl quux :freq 660)

So far we've just used a single ugen and passed it arguments, but ugens can be plugged into each other in arbitrary ways too. Basically, anywhere a ugen takes a scalar value, it can also take an input signal that will control that value. So now let's put a tremolo on our saw wave:

> (definst trem [freq 440 depth 10 rate 6 length 3]
    (* 0.3
       (line:kr 0 1 length FREE)
       (saw (+ freq (* depth (sin-osc:kr rate))))))
> (trem)
4
> (kill trem)
> (trem 200 60 0.8)
4
> (kill trem)
> (trem 60 30 0.2)
...

The line ugen outputs a value from the start value to the end value over a specific length of time. In this example we use it as a simple way to stop the synth after a few seconds. The last argument, FREE, is a typical argument to this kind of control ugen that tells the ugen to free the whole synth instance once it completes. That way we don't have to kill it by hand anymore.

Also note that we didn't just use line as a function, we actually used line:kr instead. Many of the ugens can operate at different rates, shown at the bottom of their respective doc strings. The two primary rates are audio rate and control rate, which are represented by the :ar and :kr suffixes. Audio rate runs at the rate of your audio card, and control rate runs at about 1/60 of that speed, so if you have a signal that just controls a value rather than outputting audio, you can prevent from wasting CPU by using :kr.

Where to go from here

That's it! That's all Overtone does. Just kidding :) As you'll discover, Overtone can do a lot of things, and so naturally there a lot of functions that it comes with. The cheat sheet is a good resource for knowing what's available in what context, but will likely be overwhelming for you as a beginner. While there are other topics in the wiki that you can look over, you may find it more actionable to read through the "getting started" examples and recreate them for yourself. And as a reminder, if you find a function that looks particularly interesting, you can look up the documentation for it by using the doc function.

Add a custom footer
Add a custom sidebar
Clone this wiki locally