Sound

play note, amp: release: cutoff: ...

Play a note with the current synth. Accepts MIDI numbers or note symbols. Code continues executing while the sound plays through its envelope.

play 60
sleep 0.5
play :E4, amp: 0.5, release: 2

synth :synth_name, note: amp: release: ...

Trigger a specific synth by name. Unlike use_synth, this doesn’t change the default — it’s a one-shot. The note is passed as a note: kwarg (default: 52 / E3).

synth :prophet, note: 60, release: 2
sleep 0.5
synth :tb303, note: 36, cutoff: 80

sample :name, rate: amp: pan: ...

Trigger a sample. Play back a recorded sound file. Use a built-in sample name like :bd_haus or a full path string. There are many opts for manipulating playback — rate: affects speed and pitch, amp: controls volume. You can also filter samples from a directory by passing string keywords and an optional index.

sample :loop_amen
sleep 1
sample :ambi_drone, rate: 0.5, amp: 0.3

-- filter by directory and keyword
sample :drum "kick"
sample :drum "snare" 2, rate: 0.8

use_synth :synth_name

Set the default synth for all subsequent play calls.

use_synth :saw
play 50
sleep 0.5
use_synth :prophet
play 50

Timing

sleep beats

Wait for a number of beats before the next command. Beats are scaled to seconds by the current BPM.

play 60
sleep 1
play 67
sleep 0.5
play 72

use_bpm bpm

Set the tempo in beats per minute. Affects all subsequent sleep calls and temporal synth arguments.

use_bpm 120
play 60
sleep 1
play 67

Pitch

use_transpose semitones

Shift all notes by the given number of semitones. Use negative numbers to shift down.

play 60
sleep 0.5
use_transpose 7
play 60

use_octave octaves

Shift all notes by the given number of octaves (each octave = 12 semitones).

play 60
sleep 0.5
use_octave -1
play 60

Control Flow

N.times do … end

Repeat a block of code N times.

4.times do
  sample :bd_haus
  sleep 0.5
end

if condition … else … end

Conditional execution. Run code only when a condition is true.

if dice(6) > 3
  play 72
else
  play 60
end

define :name do … end

Give a block of code a name for re-use. Call it like any other function.

define :bass do
  use_synth :tb303
  play 36, release: 0.3, cutoff: 70
end

bass
sleep 0.5
bass

in_thread do … end

Run a block of code in a new thread. The parent continues immediately while the child runs concurrently. Each thread has its own timing, so sleep in one thread doesn’t block the other.

in_thread do
  4.times do
    sample :bd_haus, lpf: 90
    sleep 0.5
  end
end

in_thread do
  16.times do
    n = [52, 55, 57, 59, 62, 64].choose
    synth :chiplead, note: n, release: 0.1
    sleep 0.125
  end
end

8.times do
  sample :hat_bdu
  sleep 0.25
end

live_loop :name do … end

A loop for live coding. Runs the body repeatedly, automatically looping back to the start when it reaches end. If you edit the code and re-run, the new version hot-swaps into the running loop — no need to stop and restart. Each iteration automatically emits a cue at /live_loop/name so other threads can sync with it. Every live loop must contain at least one sleep to avoid spinning.

live_loop :beat do
  sample :bd_haus, lpf: 100
  sleep 0.5
end

live_loop :melody do
  use_synth :subpulse
  play [50, 54, 57, 62, 74].choose, release: 0.2
  sleep 0.125
end

stop

Stop the current thread or run. Does not stop any running synths triggered previously in the thread. Useful for conditionally silencing a live loop on some iterations.

play 70
sleep 0.5
play 72
stop
play 745

Randomisation

rand (max)

Random float between 0 and max (default 1).

8.times do
  play 72 + rand(24), release: 0.1
  sleep 0.125
end

rrand (min, max)

Random float between min and max.

8.times do
  play rrand(48, 72)
  sleep 0.25
end

rrand_i (min, max)

Random integer between min and max (inclusive).

8.times do
  play rrand_i(48, 72)
  sleep 0.25
end

rand_i (max)

Random integer between 0 and max−1.

4.times do
  sample :elec_blip, rate: rand_i(4)
  sleep 0.25
end

dice (n)

Roll a dice with N sides (default 6). Returns integer from 1 to N.

4.times do
  play 50 + dice(12)
  sleep 0.25
end

use_random_seed seed

Set the random seed for reproducible sequences. The same seed always produces the same random numbers.

use_random_seed 42
4.times do
  play rrand_i(50, 80)
  sleep 0.25
end

use_random_seed 100
4.times do
  play rrand_i(50, 80)
  sleep 0.25
end

use_random_seed 42
4.times do
  play rrand_i(50, 80)
  sleep 0.25
end

Music Theory

chord (:root, :type)

Create a list of MIDI notes forming a chord. The root can be a note symbol or MIDI number. Supports major, minor, 7th, 9th, 11th, 13th, sus, dim, aug, and many more.

play chord(:E3, :minor).choose
sleep 0.25
play chord(:C4, :major).choose
sleep 0.25
play chord(:A3, :dom7).choose

scale (:root, :type)

Create a list of MIDI notes forming a scale. Supports major, minor, pentatonic, blues, modes, and many exotic scales.

8.times do
  play scale(:C4, :minor_pentatonic).choose, release: 0.1
  sleep 0.125
end

note (:symbol)

Convert a note symbol to its MIDI number. Supports sharps (s), flats (b/f), and octave numbers.

print note(:C4)
print note(:Eb3)
play note(:Fs4)

range (start, end, step)

Create a list of numbers from start to end, incrementing by step.

8.times do
  play range(50, 74, 3).choose, release: 0.1
  sleep 0.125
end

Lists

[].choose

Pick a random element from a list.

4.times do
  play [60, 64, 67, 72].choose
  sleep 0.25
end

[].shuffle

Return a new list with elements in random order.

print [60, 64, 67, 72].shuffle

Time State

@name = value

Store information in Time State for the current time. The value is visible to all threads and will remain until overwritten. Shorthand for set :name, value.

@note = 60
play @note
sleep 0.5
@note = 72
play @note

@name

Retrieve information from Time State set prior to the current time from any thread. Returns 0 if no value has been stored. Shorthand for get :name.

@root = 50
8.times do
  play @root + rrand_i(0, 12), release: 0.1
  sleep 0.125
end

set :name, value

Store information in Time State. The value will remain until overwritten by another call to set. Also triggers any threads waiting on sync :name.

set :root, 60
4.times do
  play get(:root), release: 0.2
  sleep 0.25
end
set :root, 72
4.times do
  play get(:root), release: 0.2
  sleep 0.25
end

get :name

Retrieve information from Time State. Returns the most recent value stored with set prior to the current time. Returns 0 if not set.

set :notes, [50, 54, 57, 62]
8.times do
  play get(:notes).choose, release: 0.1
  sleep 0.125
end

cue :name

Cue other threads. Send a heartbeat synchronisation message containing the virtual timestamp of the current thread. Any thread waiting on sync :name will wake up and inherit this thread’s beat. Unlike set, cues are for signalling — they don’t store a retrievable value.

in_thread do
  sleep 1
  cue :drop
end

sync :drop
sample :bd_haus
play 36, release: 2

sync :name

Sync with other threads. Pause the current thread until a matching cue, set, or live_loop event is received. When matched, the current thread’s virtual time is set to match the cueing thread — synchronising them musically.

live_loop :beat do
  sample :bd_haus, lpf: 100
  sleep 0.5
end

live_loop :melody do
  sync :beat
  use_synth :chiplead
  play [50, 54, 57, 62].choose, release: 0.1
end

Output

print value

Display a value in the output pane. Useful for debugging.

print 42
print rrand(0, 100)
print "hello"