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.

use_synth :prophet
play :E4, release: 1
sleep 0.3
play :G4, release: 1
sleep 0.3
play :B4, release: 2, amp: 0.7

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 :ambi_piano, amp: 0.9
sleep 1.5
sample :ambi_piano, rate: 0.5, amp: 0.6   -- half speed → octave down
sleep 3
sample :loop_amen, rate: 0.85, amp: 0.8   -- classic break, slightly slowed

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

use_synth :synth_name

Set the default synth for all subsequent play calls. The same note sounds very different through each synth — see the Synths tab for the full list.

use_synth :beep        -- pure sine
play :E3, release: 1
sleep 1
use_synth :prophet     -- warm analog pad
play :E3, release: 1.5
sleep 1.5
use_synth :tb303       -- acid squelch
play :E3, release: 1, cutoff: 110, res: 0.8

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 200
use_synth :prophet
16.times do
  play [:E4, :G4, :B4, :D5, :E5, :D5, :B4, :G4].tick, release: 0.3
  sleep 0.25
end

Time Warp

time_warp delta do ... end

Temporarily shift time forward or backward. All sounds triggered inside the block are scheduled at the shifted time. After the block, time returns to where it was — no drift. Only sleep, sync, and time_warp affect time.

play 60
time_warp 0.5 do
  play 72
end
play 48

Here play 60 and play 48 sound at beat 0. play 72 sounds at beat 0.5. The time_warp shifts time for its block only.

-- Schedule a chord spread across 50ms
time_warp 0 do
  play 60
end
time_warp 0.01 do
  play 64
end
time_warp 0.02 do
  play 67
end

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

use_synth_defaults key: value, …

Set default values for all subsequent play and synth calls. Replaces any previous defaults. Per-call arguments always win over defaults.

use_synth_defaults amp: 0.5, cutoff: 80
play 60
-- plays with amp: 0.5, cutoff: 80
play 60, amp: 1
-- plays with amp: 1, cutoff: 80 (explicit wins)

use_merged_synth_defaults key: value, …

Merge new defaults with existing ones. Adds new keys and updates existing keys without removing unspecified ones.

use_synth_defaults amp: 0.5, cutoff: 80
use_merged_synth_defaults release: 2
play 60
-- plays with amp: 0.5, cutoff: 80, release: 2

with_synth_defaults key: value, … do … end

Set defaults for the duration of the block only. Previous defaults are restored when the block ends.

use_synth_defaults amp: 0.5
with_synth_defaults amp: 0.1, cutoff: 90 do
  play 60
  -- amp: 0.1, cutoff: 90
end
play 60
-- amp: 0.5 (restored)

use_sample_defaults key: value, …

Set default values for all subsequent sample calls. Works the same way as use_synth_defaults but only affects samples.

use_sample_defaults amp: 2, rate: 0.5
sample :bd_haus
-- plays with amp: 2, rate: 0.5

use_merged_sample_defaults key: value, …

Merge new sample defaults with existing ones.

with_sample_defaults key: value, … do … end

Set sample defaults for the duration of the block only. Previous defaults are restored when the block ends.

current_synth_defaults

Returns the current synth defaults as a list. Useful for debugging — pass it to print and the result appears in the info panel's output pane.

use_synth_defaults amp: 0.5, cutoff: 80
print current_synth_defaults

current_sample_defaults

Returns the current sample defaults as a list.

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. Passing a chord to play triggers all its notes at once.

use_synth :prophet
with_fx :reverb, room: 0.9, mix: 0.6 do
  play chord(:C4, :major), release: 2, amp: 0.7
  sleep 1.5
  play chord(:G3, :major), release: 2, amp: 0.7
  sleep 1.5
  play chord(:A3, :minor), release: 2, amp: 0.7
  sleep 1.5
  play chord(:F3, :major), release: 2, amp: 0.7
  sleep 1.5
end

scale (:root, :type)

Create a list of MIDI notes forming a scale. Supports major, minor, pentatonic, blues, modes, and many exotic scales. Pass num_octaves: to cover a wider range.

use_synth :prophet
16.times do
  play scale(:C4, :minor_pentatonic, num_octaves: 2).tick, release: 0.3
  sleep 0.15
end

note (:symbol)

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

use_synth :prophet
play note(:C4), release: 0.5
sleep 0.5
play note(:Eb3), release: 0.5
sleep 0.5
play note(:Fs4), release: 0.5

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

octs (note, num_octaves)

Create a list of a note repeated across octaves. Each subsequent note is 12 semitones higher.

-- plays C2, C3, C4 across iterations
play octs(:c2, 3).tick

midi_to_hz (note)

Convert a MIDI note number to frequency in Hz. midi_to_hz(69) → 440.

hz_to_midi (freq)

Convert a frequency in Hz to a MIDI note number. hz_to_midi(440) → 69. You can also use the hz suffix: play 440hz.

Ring Generators

ring (...)

Create a ring (cyclic list) from arguments.

notes = ring(60, 64, 67, 72)
live_loop :arp do
  play notes.tick
  sleep 0.25
end

knit (val, count, val2, count2, ...)

Create a ring by repeating each value a specified number of times.

live_loop :rhythm do
  sample knit(:bd_haus, 3, :sn_dolf, 1).tick
  sleep 0.25
end

spread (accents, size)

Euclidean rhythm distribution — evenly space accents across beats. Returns a ring of 1s and 0s. Based on Toussaint's paper on Euclidean rhythms.

live_loop :euclidean do
  sample :bd_haus, on: spread(3, 8).tick
  sleep 0.125
end

line (start, end, steps: 4)

Linear interpolation between start and end, divided into equal steps. Returns a ring of values you can step through with .tick.

use_synth :prophet
8.times do
  play line(48, 72, steps: 8).tick, release: 0.3
  sleep 0.2
end

bools (...)

Create a boolean ring from 1s and 0s. Useful for rhythmic patterns.

sample :bd_haus, on: bools(1, 0, 0, 1, 0, 1, 0, 0).tick

halves (start, count)

Successive halvings. halves(120, 3) → [120, 60, 30]. Negative count doubles instead.

doubles (start, count)

Successive doublings. doubles(1.5, 3) → [1.5, 3, 6]. Negative count halves instead.

Ring Chain Methods

Chain methods transform lists and can be combined: [1,2,3,4,5].shuffle.drop(1).take(3)

FX

with_fx :fx_name, mix: room: ... do ... end

Wrap a block of code in an audio effect. All sounds triggered inside the block are routed through the FX before reaching the output. The FX is automatically cleaned up after all synths inside have finished and the reverb tail has decayed.

with_fx :reverb, room: 0.8, mix: 0.6 do
  play 60
  sleep 0.5
  play 64
  sleep 0.5
end
sample :bd_haus

FX can be nested:

with_fx :reverb do
  with_fx :distortion, distort: 0.5 do
    play 50, release: 2
    sleep 1
  end
end

Use in_thread inside with_fx to trigger multiple sounds simultaneously through the same FX chain:

with_fx :echo, phase: 0.25 do
  in_thread do
    play 60
    sleep 0.5
    play 64
  end
  play 48, release: 2
  sleep 1
end

See the FX tab for a full list of available effects and their parameters.

Counters

tick

Increment a thread-local counter and return its value. Starts at 0 on the first call. The counter persists across live_loop iterations, making it ideal for stepping through sequences.

4.times do
  play 60 + tick * 3
  sleep 0.25
end
-- plays: 60, 63, 66, 69 (each tick advances by one)

There is only one counter per thread. Multiple calls to tick in the same iteration share and advance the same counter, which can cause unexpected results:

live_loop :clash do
  -- tick 0, 2, 4, ...
  play [60, 64, 67].tick
  -- tick 1, 3, 5, ...
  play [72, 76, 79].tick
  sleep 0.25
end

Each .tick advances the counter by one, so the two lists step through at double speed and interleave oddly. To avoid this, use .tick on one list and .look on the others:

live_loop :clean do
  -- advances counter
  play [60, 64, 67].tick
  -- reads same position
  play [72, 76, 79].look
  sleep 0.25
end

look

Return the current tick counter value without incrementing it. Useful for reading the counter from multiple places in the same iteration.

3.times do
  play [60, 64, 67].tick    -- advances counter
  play [72, 76, 79].look    -- reads same position, no increment
  sleep 0.4
end

tick_reset

Reset the tick counter so the next call to tick returns 0 again. Useful for restarting a sequence from the beginning.

3.times do
  play 60 + tick * 3
  sleep 0.25
end
tick_reset
play 60 + tick * 3
-- plays: 60, 63, 66, then 60 again (reset)

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.

@notes = [60, 64, 67, 72].shuffle
4.times do
  play @notes.tick, release: 0.3
  sleep 0.25
end

[].tick

Tick the counter and use it to index into the list (wrapping around). This is the primary way to step through a sequence in a live_loop — each iteration automatically picks the next element.

live_loop :melody do
  play [60, 62, 64, 67].tick
  sleep 0.25
end

[].look

Index into the list using the current counter value without incrementing. Use when you need the same element from multiple lists in one iteration.

notes = [60, 64, 67, 72]
amps = [1, 0.5, 0.7, 0.3]
live_loop :multi do
  play notes.tick, amp: amps.look
  sleep 0.25
end

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 under the info panel. Useful for debugging. Switch from this Help panel to the Info panel (top-right icon) to see the printed output after running.

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