Functions

Once you start writing lots of code, you may wish to find a way to organise and structure things to make them tidier and easier to understand. Functions are a very powerful way to do this. They give us the ability to give a name to a bunch of code. Let’s take a look.

Defining functions

define :foo do
  play 50
  sleep 1
  play 55
  sleep 2
end

Here, we’ve defined a new function called foo. We do this with our old friend the do/end block and the magic word define followed by the name we wish to give to our function. We didn’t have to call it foo, we could have called it anything we want such as bar, baz or ideally something meaningful to you like main_section or lead_riff.

Remember to prepend a colon : to the name of your function when you define it.

Calling functions

Once we have defined our function we can call it by just writing its name:

define :foo do
  play 50
  sleep 1
  play 55
  sleep 0.5
end
foo
sleep 1
2.times do
  foo
end

We can even use foo inside iteration blocks or anywhere we may have written play or sample. This gives us a great way to express ourselves and to create new meaningful words for use in our compositions.

Functions are remembered across runs

So far, every time you’ve pressed the Run button, Sonic Pi has started from a completely blank slate. It knows nothing except for what is in the buffer. You can’t reference code in another buffer or another thread. However, functions change that. When you define a function, Sonic Pi remembers it. Let’s try it. Delete all the code in your buffer and replace it with:

foo

Press the Run button - and hear your function play. Where did the code go? How did Sonic Pi know what to play? Sonic Pi just remembered your function - so even after you deleted it from the buffer, it remembered what you had typed. This behaviour only works with functions created using define (and defonce).

Parameterised functions

You might be interested in knowing that just like you can pass min and max values to rrand, you can teach your functions to accept arguments. Let’s take a look:

define :my_player do |n|
  play n
end
my_player 80
sleep 0.5
my_player 90

This isn’t very exciting, but it illustrates the point. We’ve created our own version of play called my_player which is parameterised.

The parameters need to go after the do of the define do/end block, surrounded by vertical goalposts | and separated by commas ,. You may use any words you want for the parameter names.

The magic happens inside the define do/end block. You may use the parameter names as if they were real values. In this example I’m playing note n. You can consider the parameters as a kind of promise that when the code runs, they will be replaced with actual values. You do this by passing a parameter to the function when you call it. I do this with my_player 80 to play note 80. Inside the function definition, n is now replaced with 80, so play n turns into play 80. When I call it again with my_player 90, n is now replaced with 90, so play n turns into play 90.

Let’s see a more interesting example:

define :chord_player do |root, repeats| 
  repeats.times do
    play chord(root, :minor), release: 0.3
    sleep 0.5
  end
end
chord_player :e3, 2
sleep 0.5
chord_player :a3, 3
chord_player :g3, 4
sleep 0.5
chord_player :e3, 3

Here I used repeats as if it was a number in the line repeats.times do. I also used root as if it was a note name in my call to play.

See how we’re able to write something very expressive and easy to read by moving a lot of our logic into a function!