all_sample_names
Return a list of all the sample names available
Introduced in v2.0
assert arg (anything)
Raises an exception if the argument is either nil or false.
Introduced in v2.8
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
assert_equal arg1 (anything), arg2 (anything)
Raises an exception if both arguments aren’t equal.
Introduced in v2.8
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
at times (list), params (list)
Given a list of times, run the block once after waiting each given time. If passed an optional params list, will pass each param individually to each block call. If size of params list is smaller than the times list, the param values will act as rings (rotate through). If the block is given 1 arg, the times are fed through. If the block is given 2 args, both the times and the params are fed through. A third block arg will receive the index of the time.
Note, all code within the block is executed in its own thread. Therefore despite inheriting all thread locals such as the random stream and ticks, modifications will be isolated to the block and will not affect external code.
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
# Example 9 | |
|
|
# Example 10 | |
|
|
beat ()
Returns the beat value for the current thread/live_loop. Beats are advanced only by calls to sleep
and sync
. Beats are distinct from virtual time (the value obtained by calling vt
) in that it has no notion of rate. It is just essentially a counter for sleeps. After a sync
, the beat is overridden with the beat value from the thread which called cue
.
Introduced in v2.10
# Example 1 | |
|
|
block_duration ()
Given a block, runs it and returns the amount of time that has passed. This time is in seconds and is not scaled to the current BPM. Any threads spawned in the block are not accounted for.
Introduced in v2.9
# Example 1 | |
|
|
# Example 2 | |
|
|
block_slept? ()
Given a block, runs it and returns whether or not the block contained sleeps or syncs
Introduced in v2.9
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
bools list (array)
Create a new ring of booleans values from 1s and 0s, which can be easier to write and manipulate in a live setting.
Introduced in v2.2
# Example 1 | |
|
|
# Example 2 | |
|
|
bt seconds (number)
Beat time representation. Scales the time to the current BPM. Useful for adding bpm scaling
Introduced in v2.8
# Example 1 | |
|
|
choose list (array)
Choose an element at random from a list (array).
Introduced in v2.0
# Example 1 | |
|
|
chord tonic (symbol), name (symbol)
Creates an immutable ring of Midi note numbers when given a tonic note and a chord type. If only passed a chord type, will default the tonic to 0. See examples.
Introduced in v2.0
invert: |
Apply the specified num inversions to chord. See the fn |
num_octaves: |
Create an arpeggio of the chord over n octaves |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
chord_degree degree (symbol_or_number), tonic (symbol), scale (symbol), number_of_notes (number)
In music we build chords from scales. For example, a C major chord is made by taking the 1st, 3rd and 5th notes of the C major scale (C, E and G). If you do this on a piano you might notice that you play one, skip one, play one, skip one etc. If we use the same spacing and start from the second note in C major (which is a D), we get a D minor chord which is the 2nd, 4th and 6th notes in C major (D, F and A). We can move this pattern all the way up or down the scale to get different types of chords. chord_degree
is a helper method that returns a ring of midi note numbers when given a degree (starting point in a scale) which is a symbol :i
, :ii
, :iii
, :iv
, :v
, :vi
, :vii
or a number 1
-7
. The second argument is the tonic note of the scale, the third argument is the scale type and finally the fourth argument is number of notes to stack up in the chord. If we choose 4 notes from degree :i
of the C major scale, we take the 1st, 3rd, 5th and 7th notes of the scale to get a C major 7 chord.
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
chord_invert notes (list), shift (number)
Given a set of notes, apply a number of inversions indicated by the shift
parameter. Inversions being an increase to notes if shift
is positive or decreasing the notes if shift
is negative.
An inversion is simply rotating the chord and shifting the wrapped notes up or down an octave. For example, consider the chord :e3, :minor - (ring 52, 55, 59)
. When we invert it once, we rotate the notes around to (ring 55, 59, 52)
. However, because note 52 is wrapped round, it’s shifted up an octave (12 semitones) so the actual first inversion of the chord :e3, :minor is (ring 55, 59, 52 + 12)
or (ring 55, 59, 64)
.
Note that it’s also possible to directly invert chords on creation with the invert:
opt - (chord :e3, :minor, invert: 2)
Introduced in v2.6
# Example 1 | |
|
|
chord_names
Returns a ring containing all chord names known to Sonic Pi
Introduced in v2.6
# Example 1 | |
|
|
comment
Does not evaluate any of the code within the block. However, any optional args passed before the block will be evaluated although they will be ignored. See uncomment
for switching commenting off without having to remove the comment form.
Introduced in v2.0
# Example 1 | |
|
|
control node (synth_node)
Control a running synth node by passing new parameters to it. A synth node represents a running synth and can be obtained by assigning the return value of a call to play or sample or by specifying a parameter to the do/end block of an FX. You may modify any of the parameters you can set when triggering the synth, sample or FX. See documentation for opt details. If the synth to control is a chord, then control will change all the notes of that chord group at once to a new target set of notes - see example. Also, you may use the on: opt to conditionally trigger the control - see the docs for the synth
and sample
fns for more information.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
cue cue_id (symbol)
Send a heartbeat synchronisation message containing the (virtual) timestamp of the current thread. Useful for syncing up external threads via the sync
fn. Any opts which are passed are given to the thread which syncs on the cue_id
as a map. The values of the opts must be immutable. Currently only numbers, symbols and booleans are supported.
Introduced in v2.0
your_key: |
Your value |
another_key: |
Another value |
key: |
All these opts are passed through to the thread which syncs |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
current_arg_checks
Returns the current arg checking setting (true
or false
).
This can be set via the fns use_arg_checks
and with_arg_checks
.
Introduced in v2.0
# Example 1 | |
|
|
current_beat_duration
Get the duration of the current beat in seconds. This is the actual length of time which will elapse with sleep 1
.
Affected by calls to use_bpm
, with_bpm
, use_sample_bpm
and with_sample_bpm
.
Introduced in v2.6
# Example 1 | |
|
|
current_bpm
Returns the current tempo as a bpm value.
This can be set via the fns use_bpm
, with_bpm
, use_sample_bpm
and with_sample_bpm
.
Introduced in v2.0
# Example 1 | |
|
|
current_cent_tuning
Returns the cent shift value.
This can be set via the fns use_cent_tuning
and with_cent_tuning
.
Introduced in v2.9
# Example 1 | |
|
|
current_debug
Returns the current debug setting (true
or false
).
This can be set via the fns use_debug
and with_debug
.
Introduced in v2.0
# Example 1 | |
|
|
current_octave
Returns the octave shift value.
This can be set via the fns use_octave
and with_octave
.
Introduced in v2.9
# Example 1 | |
|
|
current_random_seed
Returns the current random seed.
This can be set via the fns use_random_seed
and with_random_seed. It is incremented every time you use the random number generator via fns such as
choose and
rand`.
Introduced in v2.10
# Example 1 | |
|
|
# Example 2 | |
|
|
current_sample_defaults
Returns the current sample defaults. This is a map of synth arg names to either values or functions.
This can be set via the fns use_sample_defaults
, with_sample_defaults
, use_merged_sample_defaults
and with_merged_sample_defaults
.
Introduced in v2.5
# Example 1 | |
|
|
current_sample_pack
Returns the current sample pack.
This can be set via the fns use_sample_pack
and with_sample_pack
.
Introduced in v2.0
# Example 1 | |
|
|
current_sched_ahead_time
Returns the current schedule ahead time.
This can be set via the fn set_sched_ahead_time!
.
Introduced in v2.0
# Example 1 | |
|
|
current_synth
Returns the current synth name.
This can be set via the fns use_synth
and with_synth
.
Introduced in v2.0
# Example 1 | |
|
|
current_synth_defaults
Returns the current synth defaults. This is a map of synth arg names to either values or functions.
This can be set via the fns use_synth_defaults
, with_synth_defaults
, use_merged_synth_defaults
and with_merged_synth_defaults
.
Introduced in v2.0
# Example 1 | |
|
|
current_transpose
Returns the current transpose value.
This can be set via the fns use_transpose
and with_transpose
.
Introduced in v2.0
# Example 1 | |
|
|
current_volume
Returns the current volume.
This can be set via the fn set_volume!
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
dec n (number)
Decrement a number by 1
. Equivalent to n - 1
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
define name (symbol)
Allows you to group a bunch of code and give it your own name for future re-use. Functions are very useful for structuring your code. They are also the gateway into live coding as you may redefine a function whilst a thread is calling it, and the next time the thread calls your function, it will use the latest definition.
Introduced in v2.0
# Example 1 | |
|
|
defonce name (symbol)
Allows you to assign the result of some code to a name, with the property that the code will only execute once - therefore stopping re-definitions. This is useful for defining values that you use in your compositions but you don’t want to reset every time you press run. You may force the block to execute again regardless of whether or not it has executed once already by using the override option (see examples).
Introduced in v2.0
override: |
If set to true, re-definitions are allowed and this acts like define |
# Example 1 | |
|
|
# Example 2 | |
|
|
degree degree (symbol_or_number), tonic (symbol), scale (symbol)
For a given scale and tonic it takes a symbol :i
, :ii
, :iii
, :iv
,:v
, :vi
, :vii
or a number 1
-7
and resolves it to a midi note.
Introduced in v2.1
# Example 1 | |
|
|
density d (density)
Runs the block d
times with the bpm for the block also multiplied by d
. Great for repeating sections a number of times faster yet keeping within a fixed time. If d
is less than 1, then time will be stretched accordingly and the block will take longer to complete.
Introduced in v2.3
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
dice num_sides (number)
Throws a dice with the specified num_sides (defaults to 6
) and returns the score as a number between 1
and num_sides
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
doubles start (number), num_doubles (int)
Create a ring containing the results of successive doubling of the start
value. If num_doubles
is negative, will return a ring of halves
.
Introduced in v2.10
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
factor? val (number), factor (number)
Test to see if factor is indeed a factor of val
. In other words, can val
be divided exactly by factor.
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
fx_names
Return a list of all the FX available
Introduced in v2.10
halves start (number), num_halves (int)
Create a ring containing the results of successive halving of the start
value. If num_halves
is negative, will return a ring of doubles
.
Introduced in v2.10
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
hz_to_midi freq (number)
Convert a frequency in hz to a midi note. Note that the result isn’t an integer and there is a potential for some very minor rounding errors.
Introduced in v2.0
# Example 1 | |
|
|
in_thread
Execute a given block (between do
… end
) in a new thread. Use for playing multiple ‘parts’ at once. Each new thread created inherits all the use/with defaults of the parent thread such as the time, current synth, bpm, default synth args, etc. Despite inheriting defaults from the parent thread, any modifications of the defaults in the new thread will not affect the parent thread. Threads may be named with the name:
optional arg. Named threads will print their name in the logging pane when they print their activity. If you attempt to create a new named thread with a name that is already in use by another executing thread, no new thread will be created.
It is possible to delay the initial trigger of the thread on creation with both the delay:
and sync:
opts. See their respective docstrings. If both delay:
and sync:
are specified, on initial thread creation first the delay will be honoured and then the sync.
Introduced in v2.0
name: |
Make this thread a named thread with name. If a thread with this name already exists, a new thread will not be created. |
delay: |
Initial delay in beats before the thread starts. Default is 0. |
sync: |
Initial sync symbol. Will sync with this symbol before the thread starts. |
sync_bpm: |
Initial sync symbol. Will sync with this symbol before the live_loop starts. Live loop will also inherit the BPM of the thread which cued the symbol. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
inc n (number)
Increment a number by 1
. Equivalent to n + 1
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
inspect output (anything)
Displays the information you specify as an inspected string inside the output pane. This can be a number, symbol, or a string itself.
Introduced in v2.8
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
kill node (synth_node)
Kill a running synth sound or sample. In order to kill a sound, you need to have stored a reference to it in a variable.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
knit value (anything), count (number)
Knits a series of value, count pairs to create a ring buffer where each value is repeated count times.
Introduced in v2.2
# Example 1 | |
|
|
# Example 2 | |
|
|
line start (number), finish (number)
Create a ring buffer representing a straight line between start and finish of num_slices elements. Num slices defaults to 8
. Indexes wrap around positively and negatively. Similar to range
.
Introduced in v2.5
steps: |
number of slices or segments along the line |
inclusive: |
boolean value representing whether or not to include finish value in line |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
live_loop name (symbol)
Run the block in a new thread with the given name, and loop it forever. Also sends a cue
with the same name each time the block runs. If the block is given a parameter, this is given the result of the last run of the loop (with initial value either being 0
or an init arg).
It is possible to delay the initial trigger of the live_loop on creation with both the delay:
and sync:
opts. See their respective docstrings. If both delay:
and sync:
are specified, on initial live_loop creation first the delay will be honoured and then the sync.
Introduced in v2.1
init: |
initial value for optional block arg |
auto_cue: |
enable or disable automatic cue (default is true) |
delay: |
Initial delay in beats before the live_loop starts. Default is 0. |
sync: |
Initial sync symbol. Will sync with this symbol before the live_loop starts. |
sync_bpm: |
Initial sync symbol. Will sync with this symbol before the live_loop starts. Live loop will also inherit the BPM of the thread which cued the symbol. |
seed: |
override initial random generator seed before starting loop. |
# Example 1 | |
|
|
# Example 2 | |
|
|
load_buffer path (string)
Given a path to a file, will read the contents and load it into the current buffer. This will replace any previous content.
Introduced in v2.10
# Example 1 | |
|
|
load_example path (string)
Given a keyword representing an example, will load it into the current buffer. This will replace any previous content.
Introduced in v2.10
# Example 1 | |
|
|
load_sample path (string)
Given a path to a .wav
, .wave
, .aif
, .aiff
or .flac
file, pre-loads the sample into memory.
You may also specify the same set of source and filter pre-args available to sample
itself. load_sample
will then load all matching samples. See sample
’s docs for more information.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
load_samples paths (list)
Synonym for load_sample
Introduced in v2.0
# Example 1 | |
|
|
load_synthdefs path (string)
Load all pre-compiled synth designs in the specified directory. The binary files containing synth designs need to have the extension .scsyndef
. This is useful if you wish to use your own SuperCollider synthesiser designs within Sonic Pi.
You may not trigger external synthdefs unless you enable the following GUI preference:
Studio -> Synths -> Enable external synths and FX
Also, if you wish your synth to work with Sonic Pi’s automatic stereo sound infrastructure you need to ensure your synth outputs a stereo signal to an audio bus with an index specified by a synth arg named out_bus
. For example, the following synth would work nicely:
(
SynthDef(\piTest,
{|freq = 200, amp = 1, out_bus = 0 |
Out.ar(out_bus,
SinOsc.ar([freq,freq],0,0.5)* Line.kr(1, 0, 5, amp, doneAction: 2))}
).writeDefFile("/Users/sam/Desktop/")
)
Introduced in v2.0
# Example 1 | |
|
|
look
Read and return value of default tick. If a key
is specified, read the value of that specific tick. Ticks are in_thread
and live_loop
local, so the tick read will be the tick of the current thread calling look
.
Introduced in v2.6
offset: |
Offset to add to index returned. Useful when calling look on lists, rings and vectors to offset the returned value |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
mc_block_id name (symbol_or_number)
Given a block name or id will return a number representing the id of the block or throw an exception if the name or id isn’t valid
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
mc_block_ids
Returns a list of all the valid block ids as numbers. Note not all numbers are valid block ids. For example, 19 is not a valid block id.
Introduced in v2.5
# Example 1 | |
|
|
mc_block_name id (number_or_symbol)
Given a block id or a block name will return a symbol representing the block name or throw an exception if the id or name isn’t valid.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
mc_block_names
Returns a list of all the valid block names as symbols
Introduced in v2.5
# Example 1 | |
|
|
mc_camera_fixed
Set the camera mode to fixed.
Introduced in v2.5
# Example 1 | |
|
|
mc_camera_normal
Set the camera mode to normal.
Introduced in v2.5
# Example 1 | |
|
|
mc_camera_set_location
Move the camera to a new location.
Introduced in v2.5
# Example 1 | |
|
|
mc_camera_third_person
Set the camera mode to third person
Introduced in v2.5
# Example 1 | |
|
|
mc_chat_post
See mc_message
Introduced in v2.5
mc_checkpoint_restore
Restore the world to the last snapshot taken with mc_checkpoint_save
.
Introduced in v2.5
# Example 1 | |
|
|
mc_checkpoint_save
Take a snapshot of the world and save it. Restore back with mc_checkpoint_restore
Introduced in v2.5
# Example 1 | |
|
|
mc_get_block x (number), y (number), z (number)
Returns the type of the block at the coords x
, y
, z
as a symbol.
Introduced in v2.5
# Example 1 | |
|
|
mc_get_height
See mc_ground_height
Introduced in v2.5
mc_get_pos
See mc_location
Introduced in v2.5
mc_get_tile
Returns the coordinates of the nearest block that the player is next to. This is more course grained than mc_location
as it only returns whole number coordinates.
Introduced in v2.5
# Example 1 | |
|
|
mc_ground_height x (number), z (number)
Returns the height of the ground at the specified x
and z
coords.
Introduced in v2.5
# Example 1 | |
|
|
mc_location
Returns a list of floats [x, y, z]
coords of the current location for Steve. The coordinates are finer grained than raw block coordinates but may be used anywhere you might use block coords.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
mc_message msg (string)
Post contents of msg
on the Minecraft chat display. You may pass multiple arguments and all will be joined to form a single message (with spaces).
Introduced in v2.5
# Example 1 | |
|
|
mc_set_area block_name (symbol_or_number), x (number), y (number), z (number), x2 (number), y2 (number), z2 (number)
Set an area/box of blocks of type block_name
defined by two distinct sets of coordinates.
Introduced in v2.5
mc_set_block x (number), y (number), z (number), block_name (symbol_or_number)
Change the block type of the block at coords x
, y
, z
to block_type
. The block type may be specified either as a symbol such as :air
or a number. See mc_block_ids
and mc_block_types
for lists of valid symbols and numbers.
Introduced in v2.5
# Example 1 | |
|
|
mc_set_pos
See mc_teleport
Introduced in v2.5
mc_set_tile x (number), y (number), z (number)
Introduced in v2.5
# Example 1 | |
|
|
mc_surface_teleport x (number), z (number)
Teleports you to the specified x and z coordinates with the y automatically set to place you on the surface of the world. For example, if the x and z coords target a mountain, you’ll be placed on top of the mountain, not in the air or under the ground. See mc_ground_height for discovering the height of the ground at a given x, z point.
Introduced in v2.5
# Example 1 | |
|
|
mc_teleport x (number), y (number), z (number)
Magically teleport the player to the location specified by the x
, y
, z
coordinates. Use this for automatically moving the player either small or large distances around the world.
Introduced in v2.5
# Example 1 | |
|
|
midi_notes list (array)
Create a new immutable ring buffer of notes from args. Indexes wrap around positively and negatively. Final ring consists only of MIDI numbers and nil.
Introduced in v2.7
# Example 1 | |
|
|
# Example 2 | |
|
|
midi_to_hz note (symbol_or_number)
Convert a midi note to hz
Introduced in v2.0
# Example 1 | |
|
|
ndefine name (symbol)
Does nothing. Use to stop a define from actually defining. Simpler than wrapping whole define in a comment block or commenting each individual line out.
Introduced in v2.1
note note (symbol_or_number)
Takes a midi note, a symbol (e.g. :C
) or a string (e.g. "C"
) and resolves it to a midi note. You can also pass an optional octave:
parameter to get the midi note for a given octave. Please note - octave:
param overrides any octave specified in a symbol i.e. :c3
. If the note is nil
, :r
or :rest
, then nil
is returned (nil
represents a rest)
Introduced in v2.0
octave: |
The octave of the note. Overrides any octave declaration in the note symbol such as :c2. Default is 4 |
# Example 1 | |
|
|
# Example 2 | |
|
|
note_info note (symbol_or_number)
Returns an instance of SonicPi::Note
. Please note - octave:
param overrides any octave specified in a symbol i.e. :c3
Introduced in v2.0
octave: |
The octave of the note. Overrides any octave declaration in the note symbol such as :c2. Default is 4 |
# Example 1 | |
|
|
note_range low_note (note), high_note (note)
Produces a ring of all the notes between a low note and a high note. By default this is chromatic (all the notes) but can be filtered with a :pitches argument. This opens the door to arpeggiator style sequences and other useful patterns. If you try to specify only pitches which aren’t in the range it will raise an error - you have been warned!
Introduced in v2.6
pitches: |
An array of notes (symbols or ints) to filter on. Octave information is ignored. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
octs start (note), num_octaves (pos_int)
Create a ring of successive octaves starting at start
for num_octaves
.
Introduced in v2.8
# Example 1 | |
|
|
# Example 2 | |
|
|
on condition (truthy)
Optionally evaluate the block depending on the truthiness of the supplied condition. The truthiness rules are as follows: all values are seen as true except for: false, nil and 0. Lambdas will be automatically called and the truthiness of their results used.
Introduced in v2.10
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
one_in num (number)
Returns true
or false
with a specified probability - it will return true every one in num times where num is the param you specify
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
pick list (array), n (number_or_nil)
Pick n elements from list or ring. Unlike shuffle, after each element has been picked, it is ‘returned’ to the list so it may be picked again. This means there may be duplicates in the result. If n is greater than the size of the ring/list then duplicates are guaranteed to be in the result.
If n
isn’t supplied it defaults to the size of the list/ring.
Introduced in v2.10
skip: |
Number of rands to skip over with each successive pick |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
pitch_to_ratio pitch (midi_number)
Convert a midi note to a ratio which when applied to a frequency will scale the frequency by the number of semitones. Useful for changing the pitch of a sample by using it as a way of generating the rate.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
play note (symbol_or_number)
Play note with current synth. Accepts a set of standard options which include control of an amplitude envelope with attack:
, decay:
, sustain:
and release:
phases. These phases are triggered in order, so the duration of the sound is attack + decay + sustain + release times. The duration of the sound does not affect any other notes. Code continues executing whilst the sound is playing through its envelope phases.
Accepts optional args for modification of the synth being played. See each synth’s documentation for synth-specific opts. See use_synth
and with_synth
for changing the current synth.
If note is nil
, :r
or :rest
, play is ignored and treated as a rest. Also, if the on:
opt is specified and returns false
, or nil
then play is similarly ignored and treated as a rest.
Note that the default opts listed are only a guide to the most common opts across all the synths. Not all synths support all the default opts and each synth typically supports many more opts specific to that synth. For example, the :tb303
synth supports 45 unique opts. For a full list of a synth’s opts see its documentation in the Help system.
Introduced in v2.0
amp: |
The amplitude of the note |
amp_slide: |
The duration in beats for amplitude changes to take place |
pan: |
The stereo position of the sound. -1 is left, 0 is in the middle and 1 is on the right. You may use a value in between -1 and 1 such as 0.25 |
pan_slide: |
The duration in beats for the pan value to change |
attack: |
Amount of time (in beats) for sound to reach full amplitude (attack_level). A short attack (i.e. 0.01) makes the initial part of the sound very percussive like a sharp tap. A longer attack (i.e 1) fades the sound in gently. |
decay: |
Amount of time (in beats) for the sound to move from full amplitude (attack_level) to the sustain amplitude (sustain_level). |
sustain: |
Amount of time (in beats) for sound to remain at sustain level amplitude. Longer sustain values result in longer sounds. Full length of sound is attack + decay + sustain + release. |
release: |
Amount of time (in beats) for sound to move from sustain level amplitude to silent. A short release (i.e. 0.01) makes the final part of the sound very percussive (potentially resulting in a click). A longer release (i.e 1) fades the sound out gently. |
attack_level: |
Amplitude level reached after attack phase and immediately before decay phase |
decay_level: |
Amplitude level reached after decay phase and immediately before sustain phase. Defaults to sustain_level unless explicitly set |
sustain_level: |
Amplitude level reached after decay phase and immediately before release phase. |
env_curve: |
Select the shape of the curve between levels in the envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed |
slide: |
Default slide time in beats for all slide opts. Individually specified slide opts will override this value |
pitch: |
Pitch adjustment in semitones. 1 is up a semitone, 12 is up an octave, -12 is down an octave etc. Decimal numbers can be used for fine tuning. |
on: |
If specified and false/nil/0 will stop the synth from being played. Ensures all opts are evaluated. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
play_chord notes (list)
Play a list of notes at the same time.
Accepts optional args for modification of the synth being played. See each synth’s documentation for synth-specific opts. See use_synth
and with_synth
for changing the current synth.
Introduced in v2.0
amp: |
The amplitude of the note |
amp_slide: |
The duration in beats for amplitude changes to take place |
pan: |
The stereo position of the sound. -1 is left, 0 is in the middle and 1 is on the right. You may use a value in between -1 and 1 such as 0.25 |
pan_slide: |
The duration in beats for the pan value to change |
attack: |
Amount of time (in beats) for sound to reach full amplitude (attack_level). A short attack (i.e. 0.01) makes the initial part of the sound very percussive like a sharp tap. A longer attack (i.e 1) fades the sound in gently. |
decay: |
Amount of time (in beats) for the sound to move from full amplitude (attack_level) to the sustain amplitude (sustain_level). |
sustain: |
Amount of time (in beats) for sound to remain at sustain level amplitude. Longer sustain values result in longer sounds. Full length of sound is attack + decay + sustain + release. |
release: |
Amount of time (in beats) for sound to move from sustain level amplitude to silent. A short release (i.e. 0.01) makes the final part of the sound very percussive (potentially resulting in a click). A longer release (i.e 1) fades the sound out gently. |
attack_level: |
Amplitude level reached after attack phase and immediately before decay phase |
decay_level: |
Amplitude level reached after decay phase and immediately before sustain phase. Defaults to sustain_level unless explicitly set |
sustain_level: |
Amplitude level reached after decay phase and immediately before release phase. |
env_curve: |
Select the shape of the curve between levels in the envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed |
slide: |
Default slide time in beats for all slide opts. Individually specified slide opts will override this value |
pitch: |
Pitch adjustment in semitones. 1 is up a semitone, 12 is up an octave, -12 is down an octave etc. Decimal numbers can be used for fine tuning. |
on: |
If specified and false/nil/0 will stop the synth from being played. Ensures all opts are evaluated. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
play_pattern notes (list)
Play list of notes with the current synth one after another with a sleep of 1
Accepts optional args for modification of the synth being played. See each synth’s documentation for synth-specific opts. See use_synth and with_synth for changing the current synth.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
play_pattern_timed notes (list), times (list_or_number)
Play each note in a list of notes one after another with specified times between them. The notes should be a list of MIDI numbers, symbols such as :E4 or chords such as chord(:A3, :major) - identical to the first parameter of the play function. The times should be a list of times between the notes in beats.
If the list of times is smaller than the number of gaps between notes, the list is repeated again. If the list of times is longer than the number of gaps between notes, then some of the times are ignored. See examples for more detail.
Accepts optional args for modification of the synth being played. See each synth’s documentation for synth-specific opts. See use_synth
and with_synth
for changing the current synth.
Introduced in v2.0
amp: |
The amplitude of the note |
amp_slide: |
The duration in beats for amplitude changes to take place |
pan: |
The stereo position of the sound. -1 is left, 0 is in the middle and 1 is on the right. You may use a value in between -1 and 1 such as 0.25 |
pan_slide: |
The duration in beats for the pan value to change |
attack: |
Amount of time (in beats) for sound to reach full amplitude (attack_level). A short attack (i.e. 0.01) makes the initial part of the sound very percussive like a sharp tap. A longer attack (i.e 1) fades the sound in gently. |
decay: |
Amount of time (in beats) for the sound to move from full amplitude (attack_level) to the sustain amplitude (sustain_level). |
sustain: |
Amount of time (in beats) for sound to remain at sustain level amplitude. Longer sustain values result in longer sounds. Full length of sound is attack + decay + sustain + release. |
release: |
Amount of time (in beats) for sound to move from sustain level amplitude to silent. A short release (i.e. 0.01) makes the final part of the sound very percussive (potentially resulting in a click). A longer release (i.e 1) fades the sound out gently. |
attack_level: |
Amplitude level reached after attack phase and immediately before decay phase |
decay_level: |
Amplitude level reached after decay phase and immediately before sustain phase. Defaults to sustain_level unless explicitly set |
sustain_level: |
Amplitude level reached after decay phase and immediately before release phase. |
env_curve: |
Select the shape of the curve between levels in the envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed |
slide: |
Default slide time in beats for all slide opts. Individually specified slide opts will override this value |
pitch: |
Pitch adjustment in semitones. 1 is up a semitone, 12 is up an octave, -12 is down an octave etc. Decimal numbers can be used for fine tuning. |
on: |
If specified and false/nil/0 will stop the synth from being played. Ensures all opts are evaluated. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
print output (anything)
Displays the information you specify as a string inside the output pane. This can be a number, symbol, or a string itself. Useful for debugging. Synonym for puts
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
puts output (anything)
Displays the information you specify as a string inside the output pane. This can be a number, symbol, or a string itself. Useful for debugging. Synonym for print
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
quantise n (number), step (positive_number)
Round value to the nearest multiple of step resolution.
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
ramp list (array)
Create a new immutable ramp vector from args. Indexes always return first or last value if out of bounds.
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
rand max (number_or_range)
Given a max number, produces a float between 0
and the supplied max value. If max is a range, produces a float within the range. With no args returns a random value between 0
and 1
.
Introduced in v2.0
# Example 1 | |
|
|
rand_back amount (number)
Roll the random generator back essentially ‘undoing’ the last call to rand
. You may specify an amount to roll back allowing you to skip back n calls to rand
.
Introduced in v2.7
# Example 1 | |
|
|
# Example 2 | |
|
|
rand_i max (number_or_range)
Given a max number, produces a whole number between 0
and the supplied max value exclusively. If max is a range produces an int within the range. With no args returns either 0
or 1
Introduced in v2.0
# Example 1 | |
|
|
rand_reset ()
Resets the random stream to the last specified seed. See use_random_seed
for changing the seed.
Introduced in v2.7
# Example 1 | |
|
|
rand_skip amount (number)
Jump the random generator forward essentially skipping the next call to rand
. You may specify an amount to jump allowing you to skip n calls to rand
.
Introduced in v2.7
# Example 1 | |
|
|
# Example 2 | |
|
|
range start (number), finish (number), step_size (number)
Create a new ring buffer from the range arguments (start, finish and step size). Step size defaults to 1
. Indexes wrap around positively and negatively
Introduced in v2.2
step: |
Size of increment between steps; step size. |
inclusive: |
If set to true, range is inclusive of finish value |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
ratio_to_pitch ratio (number)
Convert a frequency ratio to a midi note which when added to a note will transpose the note to match the frequency ratio.
Introduced in v2.7
# Example 1 | |
|
|
# Example 2 | |
|
|
rdist width (number), centre (number)
Returns a random number within the range with width around centre. If optional arg step:
is used, the result is quantised by step.
Introduced in v2.3
step: |
Step size of value to quantise to. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
reset_mixer!
The master mixer is the final mixer that all sound passes through. This fn resets it to its default set - undoing any changes made via set_mixer_control!
Introduced in v2.9
# Example 1 | |
|
|
rest? note_or_args (number_symbol_or_map)
Given a note or an args map, returns true if it represents a rest and false if otherwise
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
ring list (array)
Create a new immutable ring buffer from args. Indexes wrap around positively and negatively
Introduced in v2.2
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
rrand min (number), max (number)
Given two numbers, this produces a float between the supplied min and max values exclusively. Both min and max need to be supplied. For random integers, see rrand_i
. If optional arg step:
is used, the result is quantised by step.
Introduced in v2.0
step: |
Step size of value to quantise to. |
# Example 1 | |
|
|
# Example 2 | |
|
|
rrand_i min (number), max (number)
Given two numbers, this produces a whole number between the min and max you supplied inclusively. Both min and max need to be supplied. For random floats, see rrand
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
rt seconds (number)
Real time representation. Returns the amount of beats for the value in real-time seconds. Useful for bypassing any bpm scaling
Introduced in v2.0
# Example 1 | |
|
|
sample name_or_path (symbol_or_string)
Play back a recorded sound file (sample). Sonic Pi comes with lots of great samples included (see the section under help) but you can also load and play .wav
, .wave
, .aif
, .aiff
or .flac
files from anywhere on your computer too. To play a built-in sample use the corresponding keyword such as sample :bd_haus
. To play any file on your computer use a full path such as sample "/path/to/sample.wav"
.
There are many opts for manipulating the playback. For example, the rate:
opt affects both the speed and the pitch of the playback. To control the rate of the sample in a pitch-meaningful way take a look at the rpitch:
opt.
The sampler synth has three separate envelopes - one for amplitude, one for a low pass filter and another for a high pass filter. These work very similar to the standard synth envelopes except for two major differences. Firstly, the envelope times do not stretch or shrink to match the BPM. Secondly, the sustain time by default stretches to make the envelope fit the length of the sample. This is explained in detail in the tutorial.
Samples are loaded on-the-fly when first requested (and subsequently remembered). If the sample loading process takes longer than the schedule ahead time, the sample trigger will be skipped rather than be played late and out of time. To avoid this you may preload any samples you wish to work with using load_sample
or load_samples
.
Finally, the sampler supports a powerful filtering system to make it easier to work with large folders of samples. The filter commands must be used before the first standard opt. There are six kinds of filter parameters you may use:
"/foo/bar"
- which will add all samples within the folder to the set of candidates."/path/to/sample.wav"
- which will add the specific sample to the set of candidates."foobar"
- which will filter the candidates based on whether the filename contains the string./b[aA]z.*/
- which will filter the candidates based on whether the regular expression matches the filename.:quux
- will filter the candidates based on whether the keyword is a direct match of the filename (without extension).0
- will select the candidate with that index (wrapping round like a ring if necessary).["/foo/bar", "baz", /0-9.*/]
- will recurse down and work through the internal filter parameters as if they were in the top level.By combining commands which add to the candidates and then filtering those candidates it is possible to work with folders full of samples in very powerful ways. Note that the specific ordering of filter parameters is irrelevant with the exception of the numbers - in which case the last number is the index. All the candidates will be gathered first before the filters are applied.
Introduced in v2.0
rate: |
Rate with which to play back the sample. Higher rates mean an increase in pitch and a decrease in duration. Default is 1. |
beat_stretch: |
Stretch (or shrink) the sample to last for exactly the specified number of beats. Please note - this does not keep the pitch constant and is essentially the same as modifying the rate directly. |
pitch_stretch: |
Stretch (or shrink) the sample to last for exactly the specified number of beats. This attempts to keep the pitch constant using the |
attack: |
Time to reach full volume. Default is 0. |
sustain: |
Time to stay at full volume. Default is to stretch to length of sample (minus attack and release times). |
release: |
Time (from the end of the sample) to go from full amplitude to 0. Default is 0. |
start: |
Position in sample as a fraction between 0 and 1 to start playback. Default is 0. |
finish: |
Position in sample as a fraction between 0 and 1 to end playback. Default is 1. |
pan: |
Stereo position of audio. -1 is left ear only, 1 is right ear only, and values in between position the sound accordingly. Default is 0. |
amp: |
Amplitude of playback. |
pre_amp: |
Amplitude multiplier which takes place immediately before any internal FX such as the low pass filter, compressor or pitch modification. Use this opt if you want to overload the compressor. |
norm: |
Normalise the audio (make quieter parts of the sample louder and louder parts quieter) - this is similar to the normaliser FX. This may emphasise any clicks caused by clipping. |
lpf: |
Cutoff value of the built-in low pass filter (lpf) in MIDI notes. Unless specified, the lpf is not added to the signal chain. |
lpf_init_level: |
The initial low pass filter envelope value as a MIDI note. This envelope is bypassed if no lpf env opts are specified. Default value is to match the |
lpf_attack_level: |
The peak lpf cutoff (value of cutoff at peak of attack) as a MIDI note. Default value is to match the |
lpf_decay_level: |
The level of lpf cutoff after the decay phase as a MIDI note. Default value is to match the |
lpf_sustain_level: |
The sustain cutoff (value of lpf cutoff at sustain time) as a MIDI note. Default value is to match the |
lpf_release_level: |
The final value of the low pass filter envelope as a MIDI note. This envelope is bypassed if no lpf env opts are specified. Default value is to match the |
lpf_attack: |
Attack time for lpf cutoff filter. Amount of time (in beats) for sound to reach full cutoff value. Default value is set to match amp envelope’s attack value. |
lpf_decay: |
Decay time for lpf cutoff filter. Amount of time (in beats) for sound to move from full cutoff value (cutoff attack level) to the cutoff sustain level. Default value is set to match amp envelope’s decay value. |
lpf_sustain: |
Amount of time for lpf cutoff value to remain at sustain level in beats. When -1 (the default) will auto-stretch. |
lpf_release: |
Amount of time (in beats) for sound to move from lpf cutoff sustain value to lpf cutoff min value. Default value is set to match amp envelope’s release value. |
lpf_min: |
Starting value of the lpf cutoff envelope. Default is 30. |
lpf_env_curve: |
Select the shape of the curve between levels in the lpf cutoff envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed. |
hpf: |
Cutoff value of the built-in high pass filter (hpf) in MIDI notes. Unless specified, the hpf is not added to the signal chain. |
hpf_init_level: |
The initial high pass filter envelope value as a MIDI note. This envelope is bypassed if no hpf env opts are specified. Default value is set to 130. |
hpf_attack_level: |
The peak hpf cutoff (value of cutoff at peak of attack) as a MIDI note. Default value is to match the |
hpf_decay_level: |
The level of hpf cutoff after the decay phase as a MIDI note. Default value is to match the |
hpf_sustain_level: |
The sustain cutoff (value of hpf cutoff at sustain time) as a MIDI note. Default value is to match the |
hpf_release_level: |
The sustain hpf cutoff (value of hpf cutoff at sustain time) as a MIDI note. Default value is to match the |
hpf_attack: |
Attack time for hpf cutoff filter. Amount of time (in beats) for sound to reach full cutoff value. Default value is set to match amp envelope’s attack value. |
hpf_decay: |
Decay time for hpf cutoff filter. Amount of time (in beats) for sound to move from full cutoff value (cutoff attack level) to the cutoff sustain level. Default value is set to match amp envelope’s decay value. |
hpf_sustain: |
Amount of time for hpf cutoff value to remain at sustain level in beats. When -1 (the default) will auto-stretch. |
hpf_release: |
Amount of time (in beats) for sound to move from hpf cutoff sustain value to hpf cutoff min value. Default value is set to match amp envelope’s release value. |
hpf_env_curve: |
Select the shape of the curve between levels in the hpf cutoff envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed. |
hpf_max: |
Maximum value of the high pass filter envelope. Default is 200. |
rpitch: |
Rate modified pitch. Multiplies the rate by the appropriate ratio to shift up or down the specified amount in MIDI notes. Please note - this does not keep the duration and rhythmical rate constant and is essentially the same as modifying the rate directly. |
pitch: |
Pitch adjustment in semitones. 1 is up a semitone, 12 is up an octave, -12 is down an octave etc. Maximum upper limit of 24 (up 2 octaves). Lower limit of -72 (down 6 octaves). Decimal numbers can be used for fine tuning. |
window_size: |
Pitch shift-specific opt - only honoured if the |
pitch_dis: |
Pitch shift-specific opt - only honoured if the |
time_dis: |
Pitch shift-specific opt - only honoured if the |
compress: |
Enable the compressor. This sits at the end of the internal FX chain immediately before the |
threshold: |
Threshold value determining the break point between slope_below and slope_above. Only valid if the compressor is enabled by turning on the |
slope_below: |
Slope of the amplitude curve below the threshold. A value of 1 means that the output of signals with amplitude below the threshold will be unaffected. Greater values will magnify and smaller values will attenuate the signal. Only valid if the compressor is enabled by turning on the |
slope_above: |
Slope of the amplitude curve above the threshold. A value of 1 means that the output of signals with amplitude above the threshold will be unaffected. Greater values will magnify and smaller values will attenuate the signal. Only valid if the compressor is enabled by turning on the |
clamp_time: |
Time taken for the amplitude adjustments to kick in fully (in seconds). This is usually pretty small (not much more than 10 milliseconds). Also known as the time of the attack phase. Only valid if the compressor is enabled by turning on the |
relax_time: |
Time taken for the amplitude adjustments to be released. Usually a little longer than clamp_time. If both times are too short, you can get some (possibly unwanted) artefacts. Also known as the time of the release phase. Only valid if the compressor is enabled by turning on the |
slide: |
Default slide time in beats for all slide opts. Individually specified slide opts will override this value. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
# Example 9 | |
|
|
# Example 10 | |
|
|
# Example 11 | |
|
|
# Example 12 | |
|
|
# Example 13 | |
|
|
# Example 14 | |
|
|
# Example 15 | |
|
|
# Example 16 | |
|
|
# Example 17 | |
|
|
# Example 18 | |
|
|
# Example 19 | |
|
|
# Example 20 | |
|
|
# Example 21 | |
|
|
# Example 22 | |
|
|
# Example 23 | |
|
|
# Example 24 | |
|
|
# Example 25 | |
|
|
# Example 26 | |
|
|
sample_buffer path (string)
Alias for the load_sample
method. Loads sample if necessary and returns buffer information.
Introduced in v2.0
# Example 1 | |
|
|
sample_duration path (string)
Given the name of a loaded sample, or a path to a .wav
, .wave
, .aif
, .aiff
or .flac
file returns the length of time in beats that the sample would play for. sample_duration
understands and accounts for all the opts you can pass to sample
which have an effect on the playback duration such as rate:
. The time returned is scaled to the current BPM.
Note: avoid using sample_duration
to set the sleep time in live_loop
s, prefer stretching the sample with the beat_stretch:
opt or changing the BPM instead. See the examples below for details.
Introduced in v2.0
rate: |
Rate modifier. For example, doubling the rate will halve the duration. |
start: |
Start position of sample playback as a value from 0 to 1 |
finish: |
Finish position of sample playback as a value from 0 to 1 |
attack: |
Duration of the attack phase of the envelope. |
decay: |
Duration of the decay phase of the envelope. |
sustain: |
Duration of the sustain phase of the envelope. |
release: |
Duration of the release phase of the envelope. |
beat_stretch: |
Change the rate of the sample so that its new duration matches the specified number of beats. |
pitch_stretch: |
Change the rate of the sample so that its new duration matches the specified number of beats but attempt to preserve pitch. |
rpitch: |
Change the rate to shift the pitch up or down the specified number of MIDI notes. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
sample_free path (string)
Frees the memory and resources consumed by loading the sample on the server. Subsequent calls to sample
and friends will re-load the sample on the server.
You may also specify the same set of source and filter pre-args available to sample
itself. sample_free
will then free all matching samples. See sample
’s docs for more information.
Introduced in v2.9
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
sample_free_all ()
Unloads all samples therefore freeing the memory and resources consumed. Subsequent calls to sample
and friends will re-load the sample on the server.
Introduced in v2.9
# Example 1 | |
|
|
sample_groups
Return a list of all the sample groups available
Introduced in v2.0
sample_info path (string)
Alias for the load_sample
method. Loads sample if necessary and returns sample information.
Introduced in v2.0
# Example 1 | |
|
|
sample_loaded? path (string)
Given a path to a .wav
, .wave
, .aif
, .aiff
or .flac
file, returns true
if the sample has already been loaded.
Introduced in v2.2
# Example 1 | |
|
|
sample_names group (symbol)
Return a ring of sample names for the specified group
Introduced in v2.0
sample_paths pre_args (source_and_filter_types)
Accepts the same pre-args and opts as sample
and returns a ring of matched sample paths.
Introduced in v2.10
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
scale tonic (symbol), name (symbol)
Creates a ring of MIDI note numbers when given a tonic note and a scale name. Also takes an optional num_octaves:
parameter (octave 1
is the default). If only passed the scale name, the tonic defaults to 0. See examples.
Introduced in v2.0
num_octaves: |
The number of octaves you’d like the scale to consist of. More octaves means a larger scale. Default is 1. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
scale_names
Returns a ring containing all scale names known to Sonic Pi
Introduced in v2.6
# Example 1 | |
|
|
set_cent_tuning! cent_shift (number)
Globally tune Sonic Pi to play with another external instrument.
Uniformly tunes your music by shifting all notes played by the specified number of cents. To shift up by a cent use a cent tuning of 1. To shift down use negative numbers. One semitone consists of 100 cents.
See use_cent_tuning
for setting the cent tuning value locally for a specific thread or live_loop
. This is a global value and will shift the tuning for all notes. It will also persist for the entire session.
Important note: the cent tuning set by set_cent_tuning!
is independent of any thread-local cent tuning values set by use_cent_tuning
or with_cent_tuning
.
Introduced in v2.10
# Example 1 | |
|
|
set_control_delta! time (number)
Specify how many seconds between successive modifications (i.e. trigger then controls) of a specific node on a specific thread. Set larger if you are missing control messages sent extremely close together in time.
Introduced in v2.1
# Example 1 | |
|
|
set_mixer_control!
The master mixer is the final mixer that all sound passes through. This fn gives you control over the master mixer allowing you to manipulate all the sound playing through Sonic Pi at once. For example, you can sweep a lpf or hpf over the entire sound. You can reset the controls back to their defaults with reset_mixer!
.
Introduced in v2.7
pre_amp: |
Controls the amplitude of the signal prior to the FX stage of the mixer (prior to lpf/hpf stages). Has slide opts. Default 1. |
amp: |
Controls the amplitude of the signal after the FX stage. Has slide opts. Default 1. |
hpf: |
Global hpf FX. Has slide opts. Default 0. |
lpf: |
Global lpf FX. Has slide opts. Default 135.5. |
hpf_bypass: |
Bypass the global hpf. 0=no bypass, 1=bypass. Default 0. |
lpf_bypass: |
Bypass the global lpf. 0=no bypass, 1=bypass. Default 0. |
limiter_bypass: |
Bypass the final limiter. 0=no bypass, 1=bypass. Default 0. |
leak_dc_bypass: |
Bypass the final DC leak correction FX. 0=no bypass, 1=bypass. Default 0. |
# Example 1 | |
|
|
set_sched_ahead_time! time (number)
Specify how many seconds ahead of time the synths should be triggered. This represents the amount of time between pressing ‘Run’ and hearing audio. A larger time gives the system more room to work with and can reduce performance issues in playing fast sections on slower platforms. However, a larger time also increases latency between modifying code and hearing the result whilst live coding.
Introduced in v2.0
# Example 1 | |
|
|
set_volume! vol (number)
Set the main system volume to vol
. Accepts a value between 0
and 5
inclusive. Vols greater or smaller than the allowed values are trimmed to keep them within range. Default is 1
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
shuffle list (array)
Returns a new list with the same elements as the original but with their order shuffled. Also works for strings
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
sleep beats (number)
Wait for a number of beats before triggering the next command. Beats are converted to seconds by scaling to the current bpm setting.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
spark
Given a list of numeric values, this method turns them into a string of bar heights and prints them out. Useful for quickly graphing the shape of an array.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
spark_graph
Given a list of numeric values, this method turns them into a string of bar heights. Useful for quickly graphing the shape of an array. Remember to use puts so you can see the output. See spark
for a simple way of printing a spark graph.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
spread num_accents (number), size (number)
Creates a new ring of boolean values which space a given number of accents as evenly as possible throughout a bar. This is an implementation of the process described in ‘The Euclidean Algorithm Generates Traditional Musical Rhythms’ (Toussaint 2005).
Introduced in v2.4
rotate: |
rotate to the next strong beat allowing for easy permutations of the original rhythmic grouping (see example) |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
status
This returns a Hash of information about the synthesis environment. Mostly used for debugging purposes.
Introduced in v2.0
# Example 1 | |
|
|
stop
Stops the current thread or if not in a thread, stops the current run. Does not stop any running synths triggered previously in the run/thread or kill any existing sub-threads.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
stretch list (anything), count (number)
Stretches a list of values each value repeated count times. Always returns a ring regardless of the type of the list that is stretched. To preserve type, consider using .stretch
i.e. (ramp 1, 2, 3).stretch(2) #=> (ramp 1, 1, 2, 2, 3, 3)
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
sync cue_id (symbol)
Pause/block the current thread until a cue
heartbeat with a matching cue_id
is received. When a matching cue
message is received, unblock the current thread, and continue execution with the virtual time set to match the thread that sent the cue
heartbeat. The current thread is therefore synced to the cue
thread. If multiple cue ids are passed as arguments, it will sync
on the first matching cue_id
. By default the BPM of the cueing thread is inherited. This can be disabled using the bpm_sync: opt.
Introduced in v2.0
bpm_sync: |
Inherit the BPM of the cueing thread. Default is false |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
sync_bpm cue_id (symbol)
An alias for sync
with the bpm_sync:
opt set to true.`
Introduced in v2.10
# Example 1 | |
|
|
synth synth_name (symbol)
Trigger specified synth with given opts. Bypasses current_synth
value, yet still honours current_synth_defaults
. When using synth
, the note is no longer an explicit argument but an opt with the key note:
.
If note: opt is nil
, :r
or :rest
, play is ignored and treated as a rest. Also, if the on:
opt is specified and returns false
, or nil
then play is similarly ignored and treated as a rest.
If the synth name is nil
behaviour is identical to that of play
in that the current_synth
will determine the actual synth triggered.
Note that the default opts listed are only a guide to the most common opts across all the synths. Not all synths support all the default opts and each synth typically supports many more opts specific to that synth. For example, the :tb303
synth supports 45 unique opts. For a full list of a synth’s opts see its documentation in the Help system. This can be accessed directly by clicking on the name of the synth and using the shortcut C-i
Introduced in v2.0
amp: |
The amplitude of the note |
amp_slide: |
The duration in beats for amplitude changes to take place |
pan: |
The stereo position of the sound. -1 is left, 0 is in the middle and 1 is on the right. You may use a value in between -1 and 1 such as 0.25 |
pan_slide: |
The duration in beats for the pan value to change |
attack: |
Amount of time (in beats) for sound to reach full amplitude (attack_level). A short attack (i.e. 0.01) makes the initial part of the sound very percussive like a sharp tap. A longer attack (i.e 1) fades the sound in gently. |
decay: |
Amount of time (in beats) for the sound to move from full amplitude (attack_level) to the sustain amplitude (sustain_level). |
sustain: |
Amount of time (in beats) for sound to remain at sustain level amplitude. Longer sustain values result in longer sounds. Full length of sound is attack + decay + sustain + release. |
release: |
Amount of time (in beats) for sound to move from sustain level amplitude to silent. A short release (i.e. 0.01) makes the final part of the sound very percussive (potentially resulting in a click). A longer release (i.e 1) fades the sound out gently. |
attack_level: |
Amplitude level reached after attack phase and immediately before decay phase |
decay_level: |
Amplitude level reached after decay phase and immediately before sustain phase. Defaults to sustain_level unless explicitly set |
sustain_level: |
Amplitude level reached after decay phase and immediately before release phase. |
env_curve: |
Select the shape of the curve between levels in the envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed |
slide: |
Default slide time in beats for all slide opts. Individually specified slide opts will override this value |
pitch: |
Pitch adjustment in semitones. 1 is up a semitone, 12 is up an octave, -12 is down an octave etc. Decimal numbers can be used for fine tuning. |
on: |
If specified and false/nil/0 will stop the synth from being played. Ensures all opts are evaluated. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
synth_names
Return a list of all the synths available
Introduced in v2.9
tick key (symbol)
Increment the default tick by 1 and return value. Successive calls to tick
will continue to increment the default tick. If a key
is specified, increment that specific tick. If an increment value
is specified, increment key by that value rather than 1. Ticks are in_thread
and live_loop
local, so incrementing a tick only affects the current thread’s version of that tick. See tick_reset
and tick_set
for directly manipulating the tick vals.
Introduced in v2.6
step: |
The amount to tick up by. Default is 1. |
offset: |
Offset to add to index returned. Useful when calling tick on lists, rings and vectors to offset the returned value. Default is 0. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
tick_reset
Reset default tick to 0. If a key
is referenced, set that tick to 0 instead. Same as calling tick_set(0)
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
tick_reset_all value (number)
Reset all ticks - default and keyed
Introduced in v2.6
# Example 1 | |
|
|
tick_set value (number)
Set the default tick to the specified value
. If a key
is referenced, set that tick to value
instead. Next call to look
will return value
.
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
uncomment
Evaluates all of the code within the block. Use to reverse the effect of the comment without having to explicitly remove it.
Introduced in v2.0
# Example 1 | |
|
|
use_arg_bpm_scaling bool (boolean)
Turn synth argument bpm scaling on or off for the current thread. This is on by default. Note, using rt
for args will result in incorrect times when used after turning arg bpm scaling off.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
use_arg_checks true_or_false (boolean)
When triggering synths, each argument is checked to see if it is sensible. When argument checking is enabled and an argument isn’t sensible, you’ll see an error in the debug pane. This setting allows you to explicitly enable and disable the checking mechanism. See with_arg_checks for enabling/disabling argument checking only for a specific do
/end
block.
Introduced in v2.0
# Example 1 | |
|
|
use_bpm bpm (number)
Sets the tempo in bpm (beats per minute) for everything afterwards. Affects all subsequent calls to sleep
and all temporal synth arguments which will be scaled to match the new bpm. If you wish to bypass scaling in calls to sleep, see the fn rt
. Also, if you wish to bypass time scaling in synth args see use_arg_bpm_scaling
. See also with_bpm
for a block scoped version of use_bpm
.
For dance music here’s a rough guide for which BPM to aim for depending on your genre:
Introduced in v2.0
# Example 1 | |
|
|
use_bpm_mul mul (number)
Sets the tempo in bpm (beats per minute) as a multiplication of the current tempo. Affects all containing calls to sleep
and all temporal synth arguments which will be scaled to match the new bpm. See also use_bpm
Introduced in v2.3
# Example 1 | |
|
|
use_cent_tuning cent_shift (number)
Uniformly tunes your music by shifting all notes played by the specified number of cents. To shift up by a cent use a cent tuning of 1. To shift down use negative numbers. One semitone consists of 100 cents.
See with_cent_tuning
for setting the cent tuning value only for a specific do
/end
block. To tranpose entire semitones see use_transpose
.
Introduced in v2.9
# Example 1 | |
|
|
use_cue_logging true_or_false (boolean)
Enable or disable log messages created on cues. This does not disable the cues themselves, it just stops them from being printed to the log
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
use_debug true_or_false (boolean)
Enable or disable messages created on synth triggers. If this is set to false, the synths will be silent until debug is turned back on. Silencing debug messages can reduce output noise and also increase performance on slower platforms. See with_debug
for setting the debug value only for a specific do
/end
block.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
use_merged_sample_defaults
Specify new default values to be used by all subsequent calls to sample
. Merges the specified values with any previous defaults, rather than replacing them.
Introduced in v2.9
# Example 1 | |
|
|
use_merged_synth_defaults
Specify synth arg values to be used by any following call to play. Merges the specified values with any previous defaults, rather than replacing them.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
use_octave octave_shift (number)
Transposes your music by shifting all notes played by the specified number of octaves. To shift up by an octave use a transpose of 1. To shift down use negative numbers. See with_octave
for setting the octave shift only for a specific do
/end
block. For transposing the notes within the octave range see use_transpose
.
Introduced in v2.9
# Example 1 | |
|
|
# Example 2 | |
|
|
use_random_seed seed (number)
Resets the random number generator to the specified seed. All subsequently generated random numbers and randomisation functions such as shuffle
and choose
will use this new generator and the current generator is discarded. Use this to change the sequence of random numbers in your piece in a way that can be reproduced. Especially useful if combined with iteration. See examples.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
use_sample_bpm string_or_number (sample_name_or_duration)
Modify bpm so that sleeping for 1 will sleep for the duration of the sample.
Introduced in v2.1
num_beats: |
The number of beats within the sample. By default this is 1. |
# Example 1 | |
|
|
# Example 2 | |
|
|
use_sample_defaults
Specify new default values to be used by all subsequent calls to sample
. Will remove and override any previous defaults.
Introduced in v2.5
# Example 1 | |
|
|
use_sample_pack pack_path (string)
Given a path to a folder of samples on your filesystem, this method makes any .wav
, .wave
, .aif
, .aiff
or .flac
files in that folder available as samples. Use use_sample_pack :default
To revert back to the default built-in samples.
Introduced in v2.0
# Example 1 | |
|
|
use_synth synth_name (symbol)
Switch the current synth to synth_name
. Affects all further calls to play
. See with_synth
for changing the current synth only for a specific do
/end
block.
Introduced in v2.0
# Example 1 | |
|
|
use_synth_defaults
Specify new default values to be used by all subsequent calls to play
. Will remove and override any previous defaults.
Introduced in v2.0
# Example 1 | |
|
|
use_timing_guarantees bool (true_or_false)
If set to true, synths will not trigger if it is too late. If false, some synth triggers may be late.
Introduced in v2.10
# Example 1 | |
|
|
# Example 2 | |
|
|
use_transpose note_shift (number)
Transposes your music by shifting all notes played by the specified amount. To shift up by a semitone use a transpose of 1. To shift down use negative numbers. See with_transpose
for setting the transpose value only for a specific do
/end
block. To transpose entire octaves see use_octave
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
use_tuning tuning (symbol), fundamental_note (symbol_or_number)
In most music we make semitones by dividing the octave into 12 equal parts, which is known as equal temperament. However there are lots of other ways to tune the 12 notes. This method adjusts each midi note into the specified tuning system. Because the ratios between notes aren’t always equal, be careful to pick a centre note that is in the key of the music you’re making for the best sound. Currently available tunings are :just
, :pythagorean
, :meantone
and the default of :equal
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
vector list (array)
Create a new immutable vector from args. Out of range indexes return nil.
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
version
Return information representing the current version of Sonic Pi. This information may be further inspected with version.major
, version.minor
, version.patch
and version.dev
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
vt
Get the virtual time of the current thread.
Introduced in v2.1
# Example 1 | |
|
|
wait beats (number)
Synonym for sleep
- see sleep
Introduced in v2.0
with_arg_bpm_scaling
Turn synth argument bpm scaling on or off for the supplied block. Note, using rt
for args will result in incorrect times when used within this block.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
with_arg_checks true_or_false (boolean)
Similar to use_arg_checks
except only applies to code within supplied do
/end
block. Previous arg check value is restored after block.
Introduced in v2.0
# Example 1 | |
|
|
with_bpm bpm (number)
Sets the tempo in bpm (beats per minute) for everything in the given block. Affects all containing calls to sleep
and all temporal synth arguments which will be scaled to match the new bpm. See also use_bpm
For dance music here’s a rough guide for which BPM to aim for depending on your genre:
Introduced in v2.0
# Example 1 | |
|
|
with_bpm_mul mul (number)
Sets the tempo in bpm (beats per minute) for everything in the given block as a multiplication of the current tempo. Affects all containing calls to sleep
and all temporal synth arguments which will be scaled to match the new bpm. See also with_bpm
Introduced in v2.3
# Example 1 | |
|
|
with_cent_tuning cent_shift (number)
Similar to use_cent_tuning
except only applies cent shift to code within supplied do
/end
block. Previous cent tuning value is restored after block. One semitone consists of 100 cents. To tranpose entire semitones see with_transpose
.
Introduced in v2.9
# Example 1 | |
|
|
with_cue_logging true_or_false (boolean)
Similar to use_cue_logging except only applies to code within supplied do
/end
block. Previous cue log value is restored after block.
Introduced in v2.6
# Example 1 | |
|
|
with_debug true_or_false (boolean)
Similar to use_debug except only applies to code within supplied do
/end
block. Previous debug value is restored after block.
Introduced in v2.0
# Example 1 | |
|
|
with_fx fx_name (symbol)
This applies the named effect (FX) to everything within a given do
/end
block. Effects may take extra parameters to modify their behaviour. See FX help for parameter details.
For advanced control, it is also possible to modify the parameters of an effect within the body of the block. If you define the block with a single argument, the argument becomes a reference to the current effect and can be used to control its parameters (see examples).
Introduced in v2.0
reps: |
Number of times to repeat the block in an iteration. |
kill_delay: |
Amount of time to wait after all synths triggered by the block have completed before stopping and freeing the effect synthesiser. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
with_merged_sample_defaults
Specify new default values to be used by all subsequent calls to sample
within the do
/end
block. Merges the specified values with any previous sample defaults, rather than replacing them. After the do
/end
block has completed, the previous sampled defaults (if any) are restored.
Introduced in v2.9
# Example 1 | |
|
|
with_merged_synth_defaults
Specify synth arg values to be used by any following call to play within the specified do
/end
block. Merges the specified values with any previous synth defaults, rather than replacing them. After the do
/end
block has completed, previous defaults (if any) are restored.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
with_octave octave_shift (number)
Transposes your music by shifting all notes played by the specified number of octaves within the specified block. To shift up by an octave use a transpose of 1. To shift down use negative numbers. For transposing the notes within the octave range see with_transpose
.
Introduced in v2.9
# Example 1 | |
|
|
with_random_seed seed (number)
Resets the random number generator to the specified seed for the specified code block. All generated random numbers and randomisation functions such as shuffle
and choose
within the code block will use this new generator. Once the code block has completed, the original generator is restored and the code block generator is discarded. Use this to change the sequence of random numbers in your piece in a way that can be reproduced. Especially useful if combined with iteration. See examples.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
with_sample_bpm string_or_number (sample_name_or_duration)
Block-scoped modification of bpm so that sleeping for 1 will sleep for the duration of the sample.
Introduced in v2.1
num_beats: |
The number of beats within the sample. By default this is 1. |
# Example 1 | |
|
|
# Example 2 | |
|
|
with_sample_defaults
Specify new default values to be used by all subsequent calls to sample
within the do
/end
block. After the do
/end
block has completed, the previous sampled defaults (if any) are restored. For the contents of the block, will remove and override any previous defaults.
Introduced in v2.5
# Example 1 | |
|
|
with_sample_pack pack_path (string)
Given a path to a folder of samples on your filesystem, this method makes any .wav
, .wave
, .aif
, .aiff
or .flac
files in that folder available as samples inside the given block.
Introduced in v2.0
# Example 1 | |
|
|
with_synth synth_name (symbol)
Switch the current synth to synth_name
but only for the duration of the do
/end
block. After the do
/end
block has completed, the previous synth is restored.
Introduced in v2.0
# Example 1 | |
|
|
with_synth_defaults
Specify new default values to be used by all calls to play
within the do
/end
block. After the do
/end
block has completed the previous synth defaults (if any) are restored.
Introduced in v2.0
# Example 1 | |
|
|
with_timing_guarantees bool (true_or_false)
For the given block, if set to true, synths will not trigger if it is too late. If false, some synth triggers may be late. After the block has completed, the previous value is restored.
Introduced in v2.10
# Example 1 | |
|
|
# Example 2 | |
|
|
with_transpose note_shift (number)
Similar to use_transpose except only applies to code within supplied do
/end
block. Previous transpose value is restored after block. To transpose entire octaves see with_octave
.
Introduced in v2.0
# Example 1 | |
|
|
with_tuning tuning (symbol), fundamental_note (symbol_or_number)
Similar to use_tuning except only applies to code within supplied do
/end
block. Previous tuning value is restored after block.
Introduced in v2.6
# Example 1 | |
|
|